Configuração do Ruff
Ruff é um linter e formatador baseado em Rust que substitui flake8, isort, pyupgrade e dezenas de plugins em uma única ferramenta rápida. É o linter padrão para projetos Python 3.14.
Receita
uv add --group dev ruff[tool.ruff]
line-length = 88
target-version = "py314"
[tool.ruff.lint]
select = ["E", "F", "I", "UP", "B", "SIM"]uv run ruff check .
uv run ruff format .Quando usar isso:
- Substituindo flake8 + isort + autoflake + pyupgrade
- Etapas de lint em CI que levam mais de alguns segundos
- Novos projetos Python que precisam de uma linha de base de qualidade sem configuração
Exemplo de Trabalho
# pyproject.toml
[tool.ruff]
line-length = 88
target-version = "py314"
src = ["src", "tests"]
[tool.ruff.lint]
select = [
"E", # erros pycodestyle
"F", # pyflakes
"I", # isort
"UP", # pyupgrade
"B", # bugbear
"SIM", # simplify
]
ignore = ["E501"] # o comprimento da linha é tratado pelo formatador
[tool.ruff.lint.isort]
known-first-party = ["myapp"]
[tool.ruff.format]
quote-style = "double"uv run ruff check . --fix
uv run ruff format .
uv run ruff check . # verificar se está limpoO que isso demonstra:
- Um único bloco de configuração substitui várias ferramentas legadas
selecthabilita categorias de regras;ignoresuprime códigos específicos--fixcorrige automaticamente violações seguras (imports, pyupgrade, alguns bugbear)ruff formatfornece formatação compatível com Black
Mergulho Profundo
Como Funciona
- Ruff analisa o código-fonte Python com um parser Rust - tipicamente 10-100x mais rápido que flake8
- Códigos de regra mapeiam para plugins flake8 (por exemplo,
B= bugbear,I= isort) - O formatador é compatível com o estilo do Black por padrão
- Um único binário lida com lint, formato e ordenação de imports
Conjuntos de Regras Essenciais
| Código | Fonte | Captura |
|---|---|---|
| E, W | pycodestyle | Violações de estilo |
| F | pyflakes | Nomes indefinidos, imports não utilizados |
| I | isort | Ordem dos imports |
| UP | pyupgrade | Sintaxe desatualizada |
| B | bugbear | Bugs comuns |
| SIM | simplify | Código excessivamente complexo |
Armadilhas
- Executar ruff sem configuração - os padrões podem não corresponder ao estilo da equipe. Correção: confirme
[tool.ruff]empyproject.toml. - E501 conflita com o formatador - dupla aplicação. Correção: ignore
E501; deixeruff formatlidar com o comprimento da linha. - Não definir
target-version- pyupgrade não sugerirá a sintaxe 3.14. Correção: definatarget-version = "py314". - Caminhos
srcausentes - a detecção de importação de primeira parte falha. Correção: definasrc = ["src"]para projetos com layoutsrc. - Substituindo formatadores incrementalmente - Black e ruff format entram em conflito em CI. Correção: escolha um formatador; remova o outro da CI.
Alternativas
| Alternativa | Use Quando | Não Use Quando |
|---|---|---|
| flake8 + plugins | Investimento em configuração legada | Começando do zero |
| pylint | Análise semântica profunda necessária | Velocidade é importante |
| Apenas Black | Apenas formatação, sem lint | Você quer uma ferramenta |
FAQs
O ruff substitui o Black?
ruff format é compatível com Black. A maioria das equipes usa ruff para lint e formato.
Como ignoro uma linha?
# noqa: F401 na linha, ou # ruff: noqa para todas as regras nessa linha.
O ruff pode corrigir todas as violações?
Muitas regras suportam --fix. Algumas (erros de lógica) exigem correções manuais.
Como adiciono ruff ao pre-commit?
- repo: https://github.com/astral-sh/ruff-pre-commit
rev: v0.9.0
hooks:
- id: ruff
args: [--fix]
- id: ruff-formatQual a diferença entre check e format?
ruff check faz lint. ruff format formata. Execute ambos em CI.
Como vejo todas as regras habilitadas?
ruff linter lista os códigos de regra. ruff rule E501 explica uma regra específica.
O ruff suporta monorepos?
Sim. Use src e pyproject.toml por diretório ou extend config.
Posso usar ruff com mypy?
Sim. Ruff captura erros de estilo e óbvios; mypy captura erros de tipo. Execute ambos.
Quão rápido é o ruff em comparação com o flake8?
Tipicamente 10-100x mais rápido em bases de código de médio a grande porte.
Qual versão devo fixar?
ruff>=0.9 de acordo com a pilha do projeto. Fixe a versão exata em rev do pre-commit.
Relacionado
- Black / Ruff Format - detalhes de formatação
- Regras Essenciais de Lint - recomendações de conjuntos de regras
- Hooks do pre-commit - integração com hooks do git
- Linting em CI/CD - aplicação em pipelines
Versões da Pilha: 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+.