7. Розширення Distutils

Примітка

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

Distutils можна розширити різними способами. Більшість розширень мають форму нових команд або заміни існуючих команд. Нові команди можуть бути написані для підтримки нових типів пакетів, що стосуються платформи, наприклад, тоді як заміни існуючих команд можуть бути зроблені для зміни деталей того, як команда працює з пакетом.

Більшість розширень distutils створено в сценаріях setup.py, які хочуть змінити існуючі команди; багато хто просто додає кілька розширень файлів, які слід скопіювати в пакунки на додаток до файлів .py для зручності.

Більшість реалізацій команд distutils є підкласами класу distutils.cmd.Command. Нові команди можуть безпосередньо успадковувати Command, тоді як заміни часто походять від Command опосередковано, безпосередньо створюючи підклас команди, яку вони замінюють. Команди повинні походити від Command.

7.1. Інтеграція нових команд

Існують різні способи інтеграції нових реалізацій команд у distutils. Найважче — лобіювати включення нових функцій у sam distutils і чекати (і вимагати) версії Python, яка надає цю підтримку. Це дійсно важко з багатьох причин.

Найпоширенішим і, можливо, найдоцільнішим для більшості потреб є включення нових реалізацій у ваш сценарій setup.py і використання їх функцією distutils.core.setup():

from distutils.command.build_py import build_py as _build_py
from distutils.core import setup

class build_py(_build_py):
    """Specialized Python source builder."""

    # implement whatever needs to be different...

setup(cmdclass={'build_py': build_py},
      ...)

Цей підхід є найбільш цінним, якщо нові реалізації потрібно використовувати для використання конкретного пакета, оскільки кожен, хто зацікавлений у пакеті, повинен мати нову реалізацію команди.

Починаючи з Python 2.4, доступний третій параметр, призначений для додавання нових команд, які можуть підтримувати існуючі сценарії setup.py без необхідності модифікації інсталяції Python. Очікується, що це дозволить стороннім розширенням надавати підтримку для додаткових систем пакування, але команди можна використовувати для будь-яких завдань, для яких можна використовувати команди distutils. Новий параметр конфігурації, command_packages (параметр командного рядка --command-packages), можна використовувати для визначення додаткових пакетів для пошуку модулів, що реалізують команди. Як і всі параметри distutils, це можна вказати в командному рядку або у файлі конфігурації. Цей параметр можна встановити лише в розділі [global] конфігураційного файлу або перед будь-якими командами в командному рядку. Якщо встановлено у файлі конфігурації, його можна змінити з командного рядка; встановлення його як порожнього рядка в командному рядку призводить до використання типового значення. Це ніколи не можна встановлювати у файлі конфігурації, що надається разом із пакетом.

Цю нову опцію можна використовувати для додавання будь-якої кількості пакунків до списку пакетів, у яких шукаються реалізації команд; кілька назв пакетів слід розділяти комами. Якщо не вказано, пошук виконується лише в пакеті distutils.command. Коли setup.py запускається з параметром --command-packages distcmds,buildcmds, проте пакунки distutils.command, distcmds і buildcmds шукатиметься в такому порядку. Очікується, що нові команди будуть реалізовані в модулях з тим же іменем, що й команда, класами, що мають таке ж ім’я. Враховуючи наведений вище приклад командного рядка, команду bdist_openpkg можна реалізувати за допомогою класу distcmds.bdist_openpkg.bdist_openpkg або buildcmds.bdist_openpkg.bdist_openpkg.

7.2. Додавання нових типів розподілу

Команди, які створюють дистрибутиви (файли в каталозі dist/), повинні додати пари (command, filename) до self.distribution.dist_files, щоб upload міг завантажувати це в PyPI. Назва файлу в парі не містить інформації про шлях, лише назву самого файлу. У режимі сухого запуску пари все одно повинні бути додані, щоб представити те, що було б створено.