Poetry: современный менеджер зависимостей и виртуальных окружений для Python

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

В этой статье вы научитесь:

• Устанавливать и настраивать Poetry
• Создавать и управлять виртуальными окружениями
• Управлять зависимостями с точным контролем версий
• Использовать основные команды Poetry для работы с проектами
• Структурировать проекты с помощью pyproject.toml
• Интегрировать Poetry с различными IDE и инструментами

Почему Poetry лучше стандартных инструментов?

Стандартные инструменты Python (pip, venv, requirements.txt) имеют несколько недостатков:

• Неоднозначность версий: requirements.txt не всегда точно фиксирует версии зависимостей и их подзависимостей
• Ручное управление: создание виртуального окружения, активация, установка зависимостей — много ручных шагов
• Отсутствие разделения: нет встроенного разделения на production и development зависимости
• Отсутствие метаданных проекта: нет централизованного места для описания проекта

Poetry решает эти проблемы и предоставляет дополнительные преимущества:

• Детерминированная сборка: фиксирует точные версии всех зависимостей в poetry.lock
• Автоматическое управление виртуальными окружениями: Poetry создает и управляет виртуальными окружениями автоматически
• Современный формат конфигурации: использует стандарт pyproject.toml вместо множества файлов
• Встроенная поддержка публикации пакетов: легко публиковать свои пакеты в PyPI
• Интуитивный CLI: понятные команды для всех операций

Установка Poetry

Существует несколько способов установки Poetry. Рекомендуется использовать официальный установщик для обеспечения изоляции и корректного обновления.

Официальный установщик (рекомендуется)

Для Windows:

