Начало работы с Poetry — Python: Настройка окружения

Мы в Hexlet считаем, что именно poetry лучше всего подходит на роль "главного инструмента" Python-разработчика. Поэтому все проекты в рамках профессии предполагают использование poetry.

Вам стоит взять poetry на вооружение как можно раньше и приучить себя оформлять каждый эксперимент как poetry-проект, даже если этот проект может показаться маленьким. Так вы быстрее привыкнете использовать профессиональные инструменты и делать это правильным способом — выработаете хорошие привычки!

Установка poetry

Poetry, хоть и написан на Python, не является обычной Python-программой, каковые принято устанавливать с помощью pip install. Во вводном разделе документации к Poetry вы найдёте команды для установки программы в вашу операционную систему.

Если установка прошла успешно, poetry должен стать доступен как отдельная команда в shell:

$ poetry --version
Poetry version …

Как правило, указанные в документации команды, что называется, "просто работают". Но если у вас что-то не получится, напишите в наш Slack — наверняка, кто-то да сталкивался с теми же проблемами и успешно с ними справился!

Предварительная настройка

Если вы запросите перечень настроек poetry сразу после установки, то увидите что-то подобное:

$ poetry config --list
cache-dir = "/…/…/.cache/pypoetry"
virtualenvs.create = true
virtualenvs.in-project = true
virtualenvs.path = "{cache-dir}/virtualenvs"  # /home/astynax/.cache/pypoetry/virtualenvs

poetry берёт на себя работу с виртуальными окружениями и выполняет он эту работу хорошо. Однако poetry изначально настроен на то, что у вас будет целый "зоопарк" версий Python, поэтому создаёт виртуальные окружения для проектов в не совсем привычном месте — обратите внимание на настройку virtualenvs.path.

В принципе можно использовать и настройки по умолчанию, однако среди разработчиков на Python принято хранить виртуальное окружение для каждого проекта в директории проекта в поддиректории .venv (помните, как вы создавали окружения командой python3 -m venv .venv?). Стоит и poetry попросить поступать так же:

$ poetry config virtualenvs.in-project true

Теперь каждый poetry-проект будет иметь виртуальное окружение при себе! Это позволит, к примеру, переносить проект с одной машины на другую простым копированием директории.

Первый проект

Настало время создать тот самый "poetry-проект" с помощью команды poetry new ИМЯ.

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

Предположим, что вы ввели команду poetry new first, вот как будет выглядеть результат:

$ poetry new first
Created package first in first
$ cd first  # переходим в созданную директорию
$ tree .
.
├── first
│   └── __init__.py
├── pyproject.toml
├── README.rst
└── tests
    ├── __init__.py
    └── test_first.py

2 directories, 5 files

Сообщение "Created package first in first" здесь означает, что в проекте "first" был создан одноимённый пакет — видите директорию first с соответствующим __init__.py? Любой poetry-проект всегда содержит хотя бы один пакет.

Кроме пакета first, в проекте уже есть пакет tests с первым тестом. Нам пока этот пакет не интересен, но само его наличие должно вас настроить на нужный лад — настоящие проекты всегда имеют тесты!

В файле README.rst вы будете держать описание проекта.

Расширение .rst говорит о том, что это файл формата reStructuredText. Пройдите по ссылке и почитайте о формате — знать о нём полезно, ведь именно в данном формате и документируют код проектов Python!

И, наконец, самый важный файл в poetry-проекте — pyproject.toml. Это файл конфигурации проекта, описывающий всё, что нужно poetry знать, чтобы

• управлять зависимостями проекта
• запускать код на исполнение
• запускать инструменты для разработки
• собирать дистрибутив и публиковать его на PyPI

Отдельно стоит отметить последний пункт: poetry приучает к тому, чтобы вы всегда думали о проекте так, как будто вы будете его публиковать — любой "уважающий себя" пакет имеет хорошее описание и правильную структуру, ему всегда назначена какая-то версия. Стоит думать о таких вещах, даже если вы не собираетесь публиковать каждый ваш проект в индекс!

Расширение .toml говорит о том, что это файл формата TOML. Почитайте и об этом формате.

Первый взгляд на pyproject.toml

У только что созданного проекта файл конфигурации выглядит примерно так:

[tool.poetry]
name = "first"
version = "0.1.0"
description = ""
authors = ["…"]

[tool.poetry.dependencies]
python = "^3.8"

[tool.poetry.dev-dependencies]
pytest = "^5.2"

[build-system]
requires = ["poetry-core>=1.0.0"]
build-backend = "poetry.core.masonry.api"

Здесь строчки вида [tool.poetry] описывают секции, в секциях же находятся пары "ключ = значение". Важно помнить, что большинство ключей нельзя помещать "не в те" секции. Вы всегда можете посмотреть в документации, какие ключи бывают и каким секциям они принадлежат.

В данный момент нам интересны первые три секции:

• tool.poetry описывает проект целиком с точки зрения poetry и хранит версию (version), описание (description), имя, под которым пакет будет публиковаться (name)
• tool.poetry.dependencies хранит список зависимостей, требуемых для работы самого кода, их ещё называют "runtime-зависимости". Здесь всегда будет указан сам Python — без него уж точно код не запустить!
• tool.poetry.dev-dependencies хранит список зависимостей, нужных в процессе разработки проекта, так называемые "dev-зависимости". В примере выше указан pytest — это такой инструмент для автоматизации запуска тестов.

Секция build-system описывает тот факт, что перед нами именно проект, управляемый poetry. Но существуют и другие инструменты для управления проектами, для них секция build-system будет выглядеть иначе.

Инициализация виртуального окружения

Как правило, poetry сам может понять, что окружение пора создать или обновить. Но можно и явно вызвать команду poetry install:

$ poetry install
Updating dependencies
Resolving dependencies...

Writing lock file

…

Installing the current project: first (0.1.0)

В процессе будут установлены все зависимости — и "runtime" и "dev". Для рассматриваемого проекта это означает, что будет установлен пакет pytest (вместе с его зависимостями), а это значит, что теперь pytest можно запустить:

$ poetry run pytest
====== test session starts ========
platform linux -- Python 3.8.8, ...
rootdir: /.../first
collected 1 item

tests/test_first.py .       [100%]

======== 1 passed in 0.01s ========

Проект только создан, но вот уже и тесты пройдены!

Обратите внимание на то, что pytest вызывается в виде poetry run pytest — подобным образом следует вызывать любые команды, относящиеся к зависимостям. Так, REPL в рамках проекта принято запускать командой poetry run python.

Самостоятельная работа

• Создайте проект с именем hello.
• Убедитесь, что структура проекта похожа на показанную в примере и посмотрите, что же отличается.
• Создайте окружение (poetry install) и запустите проверку тестов (poetry run pytest), убедитесь, что проверка проходит успешно.

Дополнительные материалы

1. Poetry — Python packaging and dependency management made easy

Остались вопросы? Задайте их в разделе «Обсуждение»

Вам ответят команда поддержки Хекслета или другие студенты.