Ruff

Guia Completo do Linter Mais Rápido para Python

Introdução

Desenvolvedores Python profissionais enfrentam problemas recorrentes: imports desnecessários acumulados no código, variáveis declaradas mas nunca utilizadas, trechos de código morto que passam despercebidos, inconsistências de estilo espalhadas pelo projeto, e tempo precioso gasto em revisões de pull request identificando erros triviais. Esses problemas não envolvem lógica de programação, mas sim qualidade estrutural do código. É exatamente nesse contexto que o Ruff se destaca como solução.

O que é Ruff?

Ruff é um linter moderno para Python, desenvolvido em Rust, projetado para consolidar múltiplas ferramentas tradicionais de análise estática em uma única solução de alto desempenho. Sua função essencial é analisar código Python e identificar problemas antes que se transformem em bugs ou dívida técnica.

Funcionalidades principais

O Ruff oferece capacidades abrangentes para manutenção de qualidade de código:

Detecção de erros: identifica problemas comuns de programação que podem gerar bugs futuros.

Identificação de código inútil: localiza variáveis não utilizadas, imports desnecessários e trechos de código morto.

Garantia de boas práticas: verifica conformidade com convenções estabelecidas da linguagem Python.

Manutenção de consistência: assegura padrões uniformes em todo o projeto.

Correção automatizada: aplica fixes para problemas simples sem intervenção manual.

O Ruff opera durante a análise estática, antes da execução do código, examinando o código-fonte diretamente.

Consolidação de ferramentas

Historicamente, desenvolvedores Python dependiam de múltiplas ferramentas especializadas, cada uma com sua configuração e dependências. O Ruff substitui efetivamente:

• flake8: análise geral de lint
• pyflakes: detecção de variáveis e imports não utilizados
• pycodestyle: verificação de estilo conforme PEP 8
• isort: ordenação automática de imports
• bugbear: identificação de padrões perigosos

Esta consolidação resulta em menos dependências no projeto, configuração simplificada e ganhos significativos de desempenho.

Diferenciais técnicos

Performance excepcional

Desenvolvido em Rust, o Ruff alcança velocidade de 10x a 100x superior aos linters tradicionais em Python. Projetos grandes que demandavam vários segundos para análise agora são processados em milissegundos, transformando a experiência de desenvolvimento.

Correção automática

Além de identificar problemas, o Ruff possui capacidade de aplicar correções automaticamente para muitos tipos de issues, eliminando trabalho manual repetitivo.

Exemplo prático de problemas detectados

Considere este código Python comum em projetos:

import os
import sys

def calculate(values):
    total = 0
    temp = 10
    for v in values:
        total += v
    return total

Este código funciona perfeitamente, mas apresenta problemas estruturais:

• os importado mas nunca utilizado
• sys importado mas nunca utilizado
• Variável temp declarada mas nunca usada

O código executa, mas está poluído com elementos desnecessários.

Instalação

A instalação via pip é direta:

pip install ruff

Verifique a instalação:

ruff --version

Uso básico

Execute o Ruff no diretório do projeto:

ruff check .

Saída típica:

calculate.py:1:8: F401 'os' imported but unused
calculate.py:2:8: F401 'sys' imported but unused
calculate.py:5:5: F841 Local variable 'temp' is assigned to but never used

O Ruff fornece:

• Arquivo com problema
• Número da linha
• Código do erro
• Descrição clara do problema

Correção automática

Execute o comando com flag de correção:

ruff check . --fix

O código é automaticamente transformado para:

def calculate(values):
    total = 0
    for v in values:
        total += v
    return total

Imports desnecessários removidos, variável morta eliminada, código limpo sem intervenção manual.

Configuração do projeto

Embora o Ruff funcione sem configuração, é recomendável definir regras no arquivo pyproject.toml:

[tool.ruff]
line-length = 88

select = [
    "E",   # erros de estilo (pycodestyle)
    "F",   # pyflakes (variáveis/imports)
    "I",   # ordenação de imports (isort)
    "B",   # bugbear (padrões perigosos)
]

Esta configuração cobre a maioria dos casos de uso profissionais.

Fluxo de trabalho recomendado

Antes de cada commit, execute:

ruff check . --fix

Benefícios imediatos:

• Código mais limpo
• Revisões de código mais rápidas
• Menos discussões sobre formatação em PRs
• Padrão consistente no projeto

Integração com CI/CD

Exemplo de configuração para GitHub Actions:

- name: Lint com Ruff
  run: |
    pip install ruff
    ruff check .

Se o Ruff detectar problemas:

• Pipeline falha
• Código não é integrado
• Problema é corrigido antes de entrar na base

Limitações importantes

O Ruff não substitui:

