Перейти к содержимому

Борьба с Poetry 2.x: Как я настраивал проект для нормализации товарных позиций

Борьба с Poetry 2.x: Как я настраивал проект для нормализации товарных позиций

Практический опыт преодоления проблем миграции и настройки современного Python-проекта

Python 3.13 Poetry 2.x PyCharm Pro Enterprise-разработка Docker

Введение

При разработке системы нормализации товарных позиций по классификатору ОКПД2 я столкнулся с рядом проблем при настройке проекта с использованием Poetry 2.x. Несмотря на все декларируемые преимущества этого инструмента, переход с Poetry 1.x на 2.x принес неожиданные сложности, которые в итоге потребовали глубокого погружения в тонкости работы современного Python-тулчейна.

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

Контекст проекта

Цель проекта — создание production-готовой системы для нормализации товарных позиций с использованием гибридного подхода (правила + LLM). Проект включает:

  • Иерархическую обработку кодов ОКПД2 (маска XX.XX.X0)
  • Генерацию и применение шаблонов нормализации
  • Работу с PostgreSQL, Docker и FastAPI/CLI интерфейсами
  • Поддержку Python 3.13
  • Интеграцию с PyCharm Pro как основной IDE
Важно: Проект изначально разрабатывался с использованием Excel-скриптов, но требовал перехода на профессиональную инфраструктуру для production-развертывания.

Проблема 1: Несовместимость loguru с Python 3.13

Симптомы

При установке зависимостей через Poetry появлялась ошибка:

The current project's supported Python range (>=3.13) is not compatible with some of the required packages Python requirement:
- loguru requires Python <4.0,>=3.5

Решение

Явное указание совместимости через PEP 508 маркеры в pyproject.toml:

dependencies = [
    # ... другие зависимости
    "loguru (>=0.7.3,<0.8.0) ; python_version >= '3.13' and python_version < '4.0'"
]

Этот подход говорит Poetry: "Установи loguru только если версия Python находится в диапазоне 3.13-3.13.x".

Урок 1

Многие популярные пакеты еще не обновили метаданные для Python 3.13. Всегда проверяйте актуальную совместимость через PEP 508 маркеры при работе с новыми версиями Python.

Проблема 2: Отсутствие секции [tool.poetry] в Poetry 2.x

Симптомы

После создания README.md и попытки установки проекта:

Error: The current project could not be installed: No file/folder found for package okpd-normalizer

Решение

Добавление гибридной конфигурации в pyproject.toml:

[project]
name = "okpd-normalizer"
version = "0.1.0"
# ... остальные метаданные

[tool.poetry]
packages = [{include = "src"}]
Совет: Poetry 2.x поддерживает два формата конфигурации. Гибридный подход обеспечивает максимальную совместимость.

Проблема 3: Изменения в команде poetry lock

Симптомы

При использовании команды poetry lock --no-update:

The option "--no-update" does not exist

Решение

В Poetry 2.x была изменена логика работы команды:

  • poetry lock — не обновляет зависимости по умолчанию
  • poetry lock --update — обновляет зависимости
  • --no-update был удален как избыточный

Просто используйте poetry lock без дополнительных флагов.

Проблема 4: Структура проекта и установка локального пакета

Симптомы

После настройки pyproject.toml все равно возникали ошибки установки:

No file/folder found for package okpd-normalizer

Решение

1. Создание базовой структуры перед установкой:

mkdir src
echo.> src/__init__.py  # Windows
# или
touch src/__init__.py   # Linux/Mac

2. Пометить src/ как Sources Root в PyCharm Pro

3. Убедиться, что pyproject.toml содержит корректную секцию [tool.poetry]

Важно: В отличие от Poetry 1.x, версия 2.x требует явного создания структуры проекта перед установкой.

Проблема 5: Несовместимость форматов pyproject.toml

Итоговое решение

Использование гибридного подхода в pyproject.toml:

[project]
name = "okpd-normalizer"
version = "0.1.0"
description = ""
authors = [...]
readme = "README.md"
requires-python = ">=3.13"
dependencies = [...]

[build-system]
requires = ["poetry-core>=2.0.0,<3.0.0"]
build-backend = "poetry.core.masonry.api"

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

Выводы и рекомендации

Основные уроки

1. Проверяйте совместимость пакетов с Python 3.13

Многие пакеты еще не обновили метаданные. Используйте PEP 508 маркеры для явного указания совместимости при конфликтах.

2. Poetry 2.x требует гибридной конфигурации

[project] для зависимостей, [tool.poetry] для настроек Poetry — это обязательное сочетание для проектов с src/ layout.

3. Создавайте структуру проекта до установки

Особенно важно для проектов с src/ layout. Пустая директория src/ с __init__.py должна существовать до выполнения poetry install.

4. Изучайте изменения в CLI командах

Poetry 2.x упростила некоторые команды, но удалила устаревшие опции. poetry lock теперь работает без флагов по умолчанию.

Заключение

Настройка проекта с Poetry 2.x и Python 3.13 потребовала дополнительных усилий, но в результате я получил:

  • Четкое и предсказуемое управление зависимостями
  • Воспроизводимую среду разработки, готовую к CI/CD
  • Поддержку современных практик Python-разработки
  • Готовую к Docker-деплою конфигурацию

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

Технологии: Python 3.13, Poetry 2.x, PyCharm Pro, Docker

Категория: Backend разработка

Конспект:
Понедельник, 15 декабря 2025
Борьба с Poetry 2.x: Как я настраивал проект для нормализации товарных позиций