6. Индекс пакетов Python (PyPI)¶The Python Package Index (PyPI)

6.1. Регистрация пакетов¶Registering Packages

Команда distutils register используется для отправки метаданных вашего дистрибутива в индекс. Она вызывается следующим образом:

python setup.py register

Distutils ответит следующим приглашением:

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]:

Примечание: если ваши имя пользователя и пароль сохранены локально, это меню отображаться не будет.

Если вы ещё не зарегистрированы в PyPI, вам необходимо сделать это сейчас. Следует выбрать вариант 2 и ввести свои данные по запросу. Вскоре после отправки данных вы получите электронное письмо, которое будет использовано для подтверждения регистрации.

После регистрации вы можете выбрать вариант 1 из меню. Вас попросят ввести имя пользователя и пароль PyPI, а затем register отправит ваши метаданные в индекс.

Вы можете отправить любое количество версий вашего дистрибутива в индекс. Если вы измените метаданные для определённой версии, вы можете отправить их снова, и индекс будет обновлён.

PyPI хранит запись для каждой отправленной комбинации (имя, версия). Первый пользователь, отправивший информацию для данного имени, назначается Владельцем этого имени. Он может вносить изменения через команду register или через веб-интерфейс. Он также может назначать других пользователей Владельцами или Сопровождающими. Сопровождающие могут редактировать информацию о пакете, но не назначать других Владельцев или Сопровождающих.

По умолчанию PyPI отображает только самую новую версию данного пакета. Веб-интерфейс позволяет изменить это поведение по умолчанию и вручную выбрать, какие версии отображать, а какие скрывать.

6.2. Загрузка пакетов¶Uploading Packages

Команда distutils upload отправляет файлы дистрибутивов в PyPI.

Команда вызывается сразу после сборки одного или нескольких файлов дистрибутивов. Например, команда

python setup.py sdist bdist_wininst upload

вызовет загрузку исходного дистрибутива и установщика для Windows на PyPI. Обратите внимание, что они будут загружены, даже если были собраны при предыдущем вызове setup.py, но загружаются только те дистрибутивы, которые указаны в командной строке вызова, включающего команду upload.

Команда upload использует имя пользователя, пароль и URL репозитория из файла $HOME/.pypirc (см. раздел Файл .pypirc для получения дополнительной информации об этом файле). Если команда register ранее вызывалась в той же команде, и пароль был введён в приглашении, upload повторно использует введённый пароль. Это полезно, если вы не хотите хранить пароль в открытом виде в файле $HOME/.pypirc.

Можно указать другой сервер PyPI с помощью опции --repository=url:

python setup.py sdist bdist_wininst upload -r http://example.com/pypi

См. раздел Файл .pypirc для получения дополнительной информации об определении нескольких серверов.

Можно использовать опцию --sign, чтобы указать upload подписывать каждый загружаемый файл с помощью GPG (GNU Privacy Guard). Программа gpg должна быть доступна для выполнения в системе PATH. Также можно указать, какой ключ использовать для подписи, с помощью опции --identity=name.

Другие опции upload включают --repository=url или --repository=section, где url – это URL сервера, а section – имя раздела в $HOME/.pypirc, и --show-response (которая отображает полный текст ответа от сервера PyPI для помощи в отладке проблем с загрузкой).

6.3. Файл .pypirc¶The .pypirc file

Формат файла .pypirc следующий:

[distutils]
index-servers =
    pypi

[pypi]
repository: <repository-url>
username: <username>
password: <password>

Раздел distutils определяет переменную index-servers, которая перечисляет имена всех разделов, описывающих репозиторий.

Каждый раздел, описывающий репозиторий, задаёт три переменные:

• repository – задаёт URL сервера PyPI. По умолчанию

  http://www.python.org/pypi.

• username – зарегистрированное имя пользователя на сервере PyPI.

• password – пароль для аутентификации. Если опущен, пользователю

  будет предложено ввести его при необходимости.

Если требуется определить другой сервер, можно создать новый раздел и указать его в переменной index-servers:

[distutils]
index-servers =
    pypi
    other

[pypi]
repository: <repository-url>
username: <username>
password: <password>

[other]
repository: http://example.com/pypi
username: <username>
password: <password>

Затем register можно вызвать с опцией -r, чтобы указать репозиторий для работы:

python setup.py register -r http://example.com/pypi

Для удобства также можно использовать имя раздела, описывающего репозиторий:

python setup.py register -r other

6.4. Отображение пакетов PyPI¶PyPI package display

Поле long_description играет особую роль на PyPI. Оно используется сервером для отображения домашней страницы зарегистрированного пакета.

Если для этого поля используется синтаксис reStructuredText, PyPI разберёт его и отобразит домашнюю страницу пакета в формате HTML.

Поле long_description можно прикрепить к текстовому файлу, расположенному в пакете:

from distutils.core import setup

with open('README.txt') as file:
    long_description = file.read()

setup(name='Distutils',
      long_description=long_description)

В этом случае README.txt – это обычный текстовый файл reStructuredText, расположенный в корне пакета рядом с setup.py.

Чтобы предотвратить регистрацию некорректного содержимого reStructuredText, можно использовать программу rst2html, предоставляемую пакетом docutils, и проверить long_description из командной строки:

$ python setup.py --long-description | rst2html.py > output.html

docutils выдаст предупреждение, если с синтаксисом что-то не так. Поскольку PyPI применяет дополнительные проверки (например, передавая --no-raw в rst2html.py в приведённой выше команде), возможность выполнить команду без предупреждений не гарантирует, что PyPI успешно преобразует содержимое.