Poetry — менеджер пакетов для Python

Рассмотрим установку и использование инструмента для управления библиотеками и зависимостями в Python.

Введение

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

Установка

Поскольку Poetry — это пакет из репозитория PyPI, вы можете установить его с помощью pip

python3 -m pip install --user poetry

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

Как уже говорилось, приведенная выше команда установит пакет poetry в каталог site-packages. В зависимости от конфигурации это будет либо глобальный каталог site-packages, либо пользовательский каталог site-packages. Чтобы избежать этой двусмысленности, создатели проекта рекомендуют использовать альтернативный метод загрузки.

На macOS, Linux и других POSIX-совместимых системах можно установить с помощью утилиты curl

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

В операционной системе Windows установка происходит с помощью PowerShell

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

Использование

Установив его можно использовать для следующих задач

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

Чтобы инициализировать новый проект, вы должны использовать команду как показано в следующем примере

poetry new test_proj

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

test_proj/
├── README.rst
├── test_proj
│   └── __init__.py
├── pyproject.toml
└── tests
    ├── __init__.py
    └── test_test_proj.py

Как вы можете видеть, он создает несколько файлов, которые можно использовать в качестве скелетов для дальнейшей разработки. Если у вас есть уже существующий проект, вы можете инициализировать Poetry в нем с помощью команды poetry init в каталоге проекта. Разница в том, что при этом не будет создано никаких новых файлов проекта, кроме конфигурационного файла pyproject.toml.

Ядром является файл pyproject.toml, в котором хранится конфигурация проекта.

После создания нового проекта он выглядит следующим образом

[tool.poetry]
name = "test_proj"
version = "0.1.1"
description = "Test django project"
authors = ["Egorov Egor <egorov_egor@fbi.gov>"]

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

[tool.poetry.dev-dependencies]
pytest = "^5.3"

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

Как вы можете видеть, файл pyproject.toml разделен на четыре секции.

К ним относятся

• [tool.poetry]: Это набор основных метаданных проекта, таких как название, описание версии и автор. Эта информация необходима, если вы хотите опубликовать свой проект как пакет на PyPI.
• [tool.poetry.dependencies]: Это список зависимостей проекта. В свежих проектах он содержит только версию Python, но может также включать все версии пакетов, которые обычно описываются в файле requirements.txt.
• [tool.poetry.dev-dependencies]: Это список зависимостей, которые требуют локальной разработки, например, фреймворки для тестирования или инструменты для повышения производительности. Обычно принято иметь отдельный список таких зависимостей, поскольку они обычно не требуются в производственных средах.
• [build-system]: Описывает Poetry как систему сборки, используемую для управления проектом.

Файл pyproject.toml является частью официального стандарта Python, описанного в документе PEP 518

Если вы создадите новый проект или инициализируете существующий, он сможет создать новую виртуальную среду в общем месте, когда вам это понадобится. Вы можете активировать ее вместо того, чтобы использовать скрипты activate.

Это удобнее, чем использование обычного модуля venv, потому что вам не нужно помнить, где хранится реальная виртуальная среда. Единственное, что вам нужно сделать, это активировать оболочку в корне исходников вашего проекта и использовать команду, как в следующем примере:

cd test_proj
poetry shell

С этого момента в текущей оболочке будет активировано виртуальное окружение.

Вы можете проверить это с помощью команды

python3 -m site

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

С Poetry эта проблема исчезла. Существует только один способ добавления зависимостей в ваш проект, и это команда poetry add <имя пакета>.

Это позволит вам

• Разрешить целые деревья зависимостей, если другие пакеты имеют общие зависимости
• Установить все пакеты из дерева зависимостей в виртуальную среду, связанную с вашим проектом
• Сохранить изменения в файле pyproject.toml.

Следующая расшифровка представляет процесс установки фреймворка Django в среде test_proj

poetry add Django

Это даст результат, подобный следующему

Using version ^4.0.5 for Django

Updating dependencies
Resolving dependencies... (2.5s)

Writing lock file

Package operations: 3 installs, 0 updates, 0 removals

  • Installing asgiref (3.5.2)
  • Installing sqlparse (0.4.2)
  • Installing django (4.0.5)

Ниже приведен результирующий файл pyproject.toml с изменениями в зависимостях проекта

[tool.poetry]
name = "test_proj"
version = "0.1.1"
description = "Test project"
authors = ["Egorov Egor <egorov_egor@fbi.gov>"]

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

[tool.poetry.dev-dependencies]
pytest = "^5.3"

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

Предыдущая расшифровка показывает, что пакетный менеджер установил 3 пакета, когда мы просили установить только один пакет. Это потому, что у Django есть свои собственные зависимости, а у этих зависимостей есть свои собственные зависимости. Такие зависимости от зависимостей называются переходными зависимостями. Библиотеки часто имеют нестрогие спецификаторы версии, такие как setuptools ==1.2.0, чтобы обозначить, что они могут принимать широкий диапазон версий. Менеджер пакетов реализует алгоритм разрешения зависимостей, чтобы выяснить, какой набор версий может удовлетворить всем ограничениям транзитивных зависимостей.

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

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

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

Менеджер пакетов решает проблему переходных зависимостей с помощью так называемых файлов блокировки зависимостей. Когда вы уверены, что в вашей среде есть рабочий и протестированный набор версий пакетов.

Вы можете выполнить следующую команду

poetry lock

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

Каждый раз, когда новые пакеты добавляются с помощью команды poetry add, пакетный менеджер будет оценивать дерево зависимостей и обновлять файл poetry.lock. Подход с использованием файла блокировки пока что является лучшим и самым надежным способом работы с переходными зависимостями в вашем проекте.

Заключение

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

На этом его функционал не ограничивается и более подробную информацию о всех доступных опциях можно прочитать на официальном сайте приложения.