4. Создание исходного распределения¶

4.1. Указание файлов для распространения¶

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

• все исходные файлы Python, подразумеваемые опциями py_modules и packages

• все исходные файлы C, упомянутые в опциях ext_modules или libraries

• сценарии, идентифицированные опцией scripts См. Установка сценариев.

• все, что похоже на тестовый скрипт: test/test*.py (в настоящее время Distutils не делает ничего с тестовыми скриптами, кроме включения их в дистрибутивы исходников, но в будущем появится стандарт для тестирования дистрибутивов модулей Python)

• Любой из стандартных файлов README (README, README.txt или README.rst), setup.py (или как вы назвали свой установочный скрипт) и 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. Все это делается после стандартного набора include, поэтому вы можете исключить файлы из стандартного набора с помощью явных инструкций в шаблоне манифеста. (Или вы можете использовать опцию --no-defaults, чтобы полностью отключить стандартный набор). Есть несколько других команд, доступных в мини-языке шаблона манифеста; см. раздел Создание исходного дистрибутива: команда sdist.

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

• все файлы в дереве «сборки» Distutils (по умолчанию build/)

• все файлы в каталогах с именами RCS, CVS, .svn, .hg, .git, .bzr или _darcs

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

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

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

1. включить все исходные файлы Python в подкаталогах distutils и distutils/command (поскольку пакеты, соответствующие этим двум каталогам, были упомянуты в опции packages в сценарии установки - см. раздел Написание сценария настройки)

2. include README.txt, setup.py и setup.cfg (стандартные файлы)

3. include 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. Опции, связанные с манифестом¶

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

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

• если файл манифеста не существует или был ранее автоматически создан, прочитайте MANIFEST.in и создайте манифест

• если не существует ни MANIFEST, ни MANIFEST.in, создайте манифест только с набором файлов по умолчанию

• использовать список файлов, находящихся сейчас в MANIFEST (либо только что созданный, либо считанный), для создания архива(ов) исходного дистрибутива

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

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

python setup.py sdist --manifest-only

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