Пориньте у Python 3/Пакування бібліотек

Ви з'ясуєте що сором - це як біль, його відчуваєш лише раз
Маркіз де Мертеуль, Небезпечні зв'язки

Справжні художники продають. Принаймі так каже Стів Джобс. Хочете випустити скрипт, бібліотеку чи програму? Чудово. Світ потребує більше коду Python. Python 3 розповсюджується разом з фреймворком для створення пакетів який називається Distutils. Distutils це багато речей: інструмент для побудови проекту (для вас), інструмент для встановлення (для ваших користувачів), формат метаданих пакету (для пошукових програм), і багато іншого. Він інтегрується з Python Package Index ("PyPI") - центральним репозиторієм для бібліотек Python з відкритим кодом.

Всі ці грані Distutils зосереджуються навколо скрипта встановлення, який традиційно називається setup.py. Насправді ви вже могли бачити кілька скриптів встановлення Distutils протягом цієї книги. Ви використовували Distutils для того щоб встановити httplib2 в розділі веб-сервіси HTTP а також щоб встановити chardet в розділі Перенесення chardet на Python3.

В цьому розділі ви дізнаєтесь як працює скрипт встановлення для chardet та httplib2, та пройдемо процес випуску власного програмного забезпечення на мові Python.

# chardet's setup.py
from distutils.core import setup
setup(
    name = "chardet",
    packages = ["chardet"],
    version = "1.0.2",
    description = "Universal encoding detector",
    author = "Mark Pilgrim",
    author_email = "mark@diveintomark.org",
    url = "http://chardet.feedparser.org/",
    download_url = "http://chardet.feedparser.org/download/python3-chardet-1.0.1.tgz",
    keywords = ["encoding", "i18n", "xml"],
    classifiers = [
        "Programming Language :: Python",
        "Programming Language :: Python :: 3",
        "Development Status :: 4 - Beta",
        "Environment :: Other Environment",
        "Intended Audience :: Developers",
        "License :: OSI Approved :: GNU Library or Lesser General Public License (LGPL)",
        "Operating System :: OS Independent",
        "Topic :: Software Development :: Libraries :: Python Modules",
        "Topic :: Text Processing :: Linguistic",
        ],
    long_description = """\
Universal character encoding detector
-------------------------------------

Detects
 - ASCII, UTF-8, UTF-16 (2 variants), UTF-32 (4 variants)
 - Big5, GB2312, EUC-TW, HZ-GB-2312, ISO-2022-CN (Traditional and Simplified Chinese)
 - EUC-JP, SHIFT_JIS, ISO-2022-JP (Japanese)
 - EUC-KR, ISO-2022-KR (Korean)
 - KOI8-R, MacCyrillic, IBM855, IBM866, ISO-8859-5, windows-1251 (Cyrillic)
 - ISO-8859-2, windows-1250 (Hungarian)
 - ISO-8859-5, windows-1251 (Bulgarian)
 - windows-1252 (English)
 - ISO-8859-7, windows-1253 (Greek)
 - ISO-8859-8, windows-1255 (Visual and Logical Hebrew)
 - TIS-620 (Thai)

This version requires Python 3 or later; a Python 2 version is available separately.
"""
)

☞ chardet та httplib2 поширюються з відкритим кодом, проте немає вимоги поширювати ваше програмне забезпечення під певною ліцензією. Процес описаний в даному розділі працюватиме для будь-якого програмного забезпечення, незалежно від ліцензії.

* * *

Речі які Distutils не зможе зробити за вас

Випуск вашого пакета мови Python - це гнітючий процес. (Випуск другого трішки легший.) Distutils намагається автоматизувати стільки скільки може, але є деякі речі які ви просто повинні зробити самостійно.

