Black / Ruff Format
Formatadores automáticos eliminam debates de estilo ao impor um resultado determinístico. Ruff format (compatível com Black) é o padrão recomendado; Black continua sendo amplamente utilizado em projetos existentes.
Receita
# Ruff format (recomendado)
uv run ruff format .
# Black (projetos legados)
uv run black .Quando usar isso:
- Para acabar com debates de formatação em revisões de código
- Para impor um estilo consistente em uma equipe
- Com hooks de pré-commit que formatam automaticamente antes do commit
Exemplo de Trabalho
# Antes da formatação
def calculate_total(items, tax_rate=0.1, discount=0):
subtotal=sum(i.price*i.qty for i in items)
return subtotal*(1+tax_rate)-discount
# Depois: uv run ruff format file.py
def calculate_total(items, tax_rate=0.1, discount=0):
subtotal = sum(i.price * i.qty for i in items)
return subtotal * (1 + tax_rate) - discount[tool.ruff.format]
line-length = 88
quote-style = "double"
indent-style = "space"uv run ruff format --check . # CI: falha se não formatado
uv run ruff format . # corrige localmenteO que isso demonstra:
- O formatador normaliza espaços, aspas e quebras de linha
- O resultado é determinístico: a mesma entrada sempre produz o mesmo resultado
- Modo
--checkpara CI sem modificar arquivos - A configuração em
pyproject.tomlse aplica a todo o projeto
Mergulho Profundo
Como Funciona
- O formatador analisa o Python em uma AST (Abstract Syntax Tree), depois o emite novamente com regras consistentes
- O comprimento da linha (padrão 88) guia as decisões de quebra de linha
- A normalização de strings (aspas duplas por padrão) é configurável
- Ruff format visa >99% de compatibilidade com Black
Black vs Ruff Format
| Aspecto | Black | Ruff Format |
|---|---|---|
| Velocidade | Moderada | Muito rápido |
| Configuração | [tool.black] | [tool.ruff.format] |
| Compatibilidade | Implementação de referência | Compatível com Black |
| Integração | Ferramenta separada | Mesmo binário do linter |
Armadilhas
- Formatação de código gerado - diffs barulhentos. Correção: excluir
migrations/,generated/na configuração. - Executar o formatador sem verificação de CI - o desvio se acumula. Correção:
ruff format --checkna CI. - Substituições manuais de estilo - blocos
# fmt: off/ondevem ser raros. Correção: usar com moderação para casos legítimos (strings SQL longas). - Comprimento de linha diferente no linter e no formatador - E501 dispara em código formatado. Correção: ignorar E501 no lint do ruff; definir um único
line-length. - Misturar Black e ruff format - diferenças sutis de saída causam instabilidade. Correção: escolher um; remover o outro.
Alternativas
| Alternativa | Usar Quando | Não Usar Quando |
|---|---|---|
| autopep8 | Mudanças mínimas no estilo existente | Você quer determinismo total |
| yapf | Preferência pelo estilo do Google | Equipe quer compatibilidade com Black |
| Formatação manual | Scripts solo | Qualquer projeto de equipe |
FAQs
Devo usar Black ou ruff format?
Novos projetos: ruff format (mais rápido, integrado). Projetos Black existentes: migrar quando for conveniente.
Qual comprimento de linha devo usar?
88 (padrão Black) é o padrão da comunidade Python. Corresponda à sua configuração de linter.
Como faço para pular a formatação de um bloco?
# fmt: off antes e # fmt: on depois do bloco.
O formatador altera as aspas das strings?
Sim, por padrão para aspas duplas. Configure com quote-style = "single".
Posso formatar notebooks Jupyter?
ruff format notebook.ipynb (ruff 0.6+). Black também suporta notebooks.
A formatação quebrará meu código?
Não. Formatadores apenas alteram espaços em branco e estilo de aspas, nunca a semântica.
Como formatar ao salvar no VS Code?
Defina "editor.defaultFormatter": "charliermarsh.ruff" e "editor.formatOnSave": true.
Migrações geradas devem ser formatadas?
Exclua-as. Adicione exclude = ["migrations"] para evitar diffs barulhentos.
Como verificar um único arquivo?
ruff format path/to/file.py ou black path/to/file.py.
A formatação afeta a ordem dos imports?
Não. A ordenação de imports é ruff check --fix (regras isort), não do formatador.
Relacionados
- Configuração do Ruff - configuração completa do ruff
- isort e Organização de Imports - ordenação de imports
- Hooks de pré-commit - formatar no commit
- Melhores Práticas de Linting e Formatação - política de equipe
Versões da Stack: Esta página foi escrita para Python 3.14.0, 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+.