Poetry — прекрасная альтернатива pip (шпаргалка)

Poetry - это инструмент для управления зависимостями в Python проектах (аналог встроенного pip). Идея реализации данного инструмента пришла его создателю в связи с тем, что различные способы менеджмента пакетов (requirements.txt, setup.cfg, MANIFEST.ini и другие) показались создателю Poetry не очень-то удобными. 

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

Установка

Установить poetry на windows можно либо при помощи pip:

pip install poetry

Либо более гибким вариантом через powershell:

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

Отличие от pip

Pip хранит данные о зависимостях в файле requirements.txt (название на самом-то деле может быть любое), poetry хранит информацию в файле pyproject.toml, однако, в случае с pip, в его файле хранится только список зависимостей с описанием версий, а в .toml хранится вся основная информация о проекте, что очень удобно, так как все данные собраны в одном месте (далее последует более подробное описание).

Чтобы установить зависимости в pip необходимо выполнить:

pip install -r requirements.txt

Что для poetry займет всего 2 слова:

# для первичной установки
poetry install
# для обновления
poetry update

Просмотр зависимостей в pip можно сделать только командой:

pip freeze

Однако будут показаны только актуальные версии библиотек, не будет возможности увидеть структуру всех пакетов с их зависимостями. В poetry в файле poetry.lock можно увидеть сведения обо всех установленных пакетах, команда:

poetry show --tree

Покажет древовидную структуру пакетов с их личными зависимостями.

Так же запуск проекта в pip (в случае с виртуальным окружением) создает неудобства, так как первым делом необходимо зайти в это самое окружение при помощи команды:

./venv/Scripts/activate.bat

И только затем можно выполнять какие-либо изменения с проектом. В poetry нет необходимости активировать виртуальное окружение, достаточно лишь зайти в папку с проектом и начинать пользоваться командами. Poetry сам найдет нужное окружение. Также в poetry можно менять версию python без необходимости менять старое виртуальное окружение.

Это лишь малая часть преимуществ. Далее рассмотрим примеры команд и структуру poetry файлов.

pyproject.toml

Главный файл для poetry - это pyproject.toml. Все данные о проекты должны быть записаны в нём. При установке пакетов poetry берёт данные из этого файла и формирует файл с зависимостями poetry.lock (если уже есть готовый файл poetry.lock, то данные будут браться из него). Toml файл состоит из нескольких блоков, каждый из которых имеет свои особенности, рассмотрим данные блоки:

[tool.poetry] - содержит основную информацию о проекте, такую как:

• name - имя проекта

• version - версия проекта

• description - описание проекта

• license - лицензия проекта

• authors - список авторов проекта в формате name <email>

• maintainers - список менторов проекта формате name <email>

• readme - readme файл проекта в формате README.rst или README.md

• homepage - URL сайта проекта

• repository - URL репозитория проекта

• documentation- URL документации проекта

• keywords - список ключевых слов проекта  (макс: 5)

• classifier - список PyPI классификаторов

[tool.poetry.dependencies] - содержит описание всех зависимостей проекта. Каждая зависимость должна иметь название с указанием версии, также присутствует возможность скачать проекта с github с указанием ветки/версии/тэга, например:

• requests = "^2.26.0"

• requests = { git = "https://github.com/requests/requests.git" }

• requests = { git = "https://github.com/kennethreitz/requests.git", branch = "next" }

• numpy = { git = "https://github.com/numpy/numpy.git", tag = "v0.13.2" }

[tool.poetry.scripts] - в данном разделе можно описать различные сценарии или скрипты, которые будут выполняться при установке пакетов или при запуске приложения. Например:

• poetry = 'poetry.console:run'

• main-run = 'new_proj.main:run' (после чего достаточно запустить poetry main-run и будет выполнен запуск функции run в файле new_prof/main.py)

[tool.poetry.extras] - в данном блоке описываются группы зависимостей, которые можно устанавливать отдельно:

[tool.poetry.dependencies]
psycopg2 = { version = "^2.7", optional = true }
pymysql = { version = "1.0.2", optional = true }
[tool.poetry.extras]
mysql = ["pymysql"]
pgsql = ["psycopg2"]

Далее зависимости можно установить двумя способами:

poetry install --extras "mysql pgsql"
poetry install -E mysql -E pgsql

[tool.poetry.urls] - помимо основных URL, указанных в [tool.poetry], можно указывать свои URL:

• "Bug Tracker" = "https://github.com/python-poetry/poetry/issues"

