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

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.