4. Создание дистрибутива исходного кода¶Creating a Source Distribution

4.1. Определение файлов для распространения¶Specifying the files to distribute

Если не указан явный список файлов (или инструкции по его генерации), команда sdist помещает в дистрибутив исходного кода минимальный набор по умолчанию:

• все исходные файлы Python, подразумеваемые параметрами py_modules и packages
• все исходные файлы C, упомянутые в параметрах ext_modules или libraries
• Скрипты, указанные с помощью опции scripts. См. Установка скриптов.
• всё, что похоже на тестовый скрипт: test/test*.py (в настоящее время Distutils ничего не делает с тестовыми скриптами, кроме как включает их в дистрибутивы исходного кода, но в будущем появится стандарт для тестирования дистрибутивов модулей Python)
• README.txt (или README), setup.py (или как бы вы ни назвали свой сценарий setup), и setup.cfg
• все файлы, соответствующие метаданным package_data. См. Установка данных пакета.
• все файлы, соответствующие метаданным data_files. См. Установка дополнительных файлов.

Иногда этого достаточно, но обычно требуется указать дополнительные файлы для распространения. Типичный способ – написать шаблон манифеста, по умолчанию называемый MANIFEST.in. Шаблон манифеста – это просто список инструкций для создания файла манифеста, MANIFEST, который содержит точный перечень файлов, включаемых в дистрибутив исходного кода. Команда sdist обрабатывает этот шаблон и формирует манифест на основе его инструкций и того, что она находит в файловой системе.

Если вы предпочитаете создать собственный файл манифеста, его формат прост: одно имя файла на строку, только обычные файлы (или симлинки на них). Если вы указываете свой собственный MANIFEST, необходимо указать всё: описанный выше стандартный набор файлов в этом случае не применяется.

Шаблон манифеста содержит одну команду на строку, где каждая команда задаёт набор файлов для включения или исключения из дистрибутива исходного кода. В качестве примера снова обратимся к собственному шаблону манифеста Distutils:

include *.txt
recursive-include examples *.txt *.py
prune examples/sample?/build

Значения должны быть довольно очевидны: включить все файлы в корне дистрибутива, соответствующие *.txt, все файлы в любом месте каталога examples, соответствующие *.txt или *.py, и исключить все каталоги, соответствующие examples/sample?/build. Всё это делается после стандартного набора включения, поэтому можно исключить файлы из стандартного набора с помощью явных инструкций в шаблоне манифеста. (Или можно использовать опцию --no-defaults, чтобы полностью отключить стандартный набор.) В мини-языке шаблона манифеста доступны и другие команды; см. раздел Создание дистрибутива исходного кода: команда sdist.

Порядок команд в шаблоне манифеста важен: изначально имеется список стандартных файлов, описанный выше, и каждая команда в шаблоне добавляет файлы в этот список или удаляет из него. После полной обработки шаблона манифеста удаляются файлы, которые не должны включаться в дистрибутив исходного кода:

• все файлы в дереве «build» Distutils (по умолчанию build/)
• все файлы в каталогах с именами RCS, CVS, .svn, .hg, .git, .bzr или _darcs

Теперь у нас есть полный список файлов, который записывается в манифест для дальнейшего использования, а затем используется для создания архивов дистрибутива исходного кода.

Стандартный набор включаемых файлов можно отключить с помощью опции --no-defaults, а стандартный набор исключаемых – с помощью --no-prune.

Следуя собственному шаблону манифеста Distutils, проследим, как команда sdist формирует список файлов для включения в дистрибутив исходного кода Distutils:

1. включить все исходные файлы Python в подкаталогах distutils и distutils/command (поскольку пакеты, соответствующие этим двум каталогам, были указаны в опции packages в скрипте настройки – см. раздел Написание скрипта настройки)
2. включить README.txt, setup.py и setup.cfg (стандартные файлы)
3. включить test/test*.py (стандартные файлы)
4. включить *.txt в корне дистрибутива (это приведёт к повторному обнаружению README.txt, но такие дубликаты будут отсеяны позже)
5. включить всё, соответствующее *.txt или *.py, в поддереве каталога examples,
6. исключить все файлы в поддеревьях, начинающихся с каталогов, соответствующих examples/sample?/build – это может исключить файлы, включённые на двух предыдущих шагах, поэтому важно, чтобы команда prune в шаблоне манифеста располагалась после команды recursive-include
7. исключить всё дерево build, а также любые каталоги RCS, CVS, .svn, .hg, .git, .bzr и _darcs

Как и в скрипте настройки, имена файлов и каталогов в шаблоне манифеста должны всегда разделяться косой чертой; Distutils позаботится о преобразовании их в стандартное представление на вашей платформе. Таким образом, шаблон манифеста переносим между операционными системами.

4.2. Опции, связанные с манифестом¶Manifest-related options

Обычный порядок действий для команды sdist следующий:

• если файл манифеста (по умолчанию MANIFEST) существует и первая строка не содержит комментария, указывающего, что он сгенерирован из MANIFEST.in, то он используется как есть, без изменений
• если файл манифеста не существует или был ранее автоматически сгенерирован, прочитать MANIFEST.in и создать манифест
• если не существует ни MANIFEST, ни MANIFEST.in, создать манифест только с набором стандартных файлов
• Для создания архива(ов) исходного дистрибутива используется список файлов, находящихся в MANIFEST (только что созданных или прочитанных\n)

Есть несколько опций, изменяющих это поведение. Во-первых, используйте\n--no-defaults и --no-prune для отключения стандартных\nнаборов «include» и «exclude».

Во-вторых, можно просто (заново) сгенерировать манифест, но не создавать исходный\nдистрибутив:

python setup.py sdist --manifest-only

-o – это сокращение для --manifest-only.