flake8: instalar e verificar código Python

Python

O Flake8 examina código Python sem executar o programa e aponta problemas de estilo e possíveis erros, como imports não utilizados. Instale-o no ambiente do projeto e execute python -m flake8 arquivo.py; use as posições e os códigos de diagnóstico para corrigir o código. Ele não valida todas as PEPs nem faz correções automaticamente.

PEPs, PEP 8 e o que é verificado

PEP significa Python Enhancement Proposal: um documento sobre funcionalidades, processos ou projetos do Python. No sistema de documentos PEP, a PEP 8 trata especificamente do estilo do código. Verificar estilo não significa validar todas as propostas da linguagem.

O Flake8 integra o pycodestyle, a análise estática do Pyflakes e a verificação de complexidade do mccabe. A complexidade exige um limite, como --max-complexity. E e W se referem principalmente a estilo; F vem do Pyflakes. Plugins podem acrescentar verificações e códigos. O Flake8 não substitui verificadores de tipos nem testes.

Instalar no ambiente do projeto

Abra uma nova pasta de exercício no Windows PowerShell. É necessário ter Python e o inicializador py. Se o projeto já possui um ambiente com esse nome, selecione seu interpretador em vez de recriá-lo. Usar diretamente o executável evita alterar a política de execução do script de ativação.

py -3 -m venv .venv
.\.venv\Scripts\python.exe -m pip install "flake8==7.4.1"
.\.venv\Scripts\python.exe -m flake8 --version

O Flake8 7.4.1 exige Python 3.10 ou posterior. Os comandos e diagnósticos foram verificados no Windows com Python 3.12.14 e Flake8 7.4.1. Fixar a versão permite reproduzir o exemplo; ao escolher outra versão, confira os requisitos do Python e mudanças nos diagnósticos. O último comando mostra as versões do Flake8 e dos componentes.

No macOS ou Linux, crie o ambiente com o Python 3 disponível e execute pip e Flake8 por .venv/bin/python. Não copie literalmente o caminho do Windows. A execução como módulo ajuda a usar o mesmo interpretador na instalação e na verificação.

Ler posições e códigos de diagnóstico

Crie bad.py no projeto com este código completo. Inclua uma quebra de linha ao final da última linha. Ao executá-lo com o Python do ambiente, a saída será 1.

import os
value=1
print(value)

Um programa que funciona ainda pode conter código desnecessário ou problemas de estilo. Verifique o mesmo arquivo na pasta do projeto:

.\.venv\Scripts\python.exe -m flake8 bad.py

bad.py:1:1: F401 'os' imported but unused
bad.py:2:6: E225 missing whitespace around operator

O formato é arquivo:linha:coluna: código explicação. F401 informa que o import de os, na linha 1, não é usado. E225 indica ausência de espaços ao redor da atribuição na linha 2, coluna 6. A verificação termina com código de saída 1 porque encontrou violações. Consulte a referência de diagnósticos e a documentação do componente responsável.

Corrigir e verificar novamente

Remova o import não utilizado e adicione espaços ao redor do operador. Substitua todo o conteúdo do bad.py existente pelo código abaixo. A saída do programa continua sendo 1.

value = 1
print(value)

Verifique novamente o mesmo arquivo. --count acrescenta a quantidade de violações ao final:

.\.venv\Scripts\python.exe -m flake8 --count bad.py

O exemplo corrigido tem zero violações e código de saída 0. Sem --count, uma verificação sem problemas normalmente não apresenta diagnósticos. O Flake8 não faz essas alterações: salve as correções no editor e execute a verificação outra vez. Confira separadamente o resultado do programa e o resultado da análise.

Salvar regras em .flake8

Crie .flake8 na raiz do projeto. O conteúdo é configuração INI, não código Python. O limite de 88 caracteres é uma política de exemplo. O máximo padrão do Flake8 é 79; escolher 88 não altera as recomendações da PEP 8.

[flake8]
max-line-length = 88
extend-exclude = .venv,build,dist

extend-exclude mantém as exclusões padrão e acrescenta o ambiente e as pastas de compilação. Confira se não está excluindo fontes que precisam de análise. Indique explicitamente a configuração:

.\.venv\Scripts\python.exe -m flake8 --config .flake8 --count bad.py

O resultado também é zero. Troque o último bad.py por . para verificar o projeto; outros arquivos podem gerar avisos. A documentação de configuração explica a seção [flake8] em .flake8, setup.cfg e tox.ini. Os argumentos da linha de comando têm prioridade, incluindo os enviados pelo editor ou pela CI.

Exceções e verificações automáticas

Antes de ocultar um aviso, decida se o código é desnecessário ou se há uma exceção justificada. Para uma exceção inevitável de uma linha, registre o motivo e restrinja o código, como em # noqa: F401. ignore substitui a lista padrão; extend-ignore acrescenta itens. Consulte o significado das opções.

Na integração contínua (CI), preserve o código de falha. --exit-zero informa sucesso mesmo com violações e não serve para exigir aprovação da análise. Registre as versões do Flake8 e dos plugins nas dependências e confira mudanças de regras nas atualizações. Uma análise sem avisos não comprova entradas corretas, lógica de negócio ou compatibilidade de execução; execute também o programa e os testes necessários.

Python