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 файлами с уже заготовленным списком версий пакетов.