Обновление 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.

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

1. Если вам нужны только стандартные возможности, замените tool.poetry.dependencies на project.dependencies.
2. Если вы используете специфичные для Poetry функции, можете дополнить project.dependencies дополнительной информацией в tool.poetry.dependencies.
3. Если ваш проект сильно полагается на возможности 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 будет просто проверять зафиксированные группы и маркеры, чтобы решить, какой пакет установить.

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

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

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

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

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

• Уменьшает вероятность случайного обновления зависимостей при создании lock-файла.
• Обеспечивает стабильность и предсказуемость работы с зависимостями.

3. poetry add --optional требует указания extra

Что изменилось? 
Теперь нельзя добавлять опциональные зависимости без явного указания extra. Это изменение связано с поддержкой секции project.

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

• Упрощает управление опциональными зависимостями и делает их использование более явным.

4. --directory/-C теперь меняет директорию

Что изменилось? 
Флаг --directory/-C теперь переключает текущую рабочую директорию вместо того, чтобы только указывать директорию как корень проекта. Старое поведение доступно через флаг --project/-P.

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

• Более логичное поведение команды, соответствующее ожиданиям пользователей.

5. Изменение поведения tool.poetry.include

Что изменилось? 
Теперь при использовании tool.poetry.include без указания формата, Poetry по умолчанию включает только sdist. Ранее для каталогов использовался sdist, а для файлов — оба формата (sdist и wheel).

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

• Устраняет неоднозначность. Рекомендуется явно указывать форматы для включения.

6. Изменение настроек конфигурации

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

• Параметр experimental.system-git-client переименован в system-git-client.
• Параметр virtualenvs.prefer-active-python заменён на обратный virtualenvs.use-poetry-python (по умолчанию false), что изменяет стандартное поведение.
• Для миграции устаревших конфигураций добавлен флаг --migrate:
  bash poetry config --migrate

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

• Упрощает управление конфигурацией и обеспечивает более удобную миграцию старых настроек.

Список изменений

Добавлено:

• Добавлена поддержка секции project в файле pyproject.toml в соответствии с PEP 621.
• Возможность указания необходимых плагинов Poetry, которые автоматически устанавливаются, если их нет.
• Фиксация результирующих маркеров и групп в файле блокировки, а также добавлен параметр installer.re-resolve (по умолчанию: true) для установки без повторного разрешения зависимостей.
• Добавлена опция --local-version для команды poetry build.
• Добавлена опция --clean для команды poetry build.
• Поддержка FIPS для команды poetry publish.
• Возможность использования команды poetry new в интерактивном режиме с настройкой дополнительных полей.
• Добавлен параметр конфигурации installer.only-binary для принудительного использования двоичных форматов распространения.
• Поддержка команды poetry search для устаревших источников.
• Возможность возобновления загрузки после обрыва соединения.
• Опция для указания ограничения версии Poetry, необходимой для управления проектом.
• Добавлена опция --all-groups для команды poetry install.
• Добавлена команда poetry env activate как замена poetry shell.
• Добавлена опция --markers для команды poetry add для добавления зависимости с маркерами.
• Добавлена опция --migrate для команды poetry config для миграции устаревших конфигураций.
• Добавлена опция --project для поиска файла pyproject.toml в другой директории без смены текущей директории.
• Поддержка сокращённых хэшей для указания зависимостей из репозиториев Git.
• Частичная поддержка конфликтующих дополнений (extras).
• Добавлена команда poetry sync как замена poetry install --sync.

Изменено

• Изменено поведение по умолчанию команды poetry lock на --no-update, добавлена опция --regenerate для старого поведения.
• Убрана зависимость от плагина poetry-plugin-export, теперь команда poetry export не включена по умолчанию.
• Команда poetry shell вынесена в отдельный плагин poetry-plugin-shell.
• Интерфейс команды poetry add --optional изменён: теперь для добавления опциональной зависимости требуется указать дополнительную группу.
• Опция --directory/-C теперь действительно меняет рабочую директорию.
• Прекращена поддержка Python 3.8.
• Переименован параметр experimental.system-git-client в experimental.system-git.
• Параметр virtualenvs.prefer-active-python заменён на противоположный virtualenvs.use-poetry-python, при этом активная версия Python используется по умолчанию.
• Устаревшие поля в секции tool.poetry объявлены устаревшими в пользу аналогичных полей в секции project файла pyproject.toml.
• Команда poetry install --sync объявлена устаревшей, рекомендуется использовать poetry sync.
• Предупреждение о невозможности установки текущего проекта повышено до уровня ошибки.
• Удалена специальная обработка для platformdirs 2.0 на macOS.
• Оптимизированы сборки PEP 517.
• Poetry теперь используется вместо pip для управления зависимостями в изолированных окружениях сборки.
• Учёт пустых Requires-Dist при использовании современной метаинформации.
• Теперь зависимости определяются через сборки PEP 517, а не парсинг setup.py.
• Прекращена поддержка чтения файлов блокировки, созданных до версии 1.0 (Poetry до версии 1.1).
• Установлено значение >= вместо ^ для требования к версии Python при инициализации нового проекта.
• При инициализации нового проекта ограничение build-system установлено на текущую основную версию poetry-core.
• Удалён механизм установки через pip (параметр installer.modern-installation = false).
• Параметр virtualenvs.options.no-setuptools удалён, теперь setuptools никогда не включается по умолчанию.
• Исключения переименованы с добавлением суффикса Error.
• Удалены устаревшие опции CLI и методы, при этом параметр --dev больше не считается устаревшим.
• Установленные пакеты игнорируются при разрешении зависимостей.
• Улучшено сообщение об ошибке при неудачной загрузке.
• Сообщение об ошибке установки проекта теперь содержит дополнительную причину.
• Улучшен вывод команды poetry show <package>.
• Улучшено сообщение об ошибке сборки.
• Улучшено сообщение об ошибке при попытке удалить пакет без зависимостей.
• Убрана прямая зависимость от crashtest.
• Требуется версия keyring>=23.3.1.
• Требуется версия build>=1.2.1.
• Требуется версия dulwich>=0.22.6.

