1. Введение в дистрибутивы¶
Примечание
Этот документ будет храниться только до тех пор, пока в документации setuptools
по адресу https://setuptools.readthedocs.io/en/latest/setuptools.html самостоятельно не будет представлена вся соответствующая информация, которая в настоящее время включена в этот документ.
Этот документ описывает использование дистрибутивов для распространения ваших модулей Python, уделяя особое внимание роли разработчика/распространителя: если вы ищете информацию по установке модулей Python, вам следует обратиться к главе Установка модулей Python (устаревшая версия).
1.1. Концепции и терминология¶
Пользоваться дистрибутивами довольно просто, как для разработчиков модулей, так и для пользователей/администраторов, устанавливающих сторонние модули. В ваши обязанности как разработчика (помимо написания надежного, хорошо документированного и протестированного кода, конечно!) входят:
напишите сценарий установки (
setup.py
по соглашению)(необязательно) запишите установочный конфигурационный файл
создайте исходный дистрибутив
(необязательно) создайте один или несколько встроенных (двоичных) дистрибутивов
Каждая из этих задач описана в данном документе.
Не все разработчики модулей имеют доступ к множеству платформ, поэтому не всегда возможно ожидать, что они создадут множество встроенных дистрибутивов. Есть надежда, что для удовлетворения этой потребности появится класс посредников, называемых «упаковщиками». Упаковщики берут исходные тексты дистрибутивов, выпущенных разработчиками модулей, создают их на одной или нескольких платформах и выпускают готовые дистрибутивы. Таким образом, пользователи на самых популярных платформах смогут устанавливать самые популярные дистрибутивы модулей Python наиболее естественным для своей платформы способом, без необходимости запускать ни одного установочного скрипта или компилировать строку кода.
1.2. Простой пример¶
Сценарий установки обычно довольно прост, хотя, поскольку он написан на Python, нет никаких произвольных ограничений на то, что вы можете с ним делать, хотя вам следует быть осторожным, добавляя в свой сценарий установки сколь угодно дорогостоящие операции. В отличие, скажем, от сценариев настройки в стиле Autoconf, сценарий установки может быть запущен несколько раз в ходе сборки и установки вашего дистрибутива модуля.
Если все, что вы хотите сделать, это распространить модуль с именем 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 откройте окно командной строки (
) и измените команду на: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 они используют: команда 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. Специфичная для дистрибутивов терминология¶
Следующие термины более конкретно применимы к области распространения модулей Python с использованием дистрибутивов:
- распределение модулей
набор модулей Python, распространяемых в виде единого загружаемого ресурса и предназначенных для массовой установки. Примерами некоторых известных дистрибутивов модулей являются NumPy, SciPy, Pillow или mx Base. (Это можно было бы назвать пакетом, за исключением того, что этот термин уже используется в контексте Python: дистрибутив одного модуля может содержать ноль, один или много пакетов Python.)
- чистое модульное распределение
модульный дистрибутив, содержащий только чистые модули и пакеты Python. Иногда его называют «чистым дистрибутивом».
- распределение модулей не в чистом виде
модульный дистрибутив, содержащий по крайней мере один модуль расширения. Иногда его называют «неполным дистрибутивом».
- корень распределения
каталог верхнего уровня вашего дерева исходных текстов (или дистрибутива исходных текстов); каталог, в котором существует
setup.py
. Как правило,setup.py
будет запускаться из этого каталога.