Como usar Poetry na gestão de projetos Python

Deve haver uma – e de preferência apenas uma – maneira óbvia de fazê-lo.”

O Poetry traz ao Python o tipo de ferramenta de gestão de projetos “all in one” que Go e Rust desfrutam há muito tempo. Permitindo que os projetos tenham dependências determinísticas com versões específicas de pacotes, para que sejam construídos consistentemente em locais diferentes. O Poetry também facilita a criação, o empacotamento e a publicação de projetos e bibliotecas no PyPI, para que outras pessoas possam compartilhar os frutos de seus trabalhos em Python.

Neste artigo, abordamos o uso de projetos de desenvolvimento de Poetry para Python – como configurar o Poetry, como usar o Poetry para configurar as dependências e o ambiente virtual de um projeto e como evitar algumas das armadilhas que acompanham o recurso exclusivo do Poetry.

Configurar Poetry em Python

O Poetry é deliberadamente diferente de outras ferramentas de gestão de dependência e projeto Python, começando logo pela instalação. Em vez de usar  pip, o Poetry usa um instalador personalizado . O instalador adiciona a aplicação Poetry ao diretório de perfil do utilizador, para que este possa ser usado com qualquer instalação Python no seu sistema, presente ou futuro.

Embora  possa usar pip install poetrypara instalar o Poetry numa instalação específica do Python, isto não é recomendado, pois a) pode entrar em conflito com outros arquivos do sistema e b) dificulta o uso do Poetry de maneira consistente com diferentes versões do Python e diferentes ambientes virtuais.

Criar um projeto Python gerenciado por poesia

Depois de instalar o Poetry, pode criar um novo diretório de projeto gerido por Poetry simplesmente digitando poetry new <project_name>. Este comando cria um subdiretório nomeado <project_name>e preenche-o com um andaime do projeto.

O andaime do projeto Poetry inclui o seguinte:

  • pyproject.toml– o arquivo de definição para o projeto. O Poetry gere essa definição para si. Se souber o que está a fazer, poderá editar este arquivo diretamente, mas na maioria das vezes não vai precisar.
  • README.rst– um arquivo README vazio no formato ReStructuredText , o formato de arquivo usado para a documentação do Python. (Não existe uma regra que diga que deve usar o .rstformato para os documentos; pode usar o Markdown para casos mais simples.)
  • tests – um subdiretório com andaime para testes de unidade. Se não tem o hábito de escrever testes para novos projetos, deveria estar!
  • Finalmente, um subdiretório com o nome do projeto que contém o código do seu projeto.

Gerir ambientes virtuais Python em Poetry

Provavelmente, a primeira coisa que pretende com um novo projeto de Poetry é um  ambiente virtual Python . Fiel à forma, o Poetry tem a sua própria maneira distinta de lidar com ambientes virtuais. Em vez de colocar ambientes virtuais dentro do diretório do projeto, o Poetry coloca-os em um diretório de cache centralizado que varia de acordo com o sistema operativo:

  • Unix: ~/.cache/pypoetry/virtualenvs
  • Mac OS: ~/Library/Caches/pypoetry/virtualenvs
  • Windows: C:\Users\<username>\AppData\Local\pypoetry\Cache\virtualenvs or %LOCALAPPDATA%\pypoetry\Cache\virtualenvs

A vantagem da abordagem do Poetry é a capacidade de partilhar ambientes virtuais entre projetos, sempre que isso faça sentido. Mas está acção requer a alteração dos seus hábitos de trabalho.

Para configurar um ambiente virtual em Poetry, tem de ir para o diretório do projeto e digitar poetry env use python. O poetry vai criar um novo ambiente virtual, armazenará no diretório de cache e exibirá um nome gerado aleatoriamente para o ambiente virtual (tome nota disto para uso posterior).

Para maior comodidade, o Poetry também instalará quaisquer dependências listadas no pyproject.tomlarquivo do projeto. Achará isto super útil se quiser copiar um projeto de Poetry de outro lugar e configurá-lo no seu sistema. 

Tome nota que, se executar poetry env use python num diretório de projeto que já tenha um ambiente virtual designado por Poetry, o Poetry vai ativar esse ambiente virtual no contexto desta sessão da CLI.

Em seguida, vem a parte difícil, que é fazer com que seus ambientes virtuais geridos por Poetry funcionem com seu IDE. O Visual Studio Code, por exemplo, detecta automaticamente a presença de um ambiente virtual dentro de um diretório de projeto, mas ainda não detecta a presença de ambientes virtuais geridos com o Poetry. A solução (a curto prazo) é adicionar uma linha ao settings.jsonarquivo do projeto que indique onde o Poetry mantém os seus ambientes virtuais:

"python.venvPath": "C:\\Users\\username\\AppData\\Local\\pypoetry\\Cache\\virtualenvs"

Reinicie o Visual Studio Code depois de fazer esta alteração.

Se não pretende que o Poetry faça a gestão dos seus ambientes virtuais, pode desativar esse comportamento com este comando:

poetry config virtualenvs.create false

Adicionar dependências a um projeto Python no Poetry

O Poetry rastreia dois tipos de dependências do projeto: pacotes necessários para a execução do projeto (dependências de produção) e pacotes necessários apenas durante o processo de desenvolvimento (dependências de desenvolvimento). As dependências de produção incluiriam bibliotecas de terceiros usadas para a funcionalidade da aplicação; dependências de desenvolvimento que incluem ferramentas de codificação como blackmypyou docutils.

  • Para adicionar dependências de produção ao projeto , use poetry add <dependency_name>.
  • Para adicionar dependências de desenvolvimento , use poetry add <dependency_name> -D.

Note que você também usa a opção -D ao remover desenvolvimento dependências (ou seja, aqueles adicionados usando o -Dswitch) usando o comando poetry remove <dependency_name>.

Observe que o poetry addcomando funciona da mesma pip install maneira que pode especificar um nome de pacote ou um caminho Git (por exemplo, git+https://github.com/developer/project.git#branchname). Pode ainda configurar o Poetry para usar repositórios particulares . 

Depois das dependências resolvidas e instaladas, o Poetry cria um arquivo nomeado poetry.lockno diretório do projeto. Este arquivo é um manifesto de todos os downloads de dependências e deve ser salvo junto com o restante do seu projeto. Então, qualquer pessoa que extrair uma cópia do projeto do controle de origem obterá as mesmas versões de todos os pacotes necessários.

Pode considerar-se pronto para começar um projeto a sério. Tudo o que precisa é de se lembrar de usar o Poetry para gerir todas as dependências e ambientes virtuais do projeto.




Deixe um comentário

O seu email não será publicado