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

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
maintainers — список менторов проекта формате name
readme — readme файл проекта в формате README.rst или README.md
homepage — URL сайта проекта
repository — URL репозитория проекта
documentation- URL документации проекта
keywords — список ключевых слов проекта (макс: 5)
classifier — список PyPI классификаторов

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

[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:

Пример данных в pyproject.toml

[tool.poetry]
name = "new_proj"
version = "0.1.0"
description = "My description"
authors = ["Daniil Gorbenko "]

[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

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

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 при создании проекта:

Установка poetry как менеджер пакетов в Pycharm Установка poetry как менеджер пакетов в Pycharm

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

Структура проекта

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

Загрузка пакета через PyCharm Загрузка пакета через PyCharmОбновленный .toml

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

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

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

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

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

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

Зависимость	Минимальная версия	Максимальная версия
^1.2.3	>=1.2.3	<2.0.0
^1.2	>=1.2.0	<2.0.0
^1	>=1.0.0	<2.0.0
^0.2.3	>=0.0.3	<0.0.4
~1.2.3	>=1.2.3	<1.3.0
~1.2	>=1.2.0	<1.3.0
~1	>=1.0.0	<2.0.0
*	>=0.0.0	-
1.*	>=1.0.0	<2.0.0
1.2.*	>=1.2.0	<1.3.0

Заключение

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