Обрати ліцензію. Це складна тема, насичена політикою та небезпеками. Якщо бажаєте випустити своє програмне забезпечення з відкритим кодом, я скромно дам вам п'ять порад:
1. Не пишіть власну ліцензію.
2. Не пишіть власну ліцензію.
3. Не пишіть власну ліцензію.
4. Це не обов'язково повинна бути GPL, але обов'язково повинна бути GPL-сумісна
5. Не пишіть власну ліцензію.
Класифікуйте своє програмне забезпечення використавши систему класифікації PyPi. Я поясню що це означає пізніше в даному розділі.
Напишіть файл "README". Не пропускайте це. Щонайменше, він повинен давати вашим користувачам огляд того що ваше програмне забезпечення робить, і як його встановити.

* * *

Структура каталогів

Щоб почати пакувати своє програмне забезпечення, потрібно впорядкувати свої файли та каталоги. Каталог з httplib виглядає так:

httplib2/                 ①
|
+--README.txt             ②
|
+--setup.py               ③
|
+--httplib2/              ④
   |
   +--__init__.py
   |
   +--iri2uri.py

① Створіть кореневий каталог що міститиме все решта. Дайте йому таке ж ім'я як ім'я вашого модуля.

② Щоб пристосуватись до користувачів Windows, ваш файл "read me" повинен мати розширення .txt, та використовувати символи повернення каретки в стилі Windows. Тільки тому що ви використовуєте вишуканий текстовий редактор що запускається з командного рядка та має власну мову макросів, не варто робити життя складним для ваших користувачів. (Ваші користувачі використовутимуть "Блокнот". Сумно, але правда). Навіть якщо ви користуєтесь Linux чи Mac OS, ваш сучасний текстовий редактор повинен мати опцію для зберігання текстових файлів з розділювачами рядків в Windows-стилі.

③ Ваш скрипт Distutils повинен називатись setup.py, якщо звісно ви не маєте вагомої причини називати його інакше. Але в вас немає вагомої причини.

④ Якщо ваше програмне забезпечення поміщується в єдиному .py файлі, потрібно помістити його в кореневу директорію разом з файлом "read me" та скриптом встановлення. Але httplib2 - не єдиний файл .py, це багатофайловий модуль. Але це нормально! Просто покладіть в кореневий каталог каталог httplib2, так щоб файл __init__.py містився в каталозі httplib2 який сам міститься в каталозі httplib2. Це не проблема, насправді це навіть спростить ваш процес пакування.

Директорія chardet виглядає дещо по іншому. Як і в httplib2 це багатофайловий модуль, тому всередині каталогу chardet є ще одна директорія chardet. На додачу до файлу README.txt, chardet містить HTML-документацію в каталозі docs/. Директорія docs/ містить кілька .html та .css та піддиректорію images/, з кількома файлами .png та .gif. (Це буде важливо пізніше). Також, для дотримання правил (L)GPL-ліцензованого програмного забезпечення, в окремому файлі що називається COPYING.txt міститься повний текст ліцензії.

chardet/
|
+--COPYING.txt
|
+--setup.py
|
+--README.txt
|
+--docs/
|  |
|  +--index.html
|  |
|  +--usage.html
|  |
|  +--images/ ...
|
+--chardet/
   |
   +--__init__.py
   |
   +--big5freq.py
   |
   +--...

* * *

Написання власного встановлювального скрипта

Скрипт Distutils є Python-скриптом. В теорії, він може все що може Python. На практиці, він повинен робити настільки мало, настільки можливо, в настільки стандартний спосіб наскільки можливо. Встановлювальні скрипти повинні бути нудними. Чим екзотичнішим є ваш процес інсталяції, тим більш екзотичними будуть повідомлення про помилки.

Перший рядок кожного скрипта Distutils завжди однаковий:

from distutils.core import setup

Це імпортує функцію setup(), яка є головною точкою входу в Distutils. 95% всіх скриптів Distutils складаються з виклику функції setup() і нічого більше. (Я просто вигадав статистику, але якщо ваш встановлювальний скрипт робить щось більше ніж викликає функцію setup(), ви повинні мати гарний привід. У вас є гарний привід? Я так не думаю.)

Функція setup може приймати десятки параметрів. Для того щоб ті хто його читатиме не з'їхали з глузду, ви повинні використовувати іменовані аргументи для кожного параметру. Це не звичай, це жорстка вимога. Ваш встановлювальний скрипт поламається якщо ви спробуєте викликати функцію setup() з неіменованими аргументами.

