Менеджер зависимостей Poetry — полный обзор от установки до настройки

Poetry – это инструмент для управления зависимостями и сборкой пакетов в Python.

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

Содержание

Все началось с того, что создателю Poetry Себастьену Юстасу потребовался единый инструмент для управления проектами от начала до конца, надежный и интуитивно понятный, который бы мог использоваться и в рамках сообщества. Одного лишь менеджера зависимостей было недостаточно, чтобы управлять запуском тестов, процессом развертывания и всем созависимым окружением. Этот функционал находится за гранью возможностей обычных пакетных менеджеров, таких как Pip или Conda. Так появился Python Poetry.

Что умеет Poetry

Ключевой фичей Poetry Python является полное управление библиотеками, заявленными для вашего проекта, включая их установку, обновление и публикацию.
А еще он может:

• Создавать и упаковывать проекты с помощью одной команды.
• Публиковать проекты в PyPI и приватных репозиториях.
• Проверять состояния зависимостей одной командой.
• Фиксировать версии зависимостей.
• Управлять публикацией билдов.
• Использовать настроенные виртуальные сервера или создавать собственное виртуальное окружение для полной изоляции от вашей системы.

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

Установка

Poetry – кроссплатформенный инструмент. Теоретически он должен одинаково работать в Linux, MacOS и Windows. Системные требования предполагают использование актуальных версий Python, поэтому начиная с версии Poetry 1.2 не поддерживаются Python 2.7 и 3.5, будьте внимательны!

Poetry создает изолированное виртуальное окружение для вашего проекта, инсталлируя все необходимое и разруливая конфликты зависимостей (если они в принципе решаемы).

По умолчанию установка происходит в домашний каталог пользователя, но это можно изменить путем переопределения переменной окружения POETRY_HOME:

POETRY_HOME=/etc/poetry

Установка на OSX и Linux

Этапы установки на Mac и Linux идентичны:
1. Проверить версию Python (в консоли python --version, и если версия Python по умолчанию 2.7, проверить python3 --version).
2. Чтобы установить актуальную версию вводим в консоль:

curl -sSL https://raw.githubusercontent.com/python-poetry/poetry/master/get-poetry.py | python -

Если дефолтная версия языка не устраивает или если для установки хочется воспользоваться версией питона 3.x, а по умолчанию стоит 2.7, используйте команду:

curl -sSL https://raw.githubusercontent.com/python-poetry/poetry/master/get-poetry.py | python3 -

Обратите внимание: процесс установки может занять довольно длительное время.

Каталог bin, в который происходит установка инструмента, в Unix расположен в $HOME/.poetry/bin.

Установка на Windows

Для инсталляции Poetry:
1. Откройте Powershell (Win + X далее i, или найдите PoweShell через поиск).
2. Введите команду:

