Создание дистрибутива исходного кода

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

Так же, как и в скрипте setup, имена файлов и каталогов в шаблоне манифеста всегда должны быть разделены слешами; 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.