Как сделать классный Python-пакет

Бывает, напишешь какую-нибудь полезную утилиту на питоне, и хочется поделиться ей с коллегами. Лучший способ для этого — сделать пакет (package): он устанавливается одной командой и спасает от копипасты.

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

1. Заглушка

Будем делать podsearch — утилиту, которая ищет подкасты в айтюнсе. Создадим каталог и виртуальное окружение:

$ mkdir podsearch
$ cd podsearch
$ python3 -m venv env
$ . env/bin/activate

Создадим минимальную структуру пакета:

.
├── .gitignore
└── podsearch
    └── __init__.py
"""Let's find some podcasts!"""

 __version__ = "0.1.0"


 def search(name, count=5):
     """Search podcast by name."""
     raise NotImplementedError()</pre>

коммит

2. Тестовый пакет

Исторически создание пакета в питоне — дело хлопотное. К счастью, есть отличная маленькая утилита flit, которая упрощает его до предела. Установим её:

pip install flit

И создадим описание пакета:

$ flit init
Module name [podsearch]: 
Author [Anton Zhiyanov]: 
Author email [m@antonz.ru]: 
Home page [https://github.com/nalgeon/podsearch-py]:                                     
Choose a license (see http://choosealicense.com/ for more info)
1. MIT - simple and permissive
2. Apache - explicitly grants patent rights
3. GPL - ensures that code based on this is shared with the same terms
4. Skip - choose a license later
Enter 1-4 [1]: 1

Written pyproject.toml; edit that file to add optional extra info.

коммит

Flit создал файл с метаданными проекта pyproject.toml. В нём уже есть всё необходимое для публикации пакета в публичном репозитории — PyPi.

Зарегистрируемся на TestPyPi (тестовый репозиторий) и PyPi (основной). Они полностью независимы, так что потребуются две учётные записи.

Настроим доступ к репозиториям в файле ~/.pypirc:

[distutils]
index-servers =
  pypi
  pypitest

[pypi]
username: nalgeon  # replace with your PyPI username

[pypitest]
repository: https://test.pypi.org/legacy/
username: nalgeon  # replace with your TestPyPI username

И опубликуем наш пакет в тестовом репозитории:

$ flit publish --repository pypitest
Found 4 files tracked in git
...
Package is at https://test.pypi.org/project/podsearch/

Готово, пакет доступен по ссылке https://test.pypi.org/project/podsearch/

3. Публичный пакет

Доработаем утилиту, чтобы она реально искала подкасты:

# ...

SEARCH_URL = "https://itunes.apple.com/search"

@dataclass
class Podcast:
    """Podcast metadata."""

    id: str
    name: str
    author: str
    url: str
    feed: Optional[str] = None
    category: Optional[str] = None
    image: Optional[str] = None


def search(name: str, limit: int = 5) -> List[Podcast]:
    """Search podcast by name."""
    params = {"term": name, "limit": limit, "media": "podcast"}
    response = _get(url=SEARCH_URL, params=params)
    return _parse(response)

коммит

И опубликуем в основном репозитории — PyPi. Выполняйте этот шаг только после того, как у вашего пакета готов рабочий код, который делает что-то полезное. Не стоит публиковать нерабочие пакеты и пакеты-заглушки.

flit publish

Готово! Можно делиться с коллегами.

А чтобы пакетом было приятно пользоваться, рекомендую выполнить ещё несколько шагов.

А. Ридми и ченжлог

Никто не любит писать документацию. Но без неё вряд ли люди захотят устанавливать ваш пакет, так что добавим README.md и CHANGELOG.md (коммит).

Заодно в pyproject.toml настроим, чтобы ридми показывался на странице пакета в PyPi:

description-file = "README.md"

И укажем минимальную версию питона, с которой работает утилита:

requires-python = ">=3.7"

Обновим версию в __init__.py (коммит) и опубликуем пакет через flit publish. Красота:

Страница пакета на PyPi

Б. Линтеры и тесты

Позаботимся о форматировании (black), тестовом покрытии (coverage), качестве кода (flake8, pylint, mccabe) и статическом анализе (mypy). Будем выполнять это всё через tox.

$ pip install black coverage flake8 mccabe mypy pylint pytest tox

Создадим конфигурацию для tox в tox.ini:

[tox]
isolated_build = True
envlist = py37

[testenv]
deps =
    black
    coverage
    flake8
    mccabe
    mypy
    pylint
    pytest
commands =
    black podsearch
    flake8 podsearch
    pylint podsearch
    mypy podsearch
    coverage erase
    coverage run --include=podsearch/* -m pytest -ra
    coverage report -m

И выполним все проверки:

$ tox
...
py37 run-test: commands[0] | black podsearch
All done! ✨ 🍰 ✨
3 files left unchanged.

py37 run-test: commands[1] | flake8 podsearch

py37 run-test: commands[2] | pylint podsearch

--------------------------------------------------------------------
Your code has been rated at 10.00/10 (previous run: 10.00/10, +0.00)

py37 run-test: commands[3] | mypy podsearch
Success: no issues found in 3 source files

py37 run-test: commands[4] | coverage erase
py37 run-test: commands[5] | coverage run '--include=podsearch/*' -m pytest -ra
...
py37 run-test: commands[6] | coverage report -m
Name                    Stmts   Miss  Cover   Missing
-----------------------------------------------------
podsearch/__init__.py       2      0   100%
podsearch/http.py          17      0   100%
podsearch/searcher.py      35      0   100%
-----------------------------------------------------
TOTAL                      54      0   100%

py37: commands succeeded
congratulations :)

Красота! Линтеры довольны, тесты прошли, покрытие 100%.

коммит

В. Сборка в облаке

Уважающие себя opensource-проекты прогоняют тесты в «облаке» после каждого коммита. К тому же это позволяет развесить красивые бирки в ридми ツ

Будем собирать через Travis CI, мерить покрытие через Coveralls, а качество — через Code Climate. Для начала придётся зарегистрироваться во всех трёх и включить в настройках гитхаб-репозиторий, в котором живёт код библиотеки.

После этого добавим конфиг для Travis в .travis.yml:

language: python
python:
    - "3.7"
install: pip install coverage coveralls flake8 mccabe mypy pylint pytest
script:
    - flake8 podsearch
    - pylint podsearch
    - mypy podsearch
    - coverage erase
    - coverage run --include=podsearch/* -m pytest -ra
    - coveralls

коммит

Для Coveralls и Code Climate отдельные конфиги не нужны, так что просто коммитим, пушим, и через минуту наслаждаемся результатом. А чтобы насладились все, добавим бирки в README.md:

[![PyPI Version][pypi-image]][pypi-url]
[![Build Status][build-image]][build-url]
[![Code Coverage][coverage-image]][coverage-url]
[![Code Quality][quality-image]][quality-url]

...

<!-- Badges -->

[pypi-image]: https://img.shields.io/pypi/v/podsearch?style=flat-square
[pypi-url]: https://pypi.org/project/podsearch/
[build-image]: https://img.shields.io/travis/nalgeon/podsearch-py?style=flat-square
[build-url]: https://travis-ci.org/nalgeon/podsearch-py
[coverage-image]: https://img.shields.io/coveralls/github/nalgeon/podsearch-py?style=flat-square
[coverage-url]: https://coveralls.io/github/nalgeon/podsearch-py
[quality-image]: https://img.shields.io/codeclimate/maintainability/nalgeon/podsearch-py?style=flat-square
[quality-url]: https://codeclimate.com/github/nalgeon/podsearch-py

Смотрите, как хорошо:

Бирки в описании проекта
С бирками на ридми приятно посмотреть

коммит

Г. Автоматизация задач

Всё хорошо, но неудобно во время разработки гонять линтеры и мерить покрытие. Постоянно запускать tox слишком долго, а писать каждый раз в консоли pylint, coverage, и тому подобное — утомительно.

Сделаем задачи для частых действий. В этом нам поможет мейкфайл:

.DEFAULT_GOAL := help
.PHONY: changelog coverage deps help lint push test

coverage:  ## Run tests with coverage
	coverage erase
	coverage run --include=podsearch/* -m pytest -ra
	coverage report -m

deps:  ## Install dependencies
	pip install black coverage flake8 mccabe mypy pylint pytest tox

lint:  ## Lint and static-check
	flake8 podsearch
	pylint podsearch
	mypy podsearch

push:  ## Push code with tags
	git push && git push --tags

test:  ## Run tests
	pytest -ra

Список наших задач:

$ make help
Usage: make [task]

task                 help
------               ----
coverage             Run tests with coverage
deps                 Install dependencies
lint                 Lint and static-check
push                 Push code with tags
test                 Run tests
help                 Show help message

коммит

⌘ ⌘ ⌘

Ваш идеальный пакет готов! У него есть всё: чистый код, понятная документация, тесты и автосборка. Самое время рассказать коллегам и единомышленникам.

Список коммитов для всех шагов:

  1. Заглушка
  2. Конфигурация пакета
  3. Первый релиз
  4. Ридми и ченжлог
  5. Линтеры и тесты
  6. Сборка в облаке и бирки
  7. Автоматизация задач

И подписывайтесь на  «Oh My Py»