DEV Community

Cover image for Diga Adeus ao Caos: Gerenciando Dependências Python com Poetry
Carine Neris
Carine Neris

Posted on

Diga Adeus ao Caos: Gerenciando Dependências Python com Poetry

#python #poetry #webdev #ai

Você já se viu em um labirinto de requirements.txt desatualizados, venv que não ativam, e conflitos de dependência que parecem saídos de um filme de terror? Se a resposta é sim, respire fundo, porque seus problemas estão prestes a acabar (ou pelo menos, a ficar muito mais fácil de resolver!).

Hoje, vamos entrar no mundo mágico do Poetry [1], a ferramenta que veio para salvar nossos projetos do caos das dependências.

O Fim da Era do pip e venv Manual

Antes do Poetry, a vida era... rústica. Criávamos um venv na mão, ativávamos, rodávamos pip install -r requirements.txt, e torcíamos para que nada explodisse. E quando explodia, era uma caçada por versões compatíveis que podia durar horas.

O Poetry chega com uma proposta revolucionária: gerenciar tudo para você! Ele cuida das dependências, cria e gerencia seu ambiente virtual, e ainda garante que todos os seus colaboradores (e até seu servidor de produção) usem exatamente as mesmas versões de bibliotecas.

Primeiros Passos: Instalando o Poetry

Instalar o Poetry é moleza. Esqueça o pip install poetry (sim, é irônico, eu sei). A forma recomendada é usar o instalador oficial, que garante que o Poetry seja isolado do seu ambiente Python principal.

No Linux/macOS/WSL:

curl -sSL https://install.python-poetry.org | python3 -
Enter fullscreen mode Exit fullscreen mode

No Windows (PowerShell):

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

Após a instalação, você pode precisar adicionar o diretório de binários do Poetry ao seu PATH. O instalador geralmente te informa o caminho. Depois, reinicie seu terminal e digite poetry --version para confirmar que tudo está funcionando.

Iniciando um Projeto Poetry: A Magia Começa!

Para começar um novo projeto com Poetry, é tão simples quanto:

poetry new meu_projeto_incrivel
cd meu_projeto_incrivel
Enter fullscreen mode Exit fullscreen mode

Isso cria uma estrutura básica de projeto com um arquivo pyproject.toml, que é onde toda a mágica das dependências acontece. Se você já tem um projeto existente, pode inicializar o Poetry nele:

cd meu_projeto_existente
poetry init
Enter fullscreen mode Exit fullscreen mode

O poetry init fará algumas perguntas sobre seu projeto e criará o pyproject.toml para você.

O Coração do Projeto: pyproject.toml

Este arquivo é o seu manifesto. Ele substitui o requirements.txt, setup.py, setup.cfg e MANIFEST.in (ufa!). Aqui você define metadados do projeto, dependências e até scripts. Veja um exemplo simplificado:

# pyproject.toml

[tool.poetry]
name = "meu-projeto-incrivel"
version = "0.1.0"
description = "Um projeto Python que vai mudar o mundo!"
authors = ["Seu Nome <seu.email@example.com>"]
readme = "README.md"

[tool.poetry.dependencies]
python = "^3.9" # Versão do Python que seu projeto usa
requests = "^2.28.1" # Uma dependência de produção
fastapi = "^0.100.0"
uvicorn = {extras = ["standard"], version = "^0.23.2"}

[tool.poetry.group.dev.dependencies]
pytest = "^7.4.0" # Uma dependência de desenvolvimento
ipdb = "^0.13.13"

[build-system]
requires = ["poetry-core"]
build-backend = "poetry.core.masonry.api"
Enter fullscreen mode Exit fullscreen mode

Gerenciando Dependências: Adicionar, Remover, Atualizar

Adicionando Novas Bibliotecas

Para adicionar uma nova dependência de produção (aquela que seu código precisa para rodar em produção), use poetry add:

poetry add requests
# Ou com uma versão específica
poetry add beautifulsoup4@^4.12.2
Enter fullscreen mode Exit fullscreen mode

O Poetry fará a mágica: ele encontra a melhor versão compatível, instala a biblioteca e suas sub-dependências, e atualiza o pyproject.toml e o poetry.lock.

