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

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 в корне дистрибутива (это найдёт README.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.