Содержание страницы

1. Введение в Distutils¶An Introduction to Distutils

Этот документ описывает использование Distutils для распространения своих модулей Python, сосредотачиваясь на роли разработчика/распространителя: если требуется информация об установке модулей Python, следует обратиться к главе Установка модулей Python.

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

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

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

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

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

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

Сам setup-скрипт обычно довольно прост, но, поскольку он написан на 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-скрипта).

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

python setup.py sdist

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

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. Во-первых, и разработчики, и установщики имеют одинаковый базовый интерфейс – сценарий setup. Разница в том, какие команды commands 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¶General Python terminology

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

модуль: основная единица повторного использования кода в Python: блок кода, импортируемый другим кодом. Здесь нас интересуют три типа модулей: чистые Python-модули, модули-расширения и пакеты.
чистый Python-модуль: модуль, написанный на Python и содержащийся в одном файле .py (и, возможно, связанных файлах .pyc и/или .pyo). Иногда называется «чистым модулем».
модуль-расширение: модуль, написанный на низкоуровневом языке реализации Python: C/C++ для Python, Java для Jython. Обычно содержится в одном динамически загружаемом предварительно скомпилированном файле, например, shared object (.so) для расширений Python в Unix, DLL (с расширением .pyd) для расширений Python в Windows или файл Java class для расширений Jython. (Обратите внимание, что в настоящее время Distutils работает только с расширениями C/C++ для Python.)
пакет: модуль, который содержит другие модули; обычно находится в каталоге в файловой системе и отличается от других каталогов наличием файла __init__.py.
корневой пакет: корень иерархии пакетов. (На самом деле это не пакет, поскольку у него нет файла __init__.py. Но нужно же его как-то называть.) Подавляющая часть стандартной библиотеки находится в корневом пакете, как и многие небольшие самостоятельные сторонние модули, не принадлежащие более крупной коллекции модулей. В отличие от обычных пакетов, модули в корневом пакете могут находиться в нескольких каталогах: фактически, каждый каталог, перечисленный в sys.path, добавляет модули в корневой пакет.

1.4. Терминология Distutils¶Distutils-specific terminology

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

дистрибутив модулей: коллекция модулей Python, распространяемая вместе как единый загружаемый ресурс и предназначенная для установки скопом. Примеры известных дистрибутивов модулей: NumPy, SciPy, PIL (Python Imaging Library) или mxBase. (Это можно было бы назвать пакетом, но этот термин уже занят в контексте Python: один дистрибутив модулей может содержать ноль, один или много пакетов Python.)
чистый дистрибутив модулей: дистрибутив модулей, содержащий только чистые Python-модули и пакеты. Иногда называется «чистым дистрибутивом».
нечистый дистрибутив модулей: дистрибутив модулей, содержащий хотя бы один модуль-расширение. Иногда называется «нечистым дистрибутивом».
корень дистрибутива: верхний каталог дерева исходного кода (или дистрибутива исходного кода); каталог, в котором находится setup.py. Обычно setup.py запускается из этого каталога.