Создание простого пакета Python

Блог Christopher Flynn (flynn.gg) от 27-06-2017

Оригинал статьи здесь.

Создание простого пакета Python

Я зарегистрировался на GitHub после получения степени доктора философии в 2016 году. Одним из первых репозиториев, которые я создал, был перенос части моего кода MATLAB для генерации реализаций дробного броуновского движения на python. По сути, это был просто README.md со ссылкой на источники используемых алгоритмов и единственный файл с именем fbm.py.

Несколько месяцев назад я заметил, что репозиторий набрал несколько звезд и клонируется пару раз в неделю. Я подумал, что если люди будут заинтересованы в этом коде, я должен попытаться реорганизовать его и создать реальный пакет python, который любой мог бы загрузить и реализовать с помощью pip. Вот что я сделал. Пакет называется fbm и доступен на pypi.

Я пройдусь по шагам, которые сделал здесь. После рефакторинга кода и добавления некоторых полезных функций структура каталогов пакета выглядела следующим образом. Единый модуль с небольшим набором юнит-тестов в папке tests.

packagename/
    packagename/
        __init__.py
        packagename.py
    tests/
        packagename_tests.py
    requirements.txt
    README.rst
    .gitignore

setup.py

Первым шагом является создание файла с именем setup.py в каталоге верхнего уровня проекта, который импортирует функцию настройки из модуля setuptools. Пакет setuptools всегда следует использовать в пользу distutils.

from setuptools import setup


def readme():
    with open('README.rst') as f:
        return f.read()

setup(name='packagename',
      version='0.1.0',
      description='A simple module',
      long_description=readme(),
      license='MIT',
      author='author name',
      author_email='[e-mail]',
      url='github_url',
      packages=['packagename'],
      zip_safe=False,
)

Это минимум setup.py. Несколько примечаний:

• name - должно быть имя пакета, которое еще не занято. Вы можете легко выполнить поиск в pypi, чтобы узнать, занято ли желаемое имя пакета.

• version - следует выбирать на основе руководства [Semantic Versioning] (Семантическое управление версиями). Это не обязательно, но это хорошая практика.

• description - должно быть несколько слов, описывающих пакет.

• long_description - можно более подробное описание. В этом примере вы можете видеть, что мы читаем файл README.rst. Обратите внимание, что pypi обработает файлы rst (ReStructuredText) и импортирует его на страницу, созданную для пакета.

• license - это лицензия, которую вы хотите использовать для своего программного обеспечения. Если вы не уверены, вам следует обратиться к selectalicense.

• author_name - это ваше имя.

• author_email - это ваш емэйл (необходимо указать, если вы укажете свое имя).

• url - ссылка на ваш проект. Я использовал URL-адрес репозитория.

• packages - вы можете получить список пакетов вручную или использовать функцию find_packages из setuptools.

• zip_safe - смотрите здесь. Если вы не уверены, установите значение False.

Здесь вы можете указать ряд дополнительных аргументов. Вы должны использовать install_requires, если ваш пакет имеет какие-либо зависимости от других пакетов. Если вы хотите включить README, LICENSE или другие файлы, отличные от Python, вам также следует использовать аргумент include_package_data как True. Вы также можете использовать аргумент classifiers, чтобы указать категориальные теги для вашего пакета.

Если include_package_data имеет значение True, вам нужно будет создать файл MANIFEST.in на верхнем уровне вашего проекта. Внутри файла вы захотите включить в пакет любые дополнительные релевантные файлы, например:

include README.rst
include LICENSE.txt

Вы также захотите изменить файл .gitignore, чтобы игнорировать некоторые файлы, которые будут созданы при сборке пакета. Вот как выглядит мой файл игнорирования. Файл .env предназначен для работы в виртуальной среде. Файл .tox предназначен для пакета tox, который автоматизирует тестирование на основе виртуального окружения.

# Скомпилированные модули python.
*.pyc
# Папка с дистрибутивом Setuptools.
/dist/
# Метаданные egg Python, восстановленные из исходных файлов с помощью setuptools.
/*.egg-info
# файл Python virtualenv .env
.env
# tox тестирование
.tox/
# упаковка
MANIFEST
build/

Собранный вместе каталог вашего пакета может выглядеть примерно так.

packagename/
    packagename/
        __init__.py
        packagename.py
    tests/
        packagename_tests.py
    requirements.txt
    README.rst
    LICENSE.txt
    MANIFEST.in
    setup.py
    .gitignore

Создание раздачи

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

python setup.py sdist

Если ваш проект представляет собой чистый Python, вы можете создать универсальный дистрибутив wheel.

python setup.py bdist_wheel

Обе эти команды создадут файлы .tar.gz и .whl соответственно в папке dist/.

Загрузка в PyPI

Чтобы получить пакет на pypi, вам необходимо зарегистрировать аккаунт. Вы должны создать учетную запись на pypi и testpypi, что позволит вам протестировать свою загрузку, прежде чем размещать настоящую вещь на pypi. Вам также следует установить пакет twine с помощью команды pip install twine.

Затем вы должны создать и открыть файл ~/.pypirc в текстовом редакторе. Это должно выглядеть так, если ваши учетные данные pypi и testpypi записаны на:

[distutils]
index-servers =
    pypi
    testpypi

[pypi]
repository=https://pypi.python.org/pypi
username=pypi_username
password=pypi_password

[testpypi]
repository=https://test.pypi.org/legacy/
username=testpypi_username
password=testpypi_password

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

Мы будем использовать testpypi для тестирования загрузки нашего пакета. Сначала нам нужно зарегистрироваться на тестовом сервере. Чтобы зарегистрировать проект на testpypi:

python setup.py register -r https://testpypi.python.org/pypi

Чтобы загрузить:

twine upload dist/packagename-version.tar.gz -r testpypi
twine upload dist/packagename-version-py2.py3-none-any.whl -r testpypi

Вы должны увидеть, что страница была создана по адресу https://testpypi.python.org/pypi/packagename/. Чтобы проверить, что это сработало:

pip install -i https://testpypi.python.org/pypi packagename

Если все сработало, вы можете запустить эту последнюю команду, чтобы загрузить свой пакет в настоящий pypi (обрабатывает регистрацию автоматически), заменив имя пакета и версию на правильные значения:

twine upload dist/packagename-version.tar.gz
twine upload dist/packagename-version-py2.py3-none-any.whl

Все готово, и теперь вы можете увидеть свой пакет на pypi!

Обновление вашего пакета

Если вы планируете поддерживать свой проект, вам нужно будет загрузить новую версию, когда она будет готова. Не забудьте увеличить номер версии в setup.py перед сборкой новых дистрибутивов. Когда новый исходный дистрибутив и файлы wheel будут готовы, просто запустите:

twine upload dist/packagename-newversion.tar.gz
twine upload dist/packagename-newversion-py2.py3-none-any.whl

И помните, что всегда полезно сначала использовать testpypi.

Дальнейшее чтение

• Руководство пользователя упаковки Python

• Индексирование пакета Python (pypi)

• Тестирование индексирования пакета Python (testpypi)

• Образец пакета PyPA

• ReStructuredText

• Semantic Versioning

• Выбор лицензии choosealicense

• Документация setuptools

• Аргументы setup()

• Распространение пакетов и wheel

• Использование testPyPI

• twine