Aprenda a criar a sua primeira biblioteca Python! Nesta série de posts, vamos guiá-lo através do processo de criação e publicação de uma biblioteca Python usando o Poetry. Vamos começar com a construção de uma pequena aplicação de calculadora, abordando desde a configuração inicial até a implementação e testes das funções básicas. No final desta série, você terá sua biblioteca pronta para ser compartilhada com o mundo no PyPI.

O que é o Poetry?

O Poetry é uma ferramenta de gerenciamento de dependências e empacotamento para projetos Python. Ele simplifica o processo de criação e manutenção de bibliotecas e aplicativos, automatizando várias tarefas que tradicionalmente requerem múltiplas ferramentas. Poetry vem com todas as ferramentas que você pode precisar para gerenciar seus projetos de forma determinística. Aqui estão algumas das principais vantagens do Poetry:

• Construa projetos: Construa e empacote seus projetos facilmente com um único comando.
• Compartilhe seu trabalho: Torne seu trabalho conhecido publicando-o no PyPI.
• Verifique o estado de suas dependências: Obtenha uma visão das dependências do seu projeto com apenas um comando.
• Resolução de dependências: O Poetry vem com um resolvedor de dependências exaustivo, que sempre encontrará uma solução se ela existir.
• Isolamento: O Poetry usa os ambientes virtuais configurados ou cria os seus próprios para sempre estar isolado do seu sistema.
• CLI Intuitiva: Os comandos do Poetry são intuitivos e fáceis de usar, com padrões sensíveis, mas ainda assim configuráveis.

Com essas vantagens, o Poetry se destaca como uma ferramenta poderosa e eficiente para o desenvolvimento de projetos Python.

O que precisamos antes de começar nossa biblioteca Python?

Antes de começarmos a escrever o código, precisamos configurar nosso ambiente de desenvolvimento. Aqui estão as etapas para garantir que você tenha tudo pronto:

Verifique a versão do Python

Primeiro, precisamos garantir que você tenha a versão mais recente do Python instalada. Para verificar a versão do Python instalada em seu sistema, execute o seguinte comando no terminal:

python --version

Se você ainda não tiver o Python instalado ou precisar atualizá-lo, você pode baixá-lo e instalá-lo a partir do site oficial do Python.

Instalando o Poetry

Após garantir que você tem a versão mais recente do Python instalada, o próximo passo é instalar o Poetry. Você pode instalar o Poetry seguindo as instruções detalhadas na documentação oficial. Aqui está um comando rápido para instalação:

curl -sSL https://install.python-poetry.org | python3 -

Iniciando sua biblioteca: Os primeiros passos

Passo 1: Criação do projeto com o Poetry

Agora que temos o Python e o Poetry instalados, é hora de iniciar nosso projeto de calculadora. O Poetry facilita a criação de um novo projeto com um simples comando.

Navegue até o diretório onde você deseja criar seu projeto e execute o seguinte comando no terminal:

poetry new calculator
cd calculator

Este comando cria uma nova estrutura de projeto para você, que inclui pastas e arquivos essenciais.

calculator/
├── README.md
├── calculator
│   └── __init__.py
├── pyproject.toml
└── tests
    └── __init__.py

Vamos entender a estrutura gerada:

• README.md: Um arquivo de documentação para descrever seu projeto.
• calculator/: Uma pasta que contém o código-fonte da sua aplicação.
• tests/: Uma pasta para seus testes unitários.
• pyproject.toml: O arquivo de configuração principal para o Poetry.

Passo 2: Implementando as funções da calculadora

Agora vamos criar as funções da calculadora dentro do arquivo calculator/calculator.py.

calculator/
├── calculator.py
├── __init__.py

Abra o arquivo calculator.py e implemente as funções básicas da calculadora:

def add(a, b):
    return a + b

def subtract(a, b):
    return a - b

def multiply(a, b):
    return a * b

