sourcedist.md

1> **Источник:** https://python-all.ru/3.4/distutils/sourcedist.html2>3> «Документация Python на русском» – неофициальный перевод официальной документации Python: версии от 2.6 до 3.16, полнотекстовый поиск, английский оригинал рядом с переводом. Эта Markdown-версия страницы предназначена для работы с LLM: вставьте её в ChatGPT, Claude или Cursor.45---67# 4. Создание дистрибутива исходного кода89Как показано в разделе [*Простой пример*](https://python-all.ru/3.4/distutils/introduction.html#distutils-simple-example), для создания дистрибутива исходного кода используется команда **sdist**. В простейшем случае1011```python12python setup.py sdist13```1415(если в сценарии установки или файле конфигурации не указаны **параметры sdist**), **sdist** создаёт архив в формате по умолчанию для текущей платформы. Формат по умолчанию – gzip-архив tar (`.tar.gz`) в Unix и ZIP-файл в Windows.1617Можно указать любое количество форматов с помощью параметра *--formats*, например:1819```python20python setup.py sdist --formats=gztar,zip21```2223чтобы создать tar-архив, сжатый gzip, и zip-архив. Доступны следующие форматы:2425| Формат | Описание | Примечания |26| --- | --- | --- |27| `zip` | ZIP-файл (`.zip`) | (1),(3) |28| `gztar` | gzip-архив tar (`.tar.gz`) | (2) |29| `bztar` | bzip2-архив tar (`.tar.bz2`) |  |30| `ztar` | сжатый tar-архив (`.tar.Z`) | (4) |31| `tar` | tar-файл (`.tar`) |  |3233Примечания:34351. по умолчанию на Windows362. по умолчанию на Unix373. требует внешнюю утилиту **zip** или модуль [`zipfile`](https://python-all.ru/3.4/library/zipfile.html#module-zipfile) (часть стандартной библиотеки Python начиная с Python 1.6)384. требуется программа **compress**. Обратите внимание, что этот формат теперь ожидает устаревания и будет удалён в будущих версиях Python.3940При использовании любого формата `tar` (`gztar`, `bztar`, `ztar` или `tar`) в Unix можно указать имена `владельца` и `группы`, которые будут установлены для каждого элемента архива.4142Например, чтобы все файлы архива принадлежали пользователю root:4344```python45python setup.py sdist --owner=root --group=root46```4748## 4.1. Определение файлов для распространения4950Если не указан явный список файлов (или инструкции по его генерации), команда **sdist** помещает в дистрибутив исходного кода минимальный набор по умолчанию:5152- все исходные файлы Python, подразумеваемые параметрами `py_modules` и `packages`53- все исходные файлы C, упомянутые в параметрах `ext_modules` или `libraries`54- сценарии, указанные параметром `scripts`. См. [*Установка сценариев*](https://python-all.ru/3.4/distutils/setupscript.html#distutils-installing-scripts).55- всё, что похоже на тестовый сценарий: `test/test*.py` (в настоящее время Distutils ничего не делает с тестовыми сценариями, кроме включения их в дистрибутивы исходного кода, но в будущем появится стандарт для тестирования дистрибутивов модулей Python)56- `README.txt` (или `README`), `setup.py` (или как вы назвали свой сценарий установки) и `setup.cfg`57- все файлы, соответствующие метаданным `package_data`. См. [*Установка данных пакета*](https://python-all.ru/3.4/distutils/setupscript.html#distutils-installing-package-data).58- все файлы, соответствующие метаданным `data_files`. См. [*Установка дополнительных файлов*](https://python-all.ru/3.4/distutils/setupscript.html#distutils-additional-files).5960Иногда этого достаточно, но обычно требуется указать дополнительные файлы для распространения. Типичный способ – написать *шаблон манифеста*, по умолчанию называемый `MANIFEST.in`. Шаблон манифеста представляет собой просто список инструкций для создания файла манифеста `MANIFEST`, который содержит точный список файлов, включаемых в дистрибутив исходного кода. Команда **sdist** обрабатывает этот шаблон и генерирует манифест на основе его инструкций и того, что находится в файловой системе.6162Если вы предпочитаете создать собственный файл манифеста, формат прост: одно имя файла в строке, только обычные файлы (или символьные ссылки на них). Если вы предоставляете свой `MANIFEST`, необходимо указать всё: набор файлов по умолчанию, описанный выше, в этом случае не применяется.6364Изменено в версии 3.1: Существующий сгенерированный `MANIFEST` будет перегенерирован без **sdist**, сравнивающего время его изменения с временем изменения `MANIFEST.in` или `setup.py`.6566Изменено в версии 3.1.3: Файлы `MANIFEST` начинаются с комментария, указывающего, что они сгенерированы. Файлы без этого комментария не перезаписываются и не удаляются.6768Изменено в версии 3.2.2: **sdist** будет читать файл `MANIFEST`, если не существует `MANIFEST.in`, как это было раньше.6970Шаблон манифеста содержит одну команду на строку, где каждая команда задаёт набор файлов для включения или исключения из дистрибутива исходного кода. В качестве примера снова обратимся к собственному шаблону манифеста Distutils:7172```python73include *.txt74recursive-include examples *.txt *.py75prune examples/sample?/build76```7778The 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*](https://python-all.ru/3.4/distutils/commandref.html#sdist-cmd).7980Порядок команд в шаблоне манифеста важен: изначально имеется список стандартных файлов, описанный выше, и каждая команда в шаблоне добавляет файлы в этот список или удаляет из него. После полной обработки шаблона манифеста удаляются файлы, которые не должны включаться в дистрибутив исходного кода:8182- все файлы в дереве «build» Distutils (по умолчанию `build/`)83- все файлы в каталогах с именами `RCS`, `CVS`, `.svn`, `.hg`, `.git`, `.bzr` или `_darcs`8485Теперь у нас есть полный список файлов, который записывается в манифест для дальнейшего использования, а затем используется для создания архивов дистрибутива исходного кода.8687Можно отключить стандартный набор включаемых файлов с помощью параметра *--no-defaults*, а стандартный набор исключаемых – с помощью *--no-prune*.8889Следуя собственному шаблону манифеста Distutils, проследим, как команда **sdist** формирует список файлов для включения в дистрибутив исходного кода Distutils:90911. включить все исходные файлы Python в подкаталогах `distutils` и `distutils/command` (поскольку пакеты, соответствующие этим двум каталогам, были указаны в параметре `packages` в сценарии установки – см. раздел [*Написание сценария установки*](https://python-all.ru/3.4/distutils/setupscript.html#setup-script))922. включить `README.txt`, `setup.py` и `setup.cfg` (стандартные файлы)933. включить `test/test*.py` (стандартные файлы)944. включить `*.txt` в корень дистрибутива (это повторно найдёт `README.txt`, но такие дубликаты отсеиваются позже)955. включить все файлы, соответствующие `*.txt` или `*.py`, в поддереве `examples`966. 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` command977. исключить всё дерево `build`, а также каталоги `RCS`, `CVS`, `.svn`, `.hg`, `.git`, `.bzr` и `_darcs`9899Как и в скрипте настройки, имена файлов и каталогов в шаблоне манифеста должны всегда разделяться косой чертой; Distutils позаботится о преобразовании их в стандартное представление на вашей платформе. Таким образом, шаблон манифеста переносим между операционными системами.100101## 4.2. Опции, связанные с манифестом102103Обычный порядок действий для команды **sdist** следующий:104105- если файл манифеста (по умолчанию `MANIFEST`) существует и первая строка не содержит комментария, указывающего, что он сгенерирован из `MANIFEST.in`, то он используется как есть, без изменений106- если файл манифеста не существует или был ранее автоматически сгенерирован, прочитать `MANIFEST.in` и создать манифест107- если не существует ни `MANIFEST`, ни `MANIFEST.in`, создать манифест только с набором файлов по умолчанию108- использовать список файлов, находящийся в `MANIFEST` (только что сгенерированный или прочитанный), для создания архива(ов) исходного дистрибутива109110Есть несколько параметров, изменяющих это поведение. Во-первых, используйте *--no-defaults* и *--no-prune*, чтобы отключить стандартные наборы «include» и «exclude».111112Во-вторых, можно просто (заново) сгенерировать манифест, но не создавать исходный\\nдистрибутив:113114```python115python setup.py sdist --manifest-only116```117118*-o* – это сокращение для *--manifest-only*.119