Как опубликовать свою Python библиотеку на PyPI

Трудно представить программу Python без набора операторов import. Но как опубликовать библиотеку, чтобы её также легко могли импортировать другие разработчики?

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

1. Создаём элементы библиотеки

Публикация пакета требует знания некоторых деталей. В этом примере мы будем рассматривать предварительно опубликованный пакет под названием dist_alx. Чтобы вам было удобнее сверяться, эта директория доступна в виде zip-папки в репозитории на GitHub.

Каталог содержит все необходимые элементы, которые должен иметь пакет перед публикацией. Мы будем использовать этот пример в качестве эталона, поскольку все пакеты Python должны иметь одинаковую структуру. Если вам интересно, что именно делает пакет dist_alx, это объяснено там же в README-файле.

Корневой каталог dist_alx содержит следующие файлы и директории:

• setup.py – содержит метаданные пакета,

• setup.cfg – конфигурационный файл, используемый для хранения настроек,

• подпапку с тем же именем, что и родительская папка (в данном примере dist_alx), где хранится фактический код вашего пакета на Python.

Подробнее об указанных файлах можно прочитать в документации библиотеки setuptools. Примеры содержания файлов в нашем случае:

        from setuptools import setup

setup(name='dist_alx',
      version='0.0',
      description='Gaussian and Binomial distributions',
      packages=['dist_alx'],
      author_email='mihajlovic.aleksa@gmail.com',
      zip_safe=False)
    

        [egg_info]
tag_build = 
tag_date = 0

    

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

• Уникальное имя библиотеки. Никакие два существующих пакета Python не могут одинаково называться.
• Файл setup.py должен содержать параметры name и packages. Они также должны иметь то же имя, что и пакет (см. пример выше).
  
• Параметр version: в случае если что-то в пакете изменилось, нужно изменить и значение version.
  
• Файла setup.py должен иметь параметр author_email с адресом электронной почты для связи. Используйте действующий e-mail, это важно для дальнейшей регистрации программы в репозитории PyPI.
  

2. Подготавливаем код

Как указано выше, внутри вложенной папки должен находиться фактический код библиотеки. Если вы откроете подпапку dist_alx, вы увидите, что она содержит файл _init_.py. По умолчанию ядро ​​Python ищет файл _init_.py в качестве отправной точки при чтении кода. Файл _init_.py связан со всеми другими сценариями Python в подпапке. Например, в нашем файле _init_.py, есть строка импорта from .Gaussiandistribution import Gaussian. Все .py-файлы связаны. Хорошей идеей, прежде чем пытаться написать код пакета, будет обновить свои знания о классах Python.

3. Создаём аккаунт PyPI

Большинство общедоступных пакетов Python хранятся в репозитории PyPI. При установке пакета на свой компьютер инструкцией pip, вы фактически скачиваете его из репозитория PyPI. Соответственно для публикации нового пакета его нужно наоборот, загрузить на сервер PyPI. Чтобы опубликовать библиотеку, нужно завести аккаунт (это бесплатно). Адрес электронной почты должен быть тот же, что внутри setup.py в параметре author_email.

4. Публикуем библиотеку

Публикация осуществляется из командной строки или терминала. Команды идентичны в Windows и Linux.

Для публикации нам потребуется установить две библиотеки – setuptools и twine:

        pip install setuptools
    

        pip install twine
    

Переходим к родительскому каталогу.

Развёртываем пакет запустив setup.py:

        python setup.py sdist
    

Обратите внимание, что теперь в родительской папке будут созданы две новых директории (egg-info и dist).

Теперь с помощью twine развёртываем пакет на PyPI:

        twine upload dist/*
    

Здесь нужно указать своё имя пользователя и пароль PyPI.

Вуаля! Пакет размещён на сервере и готов к использованию!

Переходим в учётную запись на PyPI, идём в раздел Your projects. Если всё в порядке, вы увидите библиотеку.

Обратите внимание, что PyPI не поддерживает на сайте символ подчёркивания в именах файлов. Поэтому dist_alx отображается как dist-alx. Однако это не влияет на использование библиотеки – при последующем импорте мы будем вводить, как и задумано, dist_alx.

5. Используем

Переходим к любимому клиенту Python (например, Jupyter) и устанавливаем пакет с помощью pip. Импортируем и пользуемся в своё удовольствие!

Заключение

Прежде чем размещать пакет на главном сервере, опубликуйте его сначала на тестовом сервере PyPI.

Итак, последовательность создания библиотеки Python следующая:

1. Изготовление необходимых элементов упаковки, проверка значений параметров.
2. Подготовка кода пакета.
   
3. Создание учётной записи PyPI (если её ещё не было).
   
4. Публикация пакета на PyPI.
   
5. Тестирование: pip-установка, импорт и запуск модуля.
   

Если вы думаете, что пока не готовы публиковать свою библиотеку, вам могут быть полезны такие наши публикации:

• Погружаемся в основы и нюансы тестирования Python-кода
• Инструменты для анализа кода Python. Часть 1
  
• Инструменты для анализа кода Python. Часть 2
  
• Python: практики для написания эффективного кода