Наступні іменовані аргументи є обов'язковими:

name - назва пакета
version - номер версії пакета
author - ваше ім'я
author_email - адреса вашої електронної поштової скриньки
url - домашня сторінка проекту. Це може бути сторінка пакету на PyPI якщо в вас немає окремого сайту проекту.

Я також рекомендую додати в свій встановлювальний скрипт наступне:

description - однорядковий опис проекту.
long_description - багаторядковий рядок в форматі reStructuredText. PyPI перетворить його в HTML, та відобразить на сторінці пакету.
classifiers - список по особливому відформатованих рядків описаних в наступному розділі.

☞ метадані встановлювального скрипта описуються в PEP 314.

Тепер давайте глянемо на скрипт встановлення chardet. Він має всі обов'язкові і рекомендовані параметри, плюс один який я поки що не згадував: packages.

from distutils.core import setup
setup(
    name = 'chardet',
    packages = ['chardet'],
    version = '1.0.2',
    description = 'Universal encoding detector',
    author='Mark Pilgrim',
    ...
)

Параметр packages показує невдале перевикористання термінів в системі поширення коду. Ми говоримо про пакет як про штуку яку ви створюєте (і потенційно публікуєте в індексі пакетів Python). Але це не те що описує параметр packages. Він стосується того факту що chardet це багатофайловий модуль, часом відомий як... "пакет". Параметр packages каже Distutils включити в пакет директорію chardet/, її файл __init__.py та інші файли .py що складають модуль chardet. Це дещо важливо, так як всі ці веселі розмови про метадані та документацію не мають сенсу якщо ви забудете додати сам код!

* * *

Класифікація вашого пакета

Індекс пакетів Python ("PyPI") містить тисячі бібліотек Python. Правильні метадані класифікації дозволять людям знайти ваш пакет швидше. PyPI дозволяє вам переглядати пакети за класами. Можна навіть вибрати кілька класифікаторів для того щоб звузити пошук. Класифікатори не є невидимими метаданими які ви можете просто проігнорувати!

Щоб класифікувати ваше програмне забезпечення передайте параметр classify у функцію setup(). Цей параметр є списком рядків. Ці рядки не довільні. Всі рядки класифікації повинні братись із цього списку на PyPI.

Класифікатори не обов'язкові. Можна написати скрипт встановлення Distutils без жодних класифікаторів взагалі. Не робіть цього. Ви завжди повинні включати принаймі наступні класифікатори:

Мова програмування. Особливо, ви повинні включати як і "Programming language :: Python" так і "Programming language :: Python :: 3". Якщо ви не включите їх, ваш пакет не буде поміщено в цьому списку бібліотек сумісних з Python 3, на який посилається бічне меню кожної сторінки на pypi.python.org.
Ліцензія. Це найперше на що я дивлюсь оцінюючи сторонню бібліотеку. Не змушуйте мене полювати за цією життєвоважливою інформацією. Не включайте більш ніж один класифікатор ліцензії, якщо ваш код не є явно доступним під кількома ліцензіями одночасно. (І не випускайте програмне забезпечення під кількома ліцензіями, якщо вас не змушують цього робити. І не змушуйте інших людей так робити. Ліцензування це й без того геморой, не робіть його гіршим.)
Операційна система. Якщо ваше програмне забезпечення працює тільки під Windows (чи MacOS чи Linux), мені краще знати про це якомога раніше. Якщо ваше програмне забезпечення повинно працювати всюди і не покладається на який-небудь платформо-залежний код, використайте класифікатор "Operating System :: OS Independent". Кілька класифікаторів Operating System необхідні лише тоді коли ваше програмне забезпечення вимагатиме підтримки для кожної платформи. (Це не типово.)

Також рекомендую додати наступні класифікатори:

Development Status. Ваше програмне забезпечення знаходиться в бета версії? Альфа версії? Гірше за альфу? Виберіть. Будьте чесними.
Intended Audience. Кому варто завантажувати ваше програмне забезпечення? Типовими варіантами є Developers, End Users/Desktop, Science/Research та System Administrators.
Topic. Є купа різних тематик, виберіть ту яка підходить.

