pyproject.toml e imports bem resolvidos

O pyproject.toml em visão geral

Todo projeto Python sério precisa se apresentar: qual o nome, qual a versão, de que outras bibliotecas ele depende. Antigamente isso ficava espalhado por vários arquivos de configuração. Hoje, a comunidade convergiu para um único arquivo padronizado, o pyproject.toml. Ele é escrito num formato simples de ler, o TOML, organizado em seções. Você não precisa decorar a sintaxe agora; o importante é entender que esse arquivo é o documento de identidade do projeto, e que ferramentas modernas o leem para saber como construir, testar e verificar o seu código.

# pyproject.toml (visao simplificada)
[project]
name = "financas"
version = "0.1.0"
description = "Utilidades financeiras"
requires-python = ">=3.10"
dependencies = [
    "requests>=2.31",
]

[tool.ruff]
line-length = 100

# Metadados do projeto e configuracao de ferramentas num arquivo so.

O pyproject.toml reúne metadados na seção [project] e configura ferramentas em seções [tool.*].

Duas partes valem destacar. A seção project traz os metadados: nome, versão, descrição e a lista de dependências, ou seja, as bibliotecas externas que o projeto usa e que serão instaladas junto. As seções que começam com tool guardam a configuração de ferramentas específicas, como o formatador e o verificador de estilo, cada uma no seu espaço. Concentrar tudo num arquivo evita a proliferação de configurações soltas e deixa qualquer pessoa que abre o projeto ver, num lugar só, como ele se declara e com que ferramentas trabalha.

Imports absolutos contra relativos

Dentro de um pacote com vários módulos, um módulo frequentemente precisa usar outro. Há dois jeitos de importar. O import absoluto nomeia o caminho completo a partir da raiz do pacote: from financas.juros import juros_simples. Ele é explícito e funciona igual de qualquer lugar. O import relativo usa pontos para partir do pacote atual: from .juros import juros_simples, em que o ponto significa neste mesmo pacote. Dois pontos sobem um nível. Ambos funcionam, mas têm perfis diferentes de clareza e robustez.

# Dentro de financas/relatorios/mensal.py

# Import absoluto: caminho completo a partir da raiz do pacote
from financas.juros import juros_compostos
from financas.formatacao import formatar_brl

# Import relativo: parte do pacote atual com pontos
from ..juros import juros_compostos       # .. sobe para financas
from ..formatacao import formatar_brl

O mesmo import de dois jeitos: absoluto (caminho da raiz) e relativo (pontos a partir do pacote atual).

Qual estilo de import preferir

A recomendação da PEP 8, o guia de estilo oficial, é preferir imports absolutos, porque são mais legíveis e menos sujeitos a surpresas. Ao ler from financas.juros import juros_simples, você sabe exatamente de onde a função vem, sem precisar calcular caminhos relativos na cabeça. Os imports relativos são aceitáveis, especialmente dentro de um pacote grande, onde deixam claro que a dependência é interna e evitam repetir o nome longo do pacote. O que a PEP 8 desaconselha é o import relativo implícito, o estilo antigo sem pontos, que hoje nem funciona mais.

Há também uma boa prática de organização dos imports no topo do arquivo, que a PEP 8 recomenda e as ferramentas de estilo aplicam sozinhas: agrupar primeiro os imports da biblioteca padrão, depois os de bibliotecas de terceiros, e por último os do seu próprio projeto, cada grupo separado por uma linha em branco. Isso deixa visível, num relance, o que o módulo depende de fora e o que depende de dentro. É um detalhe pequeno que, somado, torna qualquer arquivo mais fácil de ler.