[tool.poetry]
name = "new_proj"
version = "0.1.0"
description = "My description"
authors = ["Daniil Gorbenko <dani.gorbenko@gmail.com>"]

[tool.poetry.dependencies]
python = "^3.10"
pygame = "^2.1.0"
icecream = "^2.1.1"
requests = "^2.26.0"
psycopg2 = { version = "^2.7", optional = true }
pymysql = { version = "1.0.2", optional = true }

[tool.poetry.dev-dependencies]
Pympler = "^0.9"

[tool.poetry.urls]
"Bug Tracker" = "https://github.com/python-poetry/poetry/issues"

[tool.poetry.scripts]
run-main = "new_proj.main:main_def"

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

Основные методы

new

Чтобы создать новый проект с помощью Poetry, достаточно выполнить poetry new <название папки с проектом>. После чего создастся папка с названием вашего проекта, в этой папке будет лежать файл pyproject.toml.

poetry new new_project

init

Чтобы сделать пакетным менеджером poetry в уже имеющемся проекте, достаточно выполнить:

poetry init

Далее будет предложено заполнить немного основной информации о проекте

Метод может принимать некоторые необязательные параметры:

• --name: имя проекта

• --description: описание проекта

• --author: имя автора

• --python: совместимые версии Python

• --dependency: требуемый пакет с версией пакета

• --dev-dependency: требования к разработке

После чего в проекте появится файл pyproject.toml, в котором вручную можно изменить любые данные.

install

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

poetry install

Poetry считывает данные из pyproject.toml, строит дерево зависимостей проекта, разрешая проблемы с версиями зависимостей, и устанавливает все пакеты. Однако, если в проекте уже есть файл poetry.lock, то будут использоваться точные версии из этого файла.

Метод может принимать параметры:

• --remove-untracked: удалит старые пакеты, которые больше не используются в проекте

• --no-dev: dev пакеты не будут устанавливаться

update

Чтобы обновить версии зависимостей (тем самым обновив файл poetry.lock) достаточно выполнить:

poetry update

Также есть возможность обновить лишь определенные пакеты:

poetry update icecream pygame

Метод может принимать дополнительные параметры:

• --no-dev : игнорирует обновление dev пакетов

• --lock : не устанавливает и не обновляет пакеты, а только обновляет файл poetry.lock

add

Чтобы добавить новую библиотеку достаточно выполнить:

poetry add pygame

Можно указывать версию пакета:

 poetry add "pygame>=2"
 poetry add pygame@^2

Можно передать параметры:

• --dev (-D): установит пакет в качестве dev зависимости

• --path: путь к пакету (если пакет лежит локально)

• --lock : не устанавливает зависимости, а только обновляет файл poetry.lock

remove

Чтобы удалить зависимость достаточно выполнить:

poetry remove pygame

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

• --dev : удалит пакет из dev зависимостей

show

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

poetry show

результат poetry show

Если необходимо посмотреть информацию о конкретном пакете:

poetry show pygame

результат poetry show pygame

Посмотреть дерево зависимостей проекта можно при помощи:

poetry show --tree

результат poetry show --tree

Также можно передать параметры:

• --tree: список зависимостей в виде дерева

• --latest (-l): показать последние версии проектов

• --outdated (-o): показать последние версии только для устаревших пакетов

run

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

poetry run python <имя python файла>
poetry run python main.py 
poetry run <имя скрипта, описанного в [tool.poetry.scripts]>
poetry run main-run

PyCharm & Poetry

В PyCharm 2021.3 добавили поддержку Poetry. Теперь при создании проекта можно сразу указать poetry основным пакетным менеджером. Перед использованием необходимо установить executable версию poetry (на windows через poweshell):

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

После чего можно без проблем выбрать Poetry при создании проекта:

Далее автоматически будет создан .toml файл:

При установке пакетов через менеджер PyCharm файл pyproject.toml будет автоматически обновляться сам:

Версии зависимостей

При установке пакета можно указать точную версию проекта, например:

[tool.poetry.dependencies]
pygame = "2.1.0"

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

[tool.poetry.dependencies]
pygame = "^2.1"
pygame = "~2.1"
pygame = "2.1.*"
pygame = "*"

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

Заключение

Poetry - отличная альтернатива pip. Он позволяет отказаться от requirements.txt в пользу более гибкой настройки проекта. Благодаря poetry можно в любой момент посмотреть информацию о зависимостях любого пакета, гибко настраивать версии и обмениваться poetry.lock файлами с уже заготовленным списком версий пакетов.