Aprenda Poetry em Python: gerenciamento de dependencias, ambientes virtuais, publicacao de pacotes, pyproject.toml e boas praticas para projetos modernos.

Poetry: O que É e Como Funciona | Python Brasil | Python Brasil

O que e Poetry?

Poetry e uma ferramenta moderna de gerenciamento de dependencias e empacotamento para projetos Python. Ela resolve varios problemas historicos do ecossistema Python ao unificar em uma unica ferramenta a gestao de dependencias, ambientes virtuais, build e publicacao de pacotes. Em vez de lidar com pip, virtualenv, setup.py e requirements.txt separadamente, o Poetry centraliza tudo no arquivo pyproject.toml.

Poetry garante builds reprodutiveis atraves do arquivo poetry.lock, que registra as versoes exatas de todas as dependencias e sub-dependencias instaladas.

Instalacao

# Instalacao recomendada (via pipx)
# pipx install poetry

# Ou via script oficial
# curl -sSL https://install.python-poetry.org | python3 -

# Verificar instalacao
# poetry --version

# Configurar para criar virtualenv dentro do projeto
# poetry config virtualenvs.in-project true

Criando um Projeto

# Criar novo projeto
# poetry new meu-projeto

# Estrutura gerada:
# meu-projeto/
#   pyproject.toml
#   README.md
#   meu_projeto/
#     __init__.py
#   tests/
#     __init__.py

# Ou inicializar em projeto existente
# cd projeto-existente
# poetry init

O Arquivo pyproject.toml

# pyproject.toml
# [tool.poetry]
# name = "minha-api"
# version = "1.0.0"
# description = "API REST para gerenciamento de tarefas"
# authors = ["Ana Silva <ana@email.com>"]
# license = "MIT"
# readme = "README.md"
# packages = [{include = "minha_api"}]
#
# [tool.poetry.dependencies]
# python = "^3.11"
# fastapi = "^0.109.0"
# uvicorn = {version = "^0.27.0", extras = ["standard"]}
# sqlalchemy = "^2.0"
# pydantic = "^2.5"
#
# [tool.poetry.group.dev.dependencies]
# pytest = "^8.0"
# pytest-cov = "^4.1"
# black = "^24.1"
# mypy = "^1.8"
# ruff = "^0.2"
#
# [tool.poetry.scripts]
# minha-api = "minha_api.cli:main"
#
# [build-system]
# requires = ["poetry-core"]
# build-backend = "poetry.core.masonry.api"

Gerenciamento de Dependencias

# Adicionar dependencia
# poetry add fastapi
# poetry add sqlalchemy@^2.0
# poetry add "uvicorn[standard]"

# Adicionar dependencia de desenvolvimento
# poetry add --group dev pytest black mypy

# Remover dependencia
# poetry remove flask

# Atualizar dependencias
# poetry update              # atualiza todas
# poetry update fastapi      # atualiza apenas fastapi

# Ver dependencias instaladas
# poetry show
# poetry show --tree          # arvore de dependencias
# poetry show --outdated      # dependencias desatualizadas

# Instalar dependencias do lock file
# poetry install              # todas
# poetry install --without dev  # sem dependencias de desenvolvimento

Ambiente Virtual

# Poetry cria e gerencia o virtualenv automaticamente

# Ver informacoes do ambiente
# poetry env info

# Ativar o shell do virtualenv
# poetry shell

# Executar comando no virtualenv sem ativar
# poetry run python script.py
# poetry run pytest
# poetry run uvicorn main:app --reload

# Listar ambientes virtuais
# poetry env list

# Remover ambiente virtual
# poetry env remove python3.11

# Usar versao especifica do Python
# poetry env use python3.12

Scripts e Comandos

# Definir scripts no pyproject.toml
# [tool.poetry.scripts]
# minha-cli = "minha_api.cli:main"
# servidor = "minha_api.server:start"

# arquivo: minha_api/cli.py
import argparse

