introduction.md

1> **Источник:** https://python-all.ru/3.2/distutils/introduction.html2>3> «Документация Python на русском» – неофициальный перевод официальной документации Python: версии от 2.6 до 3.16, полнотекстовый поиск, английский оригинал рядом с переводом. Эта Markdown-версия страницы предназначена для работы с LLM: вставьте её в ChatGPT, Claude или Cursor.45---67# 1. Введение в Distutils89Этот документ описывает использование Distutils для распространения своих модулей Python, сосредотачиваясь на роли разработчика/распространителя: если требуется информация об установке модулей Python, следует обратиться к главе [*Установка модулей Python*](https://python-all.ru/3.2/install/index.html#install-index).1011## 1.1. Концепции и терминология1213Использовать Distutils довольно просто как для разработчиков модулей, так и для пользователей или администраторов, устанавливающих сторонние модули. В роли разработчика ваши обязанности (помимо написания качественного, хорошо задокументированного и протестированного кода) таковы:1415- написать сценарий установки (`setup.py` по соглашению)16- (опционально) написание конфигурационного файла setup.cfg;17- создание исходной дистрибуции (source distribution);18- (опционально) создание одной или нескольких сборок (двоичных дистрибуций).1920Каждая из этих задач описана в данном документе.2122Не все разработчики модулей имеют доступ к множеству платформ, поэтому не всегда разумно требовать от них создания множества готовых сборок. Предполагается, что возникнет прослойка посредников, называемых *пакетёрами (packagers)*, которые решат эту проблему. Пакетёры будут брать исходные дистрибуции, выпущенные разработчиками, собирать их на одной или нескольких платформах и выпускать готовые двоичные дистрибуции. Таким образом, пользователи самых популярных платформ смогут устанавливать наиболее популярные дистрибуции модулей Python наиболее естественным для своей платформы способом – без необходимости запускать setup-скрипт или компилировать хотя бы строчку кода.2324## 1.2. Простой пример2526Сам setup-скрипт обычно довольно прост, но, поскольку он написан на Python, нет произвольных ограничений на то, что можно в нём делать. Однако стоит проявлять осторожность, размещая в нём слишком затратные по времени операции. В отличие от, скажем, configure-скриптов в стиле Autoconf, setup-скрипт может запускаться несколько раз в процессе сборки и установки вашей дистрибуции.2728Если всё, что нужно сделать – распространить модуль с именем `foo`, содержащийся в файле `foo.py`, то сценарий установки может быть таким:2930```python31from distutils.core import setup32setup(name='foo',33      version='1.0',34      py_modules=['foo'],35      )36```3738Несколько замечаний:3940- большая часть информации, передаваемой в Distutils, задаётся в виде именованных аргументов функции `setup()`41- эти именованные аргументы делятся на две категории: метаданные пакета (имя, номер версии) и информация о содержимом пакета (в данном случае – список чистых модулей Python);42- модули указываются по имени, а не по имени файла (то же справедливо для пакетов и расширений);43- рекомендуется указывать немного больше метаданных, в частности ваше имя, адрес электронной почты и URL проекта (пример приведён в разделе [*Написание setup-скрипта*](https://python-all.ru/3.2/distutils/setupscript.html#setup-script)).4445Чтобы создать дистрибутив исходного кода для этого модуля, нужно создать сценарий установки, `setup.py`, содержащий приведённый выше код, и выполнить эту команду из терминала:4647```python48python setup.py sdist49```5051Для Windows откройте окно командной строки (*Пуск ‣ Стандартные*) и измените команду на:5253```python54setup.py sdist55```5657**sdist** создаст архивный файл (например, tarball в Unix, ZIP-файл в Windows), содержащий сценарий установки `setup.py` и модуль `foo.py`. Архивный файл будет назван `foo-1.0.tar.gz` (или `.zip`) и распакуется в каталог `foo-1.0`.5859Если конечный пользователь хочет установить модуль `foo`, всё, что ему нужно сделать – скачать `foo-1.0.tar.gz` (или `.zip`), распаковать его и, из каталога `foo-1.0`, выполнить6061```python62python setup.py install63```6465что в конечном итоге скопирует `foo.py` в соответствующий каталог для сторонних модулей в установке Python.6667Этот простой пример демонстрирует некоторые фундаментальные концепции Distutils. Во-первых, и разработчики, и установщики имеют одинаковый базовый интерфейс – сценарий setup. Разница в том, какие команды *commands* Distutils они используют: команда **sdist** почти исключительно для разработчиков модулей, а **install** чаще используется установщиками (хотя большинство разработчиков время от времени тоже хотят устанавливать свой код).6869Если вы хотите максимально упростить работу для своих пользователей, вы можете создать для них одну или несколько сборок. Например, если вы работаете на машине с Windows и хотите облегчить жизнь другим пользователям Windows, вы можете создать исполняемый установщик (наиболее подходящий тип сборки для этой платформы) с помощью команды **bdist\_wininst**. Например:7071```python72python setup.py bdist_wininst73```7475создаст исполняемый установщик, `foo-1.0.win32.exe`, в текущем каталоге.7677Другие полезные форматы готовых дистрибутивов: RPM (реализуется командой **bdist\_rpm**), Solaris **pkgtool** (**bdist\_pkgtool**) и HP-UX **swinstall** (**bdist\_sdux**). Например, следующая команда создаст RPM-файл с именем `foo-1.0.noarch.rpm`:7879```python80python setup.py bdist_rpm81```8283(Команда **bdist\_rpm** использует исполняемый файл **rpm**, поэтому её нужно запускать на системе на базе RPM, такой как Red Hat Linux, SuSE Linux или Mandrake Linux.)8485Узнать, какие форматы дистрибутивов доступны в любой момент, можно выполнив8687```python88python setup.py bdist --help-formats89```9091## 1.3. Общая терминология Python9293Предполагается, что читатели этого документа хорошо знакомы с понятиями модулей, расширений и т.д. Тем не менее, чтобы все исходили из общего понимания, ниже приводится глоссарий общеупотребительных терминов Python:9495**модуль**9697основная единица повторного использования кода в Python: блок кода, импортируемый другим кодом. Здесь нас интересуют три типа модулей: чистые Python-модули, модули-расширения и пакеты.9899**чистый Python-модуль**100101модуль, написанный на Python и содержащийся в одном файле102103`.py`104105(и, возможно, связанных файлах106107`.pyc`108109и/или110111`.pyo`112113). Иногда называется «чистым модулем».114115**модуль-расширение**116117модуль, написанный на низкоуровневом языке реализации Python: C/C++ для Python, Java для Jython. Обычно содержится в одном динамически загружаемом предварительно скомпилированном файле, например, shared object (118119`.so`120121) для расширений Python в Unix, DLL (с расширением122123`.pyd`124125) для расширений Python в Windows или файл Java class для расширений Jython. (Обратите внимание, что в настоящее время Distutils работает только с расширениями C/C++ для Python.)126127**пакет**128129модуль, который содержит другие модули; обычно находится в каталоге в файловой системе и отличается от других каталогов наличием файла130131`__init__.py`132133.134135**корневой пакет**136137корень иерархии пакетов. (На самом деле это не пакет, поскольку у него нет файла138139`__init__.py`140141. Но нужно же его как-то называть.) Подавляющая часть стандартной библиотеки находится в корневом пакете, как и многие небольшие самостоятельные сторонние модули, не принадлежащие более крупной коллекции модулей. В отличие от обычных пакетов, модули в корневом пакете могут находиться в нескольких каталогах: фактически, каждый каталог, перечисленный в142143`sys.path`144145, добавляет модули в корневой пакет.146147## 1.4. Терминология Distutils148149Следующие термины относятся более конкретно к области распространения Python-модулей с помощью Distutils:150151**дистрибутив модулей**152153коллекция модулей Python, распространяемая вместе как единый загружаемый ресурс и предназначенная для установки154155*скопом*156157. Примеры известных дистрибутивов модулей: NumPy, SciPy, PIL (Python Imaging Library) или mxBase. (Это можно было бы назвать158159*пакетом*160161, но этот термин уже занят в контексте Python: один дистрибутив модулей может содержать ноль, один или много пакетов Python.)162163**чистый дистрибутив модулей**164165дистрибутив модулей, содержащий только чистые Python-модули и пакеты. Иногда называется «чистым дистрибутивом».166167**нечистый дистрибутив модулей**168169дистрибутив модулей, содержащий хотя бы один модуль-расширение. Иногда называется «нечистым дистрибутивом».170171**корень дистрибутива**172173верхний каталог дерева исходного кода (или дистрибутива исходного кода); каталог, в котором находится174175`setup.py`176177. Обычно178179`setup.py`180181запускается из этого каталога.182