Введение в 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 чаще используется для установщиков (хотя большинство разработчиков время от времени захотят установить свой код).

Если вы хотите сделать всё действительно простым для ваших пользователей, вы можете создать один или несколько скомпилированных дистрибутивов для них. Например, если вы работаете на компьютере с Windows и хотите упростить работу для других пользователей Windows, вы можете создать установочный исполняемый файл (самый подходящий тип скомпилированного дистрибутива для этой платформы) с помощью команды bdist_wininst. Например:

python setup.py bdist_wininst

создаст исполняемый установочный файл foo-1.0.win32.exe в текущем каталоге.

Другие полезные форматы скомпилированных дистрибутивов — 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 будет запускаться из этого каталога.