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 подбає про перетворення їх у стандартне представлення на вашій платформі. Таким чином, шаблон маніфесту переноситься між операційними системами.