Estrutura de projeto e pacotes

Módulo, pacote e projeto

Enquanto seu programa cabe num arquivo, organização não é problema. O problema começa quando ele cresce: centenas de funções soltas, nomes que se repetem, e ninguém acha nada. A solução é hierarquia. A menor unidade é o módulo, um arquivo .py que agrupa código relacionado. Quando vários módulos formam uma frente maior, você os junta numa pasta, que vira um pacote. E o conjunto de pacotes, mais os testes e a configuração, forma o projeto. Cada nível tem uma responsabilidade clara, e é essa clareza que deixa um código grande sustentável.

Pense num exemplo concreto: uma biblioteca de utilidades financeiras. As funções de juros vão para um módulo juros.py; as de formatação de moeda, para formatacao.py; as de datas, para datas.py. Todos ficam dentro de uma pasta financas, que é o pacote. Quem usa a biblioteca importa o que precisa, sabendo exatamente onde cada coisa mora. Essa arrumação não muda o que o código faz, mas muda tudo na hora de entender, alterar e reaproveitar.

O papel do __init__.py

O arquivo __init__.py é o que, tradicionalmente, transforma uma pasta comum num pacote importável. Ele pode estar vazio, e muitas vezes está: a mera presença já sinaliza pacote. Mas ele também tem um papel útil, que é definir a fachada do pacote. Colocando alguns imports nele, você escolhe o que fica acessível direto pelo nome do pacote, sem a pessoa precisar saber em qual módulo interno cada coisa está. É a diferença entre expor uma interface limpa e obrigar quem usa a decorar sua organização interna.

# financas/__init__.py
# Expoe uma fachada limpa do pacote
from .juros import juros_compostos, juros_simples
from .formatacao import formatar_brl

__all__ = ["juros_compostos", "juros_simples", "formatar_brl"]

# Agora quem usa faz:
#   from financas import juros_compostos, formatar_brl
# sem precisar saber que estao em juros.py e formatacao.py

O __init__.py define a fachada: o que o pacote expõe direto, escondendo a organização interna.

A raiz do projeto

Na raiz do projeto, a regra de ouro é separar o que é código de produção do que é teste e do que é configuração. Uma convenção muito usada é o layout src, em que todo o código do pacote fica dentro de uma pasta src, os testes numa pasta tests separada, e os arquivos de configuração, como o pyproject.toml e o README, ficam na raiz. Essa separação evita confusões sutis de import durante os testes e deixa óbvio, para qualquer pessoa que abre o projeto, onde está cada tipo de arquivo.

minha-biblioteca/
    pyproject.toml       # configuracao e metadados do projeto
    README.md
    src/
        financas/
            __init__.py
            juros.py
            formatacao.py
            datas.py
    tests/
        test_juros.py
        test_formatacao.py

Layout src: código em src/, testes em tests/, configuração na raiz. Cada coisa no seu lugar.

Repare que essa estrutura conta uma história. Quem chega ao projeto vê na hora que existe um pacote financas com três módulos, que há testes correspondentes, e que a configuração está na raiz. Não é preciso ler nenhum código para entender a forma do projeto. Essa legibilidade estrutural é tão importante quanto a legibilidade do código, e é ela que sustenta o trabalho em equipe e a manutenção ao longo dos anos. O projeto final do curso, aliás, nasce exatamente com esse layout.