Исправлено

• Исправлена ошибка, из-за которой зависимости Git с extras можно было клонировать только при явном указании ветки.
• Исправлена ошибка, из-за которой команда poetry env remove завершалась с ошибкой, если virtualenvs.in-project был установлен в true.
• Исправлена ошибка блокировки пакетов, чьё имя оканчивалось на цифру и имело нестандартные имена sdist.
• Исправлена ошибка, из-за которой учетные данные не передавались при загрузке URL-зависимости.
• Исправлена ошибка, из-за которой использование нестандартных имён групп в poetry add приводило к повреждению файла pyproject.toml.
• Исправлена ошибка, из-за которой в файле envs.toml сохранялись некорректные записи о версии Python.
• Исправлена ошибка неправильного разрешения относительных путей при использовании poetry build --directory.
• Исправлена ошибка, из-за которой неиспользуемые extras не удалялись при выполнении poetry install без существующего lock-файла.
• Исправлена ошибка, из-за которой pre-commit хук poetry-check не срабатывал при изменении только файла poetry.lock.
• Исправлена ошибка, из-за которой файлы (а не директории) не могли быть добавлены как одиночный источник.
• Исправлена ошибка, из-за которой создавались некорректные ограничения при добавлении пакета с локальной спецификацией версии.
• Исправлены несколько предупреждений о кодировке.
• Исправлена ошибка, из-за которой параметр virtualenvs.prefer-active-python не учитывался.
• Исправлена ошибка, из-за которой окончания строк в lock-файле могли быть изменены.
• Исправлена ошибка, из-за которой установка нескольких зависимостей из одного Git-репозитория иногда завершалась сбоем из-за состояния гонки.
• Исправлена ошибка, из-за которой установка нескольких зависимостей из форкнутых монорепозиториев иногда завершалась сбоем из-за состояния гонки.
• Исправлена ошибка, из-за которой дополнительный пакет не устанавливался, если он требовался несколькими extras одновременно.
• Исправлена ошибка, из-за которой файл direct_url.json записывался с URL-адресами VCS, не соответствующими PEP 610.
• Исправлена ошибка, из-за которой файлы, отличные от wheels, ошибочно распознавались как wheels.
• Исправлена ошибка, из-за которой параметр installer.max-workers игнорировался для неявного источника PyPI.
• Исправлена ошибка, из-за которой локальные настройки (poetry.toml) игнорировались для неявного источника PyPI.
• Исправлена ошибка, из-за которой разные версии dulwich приводили к разным хэшам зависимости Git, основанной на теге.
• Исправлена ошибка, из-за которой установка отозванного пакета без зависимостей завершалась сбоем IndexError.
• Исправлена ошибка, из-за которой пакет не мог быть добавлен из источника, требующего пустой пароль.
• Исправлена ошибка, из-за которой параметр allow-prereleases = false всё равно разрешал предварительные версии, если не было найдено других решений.
• Исправлена ошибка, из-за которой для проверки, является ли установленный пакет частью системных пакетов, использовалась неверная среда.
• Исправлена ошибка, из-за которой ошибки сборки, возникающие при извлечении метаданных, скрывались.
• Исправлена ошибка, из-за которой команда poetry check ошибочно сообщала, что в зависимостях ссылается на недействительный источник "pypi".
• Исправлена ошибка, из-за которой команда poetry install --sync пыталась удалить системные пакеты, если виртуальное окружение было создано с параметром virtualenvs.options.system-site-packages = true.
• Исправлена ошибка, из-за которой HTTP-запросы с потоковой передачей данных не закрывались корректно, если не были полностью обработаны.

Документация

• Добавлена информация о получении покрытия тестов в руководстве по вкладу в проект.
• Упомянута утилита pre-commit-autoupdate как альтернатива pre-commit autoupdate.
• Улучшено объяснение параметров exclude и include.
• Добавлена информация о совместимых требованиях к релизам (например, ~=).
• Добавлена документация по использованию скриптов сборки для создания модулей расширения.

poetry-core (2.0.0)

Добавлено

• Поддержка версий, не соответствующих PEP440, в маркере platform_release.
• Поддержка строковых сравнений с использованием in / not in в общих ограничениях.
• Поддержка скриптовых файлов, создаваемых с помощью скрипта сборки.
• Поддержка переменной SOURCE_DATE_EPOCH при сборке пакетов.
• Создание файлов METADATA версии 2.3 вместо 2.2.

Удалено

• Убрана поддержка x в ограничениях версий.
• Убрана поддержка скриптов с extras.
• Удалены устаревшие функции и интерфейсы.

Устарело

• Поле tool.poetry.dev-dependencies объявлено устаревшим в пользу tool.poetry.group.dev.dependencies.

Исправлено

• Исправлена проблема, из-за которой использовалась директория platlib от неправильной версии Python.
• Исправлена ошибка при сборке колеса в вложенной выходной директории.
• Исправлена ошибка, из-за которой символ + был запрещён в путях URL-адресов git.
• Исправлена проблема с очисткой временной директории при ошибке.
• Исправлено слишком строгое регулярное выражение для имён авторов.
• Исправлена ошибка, из-за которой не удавалось разобрать HTTP(S)-учётные данные для базовой аутентификации.