1. Вступ до Distutils

Примітка

Цей документ зберігається лише до тих пір, поки документація setuptools за адресою https://setuptools.readthedocs.io/en/latest/setuptools.html окремо не охопить всю відповідну інформацію, яка зараз включена тут.

Цей документ описує використання Distutils для розповсюдження ваших модулів Python, зосереджуючись на ролі розробника/розповсюджувача: якщо ви шукаєте інформацію про встановлення модулів Python, вам слід звернутися до розділу Встановлення модулів Python (застаріла версія).

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

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

  • написати сценарій налаштування (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 створить архівний файл (наприклад, tar-архів в 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 частіше для встановлювачів (хоча більшість розробників захочуть час від часу встановлювати власний код). ).

If you want to make things really easy for your users, you can create one or more built distributions for them. For instance, if you are running on a Windows machine, and want to make things easy for other Windows users, you can create an executable installer (the most appropriate type of built distribution for this platform) with the bdist_wininst command. For example:

python setup.py bdist_wininst

will create an executable installer, foo-1.0.win32.exe, in the current directory.

Іншими корисними вбудованими форматами розповсюдження є 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 запускатиметься з цього каталогу.