(Invoke-WebRequest -Uri https://raw.githubusercontent.com/python-poetry/poetry/master/get-poetry.py -UseBasicParsing).Content | python -

Перезапустите оболочку и все заработает. Папку установки для Windows вы найдете в %USERPROFILE%\.poetry\bin.

Для корректной работы установщик должен иметь возможность найти исполняемые файлы py.exe -3 или py.exe -2.

Установка через PIP и PIPX

Для данного варианта установки необходимо иметь на борту менеджер пакетов PIP (или PIPX).

Для установки Poetry через PIP выполните команду:

pip install --user poetry

Имейте ввиду, что зависимости пакета Poetry могут вызвать конфликт с уже установленными пакетами в вашей системе.

Команды Pipx для установки, обновления и удаления инструмента:

pipx install poetry
pipx upgrade poetry
pipx uninstall poetry

Pipx поддерживает только версии Python старше 3.6.

Работа с Poetry

Для начала убедимся, что Poetry корректно установлен, введя в терминал команду:

poetry --version

Если в ответ высветится актуальный номер версии, можно приступать к работе.

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

Создаем пробный проект и присваиваем ему название «project-poetry»:

poetry new project-poetry

Произойдет автоматическое создание папки проекта со следующей структурой:

project-poetry
    project-poetry
        __init__.py
    tests
        __init__.py
        test_project_poetry.py
    pyproject.toml
    README.rst

В случае, если необходимо инициализировать Poetry-проект в уже существующем каталоге, перейдите в него и выполните команду:

poetry init

Pyproject.toml

В файле pyproject.toml содержится описание вашего Poetry-проекта – название, описание, используемый репозиторий, зависимости проекта и т.д. С помощью него легко организовать зависимости вашего проекта (pyproject.toml можно назвать преемником устаревшего requirements.txt).

Если вы знакомы с Pipenv, то наверняка заметите, что pyproject.toml очень похож на Pipfile.

После инициализации проекта, содержание файла будет следующим:

[tool.poetry]
name = "project-poetry"
version = "0.1.0"
description = ""
authors = ["Alexander <info @ pythonchik.ru>"]
[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.dependencies] – раздел содержит зависимости, необходимые для проекта;
• [tool.poetry.dev-dependencies] – зависимости разработки (не войдут в сборку проекта, но необходимые для других аспектов – тестирования, документации и т. д.);
• [build-system] – если вы используете Poetry для управления своим проектом, вы должны ссылаться на него в этом разделе (команды new и init автоматически добавляют информацию в раздел build-system).

📌 О дополнительных секциях файла можете прочитать в официальной документации The pyproject.toml file.

Все переменные могут задаваться вручную в соответствующие места Pyproject.toml, а также с помощью команды add или добавляться автоматически средствами Poetry.

Установка пакета

Теперь установим новый пакет в наш проект:

poetry add pymongo

После установки пакета, в pyproject.toml появится новая запись:

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

Для добавления dev-зависимости (зависимости для разработки) необходимо добавить флаг —dev: poetry add pytest --dev.

Удаление пакета

Для удаления пакета достаточно выполнить команду:

poetry remove pymongo

При этом запись пакета также удалится из pyproject.toml.

Poetry и виртуальное окружение

По умолчанию, Poetry автоматически создает виртуальное окружение для вашего проекта в cache-директории:

• для Windows – C:\Users\<username>\AppData\Local\pypoetry\Cache\virtualenvs;
• для Linux – ~/.cache/pypoetry/virtualenvs;
• для macOS – ~/Library/Caches/pypoetry/virtualenvs.

В эту директорию будут сохраняться все зависимости для проекта.

📌 Что такое виртуальное окружение и как оно работает можно прочитать тут.

Конфигурация Poetry

Конфигурация Poetry настраивается с помощью команды poetry config. После первого запуска команды, Poetry создаст файл конфигурации config.toml, в котором будут храниться все заданные параметры. Находится файл в директории:

• для Windows – C:\Users\<username>\AppData\Roaming\pypoetry;
• для Linux – ~/.config/pypoetry;
• для macOS – ~/Library/Application Support/pypoetry.

Для примера, попробуем настроить Poetry так, чтобы он создавал виртуальное окружение virtualenvs не в cache-директории, а в корневом каталоге проекта. Для этого установим переменной virtualenvs.in-project значение true:

poetry config virtualenvs.in-project true

Чтобы убедиться, что значение успешно установилась, выполним команду:

poetry config virtualenvs.in-project

Чтобы посмотреть все текущие параметры Poetry, используйте команду poetry config --list.
Теперь все зависимости будут устанавливаться в папку .venv в корне вашего проекта.

Если параметр нужно удалить, используйте флаг --unset:

poetry config virtualenvs.in-project --unset

📌 Подробнее о настройке конфигурации Poetry читайте тут.

Список команд

Poetry охватывает множество функций, связанных с управлением конфигурацией и публикацией пакетов:

• shell – при первом запуске этой команды в каталоге вашего проекта Poetry создает виртуальную среду Python, которая будет связана с проектом. Вместо создания папки, содержащей библиотеки зависимостей, Poetry создает среду на глобальном системном пути. Как только эта виртуальная среда будет создана, ее можно активировать в любое время, запустив poetry shell в каталоге проекта.
• install – устанавливает зависимости, указанные в pyproject.toml. При первой установке создается файл .lock, который содержит фактические номера версий каждого установленного пакета. Номера версий в .lock приоритетнее, чем находящиеся в pyproject.toml.
• update – если для пакетов в pyproject.toml существуют более новые версии, они будут установлены, и .lock файл будет обновлен.
• add – добавление зависимости к pyproject.toml. Пакет устанавливается сразу после применения команды.
• remove – удаление библиотеки зависимостей.
• config – пути к текущей виртуальной среде или ее переменные. Передача опции --list вернет текущие значения конфигурации.
• check – проверяет pyproject.toml на наличие ошибок.
• show – возвращает вывод всех пакетов, установленных в проекте, включая зависимости зависимостей.
• run – выполняет сценарий, заданный в разделе tool.poetry.scripts в pyproject.toml.
• build – собирает исходники и пакеты в архив.
• publish – публикует вывод предыдущей сборки во внешнем репозитории, например, в PyPi.

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

Сборка и настройка пакета

Чтобы собрать пакет, запускаем команду build.

poetry build
Building project-poetry (0.1.0)
  - Building sdist
  - Built project-poetry-0.1.0.tar.gz
  - Building wheel
  - Built project_poetry-0.1.0-py3-none-any.whl

В результате в папке dist будут сформированы пакеты.

Если мы хотим ограничить сборку определенным типом, можно просто использовать параметр -F.

poetry build -F wheel # or sdist

Чтобы развернуть пакет, нужно настроить репозитории и учетные данные. Для этого применяется команда config.

poetry config repositories.priv https://my.repository

В примере происходит настройка репозитория с именем priv и Url-адресом https://my.repository.

Сохранить учетные данные для этого репозитория также можно с помощью команды config:

poetry config http-basic.priv user password

В приведенной команде user и password соответствуют имени пользователя и паролю для входа в наш частный репозиторий. Обратите внимание, если не указать пароль, то его будет предложено ввести при развертывании пакета.

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

poetry publish

Если использован частный репозиторий, следует указать его имя Priv с помощью опции -r.

Poetry и Docker

Использование Poetry для работы с проектом внутри Docker-контейнера иногда сопряжено со сложностями интеграции. Ключевым моментом является отключение VirtualEnv, так как он не нужен в уже изолированном докере:

poetry config virtualenvs.create false

Затем устанавливаются разные наборы зависимостей для переменной среды:

poetry install $(test "$MY_ENV" == production && echo "--no-dev")

Таким образом в $MY_ENV будет контролироваться, какой набор зависимостей следует устанавливать: все (по умолчанию) или продакшн только с --no-dev флагом.

---

Poetry выходит далеко за рамки стандартного менеджера зависимостей, предлагая такие функции, как создание файлов .lock, создание шаблонов проекта и множество параметров конфигурации, каждый из которых обрабатывается через простой интерфейс командной строки. Если вы не знаете, как чисто и эффективно структурировать свои проекты Python и облегчить управление ими, сделайте себе одолжение и используйте Poetry.

Автор: Александр Попов