Введение в Distutils

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

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

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

Каждый из этих задач рассматривается в данном документе.

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

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

Скрипт setup обычно довольно прост, хотя, поскольку он написан на Python, нет никаких ограничений на то, что вы можете с ним сделать, хотя вы должны быть осторожны, помещая в него произвольно дорогостоящие операции. В отличие от, скажем, скриптов конфигурации типа 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, распределяемая вместе как один загружаемый ресурс и предназначенная для установки en masse. Примерами некоторых известных дистрибутивов модулей являются NumPy, SciPy, Pillow или mxBase. (Это можно назвать пакетом, но этот термин уже используется в контексте Python: один дистрибутив модулей может содержать ноль, один или несколько пакетов Python.)

дистрибутив чистого модуля

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

дистрибутив нечистого модуля

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

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

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