Содержание страницы
Создание исходного дистрибутива¶Creating a Source Distribution
Как показано в разделе Простой пример, для создания дистрибутива исходного кода используется команда sdist. В простейшем случае
python setup.py sdist
(если в сценарии установки или файле конфигурации не указаны параметры sdist), sdist создаёт архив в формате по умолчанию для текущей платформы. Формат по умолчанию – gzip-архив tar (.tar.gz) в Unix и ZIP-файл в Windows.
Можно указать любое количество форматов с помощью параметра --formats, например:
python setup.py sdist --formats=gztar,zip
чтобы создать tar-архив, сжатый gzip, и zip-архив. Доступны следующие форматы:
| Формат | Описание | Примечания |
|---|---|---|
| zip | zip-файл (.zip) | (1),(3) |
| gztar | gzip-архив tar (.tar.gz) | (2),(4) |
| bztar | bzip2-архив tar (.tar.bz2) | (4) |
| ztar | сжатый tar-файл (.tar.Z) | (4) |
| tar | tar-файл (.tar) | (4) |
Примечания:
- по умолчанию на Windows
- по умолчанию на Unix
- требует либо внешнюю утилиту zip, либо модуль zipfile (входит в стандартную библиотеку Python, начиная с Python 1.6)
- требует внешних утилит: tar и, возможно, одной из gzip, bzip2 или compress
Указание файлов для распространения¶Specifying the files to distribute
Если не указан явный список файлов (или инструкции по его генерации), команда sdist помещает в дистрибутив исходного кода минимальный набор по умолчанию:
все файлы исходного кода Python, указанные опциями py_modules и packages
все C-файлы исходного кода, перечисленные в опциях ext_modules или libraries (
** получение исходных кодов библиотеки C в настоящее время не работает – нет get_source_files() метода в build_clib.py! **)
скрипты, задаваемые опцией scripts
всё, что похоже на тестовый сценарий: test/test*.py (в настоящее время Distutils ничего не делает с тестовыми сценариями, кроме включения их в дистрибутивы исходного кода, но в будущем появится стандарт для тестирования дистрибутивов модулей Python)
README.txt (или README), setup.py (или как вы назвали свой сценарий установки) и setup.cfg
Иногда этого достаточно, но обычно требуется указать дополнительные файлы для распространения. Типичный способ – написать шаблон манифеста, по умолчанию называемый MANIFEST.in. Шаблон манифеста представляет собой просто список инструкций для создания файла манифеста MANIFEST, который содержит точный список файлов, включаемых в дистрибутив исходного кода. Команда sdist обрабатывает этот шаблон и генерирует манифест на основе его инструкций и того, что находится в файловой системе.
Если вы предпочитаете создать собственный файл манифеста, формат прост: одно имя файла в строке, только обычные файлы (или символьные ссылки на них). Если вы предоставляете свой MANIFEST, необходимо указать всё: набор файлов по умолчанию, описанный выше, в этом случае не применяется.
Шаблон манифеста содержит одну команду на строку, где каждая команда задаёт набор файлов для включения или исключения из дистрибутива исходного кода. В качестве примера снова обратимся к собственному шаблону манифеста Distutils:
include *.txt
recursive-include examples *.txt *.py
prune examples/sample?/build
The meanings should be fairly clear: include all files in the distribution root matching *.txt, all files anywhere under the examples directory matching *.txt or *.py, and exclude all directories matching examples/sample?/build. All of this is done after the standard include set, so you can exclude files from the standard set with explicit instructions in the manifest template. (Or, you can use the --no-defaults option to disable the standard set entirely.) There are several other commands available in the manifest template mini-language; see section Creating a source distribution: the sdist command.
Порядок команд в шаблоне манифеста важен: изначально имеется список стандартных файлов, описанный выше, и каждая команда в шаблоне добавляет файлы в этот список или удаляет из него. После полной обработки шаблона манифеста удаляются файлы, которые не должны включаться в дистрибутив исходного кода:
- все файлы в дереве «build» Distutils (по умолчанию build/)
- все файлы в каталогах с именами RCS, CVS, .svn, .hg, .git, .bzr или _darcs
Теперь у нас есть полный список файлов, который записывается в манифест для дальнейшего использования, а затем используется для создания архивов дистрибутива исходного кода.
Можно отключить стандартный набор включаемых файлов с помощью параметра --no-defaults, а стандартный набор исключаемых – с помощью --no-prune.
Следуя собственному шаблону манифеста Distutils, проследим, как команда sdist формирует список файлов для включения в дистрибутив исходного кода Distutils:
- включает все файлы исходного кода Python в подкаталогах distutils и distutils/command (поскольку пакеты, соответствующие этим двум каталогам, были указаны в опции packages в скрипте setup – см. раздел Написание скрипта установки)
- включить README.txt, setup.py и setup.cfg (стандартные файлы)
- включить test/test*.py (стандартные файлы)
- включить *.txt в корень дистрибутива (это повторно найдёт README.txt, но такие дубликаты отсеиваются позже)
- включить все файлы, соответствующие *.txt или *.py, в поддереве examples
- exclude all files in the sub-trees starting at directories matching examples/sample?/build–this may exclude files included by the previous two steps, so it’s important that the prune command in the manifest template comes after the recursive-include command
- исключить всё дерево build, а также каталоги RCS, CVS, .svn, .hg, .git, .bzr и _darcs
Как и в скрипте настройки, имена файлов и каталогов в шаблоне манифеста должны всегда разделяться косой чертой; Distutils позаботится о преобразовании их в стандартное представление на вашей платформе. Таким образом, шаблон манифеста переносим между операционными системами.