Документация Python неофициальный перевод
Содержание страницы

7. Расширение DistutilsExtending Distutils

Примечание

Этот документ сохраняется только до тех пор, пока документация по setuptools по адресу https://setuptools.readthedocs.io/en/latest/setuptools.html не охватит самостоятельно всю соответствующую информацию, представленную здесь.

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

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

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

7.1. Интеграция новых командIntegrating new commands

Существуют разные способы интеграции новых реализаций команд в Distutils. Самый сложный – лоббировать включение новых возможностей в сам 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):
    """Специализированный сборщик исходного кода Python."""

    # реализовать то, что должно отличаться...

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. Добавление новых типов дистрибутивовAdding new distribution types

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