Analisar estilo e possíveis defeitos com Ruff

Você já usou o Ruff para padronizar a apresentação do código. O lint tem outro objetivo: examina o arquivo sem executar o programa e procura padrões de estilo ou indícios de possíveis problemas.

A formatação pode ajustar espaços, aspas e quebras de linha. O lint, por sua vez, produz diagnósticos que apontam onde um padrão foi encontrado. Nesta etapa, você apenas executará a análise e aprenderá a ler esses diagnósticos, sem corrigir o arquivo.

No terminal, crie uma pasta para a prática, entre nela e abra essa pasta no editor de sua preferência. Use o mesmo ambiente Python em que o Ruff já está instalado.

Crie o arquivo analise.py e salve exatamente este conteúdo:

Com o terminal na mesma pasta do arquivo, execute:

A aparência pode variar um pouco conforme a versão do Ruff, mas cada diagnóstico informa os mesmos elementos essenciais:

• arquivo: qual arquivo contém o trecho;
• linha e coluna: a posição inicial do trecho destacado;
• código da regra: um identificador como F821;
• mensagem: uma descrição do padrão encontrado.

Por exemplo, a localização analise.py:7:12 aponta para a linha 7, coluna 12. Nessa posição começa o nome total da instrução return total. O código e a mensagem explicam qual diagnóstico foi associado a esse ponto.

O diagnóstico F401 indica que uma importação não é utilizada no código analisado. Isso não determina sozinho a correção.

• Se o programa não precisa da importação, remova-a.
• Se a operação deveria usar o recurso importado, recupere esse uso conforme a finalidade do programa.

No exemplo, math não participa do cálculo. Se a intenção é manter a expressão atual, a importação é dispensável. Se a intenção é usar explicitamente a função de raiz quadrada da biblioteca, o retorno pode chamar math.sqrt(...).

Analise a finalidade antes de escolher entre remover a primeira linha e usar math.sqrt.

O diagnóstico F821 aponta uma referência a um nome que não está definido naquele contexto. Antes de corrigir, verifique se houve:

• erro de digitação;
• ausência de uma importação necessária;
• referência ao nome errado.

Atribuir qualquer valor ao nome elimina a mensagem, mas pode esconder o defeito. No exemplo, a função recebeu taxa; portanto, usar taxa no cálculo é mais coerente do que inventar um valor para desconto. De modo semelhante, se Path(...) for necessário, a correção pode ser importar Path de pathlib, e não criar um nome arbitrário chamado Path.

Comparação didática entre o trecho original e a correção orientada pelo parâmetro da função.

O diagnóstico F841 aparece quando uma variável local recebe um valor, mas não é utilizada depois. Isso pode revelar um cálculo abandonado, uma atribuição desnecessária ou um resultado que deveria participar de uma operação ou do retorno.

No exemplo, o contrato da função exige o preço com desconto. O valor total é calculado, mas o retorno usa subtotal.

O Ruff aponta F841 na atribuição a total.

No primeiro exemplo, apagar total apenas eliminaria o aviso e manteria o retorno incorreto. A correção coerente é return total.

Em outros casos, o valor devolvido por uma chamada pode ser dispensável, mas a própria chamada pode produzir um efeito necessário. Nesse caso, remova somente a atribuição, não a chamada inteira.

O contrato exige salvar o pedido, mas não exige usar o protocolo devolvido.

Considere o contrato descrito nos comentários de cada função.

O Ruff possui um catálogo amplo de regras, mas cada execução aplica somente as regras habilitadas aos arquivos indicados. Sem uma configuração que altere a seleção, o Ruff habilita por padrão as famílias E4, E7, E9 e F.

Uma configuração existente pode mudar esse conjunto. Portanto, “nenhum diagnóstico encontrado” significa apenas que nenhum problema foi identificado dentro dos arquivos e das regras considerados naquela execução.

A seleção de regras funciona como um filtro: primeiro existem as regras disponíveis; depois vêm as habilitadas; por fim aparecem apenas os diagnósticos encontrados no arquivo analisado.

