Ruff – Linter e Formatter Python
Ruff é o linter e formatter padrão para projetos Python a partir de agora.
Ruff é escrito em Rust, 10–100x mais rápido que Flake8/Black/isort, e substitui em um único binário: Flake8, Black, isort, pydocstyle, pyupgrade, autoflake.
Quando Usar
- Todo projeto Python (estudos e trabalho): FastAPI, Django, scripts, notebooks, libs.
- Antes de commit: rodar
ruff check e ruff format (ou ruff check --fix e ruff format).
- Em CI: incluir
ruff check e ruff format --check no pipeline.
- No código: respeitar as regras que o Ruff reporta; usar
# noqa só quando justificado.
Comandos
Lint (checagem e correção automática)
# Checar apenas (não altera arquivos)
ruff check .
# Checar e aplicar correções automáticas
ruff check . --fix
# Checar caminho específico
ruff check src/ scripts/ tests/
Format (formatação estilo Black)
# Formatar arquivos
ruff format .
# Apenas checar se está formatado (útil em CI)
ruff format . --check
Uso típico antes de commit
ruff check . --fix && ruff format .
Configuração
Configurar em pyproject.toml (preferido), ruff.toml ou .ruff.toml.
Exemplo mínimo em pyproject.toml
[tool.ruff]
line-length = 88
target-version = "py311"
[tool.ruff.lint]
select = ["E", "F", "I", "N", "W", "UP"]
ignore = ["E501"]
[tool.ruff.format]
quote-style = "double"
indent-style = "space"
Opções úteis
| Seção |
Opção |
Descrição |
[tool.ruff] |
line-length |
Comprimento máximo de linha (default 88, como Black) |
|
target-version |
Versão mínima Python: py39, py310, py311, py312 |
|
exclude |
Pastas/arquivos excluídos (ex.: .venv, build) |
[tool.ruff.lint] |
select |
Regras habilitadas (E, F, I, N, W, UP, B, etc.) |
|
ignore |
Regras desabilitadas (ex.: E501 para não forçar line-length) |
|
fixable |
Regras que podem ser corrigidas com --fix |
[tool.ruff.lint.per-file-ignores] |
"__init__.py" |
Ex.: ["E402"] para imports não no topo |
Regras comuns
- E: pycodestyle errors
- F: Pyflakes
- I: isort (imports)
- N: pep8-naming
- W: pycodestyle warnings
- UP: pyupgrade (sintaxe moderna)
- B: flake8-bugbear
Integração em projetos
Novo projeto Python
- Adicionar
ruff>=0.2.0 em requirements.txt ou [project.optional-dependencies].dev no pyproject.toml.
- Criar
[tool.ruff] (e [tool.ruff.lint], [tool.ruff.format]) no pyproject.toml do projeto.
- No Makefile (se houver):
lint: ruff check . e format: ruff format . (ou lint: ruff check . --fix && ruff format .).
- Em CI: passo que rode
ruff check . e ruff format . --check.
Projetos existentes (threat-modeling-ai, fastapi-microservice-framework, etc.)
- fastapi-microservice-framework: já usa Ruff em
pyproject.toml e no CI.
- threat-modeling-ai: adicionar
pyproject.toml com [tool.ruff] e incluir ruff nas dependências de dev; rodar ruff check --fix e ruff format no código Python e notebooks.
Regras para os agentes
- Projetos Python: usar Ruff como linter e formatter padrão. Não introduzir Black, Flake8 ou isort em projetos novos; em projetos antigos, migrar para Ruff quando for tocar no repo.
- Antes de sugerir commit: garantir que
ruff check . e ruff format . passem (ou que o usuário rode).
- Configuração: preferir
pyproject.toml com [tool.ruff] para manter tudo no mesmo lugar.
- Notebooks: Ruff linta e formata
.ipynb por padrão (Ruff 0.6+). Para só lintar ou só formatar notebooks, usar [tool.ruff.format] exclude = ["*.ipynb"] ou [tool.ruff.lint] exclude conforme necessário.
Referências
Converted and distributed by TomeVault — claim your Tome and manage your conversions.
1---2name: ruff-linter-formatter3description: Ruff como linter e formatter padrão para Python (substitui Flake8, Black, isort) Use when this capability is needed.4---56# Ruff – Linter e Formatter Python78**Ruff é o linter e formatter padrão para projetos Python a partir de agora.**910Ruff é escrito em Rust, 10–100x mais rápido que Flake8/Black/isort, e substitui em um único binário: Flake8, Black, isort, pydocstyle, pyupgrade, autoflake.1112---1314## Quando Usar1516- **Todo projeto Python** (estudos e trabalho): FastAPI, Django, scripts, notebooks, libs.17- **Antes de commit:** rodar `ruff check` e `ruff format` (ou `ruff check --fix` e `ruff format`).18- **Em CI:** incluir `ruff check` e `ruff format --check` no pipeline.19- **No código:** respeitar as regras que o Ruff reporta; usar `# noqa` só quando justificado.2021---2223## Comandos2425### Lint (checagem e correção automática)2627```bash28# Checar apenas (não altera arquivos)29ruff check .3031# Checar e aplicar correções automáticas32ruff check . --fix3334# Checar caminho específico35ruff check src/ scripts/ tests/36```3738### Format (formatação estilo Black)3940```bash41# Formatar arquivos42ruff format .4344# Apenas checar se está formatado (útil em CI)45ruff format . --check46```4748### Uso típico antes de commit4950```bash51ruff check . --fix && ruff format .52```5354---5556## Configuração5758Configurar em **`pyproject.toml`** (preferido), **`ruff.toml`** ou **`.ruff.toml`**.5960### Exemplo mínimo em `pyproject.toml`6162```toml63[tool.ruff]64line-length = 8865target-version = "py311"6667[tool.ruff.lint]68select = ["E", "F", "I", "N", "W", "UP"]69ignore = ["E501"]7071[tool.ruff.format]72quote-style = "double"73indent-style = "space"74```7576### Opções úteis7778| Seção | Opção | Descrição |79|-------|--------|-----------|80| `[tool.ruff]` | `line-length` | Comprimento máximo de linha (default 88, como Black) |81| | `target-version` | Versão mínima Python: py39, py310, py311, py312 |82| | `exclude` | Pastas/arquivos excluídos (ex.: `.venv`, `build`) |83| `[tool.ruff.lint]` | `select` | Regras habilitadas (E, F, I, N, W, UP, B, etc.) |84| | `ignore` | Regras desabilitadas (ex.: E501 para não forçar line-length) |85| | `fixable` | Regras que podem ser corrigidas com `--fix` |86| `[tool.ruff.lint.per-file-ignores]` | `"__init__.py"` | Ex.: `["E402"]` para imports não no topo |8788### Regras comuns8990- **E**: pycodestyle errors 91- **F**: Pyflakes 92- **I**: isort (imports) 93- **N**: pep8-naming 94- **W**: pycodestyle warnings 95- **UP**: pyupgrade (sintaxe moderna) 96- **B**: flake8-bugbear 9798---99100## Integração em projetos101102### Novo projeto Python1031041. Adicionar `ruff>=0.2.0` em `requirements.txt` ou `[project.optional-dependencies].dev` no `pyproject.toml`.1052. Criar `[tool.ruff]` (e `[tool.ruff.lint]`, `[tool.ruff.format]`) no `pyproject.toml` do projeto.1063. No Makefile (se houver): `lint: ruff check .` e `format: ruff format .` (ou `lint: ruff check . --fix && ruff format .`).1074. Em CI: passo que rode `ruff check .` e `ruff format . --check`.108109### Projetos existentes (threat-modeling-ai, fastapi-microservice-framework, etc.)110111- **fastapi-microservice-framework:** já usa Ruff em `pyproject.toml` e no CI.112- **threat-modeling-ai:** adicionar `pyproject.toml` com `[tool.ruff]` e incluir `ruff` nas dependências de dev; rodar `ruff check --fix` e `ruff format` no código Python e notebooks.113114---115116## Regras para os agentes1171181. **Projetos Python:** usar Ruff como linter e formatter padrão. Não introduzir Black, Flake8 ou isort em projetos novos; em projetos antigos, migrar para Ruff quando for tocar no repo.1192. **Antes de sugerir commit:** garantir que `ruff check .` e `ruff format .` passem (ou que o usuário rode).1203. **Configuração:** preferir `pyproject.toml` com `[tool.ruff]` para manter tudo no mesmo lugar.1214. **Notebooks:** Ruff linta e formata `.ipynb` por padrão (Ruff 0.6+). Para só lintar ou só formatar notebooks, usar `[tool.ruff.format] exclude = ["*.ipynb"]` ou `[tool.ruff.lint] exclude` conforme necessário.122123---124125## Referências126127- **Documentação:** https://docs.astral.sh/ruff/128- **Configuração:** https://docs.astral.sh/ruff/configuration/129- **Regras (linter):** https://docs.astral.sh/ruff/linter/130- **Editor (VS Code):** extensão Ruff oficial; usar Ruff como formatter/linter no lugar de Pylance/Black quando configurado.131132---133> Converted and distributed by [TomeVault](https://tomevault.io/claim/lucasbiason) — claim your Tome and manage your conversions.134<!-- tomevault:4.0:skill_md:2026-04-13 -->
tomevault-io