def divide(a, b):
    if b == 0:
        raise ValueError("Não é possível dividir por zero")
    return a / b

Passo 3: Testando as funções da calculadora

Testes são essenciais para garantir a qualidade do software, proporcionando confiabilidade na correção de bugs e na evolução do código. Neste exemplo, utilizaremos testes unitários para validar as funções da nossa calculadora. Vamos configurar o ambiente de testes e escrever alguns casos de teste para assegurar o funcionamento correto das operações matemáticas.

Configurando o ambiente de testes

Comece adicionando pytest como uma dependência de desenvolvimento:

poetry add --dev pytest

Agora, crie um arquivo chamado test_calculator.py dentro da pasta tests:

import pytest
from calculator.calculator import add, subtract, multiply, divide

def test_add():
    assert add(2, 3) == 5
    assert add(-1, 1) == 0
    assert add(0, 0) == 0
    assert add(-1, -1) == -2

def test_subtract():
    assert subtract(5, 2) == 3
    assert subtract(0, 0) == 0
    assert subtract(-1, 1) == -2
    assert subtract(-1, -1) == 0

def test_multiply():
    assert multiply(2, 3) == 6
    assert multiply(5, 0) == 0
    assert multiply(-1, 1) == -1
    assert multiply(-2, -3) == 6

def test_divide():
    assert divide(6, 2) == 3
    assert divide(5, 2) == 2.5
    assert divide(-10, 2) == -5
    with pytest.raises(ValueError):
        divide(4, 0)

Por fim, basta executar os testes com o seguinte comando:

poetry run pytest

Passo 4: Publicando no GitHub

Agora que nossa aplicação já está coberta com testes, vamos prepará-la para ser compartilhada no GitHub. Siga os passos abaixo para adicionar seu projeto ao GitHub:

1. Crie um repositório no GitHub: Vá para o GitHub e crie um novo repositório para sua calculadora.

2. Adicione seu projeto ao repositório:

• Inicialize o repositório Git dentro do diretório do seu projeto se ainda não estiver inicializado:

git init

• Adicione todos os arquivos ao Git e faça o primeiro commit:

git add .
git commit -m "Initial commit"

• Conecte seu repositório local ao repositório remoto no GitHub:

git remote add origin <URL_DO_SEU_REPOSITORIO_GITHUB>

• Envie seus arquivos para o GitHub:

git push -u origin main

Agora seu projeto está no GitHub e pronto para ser compartilhado e colaborado com outros desenvolvedores.

Passo 5: Instalando via Pip ou Poetry

Para instalar sua biblioteca diretamente basta usar os seguintes comandos:

• Via Pip:

pip install git+https://github.com/seu_usuario/seu_repositorio.git

• Via Poetry:

poetry add git+https://github.com/seu_usuario/seu_repositorio.git

O que vem a seguir?

Nesta primeira parte do tutorial, cobrimos os fundamentos essenciais para criar uma biblioteca Python utilizando o Poetry. Começamos configurando o ambiente de desenvolvimento, implementamos uma calculadora básica com testes unitários usando pytest, e compartilhamos o projeto no GitHub para colaboração.

Na próxima parte deste tutorial, exploraremos como publicar sua biblioteca no PyPI, o repositório padrão de pacotes Python, e aprenderemos como instalá-la usando o Poetry ou pip diretamente do PyPI. Isso não apenas facilitará o uso da sua biblioteca por outros desenvolvedores, mas também ajudará a integrá-la com a comunidade Python.

Parabéns por chegar até aqui! Espero que esteja aproveitando a criação da sua biblioteca Python. Fique à vontade para compartilhar dúvidas ou sugestões nos comentários. Vamos agora para a Parte II e continuar nossa jornada de colaboração com a comunidade Python.

Referências

• Canal Eduardo Mendes (@Dunossauro) Criando um pacote python do zero: dos requisitos ao deploy
• Documentação Poetry
• Poetry: construindo pacotes Python de uma forma fácil