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. Самый сложный - лоббировать включение новых возможностей в сам 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. Имя filename в паре не содержит информации о пути, только имя самого файла. В режиме сухого запуска следует добавить пары, чтобы представить то, что было бы создано.