def main():
    """Ponto de entrada da CLI."""
    parser = argparse.ArgumentParser(description='Minha API CLI')
    parser.add_argument('comando', choices=['iniciar', 'migrar', 'seed'])
    args = parser.parse_args()

    if args.comando == 'iniciar':
        print('Iniciando servidor...')
    elif args.comando == 'migrar':
        print('Executando migrations...')
    elif args.comando == 'seed':
        print('Populando banco de dados...')

# Apos `poetry install`, o comando fica disponivel:
# minha-cli iniciar

O Arquivo poetry.lock

# O poetry.lock garante reproducibilidade

# Gerar/atualizar o lock file
# poetry lock

# Instalar exatamente as versoes do lock
# poetry install

# IMPORTANTE: commite o poetry.lock no controle de versao!
# Isso garante que todos os desenvolvedores e ambientes
# de deploy usem exatamente as mesmas versoes.

# Verificar integridade
# poetry check

Publicacao de Pacotes

# Build do pacote
# poetry build
# Gera dist/minha_api-1.0.0.tar.gz e dist/minha_api-1.0.0-py3-none-any.whl

# Configurar repositorio (PyPI)
# poetry config pypi-token.pypi meu-token-do-pypi

# Publicar no PyPI
# poetry publish

# Build e publicar em um unico comando
# poetry publish --build

# Publicar em repositorio privado
# poetry config repositories.meu-repo https://meu-pypi.empresa.com/simple/
# poetry publish -r meu-repo

Configuracao de Ferramentas no pyproject.toml

# O pyproject.toml tambem configura outras ferramentas

# [tool.pytest.ini_options]
# testpaths = ["tests"]
# python_files = "test_*.py"
# addopts = "-v --cov=minha_api --cov-report=term-missing"
#
# [tool.black]
# line-length = 88
# target-version = ['py311']
#
# [tool.mypy]
# python_version = "3.11"
# strict = true
# warn_return_any = true
#
# [tool.ruff]
# line-length = 88
# select = ["E", "F", "I", "N", "W"]

Migrando de pip/requirements.txt

# Importar requirements.txt existente
# cat requirements.txt | xargs poetry add

# Script para migrar
import subprocess

def migrar_requirements(arquivo: str = 'requirements.txt'):
    """Migra dependencias de requirements.txt para Poetry."""
    with open(arquivo) as f:
        deps = [
            linha.strip()
            for linha in f
            if linha.strip() and not linha.startswith('#')
        ]

    for dep in deps:
        print(f'Adicionando: {dep}')
        subprocess.run(['poetry', 'add', dep])

# Exportar para requirements.txt (compatibilidade)
# poetry export -f requirements.txt -o requirements.txt --without-hashes

Erros Comuns

O erro mais frequente e nao committar o poetry.lock no repositorio, perdendo a garantia de reproducibilidade. Outro erro e misturar pip install com poetry add, instalando dependencias fora do controle do Poetry. Tambem e comum esquecer de executar poetry install apos clonar um repositorio, ou nao usar poetry run para executar scripts, usando o Python global em vez do ambiente virtual do projeto. Usar versoes de Python incompativeis com a restricao definida no pyproject.toml tambem gera erros.

Boas Praticas

Sempre commite o poetry.lock. Configure virtualenvs.in-project true para manter o virtualenv dentro do projeto. Use grupos de dependencias (dev, test, docs) para organizar dependencias. Exporte requirements.txt apenas para ambientes que exigem compatibilidade. Use poetry check para validar o pyproject.toml. Mantenha as restricoes de versao razoaveis — ^ permite atualizacoes compativeis, ~ permite apenas patches.

Quando Usar

Poetry e recomendado para qualquer projeto Python novo, especialmente quando envolve trabalho em equipe, deploy em multiplos ambientes ou publicacao de pacotes. Para scripts simples e de uso pessoal, pip com venv pode ser suficiente. A curva de aprendizado do Poetry e rapida e os beneficios de reproducibilidade e organizacao compensam rapidamente o investimento inicial.

Poetry: O que É e Como Funciona | Python Brasil