• Formatadores: Black continua sendo a ferramenta para formatação
• Análise de performance: não identifica gargalos de execução
• Validação de lógica: não verifica regras de negócio
• Testes: não substitui suíte de testes

O Ruff foca exclusivamente em qualidade estrutural do código.

Stack de ferramentas recomendada

Combinação ideal para projetos profissionais:

Ferramenta Função Ruff Lint e qualidade estrutural Black Formatação de código Pytest Testes automatizados Mypy Verificação de tipos (opcional)

Mesmo usando apenas o Ruff, o ganho de qualidade é significativo.

Regras avançadas

Além das regras básicas, considere adicionar:

[tool.ruff]
select = [
    "E",    # pycodestyle errors
    "F",    # pyflakes
    "I",    # isort
    "B",    # bugbear
    "UP",   # pyupgrade (modernização de código)
    "C90",  # mccabe (complexidade ciclomática)
    "N",    # pep8-naming
    "SIM",  # simplify (simplificações)
]

ignore = ["E501"]  # ignorar linha muito longa
[tool.ruff.mccabe]
max-complexity = 10

Integração com editores

Visual Studio Code:

• Instale a extensão “Ruff” da Astral
• Lint em tempo real durante digitação
• Problemas destacados imediatamente

PyCharm/IntelliJ:

• Configure como External Tool
• Execute via atalho personalizado

Vim/Neovim:

• Integre com null-ls ou ale

Comandos úteis

# Verificar sem corrigir
ruff check .

# Corrigir automaticamente
ruff check . --fix
# Ver estatísticas de problemas
ruff check . --statistics
# Verificar arquivo específico
ruff check arquivo.py
# Modo watch (desenvolvimento)
ruff check . --watch
# Listar todas as regras disponíveis
ruff rule --all

Exemplo de transformação real

Código original:

import sys
import os
from typing import List
import json
from pathlib import Path

def process_data(data: List[int]):
    result = []
    temp_var = 100
    unused = "teste"

    for i in data:
        if i > 0:
            result.append(i * 2)

    return result
class MyClass():
    def __init__(self):
        pass

Após Ruff:

import json
from pathlib import Path
from typing import List

def process_data(data: List[int]):
    return [i * 2 for i in data if i > 0]
class MyClass:
    pass

Adoção em projetos legados

Estratégia para introduzir Ruff em código existente:

# 1. Avaliar quantidade de problemas
ruff check . --statistics

# 2. Corrigir módulos novos primeiro
ruff check ./modulo_novo --fix
# 3. Ignorar código legado temporariamente

Configuração gradual no pyproject.toml:

[tool.ruff]
extend-exclude = [
    "legacy/",
    "modulo_antigo.py",
]

Pre-commit hooks

Arquivo .pre-commit-config.yaml:

repos:
  - repo: https://github.com/astral-sh/ruff-pre-commit
    rev: v0.7.4
    hooks:
      - id: ruff
        args: [--fix]
      - id: ruff-format

Instalação:

pip install pre-commit
pre-commit install

Ruff executará automaticamente antes de cada commit.

Comparação de performance

Teste em projeto com aproximadamente 50.000 linhas:

Ferramenta Tempo de execução flake8 + isort + pyflakes ~4.2 segundos pylint ~8.5 segundos Ruff ~0.3 segundos

O Ruff é aproximadamente 14x mais rápido que a stack tradicional.

Solução de problemas comuns

Ruff lento em projetos grandes:

• Cache está ativado por padrão, verifique se não foi desabilitado

Muitos falsos positivos:

• Ajuste regras no pyproject.toml conforme necessidades do projeto

Conflito com Black:

• Ruff e Black são compatíveis por design, não há conflitos

Quando não usar Ruff

Situações onde Ruff pode não ser ideal:

• Projetos extremamente pequenos (1–2 arquivos)
• Necessidade de regras customizadas muito específicas
• Equipe resistente a mudanças de ferramentas

Na maioria dos casos profissionais, Ruff é altamente recomendado.

Recursos adicionais

• Documentação oficial: https://docs.astral.sh/ruff/
• Lista completa de regras: https://docs.astral.sh/ruff/rules/
• Playground interativo: https://play.ruff.rs/

Conclusão

Ruff resolve um problema fundamental e recorrente no desenvolvimento Python: código que funciona mas não está estruturalmente limpo. A ferramenta oferece velocidade excepcional, correções automáticas e integração simples com requisitos mínimos de configuração.

Para desenvolvedores que trabalham profissionalmente com Python, mantêm projetos de médio ou grande porte, ou desejam reduzir ruído em revisões de código, o Ruff não é uma opção adicional, mas uma ferramenta essencial.

Comece hoje:

pip install ruff
ruff check . --fix

Se seu código executa e passa nas verificações do Ruff, você já está acima da maioria dos projetos Python em termos de qualidade estrutural.

Até a próxima!