4. Створення вихідного розповсюдження

Примітка

Цей документ зберігається лише до тих пір, поки документація setuptools за адресою https://setuptools.readthedocs.io/en/latest/setuptools.html окремо не охопить всю відповідну інформацію, яка зараз включена тут.

Як показано в розділі Простий приклад, ви використовуєте команду sdist для створення вихідного дистрибутива. У найпростішому випадку:

python setup.py sdist

(припустимо, що ви не вказали параметри sdist у сценарії встановлення чи файлі конфігурації), sdist створює архів формату за замовчуванням для поточної платформи. Типовим форматом є файл tar у форматі gzip (.tar.gz) в Unix і ZIP-файл у Windows.

Ви можете вказати скільки завгодно форматів за допомогою опції --formats, наприклад:

python setup.py sdist --formats=gztar,zip

щоб створити стиснутий архів і файл zip. Доступні формати:

Формат	Опис	Примітки
zip	zip-файл (.zip)	(1), (3)
gztar	gzip-ований tar-файл (.tar.gz)	(2)
bztar	bzip2-файл tar (.tar.bz2)	(5)
xztar	xz-ваний tar-файл (.tar.xz)	(5)
ztar	стиснутий файл tar (.tar.Z)	(4), (5)
tar	tar-файл (.tar)	(5)

Змінено в версії 3.5: Додано підтримку формату xztar.

Примітки:

1. за замовчуванням у Windows

2. за замовчуванням в Unix

3. вимагає зовнішньої утиліти zip або модуля zipfile (частина стандартної бібліотеки Python, починаючи з Python 1.6)

4. потрібна програма compress. Зверніть увагу, що цей формат зараз очікує на припинення підтримки та буде видалено в наступних версіях Python.

5. deprecated by PEP 527; PyPI only accepts .zip and .tar.gz files.

При використанні будь-якого tar формату (gztar, bztar, xztar, ztar або tar), в Unix ви можете вказати імена owner та group, які будуть встановлені для кожного члена архіву.

Наприклад, якщо ви хочете, щоб усі файли архіву належали root:

python setup.py sdist --owner=root --group=root

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.cfg.

• усі файли, які відповідають метаданим package_data. Перегляньте Встановлення пакетних даних.

• усі файли, які відповідають метаданим data_files. Перегляньте Встановлення додаткових файлів.

Іноді цього достатньо, але зазвичай ви захочете вказати додаткові файли для розповсюдження. Типовий спосіб зробити це — написати шаблон маніфесту, який за замовчуванням називається MANIFEST.in. Шаблон маніфесту — це лише список інструкцій щодо того, як створити файл маніфесту, MANIFEST, який є точним списком файлів, які потрібно включити у вихідний дистрибутив. Команда sdist обробляє цей шаблон і створює маніфест на основі його інструкцій і того, що вона знаходить у файловій системі.

Якщо ви віддаєте перевагу створенню власного файлу маніфесту, формат простий: одна назва файлу на рядок, лише звичайні файли (або символічні посилання на них). Якщо ви надаєте власний MANIFEST, ви повинні вказати все: набір файлів за замовчуванням, описаний вище, у цьому випадку не застосовується.

Змінено в версії 3.1: Існуючий згенерований MANIFEST буде повторно згенерований без sdist порівняння часу його модифікації з часом MANIFEST.in або setup.py.

Змінено в версії 3.1.3: Файли MANIFEST починаються з коментаря, який вказує на те, що вони створені. Файли без цього коментаря не перезаписуються та не видаляються.

Змінено в версії 3.2.2: sdist прочитає файл MANIFEST, якщо не існує MANIFEST.in, як це було раніше.

Змінено в версії 3.7: README.rst тепер включено до списку стандартних файлів README distutils.

У шаблоні маніфесту є одна команда на рядок, де кожна команда визначає набір файлів, які потрібно включити або виключити з вихідного розповсюдження. Для прикладу ми знову звернемося до власного шаблону маніфесту Distutils:

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

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

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

• усі файли в дереві збірок Distutils (за замовчуванням 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 каталоги

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

4.2. Опції, пов’язані з маніфестом

Нормальний хід операцій для команди sdist такий:

• якщо файл маніфесту (MANIFEST за замовчуванням) існує, і перший рядок не має коментаря, який вказує, що він створений з MANIFEST.in, тоді він використовується як є, без змін

• якщо файл маніфесту не існує або був попередньо створений автоматично, прочитайте MANIFEST.in і створіть маніфест

• якщо ані MANIFEST, ані MANIFEST.in не існує, створіть маніфест лише з набором файлів за замовчуванням

• використовуйте список файлів у MANIFEST (щойно створений або прочитаний), щоб створити архів(и) розповсюдження коду

Є кілька варіантів, які змінюють цю поведінку. По-перше, використовуйте --no-defaults і --no-prune, щоб вимкнути стандартні набори «include» і «exclude».

По-друге, ви можете просто захотіти (повторно) створити маніфест, але не створювати вихідний розподіл:

python setup.py sdist --manifest-only

-o — це ярлик для --manifest-only.