Dependências de Desenvolvimento

Ferramentas como pytest, black, flake8 são essenciais para o desenvolvimento, mas não precisam ir para produção. Para elas, usamos a flag --group dev (ou -D):

poetry add pytest --group dev
# Ou a forma curta
poetry add black -D
Enter fullscreen mode Exit fullscreen mode

Elas serão listadas na seção [tool.poetry.group.dev.dependencies] do seu pyproject.toml.

Removendo uma Biblioteca

Não precisa mais de uma biblioteca? Sem problemas:

poetry remove requests
# Para remover uma dependência de desenvolvimento
poetry remove pytest --group dev
Enter fullscreen mode Exit fullscreen mode

O Poetry desinstala a biblioteca e atualiza seus arquivos de configuração.

Atualizando Dependências

Para atualizar todas as dependências para as versões mais recentes compatíveis com seu pyproject.toml:

poetry update
Enter fullscreen mode Exit fullscreen mode

Se quiser atualizar uma biblioteca específica:

poetry update requests
Enter fullscreen mode Exit fullscreen mode

O Segredo da Consistência: poetry.lock

Quando você adiciona ou atualiza uma dependência, o Poetry cria (ou atualiza) um arquivo chamado poetry.lock. Este arquivo é um tesouro! Ele registra exatamente quais versões de todas as dependências (diretas e transitivas) foram instaladas e funcionaram juntas.

Por que isso é incrível?

  • Reprodutibilidade: Garante que, não importa onde seu projeto seja clonado ou implantado, ele sempre terá as mesmas versões de bibliotecas.
  • Estabilidade: Evita que atualizações inesperadas de sub-dependências quebrem seu código.

Regra de Ouro: Sempre comite o poetry.lock no seu controle de versão (Git)! Ele é tão importante quanto seu código.

Ambientes Virtuais: Onde o Poetry Brilha

O Poetry cria e gerencia automaticamente ambientes virtuais para seus projetos. Você não precisa mais de python -m venv .venv ou source .venv/bin/activate! O Poetry faz isso nos bastidores.

Para executar um comando dentro do ambiente virtual do seu projeto:

poetry run python meu_script.py
poetry run pytest
Enter fullscreen mode Exit fullscreen mode

Se você realmente quiser entrar no ambiente virtual (para depuração, por exemplo):

poetry shell
Enter fullscreen mode Exit fullscreen mode

Isso ativa o ambiente virtual na sua sessão do terminal. Para sair, digite exit.

Comandos Essenciais para o Dia a Dia

Comando Descrição Exemplo
poetry install Instala todas as dependências listadas no poetry.lock (ou pyproject.toml se o lockfile não existir). Ideal para configurar um projeto pela primeira vez. poetry install
poetry install --no-root Instala apenas as dependências, sem instalar o próprio projeto como um pacote. Útil em ambientes de produção. poetry install --no-root
poetry install --only main Instala apenas as dependências de produção. poetry install --only main
poetry install --only dev Instala apenas as dependências de desenvolvimento. poetry install --only dev
poetry show Lista todas as dependências instaladas no projeto. poetry show
poetry show --tree Mostra as dependências em formato de árvore. poetry show --tree
poetry env list Lista os ambientes virtuais associados ao projeto. poetry env list
poetry env use python3.10 Define qual interpretador Python usar para o ambiente virtual. poetry env use python3.10

Conclusão: Sua Vida Python Nunca Mais Será a Mesma!

O Poetry não é apenas uma ferramenta; é uma filosofia de gerenciamento de projetos Python. Ele simplifica o fluxo de trabalho, aumenta a reprodutibilidade e permite que você se concentre no que realmente importa: escrever código incrível.

Então, da próxima vez que você iniciar um projeto Python, dê uma chance ao Poetry. Seu eu do futuro (e seus colegas de equipe) agradecerão! Diga adeus ao caos.

Referências

[1] Poetry Documentation: https://python-poetry.org/docs/
[2] PEP 518 – Specifying build system dependencies for Python projects: https://peps.python.org/pep-0518/

Top comments (0)