Обновление Poetry: 2.0.0

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

В версии 2.0 была добавлена поддержка секции project в файле pyproject.toml (PEP 621), оптимизировано поведение установки зависимостей, а также реализовано множество важных внутренних улучшений. Однако обновление принесло и несколько критических изменений, включая удаление устаревших функций и добавление новых подходов к использованию плагинов.

Poetry 2.0.0

Если у вас уже установлена предыдущая версия Poetry через pipx, обновление до версии 2.0.0 будет простым:

pipx upgrade poetry

Если вы использовали официальный установщик, достаточно выполнить команду:

poetry self update

Узнать подробнее про Poetry можно в статье "FastAPI 1. Инициализация проекта".

Официальный список изменений.

Основные изменения

1. Поддержка секции `project` в pyproject.toml (PEP 621)

Теперь Poetry 2.0 поддерживает секцию project в файле pyproject.toml, как это описано в PEP 621 и спецификации pyproject.toml. Это позволяет заменить множество полей в секции tool.poetry их эквивалентами из секции project.

Пример нового формата:

[project]
name = "poetry-demo"
version = "0.1.0"
description = ""
authors = [
    {name = "Sébastien Eustace", email = "sebastien@eustace.io"}
]
readme = "README.md"
requires-python = ">=3.8"

[tool.poetry]
packages = [{include = "poetry_demo"}]

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

Что это значит для пользователей?

Унификация и совместимость: Секция project является стандартом, поддерживаемым другими инструментами экосистемы Python. Использование её делает ваш проект более совместимым.
Упрощение структуры: Теперь можно избежать дублирования информации, так как поля, связанные с описанием проекта, переходят в единую секцию.

Депрекация полей

Многие поля из секции tool.poetry устарели (депрекейтед) в пользу их аналогов из секции project. Чтобы проверить, какие поля устарели в вашем проекте и на что их нужно заменить, используйте команду:

poetry check

Или обратитесь к документации, чтобы ознакомиться с изменениями.

Примечание: Секция tool.poetry.dependencies остаётся актуальной, поскольку она поддерживает функции, которые отсутствуют в project.dependencies.

Вы можете использовать одну из следующих стратегий:

Если вам нужны только стандартные возможности, замените tool.poetry.dependencies на project.dependencies.
Если вы используете специфичные для Poetry функции, можете дополнить project.dependencies дополнительной информацией в tool.poetry.dependencies.
Если ваш проект сильно полагается на возможности Poetry, объявите project.dependencies как динамическую и полностью используйте tool.poetry.dependencies.

2. Поддержка плагинов и указание минимальной версии Poetry

Поддержка плагинов

Теперь в Poetry 2.0 вы можете указать, что ваш проект зависит от определённых плагинов. Для этого добавьте секцию requires-plugins в tool.poetry:

[tool.poetry.requires-plugins]
my-application-plugin = ">1.0"

Если плагин ещё не установлен, команда poetry install автоматически установит его только для вашего проекта. Это упрощает управление зависимостями, связанными с плагинами, и делает использование плагинов более прозрачным.

Что это даёт пользователю?

Автоматическая установка плагинов: Не нужно вручную устанавливать плагины, которые требуются вашему проекту.
Изоляция окружения: Установка плагинов только для проекта помогает избежать конфликтов между проектами.

Подробнее о плагинах можно узнать в документации по плагинам.

Указание минимальной версии Poetry

Вы можете явно указать минимальную версию Poetry, которая необходима для работы вашего проекта. Например, если вы используете новую секцию project, добавьте:

[tool.poetry]
requires-poetry = ">=2.0"

Что это даёт пользователю?

Гарантия совместимости: Позволяет избежать проблем, если кто-то попытается работать с проектом, используя устаревшую версию Poetry.
Прозрачность требований: Указывает разработчикам, какую версию Poetry следует установить для работы с проектом.

3. Фиксация групп и маркеров зависимостей в lock-файле

Что изменилось?

Poetry теперь добавляет в файл poetry.lock информацию о группах и маркерах для каждой зависимости. Например:

groups = ["main", "dev"]
markers = 'sys_platform  "win32"'

Это означает, что конкретный пакет требуется как для основной группы (main), так и для группы разработки (dev), но только для Windows.

На данный момент эта информация не используется по умолчанию, но может быть полезна для:

Отладки: Просмотр зависимостей и их условий установки (маркеров).
Аудита: Анализа, какие зависимости связаны с определёнными группами или платформами.
Будущих улучшений: Закладка возможностей для оптимизации процесса установки.

Настройка установки без повторного разрешения зависимостей

По умолчанию при установке пакетов из poetry.lock, Poetry повторно разрешает зависимости (re-resolve), используя только источники, указанные в lock-файле. Теперь вы можете отключить это поведение:

poetry config installer.re-resolve false

Если вы используете эту настройку (и lock-файл был создан с Poetry 2.0), Poetry будет просто проверять зафиксированные группы и маркеры, чтобы решить, какой пакет установить.

Пример сценария:

Для проекта с глубокой, но не широкой структурой зависимостей (например, большое количество зависимостей с длинной цепочкой), отключение повторного разрешения может существенно ускорить установку.

Что это даёт пользователю?

Оптимизация производительности: Быстрая установка пакетов за счёт использования информации из lock-файла без повторного анализа дерева зависимостей.
Прозрачность зависимостей: Возможность видеть, какие группы и маркеры относятся к каждой зависимости, прямо в lock-файле.
Гибкость: Возможность выбора между повторным разрешением зависимостей (по умолчанию) или использованием данных из lock-файла.

4. Критические изменения и удалённые функции

Poetry 2.0 содержит множество изменений, которые могут повлиять на совместимость. Здесь рассмотрены ключевые изменения и удалённые функции.

1. `poetry export` и `poetry shell` доступны только через плагины

Что изменилось?
- Команда poetry export теперь доступна только через плагин poetry-plugin-export. Ранее этот плагин устанавливался по умолчанию, но теперь он исключён из базовой установки Poetry. Для использования необходимо вручную установить плагин. Подробнее — в разделе Использование плагинов.
- Команда poetry shell удалена из ядра. Вместо неё рекомендуется использовать команду poetry env activate, которая выводит команду для активации виртуального окружения в текущем shell. Если вам всё ещё нужна poetry shell, вы можете установить плагин poetry-plugin-shell.
Что это даёт пользователю?
- Разделение функционала на плагины делает базовую установку Poetry легче и менее загромождённой.

2. `poetry lock` по умолчанию использует `--no-update`

Что изменилось?
Команда poetry lock больше не обновляет зависимости по умолчанию. Если вы хотите полностью перегенерировать lock-файл, необходимо явно указать --regenerate.