Gerenciamento de Dependências em Python com Poetry 2+⚓︎

O Poetry é uma ferramentas Python para, entre outros, realizar gerenciamento de dependências e publicação de pacotes. Para mim, ele se consolida a cada dia como uma alternativa robusta ao uso tradicional do pip e virtualenv, oferecendo uma solução integrada e mais eficiente para nossos projetos.

🚨 Vamos tratar mais a fundo aqui apenas das funcionalidades de gerenciamento de dependências, podendo as opções referentes a publicação de pacotes serem tratado em outro Post.

O que é o Poetry?⚓︎

O Poetry é uma ferramenta que simplifica a gestão de dependências e ambientes virtuais em projetos Python. Ele resolve automaticamente versões de pacotes, cria ambientes isolados e facilita a publicação de bibliotecas no PyPI. Além disso, sua abordagem baseada no arquivo pyproject.toml proporciona um gerenciamento mais organizado e replicável de nossos projetos.

Diferenças entre Poetry e Pip⚓︎

Pip⚓︎

Usa arquivos requirements.txt para definir dependências. (1)

🙋‍♂️ Para instalar todas as dependências listadas em um arquivo requirements.txt você deve primeiro criar e ativar um ambiente virtual Python utilizando o módulo venv:

# Criação ambiente virtual Python Linux Ubuntu
python3 -m venv venv

# Criação ambiente virtual Python Windows
python -m venv venv

# Ativação ambiente virtual Python Linux Ubuntu
source venv/bin/activate

# Ativação ambiente virtual Python Windows
source venv/Scripts/activate

# Instalação pacotes Linux e Windows
pip install -r requirements.txt

Requer o uso separado de virtualenv ou venv para criar ambientes isolados.
Não possui um gerenciador de versões embutido.

Poetry⚓︎

Utiliza pyproject.toml para definir dependências, tornando a configuração mais estruturada.
Gerencia ambientes virtuais automaticamente.
Possui resolução de dependências mais eficiente.
Facilita a publicação de pacotes Python sem necessidade de comandos extras.

Como Utilizar o Poetry⚓︎

Instalação⚓︎

A primeira maneira sugerida pela documentação oficial é utilizando o pipx:

pipx install poetry

Criando um Novo Projeto⚓︎

poetry new meu_projeto
cd meu_projeto

Isso cria um diretório com a estrutura padrão de um pacote Python, incluindo pyproject.toml:

meu-projeto
├── pyproject.toml
├── README.md
├── meu_projeto
│   └── __init__.py
└── tests
    └── __init__.py

Inicializando o Poetry em um Projeto Existente⚓︎

Se você já tem um projeto (repositório), e deseja incluir o Poetry criando o arquivo pyproject.toml, basta rodar:

poetry init # (1)!

O assistente iterativo ajudará a configurar o novo arquivo pyproject.toml que será incluído no projeto. Se quiser que o arquivo seja gerado sem essa iteração basta incluir a flag -n no comando (poetry init -n).

Instalando Dependências (clone de um repositório já existente)⚓︎

Se você já tem um projeto (repositório) que usa o Poetry (ou já contém o arquivo pyproject.toml) e deseja realizar o setup do mesmo em outro computador, basta rodar:

poetry install

O Poetry, então, seguirá a seguinte lógica:

Se o arquivo poetry.lock existir no repositório, serão instaladas as dependências exatamente nas versões especificadas nele, garantindo um ambiente reprodutível.
Se poetry.lock não existir, ele resolve as dependências a partir do pyproject.toml, gera o poetry.lock e então instala os pacotes.

Agora, se o pyproject.toml foi modificado e você deseja ignorar essas alterações e instalar somente o que está no poetry.lock, você pode usar:

poetry install --no-root

Isso evita a reinstalação do próprio projeto no ambiente virtual e foca apenas nas dependências.

Se precisar de mais controle, há também o comando:

poetry lock --no-update

Ele garante que o poetry.lock não seja modificado antes de uma instalação. Assim, quando você rodar poetry install, as dependências serão mantidas exatamente como estão no lockfile. 😊

Adicionando Dependências⚓︎

Para adicionar um pacote ao projeto:

poetry add requests # (1)!

O comando poetry add, além de adicionar o pacote nos arquivos pyproject.toml e poetry.lock ele também o instala. Se quiser que não instale mas somente insira nos arquivos pyproject.toml e poetry.lock utilize a flag --lock (poetry add requests --lock).

Se for uma dependência de desenvolvimento:

poetry add pytest --group test

Executando o Ambiente Virtual⚓︎

O comando poetry env activate printa na tela o caminho para ativação de seu ambiente virtual, mas não o ativa.

CódigoResultado

poetry env activate

source /home/gabrielbdornas/code/splor-mg/handbook/.venv/bin/activate # (1)!

Para criar o ambiente virtual dentro do seu projeto é necessário configurar a variável Poetry virtualenvs.in-project para true. Toda documentação de configuração Poetry pode ser encontrada aqui. Para acessar a lista das configurações de sua instalção Poetry basta utilizar o comando poetry config --list.

A documentação sugere que vocë pode usar o resultado deste comando para ativar o ambiente manualmente ou alimentar o comando eval() para esta ativação(1).

Versões anteriores do Poetry utilizavam o comando poetry shell para ativação do ambiente virtual.

eval $(poetry env activate) # (1)!

O comando eval $(poetry env activate) interpreta e executa o comando de ativação do ambiente virtual dentro do próprio terminal. Ele pega um comando passado como argumento, no nosso caso poetry env activate, e o executa. Ou seja, ele não ativa o ambiente diretamente, mas retorna a string com o comando de ativação correto para o terminal que você está usando (por exemplo, source /caminho/do/venv/bin/activate). O terminal então executa a saída do comando poetry env activate, ativando o ambiente virtual sem iniciar um novo subprocesso. Isso evita que você tenha que copiar e colar manualmente o comando de ativação.

Outros comando interessantes⚓︎

poetry list: mostra todos os comandos Poetry disponíves.
poetry show: mostra os pacotes instalados.

Tópicos Adicionais Importantes para pesquisa⚓︎

Destaque para o suporte a múltiplas versões do Python: O Poetry pode gerenciar diferentes versões do Python de forma mais eficiente quando integrado ao Pyenv.
Melhoria na explicação sobre poetry.lock: Entender melhor seu funcionamento e como os processos de atualização podem impactar um projeto.
Seção sobre poetry export: O Poetry permite exportar dependências para um formato compatível com pip com o comando poetry export -f requirements.txt --output requirements.txt. Isso pode ser útil para ambientes onde o Poetry não está instalado.
Dicas sobre troubleshooting: Algumas pessoas podem enfrentar problemas ao rodar poetry install, especialmente com dependências conflitantes.
Poetry e GitHub Actions: Automatização de atualização dos pacotes utilizando GitHub Actions.
Publicação de pacotes: Como dito no início, podemos utilizar o Poetry para publicação de pacotes Python. Entender bem este funcionamento, bem como a exclusão desta funcionalidade caso necessário também é interessante.

Conclusão⚓︎

Com o Poetry 2+, gerenciar dependências se tornou mais intuitivo e confiável, tornando essa ferramenta uma excelente escolha para projetos Python de qualquer tamanho. A combinação de um gerenciamento estruturado, resolução eficiente de dependências e integração com PyPI e Pyenv torna o Poetry indispensável para desenvolvedores que buscam produtividade e consistência em seus projetos. Se você ainda não experimentou o Poetry, vale a pena adotá-lo para melhorar seu fluxo de trabalho e garantir um ambiente mais organizado e previsível.