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

Во всех проектах профессии мы предлагаем использовать инструмент poetry — с его помощью можно управлять зависимостями. Сегодня это главный инструмент Python-разработчика.

Poetry — простой и удобный инструмент, который упрощает ведение и разработку проекта. Советуем оформлять каждый учебный эксперимент как poetry-проект, так вы быстрее привыкнете к профессиональным инструментам.

В этом уроке будем разбираться, как работать с Poetry. Пойдем по следующим шагам:

• Установка
• Настройка
• Создание первого poetry-проекта
• Работа с pyproject.toml
• Инициализация виртуального окружения

Как установить Poetry

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

Когда вы установите Poetry, он станет доступен как отдельная команда в shell:

poetry --version

Poetry version …

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

Как настроить Poetry

Если сразу после установки запросить перечень настроек Poetry, можно увидеть следующее:

poetry config --list

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

Poetry работает с виртуальными окружениями. При этом он изначально настроен так, что у вас будет много разных версий Python. По этой причине инструмент создает виртуальные окружения для проектов в непривычном месте — обратите внимание на настройку virtualenvs.path.

Можно использовать настройки по умолчанию, но Python-разработчики обычно хранят виртуальное окружение для каждого проекта в директории проекта, а именно в поддиректории .venv.

Вспомните, как вы создавали окружения командой python3 -m venv .venv. В Poetry стоит делать так же:

poetry config virtualenvs.in-project true

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

Когда мы настроим Poetry, он будет готов для создания первого проекта.

Как создать первый проект

Создадим poetry-проект с помощью команды poetry new ИМЯ. Перед запуском Poetry убедитесь, что в системе доступна команда python3.

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

poetry new first

Created package first in first

cd first  # Переходим в созданную директорию
tree .

.
├── first
│   └── __init__.py
├── pyproject.toml
├── README.md
└── tests
    └── __init__.py

2 directories, 4 files

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

Кроме пакета first в проекте уже есть пакет tests. Пока он нам не нужен, но стоит знать, что у настоящих проектов всегда есть пакет с тестами.

Еще в реальном проекте у вас будет файл README.md, в котором вы будете держать описание проекта. У этого файла расширение .md — это файл формата Markdown. Это очень популярный формат разметки, даже этот урок написан на нем.

Самый важный файл в poetry-проекте — pyproject.toml. Это файл формата TOML, можете почитать о нем подробнее по ссылке.

Файл pyproject.toml содержит конфигурацию проекта. Информация из этого файла нужна, чтобы Poetry мог:

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

Чем больше вы работаете с Poetry, тем лучше вы разбираетесь в публикации проектов. Постепенно вы привыкаете, что в каждом пакете должно быть описание, правильная структура, указанная версия. Мы советуем всегда оформлять проекты по этим стандартам, даже если вы не собираетесь публиковать проект в индекс.

Мы создали первый проект. Теперь нужно разобраться с pyproject.toml.

Как работать с pyproject.toml

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

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

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

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

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

Здесь мы рассмотрим такие строчки:

• tool.poetry — описывает проект с точки зрения Poetry. Здесь хранится версия version, описание description и название проекта name

• tool.poetry.dependencies — хранит список зависимостей, которые требуются для работы самого кода. Здесь всегда будет указан сам Python — без него код не запустить

Секция 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)

Эта команда устанавливает все зависимости в окружение в директорию .venv внутри проекта. Активируется окружение командой poetry shell, а завершается командой exit:

# Выведем список пакетов,установленных в системе
pip list
Package              Version
-------------------- ---------------
asciinema            2.2.0
attrs                22.1.0
blinker              1.4
# Тут продолжение большого списка
...

# Как видите, в системе уже стоит немало пакетов
# Поэтому мы можем столкнуться с конфликтом версий при установке нового пакета
# Чтобы этого избежать, мы и используем виртуальные окружения

# Выведем список пакетов в окружении
poetry shell
Spawning shell within /../first/.venv

pip list
# В новом окружении есть только необходимый минимум для работы Poetry
Package    Version
---------- -------
pip        22.2.2
setuptools 65.3.0
wheel      0.37.1

Зачастую активация окружения необязательна — Poetry предлагает команду run, которая исполняет программы уже изнутри окружения. Например, REPL в рамках проекта принято запускать командой poetry run python.

Так выглядит работа с Poetry. Это удобный инструмент, поэтому мы советуем пользоваться им. Оформляйте даже самые маленькие эксперименты как poetry-проекты — так вы быстрее научитесь работать с инструментом.

Выводы

• Poetry — удобный инструмент, который упрощает ведение и разработку проекта
• Poetry устанавливают не через pip install. Для этого используются специальные команды, которые есть в документации к Poetry
• Нужно, чтобы у каждого проекта виртуальное окружение было при себе. Для этого Poetry нужно предварительно настроить
• В каждом пакете должно быть описание и правильная структура, а также назначена версия

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

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

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

1. Poetry — Python packaging and dependency management made easy

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

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