Приклади гарних класифікаторів пакетів

Заради прикладу наведу тут класифікатори для Django - готового до використання, кросплатформенного веб-фреймворка ліцензованого під BSD. (Django поки що не сумісний з Python 3, тому класифікатор Programming Language :: Python :: 3 не перелічується.)

Programming Language :: Python
License :: OSI Approved :: BSD License
Operating System :: OS Independent
Development Status :: 5 - Production/Stable
Environment :: Web Environment
Framework :: Django
Intended Audience :: Developers
Topic :: Internet :: WWW/HTTP
Topic :: Internet :: WWW/HTTP :: Dynamic Content
Topic :: Internet :: WWW/HTTP :: WSGI
Topic :: Software Development :: Libraries :: Python Modules

А ось класифікатори для chardet, бібліотека для визначення кодування символів, яка описується в розділі Перенесення chardet на Python 3. chardet це бета-версія, кросплатформенного, сумісного з Python 3, LGPL-ліцензованого, коду для використання розробниками в своїх власних продуктах.

Programming Language :: Python
Programming Language :: Python :: 3
License :: OSI Approved :: GNU Library or Lesser General Public License (LGPL)
Operating System :: OS Independent
Development Status :: 4 - Beta
Environment :: Other Environment
Intended Audience :: Developers
Topic :: Text Processing :: Linguistic
Topic :: Software Development :: Libraries :: Python Modules

А ось класифікатори для httplib2, бібліотеки описаної в розділі Веб-сервіси HTTP. httplib2 це бета-версія кросплатформенної бібліотеки під ліцензією MIT, яка призначена для розробників.

Programming Language :: Python
Programming Language :: Python :: 3
License :: OSI Approved :: MIT License
Operating System :: OS Independent
Development Status :: 4 - Beta
Environment :: Web Environment
Intended Audience :: Developers
Topic :: Internet :: WWW/HTTP
Topic :: Software Development :: Libraries :: Python Modules

Опис додаткових файлів маніфестом

За замовчуванням, Distutils додасть наступні файли до вихідного пакету:

README.txt
setup.py
Файли .py які потрібні багатофайловим модулям переліченим в параметрі packages.
Окремі файли .py перелічені в параметрі py_modules.

Це включить всі файли в проекті httplib2. Але в проекті chardet ми також хочемо включити файл COPYING.txt та ввесь каталог docs/ що містить зображення та файли HTML. Для того щоб сказати Distutils включити ці додаткові файли та директорії коли він створить готовий пакет chardet, вам потрібен файл-маніфест.

Файл-маніфест це текстовий файл що називається MANIFEST.in. Покладіть його в кореневий каталог пакета, поруч з README.txt та setup.py. Файли маніфесту не є скриптами Python, це звичайні текстові файли які містять послідовності "команд" в форматі описаному Distutils. Команди маніфесту дозволяють вам включати чи виключати певні файли та каталоги.

Це ввесь маніфест для проекту chardet:

include COPYING.txt
recursive-include docs *.html *.css *.png *.gif

Перший рядок самозрозумілий: включити файл COPYING.txt з кореневого каталогу.

Другий рядок дещо складніший. Команда recursive-include приймає ім'я каталогу та одне чи більше імен файлів. Імена файлів не обмежуються іменами конкретних файлів, це можуть бути шаблони. Цей рядок означає "Бачиш каталог docs/ в корені проекту? Переглянь його (рекурсивно) на наявність файлів .html, .css, .png та .gif. Я хочу щоб вони всі попали в кінцевий пакет".

