Posted on April 12, 2019· Updated on July 3, 2022

Projetos Python com Poetry e VSCode Parte 1 - Folha de Dicas Python

#python #intermediate #vscode #packaging

Um Ambiente Virtual é uma instalação Python isolada, projetada para evitar preencher nossa instalação base com bibliotecas que poderemos usar para apenas um projeto. Também nos permite gerenciar múltiplas versões do mesmo pacote em diferentes projetos. Poderíamos, por exemplo, precisar do Django 4.1 para um e 1.9 para o outro.

Python Poetry

Poetry é uma ferramenta para lidar com a instalação de dependências, bem como a construção e empacotamento de pacotes Python. Ele só precisa de um arquivo para fazer tudo isso: o novo, padronizado pyproject.toml`. Em outras palavras, poetry usa pyproject.toml para substituir setup.py, requirements.txt, setup.cfg, MANIFEST.in e o recém-adicionado Pipfile.

Nesta série de artigos, usaremos o Poetry para gerenciar nossas dependências, construir um projeto simples e, com um único comando, publicá-lo no PyPI.

Nesta primeira parte, nós iremos:

Iniciar um novo projeto.
Criar um Ambiente Virtual.
Gerenciar dependências.

No segundo artigo, nós iremos:

Adicionar nosso Ambiente Virtual ao VSCode.
Integrar nossas dependências de desenvolvimento:
- Flake8
- Black
- Pytest

E finalmente, em um terceiro artigo nós iremos:

Escrever uma biblioteca de exemplo.
Construir nosso projeto com Poetry.
Publicá-lo no PyPI.

Instalando Poetry

A maneira mais fácil é usar pip:

pip install poetry

Mas usaremos o instalador próprio do Poetry para isolá-lo do resto do sistema, terceirizando suas dependências. Esta é a maneira recomendada de instalar o poetry:

curl -sSL https://raw.githubusercontent.com/python-poetry/poetry/master/get-poetry.py | python -

Desta forma, mais tarde poderemos atualizar o poetry para a versão estável mais recente com o comando poetry self update.

Iniciando um novo projeto

Podemos agora iniciar um novo projeto Python usando o comando poetry new [nome_do_projeto]. Eu o chamarei de how-long e será uma biblioteca simples para medir o tempo de execução de uma função:

poetry new how-long

Nota: Para projetos existentes, você pode usar o comando poetry init e criar interativamente um pyproject.toml.

O diretório how-long é criado e dentro dele há uma estrutura de projeto básica:

how-long
├── README.rst
├── how_long
│   └── __init__.py
├── pyproject.toml
└── tests
    ├── __init__.py
    └── test_how_long.py

Para um guia abrangente sobre como lidar com caminhos de arquivos e diretórios, o que é essencial para gerenciar estruturas de projetos, consulte a página File and directory Paths.

Nota: Para poder publicar seu projeto, você precisa de um nome disponível. Use a pesquisa do PyPI para isso.

O arquivo pyproject.toml

O arquivo pyproject.toml gerenciará os detalhes e as dependências do projeto:

[tool.poetry]
name = "how-long"
version = "0.1.0"
description = "A simple decorator to measure a function execution time."
authors = ["wilfredinni <carlos.w.montecinos@gmail.com>"]

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

[tool.poetry.dev-dependencies]
pytest = "^3.0"

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

[tool.poetry]

Os detalhes. Adicionar uma licença e um README pode ser uma boa ideia:

[tool.poetry]
...
license = "MIT"
readme = "README.rst"

[tool.poetry.dependencies]

O primeiro é a versão do Python. Basicamente, este projeto será compatível com Python 3.7 e superior. Além disso, a partir de agora, todo pacote que instalarmos e que se destina a ser usado em produção será listado aqui.

[tool.poetry.dev-dependencies]

Estes pacotes são apenas para desenvolvimento e não serão incluídos quando publicarmos nosso projeto. Por padrão, o Poetry inclui o Pytest, então o usaremos para testar nosso projeto mais tarde.

Criando um Ambiente Virtual

Para criar um Ambiente Virtual e instalar o Pytest, usaremos o comando poetry install:

poetry install

poetry-install-command

Depois de concluído, um novo arquivo, poetry.lock, será criado.

Quando o Poetry terminar a instalação, ele grava todos os pacotes e as versões exatas deles que baixou no arquivo poetry.lock, travando o projeto nessas versões específicas. Você deve commitar o arquivo poetry.lock no repositório do seu projeto para que todas as pessoas que trabalham no projeto fiquem travadas nas mesmas versões das dependências.

Gerenciamento de Dependências

Uma maneira de adicionar ou remover dependências é editar diretamente o pyproject.toml e depois executar poetry install para aplicar as alterações. Em vez disso, usaremos os comandos add e remove para evitar modificações manuais.

Adicionando dependências

Vamos adicionar dois pacotes ao projeto, pendulum e coo:

poetry add pendulum coo

poetry-add-command

Abra pyproject.toml e poetry.lock e veja como eles foram atualizados.

Adicionando dependências de Desenvolvimento

Estas dependências estarão disponíveis apenas durante o desenvolvimento; o Poetry não as incluirá ao construir e publicar o projeto.

Já instalamos o Pytest, mas também usaremos o flake8 para linting e o mypy para tipagem estática:

poetry add -D flake8 mypy

Agora que penso bem, esqueci de adicionar um formatador. Vamos usar o black:

poetry add -D black
[ValueError]
Could not find a matching version of package black

add [-D|--dev] [--git GIT] [--path PATH] [-E|--extras EXTRAS] [--optional] [--python PYTHON] [--platform PLATFORM] [--allow-prereleases] [--dry-run] [--] <name> (<name>)...

Este erro acontece porque o black está em estado de pré-lançamento, então o Poetry não consegue encontrar nenhuma versão estável para nós. Mas eu realmente o quero, então vamos instalá-lo mesmo assim com a flag --allow-prereleases:

poetry add -D black --allow-prereleases

poetry-add-dev-command

Removendo dependências

Sabe de uma coisa, mudei de ideia, este projeto não usará nem coo nem mypy. Comece removendo coo, uma dependência normal do nosso projeto:

poetry remove coo

Agora mypy, que é uma dependência de desenvolvimento:

poetry remove -D mypy

Conclusão

Nesta primeira parte, iniciamos um novo projeto, criamos um Ambiente Virtual e adicionamos e removemos dependências usando os seguintes comandos:

Comando	Descrição
`poetry new [nome-do-pacote]`	Iniciar um novo Projeto Python.
`poetry init`	Criar um arquivo pyproject.toml interativamente.
`poetry install`	Instalar os pacotes dentro do arquivo pyproject.toml.
`poetry add [nome-do-pacote]`	Adicionar um pacote a um Ambiente Virtual.
`poetry add -D [nome-do-pacote]`	Adicionar um pacote de desenvolvimento a um Ambiente Virtual.
`poetry remove [nome-do-pacote]`	Remover um pacote de um Ambiente Virtual.
`poetry remove -D [nome-do-pacote]`	Remover um pacote de desenvolvimento de um Ambiente Virtual.
`poetry self:update`	Atualizar o poetry para a versão estável mais recente.

Em um segundo artigo, veremos mais comandos do Poetry, adicionaremos nosso Ambiente Virtual ao VSCode e usaremos os pacotes de desenvolvimento que instalamos para fazer lint (Flake8), formatar (Black) e testar (Pytest) nosso código dentro do editor. Finalmente, em um terceiro, escreveremos e publicaremos uma biblioteca de exemplo no PyPI.

Alguma dúvida ou sugestão? Por favor, deixe um comentário.