1. Введение в Distutils¶

1.1. Концепции и терминология¶

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

• написать скрипт настройки (setup.py по условию)

• (необязательно) запись файла конфигурации установки

• создать исходное распределение

• (необязательно) создать один или несколько собранных (бинарных) дистрибутивов

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

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

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

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

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

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

Некоторые наблюдения:

• Большая часть информации, которую вы предоставляете Distutils, предоставляется в качестве аргументов ключевых слов функции setup().

• эти ключевые аргументы делятся на две категории: метаданные пакета (имя, номер версии) и информация о том, что находится в пакете (в данном случае список чистых модулей Python).

• модули задаются именем модуля, а не именем файла (то же самое будет справедливо для пакетов и расширений)

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

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

python setup.py sdist

Для Windows откройте окно командной строки (Start ‣ Accessories) и измените команду на:

setup.py sdist

sdist создаст архивный файл (например, tarball на Unix, ZIP-файл на Windows), содержащий ваш установочный скрипт 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. Во-первых, и разработчики, и установщики имеют один и тот же базовый пользовательский интерфейс, т.е. скрипт установки. Разница заключается в том, какие *команды 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 запускается из этого каталога.