Зачем нужен poetry?

Poetry — управление зависимостями Python

Poetry — это современный инструмент для управления проектами на Python. Он решает проблемы с зависимостями, версионированием и распределением пакетов.

Проблемы без Poetry

С pip и requirements.txt (старый способ)

# requirements.txt
Django==4.0.0
django-rest-framework==3.13.0
celery==5.2.0
redis==4.1.0

# Проблемы:
# 1. Конфликты версий
requests==2.27.0  # django требует requests >= 2.25.0
some-package==1.0  # но требует requests < 2.27.0
# → Невозможно установить обе!

# 2. Нет информации о зависимостях зависимостей
# pip install -r requirements.txt
# Что установилось? На какие версии?

# 3. Перегенерация requirements.txt вручную
# Добавил пакет → обнови requirements.txt
# Удалил пакет → обнови requirements.txt
# Легко забыть неиспользуемый пакет

# 4. Разделение dev и production зависимостей сложное
# requirements-dev.txt и requirements.txt вручную

Решение: Poetry

Poetry автоматически управляет зависимостями

# Инициализация проекта
poetry new my-project
# или в существующем проекте
poetry init

# Добавить зависимость
poetry add django
# Или конкретную версию
poetry add "django>=4.0,<5.0"

# Добавить dev-зависимость
poetry add --group dev pytest pytest-cov black

# Удалить зависимость
poetry remove django

# Создать lock файл (фиксирует точные версии)
poetry lock

# Установить все зависимости
poetry install

# Запустить скрипт в виртуальном окружении
poetry run python manage.py runserver
poetry run pytest

# Проверить конфликты
poetry check

Структура проекта с Poetry

pyproject.toml — главный файл конфигурации

[tool.poetry]
name = "my-project"
version = "0.1.0"
description = "Мой проект на Python"
authors = ["Alice <alice@example.com>"]

[tool.poetry.dependencies]
python = "^3.10"  # Поддержка Python 3.10 и выше
django = "^4.0"
django-rest-framework = "^3.13"
celery = "^5.2"

[tool.poetry.group.dev.dependencies]
pytest = "^7.0"
pytest-cov = "^4.0"
black = "^23.0"
flake8 = "^6.0"

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

poetry.lock — фиксирует точные версии для воспроизводимости

django==4.0.5
django-rest-framework==3.13.1
celery==5.2.3
kombu==5.2.4  # Зависимость celery

Практический пример

# 1. Создать проект
poetry new blog-api
cd blog-api

# 2. Добавить основные зависимости
poetry add fastapi uvicorn sqlalchemy psycopg2-binary pydantic-settings

# 3. Добавить dev зависимости
poetry add --group dev pytest pytest-asyncio black ruff mypy

# 4. Проверить проект
poetry check

# 5. Установить зависимости
poetry install

# 6. Запустить код
poetry run python main.py
poetry run pytest
poetry run black .
poetry run ruff check .

Версионирование с Poetry

[tool.poetry.dependencies]
python = "^3.10"  # >= 3.10, < 4.0

# Точная версия
requests = "2.28.1"

# Минимальная версия
celery = ">5.0"

# Диапазон
django = ">=4.0,<5.0"

# Совместимая версия (caret)
fastapi = "^0.100"  # >= 0.100, < 0.200

# Совместимая версия (tilde)
uvicorn = "~0.23"   # >= 0.23, < 0.24

# Исключить версию
pandas = "!=1.5.0"

Групповые зависимости

[tool.poetry]
name = "my-api"

[tool.poetry.dependencies]
python = "^3.10"
fastapi = "^0.100"
uvicorn = "^0.23"

# Dev группа
[tool.poetry.group.dev.dependencies]
pytest = "^7.0"
black = "^23.0"

# Test группа
[tool.poetry.group.test.dependencies]
pytest-cov = "^4.0"
pytest-asyncio = "^0.21"

# Docs группа
[tool.poetry.group.docs.dependencies]
sphinx = "^5.0"
sphinx-rtd-theme = "^1.0"

