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

Entrada	Por quê
Caminho alvo	Escopo `src/billing/`
Tolerância a risco	Correção automática segura vs. revisão manual
Presença de testes	Necessário antes de refatorações que alteram comportamento
Configuração de estilo	Seção `tool` de `ruff.toml` / `pyproject`
Regras da equipe	Link para ADRs da seção `python-rules`

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

Testes verdes antes e depois - sem alterações de comportamento inesperadas.
Sem renomeação em massa sem depreciação - semver para API pública.
Use raise ... from exc - preserve os tracebacks.
Substitua argumentos padrão mutáveis - use o sentinela None.
Apenas f-strings - sem % ou .format em novas edições.
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

Aplicar automaticamente todas as correções do ruff?

Correções seguras apenas no primeiro PR - regras inseguras precisam de revisão humana por arquivo.

Black ainda é necessário?

ruff format substitui Black quando habilitado - um formatador por repositório.

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+.

Entradas

Entrada	Por quê
Caminho alvo	Escopo `src/billing/`
Tolerância a risco	Correção automática segura vs. revisão manual
Presença de testes	Necessário antes de refatorações que alteram comportamento
Configuração de estilo	Seção `tool` de `ruff.toml` / `pyproject`
Regras da equipe	Link para ADRs da seção `python-rules`

Guardrails

Testes verdes antes e depois - sem alterações de comportamento inesperadas.

Sem renomeação em massa sem depreciação - semver para API pública.

Use raise ... from exc - preserve os tracebacks.

Substitua argumentos padrão mutáveis - use o sentinela None.

Apenas f-strings - sem % ou .format em novas edições.

Alinhe com as 50 Regras Python quando adotado pela organização.

# 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

Relacionados

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+.

Skill de Melhores Práticas em Python

Buscar na documentação

Skill de Melhores Práticas em Python