Skill de Melhores Práticas em Python

Refatorações e auditorias idiomáticas - uma Skill de Agente para qualidade de código em Python 3.14.

O Que Esta Skill Faz

Audita um pacote para Python idiomático: correções de lint/format com ruff, pathlib em vez de os.path, dataclasses vs dicts, encadeamento de exceções, logging em vez de print, cheiros de segurança (eval, pickle, f-strings SQL), e produz um plano de PR de refatoração escalonado.

Quando Invocar

• Módulo legado antes da extração para biblioteca
• Passagem de segurança pré-lançamento
• Sprint de limpeza de onboarding em caminhos críticos
• PR parece "Java-ish" ou não idiomático

Entradas

Saídas

• Resumo do diff de ruff check --fix e ruff format
• Auditoria em Markdown: achados críticos / principais / menores
• ADR sugerido para padrões (Tipo de Resultado, DI, etc.)
• Lista de lacunas de teste se a cobertura estiver faltando em módulos alterados
• Bloco de comando de verificação

Guardrails

1. Testes verdes antes e depois - sem alterações de comportamento inesperadas.
2. Sem renomeação em massa sem depreciação - semver para API pública.
3. Use raise ... from exc - preserve os tracebacks.
4. Substitua argumentos padrão mutáveis - use o sentinela None.
5. Apenas f-strings - sem % ou .format em novas edições.
6. Alinhe com as 50 Regras Python quando adotado pela organização.

Receita

uv run ruff check src/ --fix
uv run ruff format src/
uv run pytest -q
uv run mypy src/  # gate opcional

Exemplo de Trabalho (correção de padrão mutável)

# antes
def add_item(item, bucket=[]):
    bucket.append(item)
    return bucket
 
# depois
def add_item(item, bucket=None):
    if bucket is None:
        bucket = []
    bucket.append(item)
    return bucket

FAQs

Relacionados

• 50 Regras Python que Todo Especialista Deve Seguir - regras
• Referência de Estilo e PEP 8 - estilo
• Linting e Formatação - configuração do ruff
• Decisões de Refatoração - quando refatorar

Versões da Stack: Esta página foi escrita para Python 3.14.0 (3.14 estável, 3.13 em manutenção), 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+.