# Установить только основные зависимости
poetry install --no-dev

# Установить основные + dev
poetry install

# Установить основные + test
poetry install --with test

# Установить основные + docs
poetry install --with docs

Виртуальное окружение

# Poetry автоматически создает окружение
# Путь к окружению
poetry env info

# Список всех окружений
poetry env list

# Удалить окружение
poetry env remove python3.10

# Переключиться на другую версию Python
poetry env use python3.11

# Активировать shell
poetry shell
# Теперь можешь использовать python и pip как обычно

Скрипты в pyproject.toml

[tool.poetry.scripts]
myapp = "my_project.main:cli"  # poetry run myapp

[tool.poetry.scripts]
start = "uvicorn main:app --reload"
test = "pytest --cov"
lint = "black . && ruff check ."
migrate = "alembic upgrade head"

poetry run start
poetry run test
poetry run lint

Публикация пакета

# Обновить версию
poetry version minor  # 0.1.0 → 0.2.0
poetry version 0.2.1  # Конкретная версия

# Создать dist файлы
poetry build
# Создает dist/my-project-0.2.0.tar.gz и dist/my-project-0.2.0-py3-none-any.whl

# Опубликовать на PyPI
poetry publish

# Опубликовать на другой репозиторий
poetry publish --repository custom-repo

Практический пример: FastAPI проект

[tool.poetry]
name = "fastapi-blog"
version = "0.1.0"
description = "Blog API на FastAPI"
authors = ["Alice <alice@example.com>"]
readme = "README.md"

[tool.poetry.dependencies]
python = "^3.10"
fastapi = "^0.100"
uvicorn = {extras = ["standard"], version = "^0.23"}
sqlalchemy = "^2.0"
psycopg2-binary = "^2.9"
pydantic-settings = "^2.0"
python-dotenv = "^1.0"

[tool.poetry.group.dev.dependencies]
pytest = "^7.0"
pytest-asyncio = "^0.21"
black = "^23.0"
ruff = "^0.1"
mypy = "^1.0"
ipython = "^8.0"

[tool.poetry.group.test.dependencies]
pytest-cov = "^4.0"
faker = "^18.0"
factory-boy = "^3.2"

[tool.poetry.scripts]
dev = "uvicorn main:app --reload"
test = "pytest --cov=src"
lint = "ruff check . && black --check ."
format = "black . && ruff check . --fix"

[tool.black]
line-length = 88
target-version = ["py310"]

[tool.ruff]
line-length = 88
select = ["E", "F", "W"]

[tool.mypy]
python_version = "3.10"
strict = true

# Разработка
poetry run dev

# Тестирование
poetry run test

# Проверка кода
poetry run lint

# Форматирование
poetry run format

Сравнение: pip vs Poetry

Миграция с pip на Poetry

# Если есть requirements.txt
pip freeze > requirements.txt

# Инициализировать Poetry
poetry init

# Добавить зависимости из requirements.txt
while read package; do
  poetry add "$package"
done < requirements.txt

# Или вручную скопировать в pyproject.toml

Лучшие практики

# 1. Всегда коммитить pyproject.toml и poetry.lock
git add pyproject.toml poetry.lock
git commit -m "Add new dependencies"

# 2. Регулярно обновлять зависимости
poetry update  # Обновить all в рамках версионирования
poetry show --outdated  # Посмотреть устаревшие пакеты

# 3. Разделять dev и production
# Dev используются только при разработке
poetry add --group dev pytest black

# 4. Проверять конфликты
poetry check

# 5. Использовать точные версии в production
# pyproject.toml отправляется в git
# poetry.lock обеспечивает воспроизводимость

Вывод

Poetry — это современный стандарт управления Python проектами:

✓ Автоматическое управление зависимостями ✓ Воспроизводимые сборки (lock файл) ✓ Разделение dev/production зависимостей ✓ Встроенное управление виртуальным окружением ✓ Легкая публикация пакетов ✓ Поддержка всех современных стандартов

Любой новый Python проект должен использовать Poetry вместо pip и requirements.txt.