introduction.md

1> **Источник:** https://python-all.ru/3.5/distutils/introduction.html2>3> «Документация Python на русском» – неофициальный перевод официальной документации Python: версии от 2.6 до 3.16, полнотекстовый поиск, английский оригинал рядом с переводом. Эта Markdown-версия страницы предназначена для работы с LLM: вставьте её в ChatGPT, Claude или Cursor.45---67# 1. Введение в Distutils89Этот документ посвящён использованию Distutils для распространения модулей Python, с упором на роль разработчика/распространителя: если вам нужна информация об установке модулей Python, обратитесь к разделу [Installing Python Modules (Legacy version)](https://python-all.ru/3.5/install/index.html#install-index).1011## 1.1. Концепции и терминология1213Использовать Distutils довольно просто как для разработчиков модулей, так и для пользователей или администраторов, устанавливающих сторонние модули. В роли разработчика ваши обязанности (помимо написания качественного, хорошо задокументированного и протестированного кода) таковы:1415- написание setup-скрипта (`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`, то ваш setup-скрипт может быть таким: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.5/distutils/setupscript.html#setup-script)).4445Чтобы создать исходную дистрибуцию для этого модуля, напишите setup-скрипт `setup.py`, содержащий приведённый выше код, и выполните в терминале команду:4647```python48python setup.py sdist49```5051Для Windows откройте окно командной строки (Пуск ‣ Стандартные) и измените команду на:5253```python54setup.py sdist55```5657Команда **sdist** создаст архивный файл (например, tarball в Unix, ZIP-файл в Windows), содержащий ваш setup-скрипт `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**модуль-расширение**112113модуль, написанный на низкоуровневом языке реализации Python: C/C++ для Python, Java для Jython. Обычно содержится в одном динамически загружаемом предварительно откомпилированном файле, например, файл разделяемого объекта (114115`.so`116117) для расширений Python в Unix, DLL (с расширением118119`.pyd`120121) для расширений Python в Windows или файл класса Java для расширений Jython. (Обратите внимание, что в настоящее время Distutils поддерживает только расширения C/C++ для Python.)122123**пакет**124125модуль, содержащий другие модули; обычно содержится в каталоге в файловой системе и отличается от других каталогов наличием файла126127`__init__.py`128129.130131**корневой пакет**132133корень иерархии пакетов. (На самом деле это не пакет, так как у него нет файла134135`__init__.py`136137. Но нужно же его как-то называть.) Подавляющая часть стандартной библиотеки находится в корневом пакете, как и многие небольшие самостоятельные сторонние модули, не принадлежащие к более крупной коллекции модулей. В отличие от обычных пакетов, модули корневого пакета могут находиться во многих каталогах: фактически, каждый каталог, перечисленный в138139`sys.path`140141, добавляет модули в корневой пакет.142143## 1.4. Терминология Distutils144145Следующие термины относятся более конкретно к области распространения Python-модулей с помощью Distutils:146147**дистрибутив модулей**148149коллекция модулей Python, распространяемая вместе как единый загружаемый ресурс и предназначенная для установки150151*скопом*152153. Примеры известных дистрибутивов модулей: NumPy, SciPy, PIL (Python Imaging Library) или mxBase. (Это можно было бы назвать154155*пакетом*156157, но этот термин уже занят в контексте Python: один дистрибутив модулей может содержать ноль, один или много пакетов Python.)158159**чистый дистрибутив модулей**160161дистрибутив модулей, содержащий только чистые Python-модули и пакеты. Иногда называется «чистым дистрибутивом».162163**нечистый дистрибутив модулей**164165дистрибутив модулей, содержащий хотя бы один модуль-расширение. Иногда называется «нечистым дистрибутивом».166167**корень дистрибутива**168169корневой каталог дерева исходных файлов (или исходного дистрибутива); каталог, где находится170171`setup.py`172173. Обычно команда174175`setup.py`176177запускается из этого каталога.178