Введение в Distutils

1.1. Понятия и терминология

Использование Distutils довольно просто как для разработчиков модулей, так и для пользователей/администраторов, устанавливающих модули сторонних разработчиков. В качестве разработчика ваши обязанности (помимо написания качественного, хорошо документированного и протестированного кода, конечно же!):

• написать скрипт setup (setup.py по соглашению)
• (необязательно) написать конфигурационный файл setup
• создать дистрибутив исходного кода
• (необязательно) создать один или несколько скомпилированных (бинарных) дистрибутивов

В данном документе рассматриваются все эти задачи.

Не все разработчики модулей имеют доступ к множеству платформ, поэтому не всегда целесообразно ожидать от них создания множества скомпилированных дистрибутивов. Надеемся, что возникнет класс посредников, называемых *упаковщиками*, которые восполнят этот недостаток. Упаковщики будут собирать дистрибутивы исходного кода, выпущенные разработчиками модулей, на одной или нескольких платформах и выпускать полученные скомпилированные дистрибутивы. Таким образом, пользователи на наиболее популярных платформах смогут устанавливать большинство популярных дистрибутивов модулей Python наиболее естественным для их платформы способом, без необходимости запускать ни одного скрипта setup или компилировать ни одной строки кода.

1.2. Простой пример

Скрипт setup обычно довольно прост, хотя, поскольку он написан на Python, нет никаких ограничений на то, что вы можете с ним сделать, хотя следует быть осторожным с включением чрезмерно ресурсоемких операций в скрипт setup. В отличие, скажем, от скриптов конфигурации типа Autoconf, скрипт setup может запускаться несколько раз в процессе сборки и установки дистрибутива вашего модуля.

Если все, что вам нужно сделать, это распространить модуль под названием foo, содержащийся в файле foo.py, то ваш скрипт setup может быть таким простым:

from distutils.core import setup
setup(name='foo',
      version='1.0',
      py_modules=['foo'],
      )

Некоторые замечания:

• большая часть информации, которую вы предоставляете Distutils, предоставляется в качестве ключевых аргументов функции setup()
• эти ключевые аргументы делятся на две категории: метаданные пакета (имя, номер версии) и информация о содержимом пакета (список чистых модулей Python в данном случае)
• модули указываются по имени модуля, а не имени файла (то же самое будет справедливо для пакетов и расширений)
• рекомендуется предоставить немного больше метаданных, в частности ваше имя, адрес электронной почты и URL-адрес проекта (см. раздел Написание скрипта Setup для примера)

Для создания дистрибутива исходного кода для этого модуля вам нужно создать скрипт setup, setup.py, содержащий приведенный выше код, и выполнить эту команду из терминала:

python setup.py sdist

Для Windows откройте окно командной строки (Пуск ‣ Стандартные программы) и измените команду на:

setup.py sdist

sdist создаст архивный файл (например, tarball в Unix, ZIP-файл в Windows), содержащий ваш скрипт setup setup.py, и ваш модуль foo.py. Имя архивного файла будет foo-1.0.tar.gz (или .zip), и он будет распаковываться в каталог foo-1.0.

Если конечный пользователь хочет установить ваш модуль foo, ему нужно загрузить foo-1.0.tar.gz (или .zip), распаковать его и — из каталога foo-1.0 — выполнить

python setup.py install

что в конечном итоге скопирует foo.py в соответствующий каталог для модулей сторонних разработчиков в их установке Python.

Этот простой пример демонстрирует некоторые фундаментальные концепции Distutils. Во-первых, у разработчиков и установщиков одинаковый базовый пользовательский интерфейс, то есть скрипт setup. Разница заключается в том, какие команды Distutils они используют: команда sdist почти исключительно для разработчиков модулей, в то время как install чаще используется установщиками (хотя большинство разработчиков время от времени захотят установить свой собственный код).

Другие полезные форматы скомпилированных дистрибутивов — RPM, реализованные командой bdist_rpm, Solaris pkgtool (bdist_pkgtool) и HP-UX swinstall (bdist_sdux). Например, следующая команда создаст файл RPM с именем foo-1.0.noarch.rpm.

python setup.py bdist_rpm

(Команда bdist_rpm использует исполняемый файл rpm, поэтому ее нужно запускать в системе на основе RPM, такой как Red Hat Linux, SuSE Linux или Mandrake Linux.)

Вы можете узнать о доступных форматах дистрибутивов в любое время, выполнив

python setup.py bdist --help-formats

1.3. Общая терминология Python

Если вы читаете этот документ, то, вероятно, имеете хорошее представление о том, что такое модули, расширения и т. д. Тем не менее, чтобы убедиться, что все мы работаем из одной исходной точки, мы предлагаем следующий глоссарий распространенных терминов Python:

модуль

основная единица повторного использования кода в Python: блок кода, импортируемый другим кодом. Три типа модулей нас здесь интересуют: чистые модули Python, модули расширений и пакеты.

чистый модуль Python

модуль, написанный на Python и содержащийся в одном файле .py (и, возможно, связанных файлах .pyc). Иногда называется «чистым модулем».

модуль расширения

модуль, написанный на низкоуровневом языке реализации Python: C/C++ для Python, Java для Jython. Как правило, содержится в одном динамически загружаемом предварительно скомпилированном файле, например, файле разделяемой библиотеки (.so) для расширений Python в Unix, файле DLL (с расширением .pyd для расширений Python в Windows или файле класса Java для расширений Jython. (Обратите внимание, что в настоящее время Distutils обрабатывает только расширения C/C++ для Python.)

пакет

модуль, содержащий другие модули; обычно содержится в каталоге в файловой системе и отличается от других каталогов наличием файла __init__.py.

корневой пакет

корень иерархии пакетов. (Это не совсем пакет, так как у него нет файла __init__.py. Но нам нужно его как-то назвать.) Большая часть стандартной библиотеки находится в корневом пакете, как и многие небольшие, самостоятельные модули сторонних разработчиков, которые не входят в более крупное собрание модулей. В отличие от обычных пакетов, модули в корневом пакете можно найти во многих каталогах: фактически, каждый каталог, указанный в sys.path, вносит вклад модулей в корневой пакет.

1.4. Терминология, специфичная для Distutils

Следующие термины более специфичны для области распространения модулей Python с помощью Distutils:

дистрибутив модулей

коллекция модулей Python, распространяемых вместе как один загружаемый ресурс и предназначенная для одновременной установки. Примерами известных дистрибутивов модулей являются NumPy, SciPy, Pillow или mxBase. (Это было бы названо *пакетом*, за исключением того, что этот термин уже используется в контексте Python: один дистрибутив модулей может содержать ноль, один или несколько пакетов Python.)

дистрибутив чистых модулей

дистрибутив модулей, который содержит только чистые модули и пакеты Python. Иногда называется «чистым дистрибутивом».

дистрибутив нечистых модулей

дистрибутив модулей, который содержит по крайней мере один модуль расширения. Иногда называется «нечистым дистрибутивом».

корень дистрибутива

главный каталог дерева исходного кода (или дистрибутива исходного кода); каталог, в котором существует setup.py. Как правило, setup.py будет выполняться из этого каталога.