Estrutura de Projetos Python e Arquitetura de Módulos

Projete projetos Python bem organizados com limites claros de módulos, interfaces públicas explícitas e estruturas de diretórios fáceis de manter. Uma boa organização torna o código descoberto e as mudanças previsíveis.

Quando Usar Esta Habilidade

• Iniciando um novo projeto Python do zero
• Reorganizando uma base de código existente para clareza
• Definindo APIs públicas de módulos com __all__
• Decidindo entre estruturas de diretórios planas e aninhadas
• Determinando estratégias de posicionamento de arquivos de teste
• Criando pacotes de biblioteca reutilizáveis

Conceitos Principais

1. Coesão de Módulos

Agrupe código relacionado que muda junto. Um módulo deve ter um propósito único e claro.

2. Interfaces Explícitas

Defina o que é público com __all__. Tudo o que não estiver listado são detalhes de implementação interna.

3. Hierarquias Planas

Prefira estruturas de diretórios rasas. Adicione profundidade apenas para subdomínios genuínos.

4. Convenções Consistentes

Aplique padrões de nomenclatura e organização uniformemente em todo o projeto.

Início Rápido

myproject/
├── src/
│   └── myproject/
│       ├── __init__.py
│       ├── services/
│       ├── models/
│       └── api/
├── tests/
├── pyproject.toml
└── README.md

Padrões Fundamentais

Padrão 1: Um Conceito por Arquivo

Cada arquivo deve focar em um único conceito ou conjunto de funções intimamente relacionadas. Considere dividir quando um arquivo:

• Lida com múltiplas responsabilidades não relacionadas
• Cresce além de 300-500 linhas (varia com a complexidade)
• Contém classes que mudam por razões diferentes

# Good: Focused files
# user_service.py - User business logic
# user_repository.py - User data access
# user_models.py - User data structures

# Avoid: Kitchen sink files
# user.py - Contains service, repository, models, utilities...

Padrão 2: APIs Públicas Explícitas com __all__

Defina a interface pública para cada módulo. Membros não listados são detalhes de implementação interna.

# mypackage/services/__init__.py
from .user_service import UserService
from .order_service import OrderService
from .exceptions import ServiceError, ValidationError

__all__ = [
    "UserService",
    "OrderService",
    "ServiceError",
    "ValidationError",
]

# Internal helpers remain private by omission
# from .internal_helpers import _validate_input  # Not exported

Padrão 3: Estrutura de Diretório Plana

Prefira aninhamento mínimo. Hierarquias profundas tornam as importações verbosas e a navegação difícil.

# Preferred: Flat structure
project/
├── api/
│   ├── routes.py
│   └── middleware.py
├── services/
│   ├── user_service.py
│   └── order_service.py
├── models/
│   ├── user.py
│   └── order.py
└── utils/
    └── validation.py

# Avoid: Deep nesting
project/core/internal/services/impl/user/

Adicione subpacotes apenas quando houver um subdomínio genuíno que exija isolamento.

Padrão 4: Organização de Arquivos de Teste

Escolha uma abordagem e aplique-a consistentemente em todo o projeto.

Opção A: Testes Colocados

src/
├── user_service.py
├── test_user_service.py
├── order_service.py
└── test_order_service.py

Benefícios: Testes ficam ao lado do código que eles verificam. Fácil de ver lacunas de cobertura.

Opção B: Diretório de Testes Paralelo

src/
├── services/
│   ├── user_service.py
│   └── order_service.py
tests/
├── services/
│   ├── test_user_service.py
│   └── test_order_service.py

Benefícios: Separação limpa entre código de produção e de teste. Padrão para projetos maiores.

Padrões Avançados

Padrão 5: Inicialização de Pacotes

Use __init__.py para fornecer uma interface pública limpa para os consumidores do pacote.

# mypackage/__init__.py
"""MyPackage - A library for doing useful things."""

from .core import MainClass, HelperClass
from .exceptions import PackageError, ConfigError
from .config import Settings

__all__ = [
    "MainClass",
    "HelperClass",
    "PackageError",
    "ConfigError",
    "Settings",
]

__version__ = "1.0.0"

Os consumidores podem então importar diretamente do pacote:

from mypackage import MainClass, Settings

Padrão 6: Arquitetura em Camadas

Organize o código por camada arquitetônica para uma clara separação de responsabilidades.

myapp/
├── api/           # HTTP handlers, request/response
│   ├── routes/
│   └── middleware/
├── services/      # Business logic
├── repositories/  # Data access
├── models/        # Domain entities
├── schemas/       # API schemas (Pydantic)
└── config/        # Configuration

…