Orientação da Base de Código
Como ler um repositório de serviço Python - estrutura de pastas, propriedade, convenções e o caminho mais rápido do clone à navegação confiante.
//
Busque em todas as páginas da documentação
Como ler um repositório de serviço Python - estrutura de pastas, propriedade, convenções e o caminho mais rápido do clone à navegação confiante.
service/
├── src/billing/ # pacote da aplicação
├── tests/ # espelha o layout de src
├── alembic/ # migrações de DB (se SQLAlchemy)
├── pyproject.toml # deps, ruff, config do pytest
├── uv.lock # resolução reproduzível
├── docs/ # ADRs, onboarding, runbooks
└── .github/workflows/ # fonte da verdade de CIQuando usar isso:
# Script de sessão de orientação (30-60 min auto-guiado)
tree -L 2 src/ tests/
rg -l "router|Blueprint|urlpatterns" src/ # encontra pontos de entrada HTTP
cat pyproject.toml | rg "name|requires-python|scripts"
cat docs/adr/0001-*.md 2>/dev/null || ls docs/
gh api repos/:owner/:repo/contents/CODEOWNERS 2>/dev/null || cat CODEOWNERS
uv run pytest --collect-only -q | head # vê módulos de testeRastreie uma história de usuário:
src/billing/api/routes/orders.py).services/order_service.py).repositories/order_repo.py).alembic/versions/).O que isso demonstra:
src/ separa o pacote importável da raiz do repositóriosrc - O pacote em src/<nome>/ evita importações acidentais da raiz do repositório em PYTHONPATH.pyproject.toml - Manifesto único para metadados, dependências, configuração de ferramentas (ruff, pytest, mypy).src - tests/billing/api/test_orders.py mapeia para src/billing/api/orders.py.CODEOWNERS solicita automaticamente especialistas de domínio em PRs.| Artefato | Respostas |
|---|---|
| README | Comandos de Quickstart |
docs/onboarding.md | Armadilhas específicas da equipe |
| ADRs | Decisões de framework e esquema |
| Fluxo de CI | Portões de qualidade obrigatórios |
CONTRIBUTING.md | Regras de PR e commit |
# Descobre a versão do pacote e os pontos de entrada programaticamente
import importlib.metadata as m
m.version("billing")
# console_scripts de pyproject [project.scripts]pyproject..env.example desatualizado. Correção: documentar o bug no primeiro chave ausente.docs/onboarding.md.| Alternativa | Usar Quando | Não Usar Quando |
|---|---|---|
| Wiki de diagrama de arquitetura | Apenas alto nível | Diagrama desatualizado em relação ao código |
pydeps / grafos de importação | Desembaraçar ciclos | Primeira hora no repositório |
| Busca de código IDE | Salto de símbolo | Ainda sem clone local |
| Tour de pareamento | Legado complexo | Escala de onboarding auto-atendida |
Ler README raiz para lista de pacotes; cd services/billing-api por serviço com seu próprio uv.lock.
Equipes usam a camada services/ ou o pacote de domínio - evite manipuladores de rota "gordos"; procure por class *Service.
Verificar Makefile / scripts/generate - não editar manualmente a saída do cliente OpenAPI.
Procurar settings ou inicialização do SDK do LaunchDarkly - flags escondem caminhos incompletos.
Seguir submodule git ou libs/ do monorepo - observar processo de atualização de versão separado.
Pode ser pré-migração de src - README deve indicar status da migração; preferir src/ para novo código.
CODEOWNERS em infra/ ou tag da equipe de plataforma no README.
Data no nome do arquivo - se mais antigo que 2 anos, verificar se ainda é verdade com um colega.
Cada apps/* é um contexto delimitado - começar em urls.py e models.py por app.
rg "@app.task" src/ ou lista de inclusão de celery.py.
Versões do Stack: Esta página foi escrita para Python 3.14.0 (estável 3.14, manutenção 3.13), FastAPI 0.115+, Django 5.2, Flask 3.1, Pydantic 2, PyTorch 2.6+, pandas 2.2+, Polars 1.x, ruff 0.9+, e uv 0.6+.
Revisado por Chris St. John·Última atualização: 16 de jul. de 2026