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

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

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

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

• все исходные файлы на языке Си, указанные в параметрах ext_modules или libraries

• сценарии, указанные с помощью параметра scripts, см. в разделе Установка скриптов.

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

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

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

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

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

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

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

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

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

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

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.