Posted on May 21, 2019· Updated on July 3, 2022

Projetos Python com Poetry e VSCode Parte 3 - Guia Rápido Python

#python #intermediate #vscode #packaging

No primeiro artigo começamos um novo projeto, criamos um Ambiente Virtual e gerenciamos as dependências. Na segunda parte, adicionamos nosso Ambiente Virtual ao VSCode e integramos nossas dependências de desenvolvimento.

E finalmente, nesta terceira e última parte, faremos:

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

Comandos do Poetry

Aqui está uma tabela com os comandos usados nesta série, bem como suas descrições. Para uma lista completa, leia a Documentação do Poetry.

Comando	Descrição
`poetry new [nome-do-pacote]`	Inicia um novo Projeto Python.
`poetry init`	Cria um arquivo pyproject.toml interativamente.
`poetry install`	Instala os pacotes dentro do arquivo pyproject.toml.
`poetry add [nome-do-pacote]`	Adiciona um pacote a um Ambiente Virtual.
`poetry add -D [nome-do-pacote]`	Adiciona um pacote de desenvolvimento a um Ambiente Virtual.
`poetry remove [nome-do-pacote]`	Remove um pacote de um Ambiente Virtual.
`poetry remove -D [nome-do-pacote]`	Remove um pacote de desenvolvimento de um Ambiente Virtual.
`poetry update`	Obtém as versões mais recentes das dependências
`poetry shell`	Inicia um shell dentro do ambiente virtual.
`poetry build`	Constrói os arquivos de origem e wheels.
`poetry publish`	Publica o pacote no Pypi.
`poetry publish --build`	Constrói e publica um pacote.
`poetry self:update`	Atualiza o poetry para a versão estável mais recente.

O Projeto

Você pode baixar o código-fonte do GitHub se desejar, mas como mencionado anteriormente, este será um decorador simples que imprimirá no console quanto tempo leva para uma função ser executada.

Funcionará assim:

from how_long import timer

@timer
def test_function():
    [i for i in range(10000)]

test_function()
# Execution Time: 955 ms.

E o diretório do projeto será o seguinte:

how-long
├── how_long
│   ├── how_long.py
│   └── __init__.py
├── how_long.egg-info
│   ├── dependency_links.txt
│   ├── PKG-INFO
│   ├── requires.txt
│   ├── SOURCES.txt
│   └── top_level.txt
├── LICENSE
├── poetry.lock
├── pyproject.toml
├── README.rst
└── tests
    ├── __init__.py
    └── test_how_long.py

Antes de começarmos, verifique as atualizações do pacote com o comando poetry update:

poetry update

Adicione uma breve descrição para o projeto no README.rst:

how_long
========

Simple Decorator to measure a function execution time.

Example
_______

.. code-block:: python

    from how_long import timer

    @timer
    def some_function():
        return [x for x in range(10_000_000)]

Navegue até how_long/how_long.py:

# how_long.py
from functools import wraps

import pendulum

def timer(function):
    """
    Simple Decorator to measure a function execution time.
    """

    @wraps(function)
    def function_wrapper():
        start = pendulum.now()
        function()
        elapsed_time = pendulum.now() - start
        print(f"Execution Time: {elapsed_time.microseconds} ms.")

    return function_wrapper

Em how_long/__init__.py:

from .how_long import timer

__version__ = "0.1.1"

E finalmente, o arquivo tests/test_how_long.py:

from how_long import __version__
from how_long import timer

def test_version():
    assert __version__ == "0.1.1"

def test_wrap():
    @timer
    def wrapped_function():
        return

    assert wrapped_function.__name__ == "wrapped_function"

Você pode agora usar poetry install no seu terminal para instalar e provar seu pacote localmente. Ative seu ambiente virtual se ainda não o fez e no shell interativo do Python:

>>> from how_long import timer
>>>
>>> @timer
... def test_function():
...     [i for i in range(10000)]
...
>>> test_function()
Execution Time: 705 ms.

Execute os testes e se tudo estiver correto, siga em frente.

Construção e Publicação

Finalmente, chegou a hora de tornar este projeto disponível para o mundo! Certifique-se de ter uma conta no PyPI. Lembre-se de que o nome do pacote deve ser exclusivo; se tiver dúvidas, use a busca para verificar.

Construção (Build)

O comando poetry build constrói os arquivos de origem e wheels que serão posteriormente carregados como a fonte do projeto:

poetry build

O diretório how_long.egg-info será criado.

Publicação (Publish)

Este comando publica o pacote no PyPI e o registra automaticamente antes de fazer o upload se for a primeira vez que é enviado:

poetry publish

Você também pode construir e publicar seu projeto com $ poetry publish --build.

Insira suas credenciais e, se tudo estiver ok, navegue pelo seu projeto, e você verá algo como isto:

pipy how-long

Agora podemos informar aos outros que eles podem usar pip install how-long de qualquer máquina, em qualquer lugar!

Conclusão

Lembro-me da primeira vez que tentei publicar um pacote, e foi um pesadelo. Eu estava apenas começando em Python e tive que gastar algumas “poucas horas” tentando entender o que era o arquivo setup.py e como usá-lo. No final, acabei com vários arquivos: um Makefile, um MANIFEST.in, um requirements.txt e um test_requirements.txt. É por isso que as palavras de Sébastien Eustace, o criador do Poetry, fizeram muito sentido para mim:

Packaging and dependency management in Python are rather convoluted and hard to understand for newcomers. Even for seasoned developers it might be cumbersome at times to create all files needed in a Python project: setup.py, requirements.txt, setup.cfg, MANIFEST.in and the newly added Pipfile.
So I wanted a tool that would limit everything to a single configuration file to do: dependency management, packaging and publishing.
It takes inspiration in tools that exist in other languages, like composer (PHP) or cargo (Rust).
And, finally, there is no reliable tool to properly resolve dependencies in Python, so I started poetry to bring an exhaustive dependency resolver to the Python community.

Poetry não é de forma alguma perfeito, mas, ao contrário de outras ferramentas, ele realmente faz o que promete.