introduction.md

1> **Источник:** https://python-all.ru/3.0/distutils/introduction.html2>3> «Документация Python на русском» – неофициальный перевод официальной документации Python: версии от 2.6 до 3.16, полнотекстовый поиск, английский оригинал рядом с переводом. Эта Markdown-версия страницы предназначена для работы с LLM: вставьте её в ChatGPT, Claude или Cursor.45---67# Введение в Distutils89Этот документ описывает использование Distutils для распространения своих модулей Python, сосредотачиваясь на роли разработчика/распространителя: если требуется информация об установке модулей Python, следует обратиться к главе [*Установка модулей Python*](https://python-all.ru/3.0/install/index.html#install-index).1011## Концепции и терминология1213Использовать Distutils довольно просто как для разработчиков модулей, так и для пользователей или администраторов, устанавливающих сторонние модули. В роли разработчика ваши обязанности (помимо написания качественного, хорошо задокументированного и протестированного кода) таковы:1415- написать сценарий установки (`setup.py` по соглашению)16- (опционально) написание конфигурационного файла setup.cfg;17- создание исходной дистрибуции (source distribution);18- (опционально) создание одной или нескольких сборок (двоичных дистрибуций).1920Каждая из этих задач описана в данном документе.2122Не все разработчики модулей имеют доступ к множеству платформ, поэтому не всегда разумно требовать от них создания множества готовых сборок. Предполагается, что возникнет прослойка посредников, называемых *пакетёрами (packagers)*, которые решат эту проблему. Пакетёры будут брать исходные дистрибуции, выпущенные разработчиками, собирать их на одной или нескольких платформах и выпускать готовые двоичные дистрибуции. Таким образом, пользователи самых популярных платформ смогут устанавливать наиболее популярные дистрибуции модулей Python наиболее естественным для своей платформы способом – без необходимости запускать setup-скрипт или компилировать хотя бы строчку кода.2324## Простой пример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.0/distutils/setupscript.html#setup-script)).4445Чтобы создать дистрибутив исходного кода для этого модуля, нужно создать сценарий установки `setup.py`, содержащий указанный выше код, и выполнить:4647```python48python setup.py sdist49```5051Это создаст архивный файл (например, tarball в Unix, ZIP-файл в Windows), содержащий ваш сценарий установки `setup.py` и ваш модуль `foo.py`. Архивный файл будет назван `foo-1.0.tar.gz` (или `.zip`) и распакуется в каталог `foo-1.0`.5253Если конечный пользователь хочет установить модуль `foo`, всё, что ему нужно сделать – скачать `foo-1.0.tar.gz` (или `.zip`), распаковать его и, из каталога `foo-1.0`, выполнить5455```python56python setup.py install57```5859что в конечном итоге скопирует `foo.py` в соответствующий каталог для сторонних модулей в установке Python.6061Этот простой пример демонстрирует некоторые фундаментальные концепции Distutils. Во-первых, и разработчики, и установщики имеют одинаковый базовый интерфейс – сценарий setup. Разница в том, какие команды *commands* Distutils они используют: команда **sdist** почти исключительно для разработчиков модулей, а **install** чаще используется установщиками (хотя большинство разработчиков время от времени тоже хотят устанавливать свой код).6263Если вы хотите максимально упростить работу для своих пользователей, вы можете создать для них одну или несколько сборок. Например, если вы работаете на машине с Windows и хотите облегчить жизнь другим пользователям Windows, вы можете создать исполняемый установщик (наиболее подходящий тип сборки для этой платформы) с помощью команды **bdist\_wininst**. Например:6465```python66python setup.py bdist_wininst67```6869создаст исполняемый установщик, `foo-1.0.win32.exe`, в текущем каталоге.7071Другие полезные форматы готовых дистрибутивов: RPM (реализуется командой **bdist\_rpm**), Solaris **pkgtool** (**bdist\_pkgtool**) и HP-UX **swinstall** (**bdist\_sdux**). Например, следующая команда создаст RPM-файл с именем `foo-1.0.noarch.rpm`:7273```python74python setup.py bdist_rpm75```7677(Команда **bdist\_rpm** использует исполняемый файл **rpm**, поэтому её нужно запускать на системе на базе RPM, такой как Red Hat Linux, SuSE Linux или Mandrake Linux.)7879Узнать, какие форматы дистрибутивов доступны в любой момент, можно выполнив8081```python82python setup.py bdist --help-formats83```8485## Общая терминология Python8687Предполагается, что читатели этого документа хорошо знакомы с понятиями модулей, расширений и т.д. Тем не менее, чтобы все исходили из общего понимания, ниже приводится глоссарий общеупотребительных терминов Python:8889**модуль**9091основная единица повторного использования кода в Python: блок кода, импортируемый другим кодом. Здесь нас интересуют три типа модулей: чистые Python-модули, модули-расширения и пакеты.9293**чистый Python-модуль**9495модуль, написанный на Python и содержащийся в одном файле9697`.py`9899(и, возможно, связанных файлах100101`.pyc`102103и/или104105`.pyo`106107). Иногда называется «чистым модулем».108109**модуль-расширение**110111модуль, написанный на низкоуровневом языке реализации Python: C/C++ для Python, Java для Jython. Обычно содержится в одном динамически загружаемом предварительно скомпилированном файле, например, shared object (112113`.so`114115) для расширений Python в Unix, DLL (с расширением116117`.pyd`118119) для расширений Python в Windows или файл Java class для расширений Jython. (Обратите внимание, что в настоящее время Distutils работает только с расширениями C/C++ для Python.)120121**пакет**122123модуль, который содержит другие модули; обычно находится в каталоге в файловой системе и отличается от других каталогов наличием файла124125`__init__.py`126127.128129**корневой пакет**130131корень иерархии пакетов. (На самом деле это не пакет, поскольку у него нет файла132133`__init__.py`134135. Но нужно же его как-то называть.) Подавляющая часть стандартной библиотеки находится в корневом пакете, как и многие небольшие самостоятельные сторонние модули, не принадлежащие более крупной коллекции модулей. В отличие от обычных пакетов, модули в корневом пакете могут находиться в нескольких каталогах: фактически, каждый каталог, перечисленный в136137`sys.path`138139, добавляет модули в корневой пакет.140141## Терминология Distutils142143Следующие термины относятся более конкретно к области распространения Python-модулей с помощью Distutils:144145**дистрибутив модулей**146147набор модулей Python, распространяемых вместе как единый загружаемый ресурс и предназначенных для установки148149*все вместе*150151. Примеры известных дистрибутивов модулей: Numeric Python, PyXML, PIL (Python Imaging Library) или mxBase. (Это называлось бы152153*пакетом*154155, но этот термин уже занят в контексте Python: один дистрибутив модулей может содержать ноль, один или много пакетов Python.)156157**чистый дистрибутив модулей**158159дистрибутив модулей, содержащий только чистые Python-модули и пакеты. Иногда называется «чистым дистрибутивом».160161**нечистый дистрибутив модулей**162163дистрибутив модулей, содержащий хотя бы один модуль-расширение. Иногда называется «нечистым дистрибутивом».164165**корень дистрибутива**166167верхний каталог дерева исходного кода (или дистрибутива исходного кода); каталог, в котором находится168169`setup.py`170171. Обычно172173`setup.py`174175запускается из этого каталога.176