Создание распределения исходных кодов

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, по умолчанию называемого MANIFEST.in. Шаблон manifest – это просто список инструкций по генерации файла manifest, MANIFEST, который содержит точный список файлов для включения в распределение исходных кодов. Команда sdist обрабатывает этот шаблон и генерирует manifest на основе его инструкций и того, что находит в файловой системе.

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

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

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

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

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

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

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

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

Следуя собственной структуре manifest 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 в шаблоне manifest шла после команды recursive-include
7. исключить всё дерево build, а также любые каталоги RCS, CVS, .svn, .hg, .git, .bzr и _darcs

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

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.