Всі команди маніфесту зберігають структуру каталогів яку ви створили всередині проекту. Команда recursive-include не буде копіювати всі файли .html та .png в одну купу всередині одного каталогу в пакеті. Вона збереже існуюче всередині docs/ дерево каталогів, просто скопіює лише ті файли, які відповідають іменам переліченим у переданих параметрах. (Я цього раніше не згадував, але документація до chardet насправді написана в XML та перетворюється в HTML окремим скриптом. Я не хочу включати файли XML у вміст пакету, лише результуючий HTML та зображення.

☞ Файли маніфести мають свій власний формат. Дивіться Specifying the files to distribute та the manifest template commands для деталей.

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

Перевірка вашого скрипта встановлення на помилки

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

c:\Users\pilgrim\chardet> c:\python31\python.exe setup.py check
running check
warning: check: missing required meta-data: version

Як тільки ви додасте параметр version (і всі інші потрібні частини метаданих), команда check працюватиме так:

c:\Users\pilgrim\chardet> c:\python31\python.exe setup.py check
running check

* * *

Створення дистрибутиву з кодом

Distutils підтримують побудову різних типів вихідних пакетів. Як мінімум ви повинні побудувати "дистрибутив з кодом" який міститиме ваш код, ваш скрипт встановлення, ваш файл "read me", і будь-які додаткові файли які ви захочете включити. Для того щоб створити дистрибутив з кодом передайте команду sdist у ваш скрипт встановлення Distutils.

c:\Users\pilgrim\chardet> c:\python31\python.exe setup.py sdist
running sdist
running check
reading manifest template 'MANIFEST.in'
writing manifest file 'MANIFEST'
creating chardet-1.0.2
creating chardet-1.0.2\chardet
creating chardet-1.0.2\docs
creating chardet-1.0.2\docs\images
copying files to chardet-1.0.2...
copying COPYING -> chardet-1.0.2
copying README.txt -> chardet-1.0.2
copying setup.py -> chardet-1.0.2
copying chardet\__init__.py -> chardet-1.0.2\chardet
copying chardet\big5freq.py -> chardet-1.0.2\chardet
...
copying chardet\universaldetector.py -> chardet-1.0.2\chardet
copying chardet\utf8prober.py -> chardet-1.0.2\chardet
copying docs\faq.html -> chardet-1.0.2\docs
copying docs\history.html -> chardet-1.0.2\docs
copying docs\how-it-works.html -> chardet-1.0.2\docs
copying docs\index.html -> chardet-1.0.2\docs
copying docs\license.html -> chardet-1.0.2\docs
copying docs\supported-encodings.html -> chardet-1.0.2\docs
copying docs\usage.html -> chardet-1.0.2\docs
copying docs\images\caution.png -> chardet-1.0.2\docs\images
copying docs\images\important.png -> chardet-1.0.2\docs\images
copying docs\images\note.png -> chardet-1.0.2\docs\images
copying docs\images\permalink.gif -> chardet-1.0.2\docs\images
copying docs\images\tip.png -> chardet-1.0.2\docs\images
copying docs\images\warning.png -> chardet-1.0.2\docs\images
creating dist
creating 'dist\chardet-1.0.2.zip' and
adding 'chardet-1.0.2' to it
adding 'chardet-1.0.2\COPYING'
adding 'chardet-1.0.2\PKG-INFO'
adding 'chardet-1.0.2\README.txt'
adding 'chardet-1.0.2\setup.py'
adding 'chardet-1.0.2\chardet\big5freq.py'
adding 'chardet-1.0.2\chardet\big5prober.py' ...
adding 'chardet-1.0.2\chardet\universaldetector.py'
adding 'chardet-1.0.2\chardet\utf8prober.py'
adding 'chardet-1.0.2\chardet\__init__.py'
adding 'chardet-1.0.2\docs\faq.html'
adding 'chardet-1.0.2\docs\history.html'
adding 'chardet-1.0.2\docs\how-it-works.html'
adding 'chardet-1.0.2\docs\index.html'
adding 'chardet-1.0.2\docs\license.html'
adding 'chardet-1.0.2\docs\supported-encodings.html'
adding 'chardet-1.0.2\docs\usage.html'
adding 'chardet-1.0.2\docs\images\caution.png'
adding 'chardet-1.0.2\docs\images\important.png'
adding 'chardet-1.0.2\docs\images\note.png'
adding 'chardet-1.0.2\docs\images\permalink.gif'
adding 'chardet-1.0.2\docs\images\tip.png'
adding 'chardet-1.0.2\docs\images\warning.png'
removing 'chardet-1.0.2' (and everything under it)

Кілька речей які потрібно зауважити:

Distutils побачили маніфест (MANIFEST.in).
Distutils успішно прочитали маніфест і додали файли які ми хотіли: COPYING.txt та HTML і картинки з каталогу docs/.
Якщо ви подивитесь в каталог свого проекту ви побачите що Distutils створила директорію dist/. Всередині dist/ знаходиться .zip-файл який ви можете розповсюджувати.

* * *

Створення графічного інсталятора

На мою думку, кожна бібліотека мови Python заслуговує на графічний інсталятор для користувачів Windows. Його просто зробити (навіть якщо ви самі не використовуєте Windows), і користувачі Windows це цінуватимуть.

Distutils можуть створити графічний інсталятор для вас, якщо їм передати команду bdist_wininst через скрипт setup.py.

c:\Users\pilgrim\chardet> c:\python31\python.exe setup.py bdist_wininst
running bdist_wininst
running build
running build_py
creating build
creating build\lib
creating build\lib\chardet
copying chardet\big5freq.py -> build\lib\chardet
copying chardet\big5prober.py -> build\lib\chardet
...
copying chardet\universaldetector.py -> build\lib\chardet
copying chardet\utf8prober.py -> build\lib\chardet
copying chardet\__init__.py -> build\lib\chardet
installing to build\bdist.win32\wininst
running install_lib
creating build\bdist.win32
creating build\bdist.win32\wininst
creating build\bdist.win32\wininst\PURELIB
creating build\bdist.win32\wininst\PURELIB\chardet
copying build\lib\chardet\big5freq.py -> build\bdist.win32\wininst\PURELIB\chardet
copying build\lib\chardet\big5prober.py -> build\bdist.win32\wininst\PURELIB\chardet
...
copying build\lib\chardet\universaldetector.py -> build\bdist.win32\wininst\PURELIB\chardet
copying build\lib\chardet\utf8prober.py -> build\bdist.win32\wininst\PURELIB\chardet
copying build\lib\chardet\__init__.py -> build\bdist.win32\wininst\PURELIB\chardet
running install_egg_info
Writing build\bdist.win32\wininst\PURELIB\chardet-1.0.2-py3.1.egg-info
creating 'c:\users\pilgrim\appdata\local\temp\tmp2f4h7e.zip' and adding '.' to it
adding 'PURELIB\chardet-1.0.2-py3.1.egg-info'
adding 'PURELIB\chardet\big5freq.py'
adding 'PURELIB\chardet\big5prober.py'
...
adding 'PURELIB\chardet\universaldetector.py'
adding 'PURELIB\chardet\utf8prober.py'
adding 'PURELIB\chardet\__init__.py'
removing 'build\bdist.win32\wininst' (and everything under it)

Побудова самовстановлювальних пакетів для інших операційних систем

Distutils можуть допомогти побудувати встановлювальні пакети для користувачів Linux. На мою думку, це напевне не варто вашого часу. Якщо ви хочете щоб ваше програмне забезпечення поширювалось на Linux, краще використати ваш час працюючи з членами спільноти яка спеціалізується в пакуванні програмного забезпечення для основних дистрибутивів Linux.

Наприклад, моя бібліотека chardet присутня в репозиторіях Debian GNU/Linux (а тому і в репозиторіях Ubuntu також). Я ніяк з цим не пов'язаний, одного дня ці пакети там просто лише з'явились. Спільнота Debian має власні правила для пакування бібліотек Python, і пакет python-chardet зроблений у відповідності до цих правил. А так як пакет знаходиться в репозиторіях Debian, користувачі цього дистрибутиву будуть отримувати оновлення безпеки та нові версії залежно від обраних ними налаштувань системи.

Пакети Linux які створюються за допомогою Distutils не мають таких переваг. Краще витратити свій час де-інде.

* * *

Додавання вашого програмного забезпечення до Python Package Index

Завантаження програмного забезпечення в Python Package Index це трикроковий процес.

Зареєструйтесь самі.
Зареєструйте своє програмне забезпечення.
Завантажте пакет який ви створили з setup.py sdist та setup.py bdist_*.

Для того щоб зареєструватись, перейдіть на сторінку реєстрації PyPI. Введіть обраний логін та пароль, надайте дійсну адресу email, і натисніть кнопку Register. (Якщо в вас є ключ PGP чи GPG, можете також надати їх. Якщо ви їх не маєте, чи не знаєте що це означає, не переживайте). Перевірте свій email, через кілька хвилин ви повинні отримати повідомлення від PyPI з посиланням для підтвердження. Натисніть посилання для того щоб завершити процес реєстрації.

Тепер потрібно зареєструвати своє програмне забезпечення і завантажити його на PyPI. Це все можна зробити за один крок.

c:\Users\pilgrim\chardet> c:\python31\python.exe setup.py register sdist bdist_wininst upload ①
running register
We need to know who you are, so please choose either:
1. use your existing login,
2. register as a new user,
3. have the server generate a new password for you (and email it to you), or
4. quit
Your selection [default 1]: 1 ②
Username: MarkPilgrim ③
Password:
Registering chardet to http://pypi.python.org/pypi ④
Server response (200): OK
running sdist ⑤
... вивід обрізаний ...
running bdist_wininst ⑥
... output trimmed for brevity ...
running upload ⑦
Submitting dist\chardet-1.0.2.zip to http://pypi.python.org/pypi
Server response (200): OK
Submitting dist\chardet-1.0.2.win32.exe to http://pypi.python.org/pypi
Server response (200):
OK I can store your PyPI login so future submissions will be faster.
(the login will be stored in c:\home\.pypirc)
Save your login (y/N)?n ⑧

① Коли ви вперше випускаєте свій проект, Distutils додасть ваше програмне забезпечення до індексу пакетів, і дасть йому власне URL. Щоразу після цього, він просто оновлюватиме метадані проекту з будь-якими змінами що ви зробите в параметрах у setup.py. Потім він створює дистрибутив з кодом (sdist) та інсталятор для Windows (bdist_wininst), після чого завантажує їх до PyPI (upload).

② Натисніть 1, чи просто натисність ENTER щоб вибрати "використати існуючий логін".

③ Введіть логін і пароль який ви вибрати на сторінці регістрації PyPI. Distutils не буде виводити ваш пароль, і навіть не буде виводити зірочки замість символів. Просто введіть пароль і натисніть Enter.

④ Distutils зареєструє ваш пакет у Python Package Index

⑤ ... збудує дистрибутив з кодом ...

⑥ ... а також інсталятор для Windows ...

⑦ ... та завантажить їх обох в індекс пакетів Python ...

⑧ якщо ви хочете автоматизувати процес випуску нових версій, потрібно зберегти свій логін та пароль до PyPI в локальному файлі. Це дуже небезпечно, і зовсім необов'язково.

Вітання, тепер у вас є власна сторінка на Python Package Index! Адреса має вигляд http://pypi.python.org/pypi/NAME, де NAME - рядок який ви передали в параметр name у вашому файлі setup.py.

Якщо ви хочете випустити нову версію, просто оновіть номер версії в setup.py і знову запустіть команду завантаження:

c:\Users\pilgrim\chardet> c:\python31\python.exe setup.py register sdist bdist_wininst upload

* * *

Різні варіанти майбутнього системи пакетів Python

Distutils це не останнє і не все що є у світі керування пакетами в Python, але на час написання цього (Серпень 2009), це єдиний фреймворк пакетів який працює з Python 3. Існує кілька інших фреймворків для Python 2; деякі фокусуються на інсталяції, інші на тестуванні і розгортанні. Деякі з них можливо будуть перенесеними на Python 3 в майбутньому.

Ось ці фреймворки фокусуються на інсталяції:

А ці фокусуються на тестуванні та розгортанні:

Для подальшого читання

PEP 370: Per user site-packages directory

Про Pip та Virtualenv
The Hitchhiker’s Guide to Packaging - здається все що потрібно знати

← Приклад: Перенесення chardet на Python 3 · Імена магічних методів →