(Invoke-WebRequest -Uri https://install.python-poetry.org/ -UseBasicParsing).Content | python -

Для Linux/macOS:

curl -sSL https://install.python-poetry.org | python3 -

Результат выполнения в терминале:

Retrieving Poetry metadata

# Welcome to Poetry!

This will download and install the latest version of Poetry,
a dependency and package manager for Python.

It will add the `poetry` command to Poetry's bin directory, located at:

$HOME/.local/bin

You can uninstall at any time by executing this script with the --uninstall option,
and these changes will be reverted.

Installing Poetry (1.7.1): Done

Poetry (1.7.1) is installed now. Great!

To get started you need Poetry's bin directory ($HOME/.local/bin) in your PATH
environment variable.

Alternatively, you can call Poetry explicitly with $HOME/.local/bin/poetry.

Проверка установки

После установки проверьте версию Poetry:

poetry --version

Результат выполнения в терминале:

Poetry (version 1.7.1)

Альтернативные методы установки

Хотя официальный установщик является предпочтительным, можно использовать и другие методы:

# Установка через pip (не рекомендуется для глобальной установки)
pip install poetry

# Установка через pipx (рекомендуется, если вы предпочитаете pipx)
pipx install poetry

Инициализация нового проекта

Создание нового проекта с Poetry начинается с инициализации. Эта команда создаст файл pyproject.toml с метаданными проекта.

Запуск инициализации

poetry init

Результат выполнения в терминале:

This command will guide you through creating your pyproject.toml config.

Package name [my-project]: my-awesome-app
Version [0.1.0]:
Description: My first Poetry project
Author [Alex Smith <Адрес электронной почты защищен от спам-ботов. Для просмотра адреса в браузере должен быть включен Javascript.>, n to skip]: Maria Johnson <Адрес электронной почты защищен от спам-ботов. Для просмотра адреса в браузере должен быть включен Javascript.>
License [MIT]:
Compatible Python versions [^3.8]: ^3.9

Would you like to define your main dependencies interactively? (yes/no) [no] no
Would you like to define your development dependencies interactively? (yes/no) [no] no

Do you confirm generation? (yes/no) [yes] yes

Результат инициализации

В результате будет создан файл pyproject.toml со следующим содержимым:

[tool.poetry]
name = "my-awesome-app"
version = "0.1.0"
description = "My first Poetry project"
authors = ["Maria Johnson <Адрес электронной почты защищен от спам-ботов. Для просмотра адреса в браузере должен быть включен Javascript.>"]
license = "MIT"
readme = "README.md"
packages = [{include = "my_awesome_app"}]

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

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

Разберем структуру файла:

• [tool.poetry] — основные метаданные проекта
• [tool.poetry.dependencies] — зависимости для production
• [build-system] — настройки сборки пакета

Основные команды Poetry

Poetry предоставляет множество команд для управления проектами. Рассмотрим самые важные из них.

poetry install

Команда poetry install устанавливает все зависимости, указанные в pyproject.toml, создает виртуальное окружение и устанавливает проект в режиме разработки.

poetry install

Особенности команды:

• Если файл poetry.lock существует, зависимости будут установлены с версиями, указанными в нем
• Если файл poetry.lock отсутствует, Poetry создаст его автоматически
• По умолчанию устанавливаются и production, и development зависимости
• Для установки только production зависимостей: poetry install --no-dev

poetry update

Команда poetry update обновляет все зависимости до последних версий, разрешенных в pyproject.toml, и обновляет файл poetry.lock.

poetry update

Особенности команды:

• Обновляет все зависимости до последних версий в рамках заданных ограничений
• Обновляет файл poetry.lock с новыми версиями
• Для обновления конкретного пакета: poetry update package_name

poetry add

Команда poetry add добавляет новую зависимость в проект и обновляет файлы конфигурации.

poetry add requests

Особенности команды:

• Автоматически определяет последнюю версию пакета
• Добавляет зависимость в pyproject.toml
• Обновляет файл poetry.lock
• Устанавливает пакет в текущее виртуальное окружение

poetry remove

Команда poetry remove удаляет зависимость из проекта.

poetry remove requests

Особенности команды:

• Удаляет зависимость из pyproject.toml
• Обновляет файл poetry.lock
• Удаляет пакет из виртуального окружения

poetry show

Команда poetry show показывает информацию о зависимостях проекта.

poetry show

Результат выполнения в терминале:

fastapi          0.103.2 The ultimate Python web framework.
pydantic         2.4.2   Data validation using Python type hints
starlette        0.27.0  The little ASGI framework that shines
typing-extensions 4.8.0  Backported and Experimental Type Hints for Python
uvicorn          0.23.2  The lightning-fast ASGI server

Полезные опции:

• --tree — показывает дерево зависимостей
• --outdated — показывает устаревшие пакеты
• --latest — показывает последние доступные версии
• --all — показывает все пакеты, включая development зависимости

poetry lock

Команда poetry lock генерирует или обновляет файл poetry.lock без установки зависимостей.

poetry lock

Особенности команды:

• Полезно при работе с CI/CD пайплайнами
• Гарантирует, что все разработчики используют одинаковые версии зависимостей
• С --no-update обновляет только хеш-суммы без изменения версий

poetry build

Команда poetry build собирает проект в формате wheel и source distribution.

poetry build

Результат выполнения:

Создает два файла в директории dist/:

• my_project-0.1.0-py3-none-any.whl — wheel дистрибутив
• my_project-0.1.0.tar.gz — source дистрибутив

poetry publish

Команда poetry publish публикует собранный пакет в PyPI или другой репозиторий.

poetry publish

Подготовка к публикации:

# Настройка учетных данных
poetry config pypi-token.pypi your-pypi-token

# Сборка и публикация
poetry build
poetry publish

Работа с зависимостями и версиями

Одна из сильных сторон Poetry — точный контроль над версиями зависимостей. Рассмотрим различные способы указания версий.

Семантическое версионирование в Poetry

Poetry использует семантическое версионирование (SemVer) для управления зависимостями. Основные операторы:

• ^1.2.3 — версии >=1.2.3, но <2.0.0
• ~1.2.3 — версии >=1.2.3, но <1.3.0
• >=1.2.3 — версии >=1.2.3
• >=1.2.3,<2.0 — версии в диапазоне от 1.2.3 до 2.0
• ==1.2.3 — точная версия 1.2.3
• * — любая версия

Примеры использования

# Точная версия
poetry add "django==3.2.18"

# Минимальная версия
poetry add "numpy>=1.21.0"

# Диапазон версий
poetry add "pandas>=1.3.0,<1.4.0"

# Совместимая версия (SemVer)
poetry add "requests^2.28.0"

# Точное соответствие major версии
poetry add "flask~2.2.0"

Работа с предрелизными версиями

Poetry поддерживает работу с предрелизными версиями (alpha, beta, rc):

# Установка конкретной предрелизной версии
poetry add "fastapi==0.100.0rc1"

# Установка любой предрелизной версии
poetry add "fastapi=0.100.0-rc1 --allow-prereleases"

# Установка последней версии, включая предрелизы
poetry add "fastapi@latest --allow-prereleases"

Управление версиями в pyproject.toml

После добавления зависимостей файл pyproject.toml содержит информацию о версиях:

[tool.poetry.dependencies]
python = "^3.9"
fastapi = "^0.103.2"
uvicorn = {extras = ["standard"], version = "^0.23.2"}
requests = ">=2.28.0,<3.0.0"
numpy = "==1.24.3"
pandas = {version = "^1.5.3", optional = true}

Файл poetry.lock

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

Пример фрагмента файла poetry.lock:

[[package]]
name = "fastapi"
version = "0.103.2"
description = "FastAPI framework, high performance, easy to learn, fast to code, ready for production"
category = "main"
optional = false
python-versions = ">=3.7"

[[package]]
name = "pydantic"
version = "2.4.2"
description = "Data validation using Python type hints"
category = "main"
optional = false
python-versions = ">=3.7"

# Зависимости pydantic
[package.dependencies]
annotated-types = ">=0.4.0,<0.7.0"
pydantic-core = "2.10.1"
typing-extensions = ">=4.6.0"

Правила работы с poetry.lock:

• Всегда добавляйте poetry.lock в Git для библиотек и приложений
• Не добавляйте poetry.lock в Git для пакетов, которые будут использоваться как зависимости
• Для обновления версий используйте poetry update, а не ручное редактирование файла

Управление группами зависимостей

Poetry поддерживает разделение зависимостей на группы, что позволяет различать production и development зависимости.

Добавление development зависимостей

poetry add pytest --group dev
poetry add black --group dev
poetry add mypy --group dev

Результат в pyproject.toml:

[tool.poetry.group.dev.dependencies]
pytest = "^7.4.4"
black = "^23.11.0"
mypy = "^1.7.1"

Работа с кастомными группами

Можно создавать кастомные группы зависимостей:

poetry add pytest --group test
poetry add sphinx --group docs

Запуск с определенными группами:

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

# Установка production + test зависимостей
poetry install --only main,test

# Установка только development зависимостей
poetry install --only dev

Работа с виртуальными окружениями

Poetry автоматически управляет виртуальными окружениями, но предоставляет команды для явного управления ими.

Активация виртуального окружения

Чтобы активировать виртуальное окружение, созданное Poetry:

poetry shell

Результат выполнения в терминале:

Spawning shell within /Users/maria/Library/Caches/pypoetry/virtualenvs/fastapi-app-5zX4i6vT-py3.8
. /Users/maria/Library/Caches/pypoetry/virtualenvs/fastapi-app-5zX4i6vT-py3.8/bin/activate
(fastapi-app-py3.8) $

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

Чтобы выполнить команду в виртуальном окружении без его активации:

poetry run uvicorn main:app --reload

Результат выполнения в терминале:

INFO:     Will watch for changes in these directories: ['D:\\projects\\fastapi-app']
INFO:     Uvicorn running on http://127.0.0.1:8000 (Press CTRL+C to quit)
INFO:     Started reloader process [12345] using StatReload
INFO:     Started server process [12346]
INFO:     Waiting for application startup.
INFO:     Application startup complete.

Просмотр информации об окружении

Чтобы узнать, где находится виртуальное окружение:

poetry env info

Результат выполнения в терминале:

Virtualenv
Python:         3.9.18
Implementation: CPython
Path:           /Users/maria/Library/Caches/pypoetry/virtualenvs/my-awesome-app-5zX4i6vT-py3.9
Executable:     /Users/maria/Library/Caches/pypoetry/virtualenvs/my-awesome-app-5zX4i6vT-py3.9/bin/python
Valid:          True

System
Platform:   darwin
OS:         posix
Python:     3.9.18
Path:       /Users/maria/.pyenv/versions/3.9.18
Executable: /Users/maria/.pyenv/versions/3.9.18/bin/python

Удаление виртуального окружения

Если нужно пересоздать виртуальное окружение:

poetry env remove python

Или для конкретной версии Python:

poetry env remove 3.9

Управление несколькими окружениями

Poetry позволяет работать с несколькими версиями Python в одном проекте:

# Просмотр доступных окружений
poetry env list

# Использование конкретной версии Python
poetry env use python3.9
poetry env use /path/to/python3.11

# Создание окружения для конкретной версии
poetry env use 3.10

Экспорт и импорт зависимостей

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

Экспорт в requirements.txt

Для экспорта всех зависимостей (включая подзависимости) в формат requirements.txt:

poetry export -f requirements.txt --output requirements.txt

Для экспорта только production-зависимостей:

poetry export -f requirements.txt --without-hashes --output requirements.txt

Для экспорта с development-зависимостями:

poetry export -f requirements.txt --dev --output requirements-dev.txt

Импорт из requirements.txt

Чтобы импортировать зависимости из существующего файла requirements.txt:

# Импорт всех зависимостей
cat requirements.txt | xargs poetry add

# Импорт development зависимостей
cat requirements-dev.txt | xargs poetry add --group dev

Практический пример: создание FastAPI проекта с Poetry

Давайте рассмотрим полный пример создания FastAPI-приложения с использованием Poetry.

Шаг 1: Инициализация проекта

mkdir fastapi-project
cd fastapi-project
poetry init

Ответьте на вопросы инициализатора. Результат — файл pyproject.toml.

Шаг 2: Добавление зависимостей

poetry add fastapi "uvicorn[standard]"
poetry add pydantic[email] --optional
poetry add requests
poetry add python-jose[cryptography] passlib[bcrypt] --optional

После этих команд файл pyproject.toml будет выглядеть примерно так:

[tool.poetry]
name = "fastapi-project"
version = "0.1.0"
description = ""
authors = ["Your Name <Адрес электронной почты защищен от спам-ботов. Для просмотра адреса в браузере должен быть включен Javascript.>"]
readme = "README.md"
packages = [{include = "fastapi_project"}]

[tool.poetry.dependencies]
python = "^3.9"
fastapi = "^0.103.2"
uvicorn = {extras = ["standard"], version = "^0.23.2"}
pydantic = {extras = ["email"], version = "^2.4.2", optional = true}
requests = "^2.31.0"
python-jose = {extras = ["cryptography"], version = "^3.3.0", optional = true}
passlib = {extras = ["bcrypt"], version = "^1.7.4", optional = true}

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

Шаг 3: Создание структуры проекта

mkdir fastapi_project
touch fastapi_project/__init__.py
touch fastapi_project/main.py
mkdir fastapi_project/api
touch fastapi_project/api/__init__.py
touch fastapi_project/api/items.py
touch fastapi_project/api/users.py

Шаг 4: Написание кода приложения

Файл fastapi_project/api/items.py:

from fastapi import APIRouter
from typing import List, Dict, Any

router = APIRouter(tags=['items'])

@router.get('/')
def items_list() -> Dict[str, List[Dict[str, Any]]]:
    return {
        "items": [
            {"id": 1, "name": "foobar"},
            {"id": 2, "name": "spam-and-eggs"},
        ]
    }

@router.post('/')
def create_item(name: str, data: Dict[str, Any]) -> Dict[str, Any]:
    return {
        "data": data,
        "name": name
    }

@router.get('/{item_id}/')
def get_item(item_id: int) -> Dict[str, Dict[str, Any]]:
    return {
        "data": {
            "id": item_id,
            "name": f"item-{item_id}"
        }
    }

Файл fastapi_project/main.py:

from fastapi import FastAPI
import uvicorn
from .api.items import router as items_router

app = FastAPI(title="FastAPI Project", version="1.0.0")

app.include_router(items_router, prefix="/items")

@app.get("/")
def index():
    return {"message": "Hello Index!"}

@app.get("/hello/")
def hello(name: str = "World"):
    return {"message": f"Hello {name}"}

if __name__ == "__main__":
    uvicorn.run("fastapi_project.main:app", host="0.0.0.0", port=8000, reload=True)

Шаг 5: Запуск приложения

poetry run python -m fastapi_project.main

Результат выполнения в терминале:

INFO:     Will watch for changes in these directories: ['/Users/maria/projects/fastapi-project']
INFO:     Uvicorn running on http://0.0.0.0:8000 (Press CTRL+C to quit)
INFO:     Started reloader process [12345] using StatReload
INFO:     Started server process [12346]
INFO:     Waiting for application startup.
INFO:     Application startup complete.

Шаг 6: Добавление инструментов разработки

poetry add pytest httpx --group dev
poetry add black isort mypy --group dev

Теперь можно писать тесты и запускать их:

poetry run pytest
poetry run black .
poetry run mypy fastapi_project

Интеграция с IDE

VS Code

Для интеграции с VS Code установите расширение "Python" и добавьте следующие настройки в .vscode/settings.json:

{
    "python.pythonPath": ".venv/bin/python",
    "python.formatting.provider": "black",
    "python.linting.enabled": true,
    "python.linting.pylintEnabled": false,
    "python.linting.flake8Enabled": true,
    "python.linting.mypyEnabled": true,
    "python.testing.pytestEnabled": true,
    "python.testing.unittestEnabled": false,
    "python.testing.nosetestsEnabled": false,
    "terminal.integrated.env.linux": {
        "PATH": "${workspaceFolder}/.venv/bin:${env:PATH}"
    },
    "terminal.integrated.env.osx": {
        "PATH": "${workspaceFolder}/.venv/bin:${env:PATH}"
    },
    "terminal.integrated.env.windows": {
        "PATH": "${workspaceFolder}\\.venv\\Scripts;${env:PATH}"
    }
}

PyCharm

В PyCharm:

1. Выберите File → Settings → Project → Python Interpreter
2. Нажмите на шестеренку → Add
3. Выберите "Poetry Environment"
4. Укажите путь к файлу pyproject.toml
5. PyCharm автоматически создаст и настроит виртуальное окружение

GitHub Actions

Пример конфигурации GitHub Actions для Poetry-проекта:

name: CI

on:
  push:
    branches: [ main ]
  pull_request:
    branches: [ main ]

jobs:
  test:
    runs-on: ubuntu-latest
    steps:
    - uses: actions/checkout@v4
    
    - name: Set up Python
      uses: actions/setup-python@v4
      with:
        python-version: "3.11"
    
    - name: Install Poetry
      run: pipx install poetry
    
    - name: Install dependencies
      run: poetry install --no-interaction
    
    - name: Run tests
      run: poetry run pytest
    
    - name: Run linting
      run: poetry run black --check . && poetry run mypy .

Чек-лист для проверки усвоения материала

Практическое задание для закрепления

1. Создайте виртуальное окружение для нового проекта с помощью Poetry:
   • Инициализируйте проект с помощью poetry init
   • Заполните метаданные (имя, описание, автора, лицензию)
   • Добавьте зависимости: fastapi и uvicorn[standard]
   • Добавьте development-зависимости: pytest, black, mypy
2. Работа с версиями:
   • Добавьте requests с точной версией 2.31.0
   • Добавьте numpy с ограничением >=1.24.0,<2.0.0
   • Просмотрите дерево зависимостей с помощью poetry show --tree
   • Обновите все зависимости до последних версий с помощью poetry update
3. Создайте тесты:
   • Напишите несколько unit-тестов для вашего приложения
   • Запустите тесты с помощью poetry run pytest
   • Проверьте типы с помощью poetry run mypy .
   • Отформатируйте код с помощью poetry run black .
4. Экспорт и интеграция:
   • Экспортируйте production-зависимости в requirements.txt
   • Создайте GitHub Actions workflow для автоматического тестирования
   • Настройте интеграцию с вашей IDE (VS Code или PyCharm)

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

Совет: Используйте Poetry для всех своих новых проектов, даже небольших. Привычка работать с современными инструментами значительно упростит вашу жизнь при переходе к большим и сложным проектам. Всегда коммитьте файл poetry.lock в Git — это гарантирует воспроизводимость сборки на всех машинах.

Удачной разработки!