Para verificar explicitamente F401, F821 e F841 em analise.py, execute o comando abaixo na pasta em que o arquivo está salvo.

Alguns diagnósticos do Ruff têm correção automática; outros exigem uma decisão manual baseada na intenção do programa. A disponibilidade de uma correção não elimina a revisão.

O comando python -m ruff check analise.py --diff apresenta uma prévia das correções aplicáveis sem gravar o arquivo. Em um diff, linhas com - seriam removidas e linhas com + seriam acrescentadas. Confirme se essas mudanças preservam o comportamento esperado.

A correção automática deve passar por uma etapa de revisão antes de ser aplicada.

Em uma pasta dedicada, salve os arquivos abaixo como analise.py e test_analise.py. O exemplo contém uma importação sem uso e um nome indefinido. O teste registra o comportamento esperado para o desconto.

Execute na pasta que contém os dois arquivos. Essa execução normal mostra tanto o F401 quanto o F821.

Execute --diff e procure a remoção de import math. Ela é coerente porque o módulo não participa do cálculo. A prévia mostra somente correções aplicáveis e não substitui a execução normal usada para listar os diagnósticos restantes.

Depois da revisão, aplique as correções disponíveis com --fix e abra novamente analise.py para conferir o resultado.

Depois de --fix, execute novamente o Ruff. O F401 deve ter desaparecido, mas o F821 referente a total permanece. Execute também os testes: o cenário com desconto falha porque esse nome não existe.

A intenção registrada pelo teste indica que o desconto deve ser subtraído de subtotal. Corrija manualmente a linha para return subtotal - desconto e repita as duas verificações.

Uma supressão instrui o Ruff a não apresentar um diagnóstico, mas não altera o comportamento do programa. Ela só é adequada quando o código é intencional e existe uma justificativa clara para manter a situação indicada.

Aqui, a importação serve somente para verificar se o módulo está disponível. O comentário limita a supressão a F401, e a linha anterior registra a intenção.

Prefira # noqa: F401 na própria linha diagnosticada. Um # noqa sem código pode ocultar outros problemas presentes na mesma linha, dificultando revisões futuras.

Quando o Ruff não apresenta diagnósticos, a conclusão correta é limitada: nenhuma das regras habilitadas encontrou um problema nos arquivos analisados, considerando também eventuais supressões. Isso não comprova que todos os resultados do programa estejam corretos.

As ferramentas observam aspectos diferentes:

• Lint: padrões estáticos abrangidos pelas regras habilitadas.
• Verificação de tipos: compatibilidade de tipos descrita no código.
• Testes: resultados observáveis nos cenários executados.

Elas se complementam, mas nenhuma fornece, sozinha, uma prova geral de correção.

Crie os dois arquivos abaixo na mesma pasta. A função não contém F401, F821 nem F841, mas sua operação está errada: ela aumenta o preço quando deveria aplicar um desconto.

O Ruff não deve encontrar as três regras selecionadas em analise.py. Já o pytest deve mostrar que o resultado obtido é 110.0, e não 90.

Crie uma pasta dedicada e salve nela os dois arquivos abaixo. O contrato é simples: calcular_total deve devolver a soma dos preços menos o desconto. Primeiro execute o Ruff sem modificar o código e classifique os diagnósticos encontrados.

Salve este conteúdo no arquivo pedidos.py.

Salve o teste na mesma pasta.

Execute os comandos na pasta dos arquivos. Relacione cada F401, F821 e F841 à linha correspondente. Use --diff para examinar as correções automáticas disponíveis sem gravar o arquivo. Se as alterações respeitarem o contrato, aplique-as com --fix; depois faça manualmente as correções restantes. Neste caso, uma supressão só seria adequada se houvesse uma intenção real e documentável — não use noqa apenas para obter uma saída limpa.

Revise o arquivo depois de --diff e novamente depois de --fix. A disponibilidade exata de correções pode variar conforme a versão do Ruff.

Uma saída limpa só ganha significado quando você conhece o arquivo analisado, as regras executadas e as mudanças realizadas.