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-файл ( |
(1), (3) |
|
gzip-ований tar-файл ( |
(2) |
|
bzip2-файл tar ( |
(5) |
|
xz-ваний tar-файл ( |
(5) |
|
стиснутий файл tar ( |
(4), (5) |
|
tar-файл ( |
(5) |
Змінено в версії 3.5: Додано підтримку формату xztar
.
Примітки:
за замовчуванням у Windows
за замовчуванням в Unix
вимагає зовнішньої утиліти zip або модуля
zipfile
(частина стандартної бібліотеки Python, починаючи з Python 1.6)потрібна програма compress. Зверніть увагу, що цей формат зараз очікує на припинення підтримки та буде видалено в наступних версіях Python.
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:
включити всі вихідні файли Python у підкаталоги
distutils
іdistutils/command
(оскільки пакунки, що відповідають цим двом каталогам, були згадані в параметріpackages
у сценарії встановлення — див. розділ Написання сценарію налаштування)включають
README.txt
,setup.py
іsetup.cfg
(стандартні файли)включає
test/test*.py
(стандартні файли)включити
*.txt
в кореневу папку дистрибутива (це знайдеREADME.txt
вдруге, але такі надмірності будуть видалені пізніше)включити все, що відповідає
*.txt
або*.py
у піддереві підexamples
,виключити всі файли в піддеревах, починаючи з каталогів, що відповідають
examples/sample?/build
—це може виключити файли, включені двома попередніми кроками, тому важливо, щоб командаprune
у шаблон маніфесту йде після командиrecursive-include
виключити все дерево
build
і будь-якіRCS
,CVS
,.svn
,.hg
,.git
,.bzr
і_darcs
каталоги
Так само, як і в сценарії встановлення, імена файлів і каталогів у шаблоні маніфесту завжди мають бути розділені косою рискою; Distutils подбає про перетворення їх у стандартне представлення на вашій платформі. Таким чином, шаблон маніфесту переноситься між операційними системами.