O Modelo de Pipeline de Análise Estática

Ruff, Black, mypy e pre-commit são agrupados como "ferramentas de qualidade de código", mas não são variações de um único mecanismo - são três técnicas genuinamente diferentes para ler código-fonte sem executá-lo, conectadas em um pipeline. Configuração do Ruff e as páginas que o seguem mostram como configurar cada ferramenta; esta página explica por que linting, formatação e verificação de tipos existem como preocupações separadas e por que executar as mesmas verificações em um editor, um hook de pre-commit e CI é uma estratégia deliberada em vez de repetição desperdiçada.

Essa distinção importa no momento em que algo dá errado: um formatador brigando com um linter sobre o comprimento da linha, um verificador de tipos sinalizando algo que o Ruff ignorou tranquilamente, ou um hook de pre-commit que passa localmente, mas falha no CI, todos rastreiam a incapacidade de saber qual desses três mecanismos é realmente responsável pela verificação em questão.

Resumo

Ferramentas de análise estática respondem a três perguntas distintas sobre o código-fonte sem executá-lo - isso é sintática/estilisticamente correto (linting), isso está formatado consistentemente (formatação) e isso verifica tipos (análise semântica) - e cada uma usa um mecanismo interno diferente para fazê-lo.
Por que Importa: Tratar linting, formatação e verificação de tipos como um "gate de qualidade" indiferenciado leva a pipelines mal configurados - regras que lutam entre si, verificações colocadas no estágio errado do pipeline ou erros de tipo confundidos com detalhes de estilo.
Conceitos Chave: árvore de sintaxe abstrata (AST), regra de lint, idempotência do formatador, inferência de tipo, shift-left, hook de pre-commit.
Quando Usar Este Modelo: Decidir onde uma nova verificação pertence (editor, pre-commit ou apenas CI), diagnosticar por que um formatador e um linter discordam, explicar a uma equipe por que a verificação de tipos não é "apenas um linter mais rigoroso" e projetar um pipeline que falhe rapidamente sem se tornar lento ou barulhento.
Limitações / Trade-offs: Nenhuma dessas ferramentas prova que o programa está correto - um linter captura padrões ruins conhecidos, um formatador impõe consistência e um verificador de tipos verifica a consistência interna dos tipos declarados, mas um programa totalmente lintado, formatado e verificado por tipo ainda pode ter lógica de negócios incorreta.
Tópicos Relacionados: o pipeline CI/CD em que esses gates são executados, pytest como a camada que realmente verifica o comportamento, ferramentas de editor e servidores de linguagem.

Fundamentos

Linting e formatação começam com o mesmo primeiro passo - analisar o código-fonte em uma árvore de sintaxe abstrata (AST), uma representação estruturada da gramática do código sem comentários ou espaços em branco anexados - mas depois fazem coisas completamente diferentes com ela. Um linter percorre essa árvore procurando padrões que correspondam a problemas conhecidos: um import não utilizado, um except: genérico, um argumento padrão mutável - cada padrão é uma regra, e o disparo de uma regra produz um diagnóstico com uma localização e uma mensagem, opcionalmente acompanhado de uma correção automática. Um formatador, por outro lado, não procura problemas; ele pega a mesma AST (ou uma árvore de sintaxe concreta semelhante) e a reimprime de acordo com um estilo fixo, descartando completamente os espaços em branco e quebras de linha originais e regenerando-os do zero.

É por isso que executar um formatador duas vezes em um código já formatado não produz alterações - idempotência é o contrato principal do formatador, e qualquer formatador que não possa garanti-lo está quebrado por definição. Um linter não tem um contrato equivalente, porque corrigir uma violação às vezes pode revelar ou introduzir outra (remover um import não utilizado pode revelar uma variável não utilizada que dependia dele), então lint-e-corrija é tipicamente executado até um ponto fixo ou com um número limitado de passes em vez de assumir que converge em um.

Uma analogia útil: um formatador é um editor de cópias que impõe um estilo de casa sem julgamentos - todo manuscrito sai formatado da mesma maneira, independentemente do conteúdo. Um linter está mais próximo de um revisor que sinaliza erros específicos conhecidos - um modificador pendente aqui, uma conjugação verbal incorreta ali - cada um sinalizado individualmente, com algumas sinalizações fáceis de corrigir automaticamente e outras exigindo uma decisão humana.

# pyproject.toml - dois mecanismos diferentes, um arquivo de configuração
[tool.ruff.lint]
select = ["E", "F", "B"]   # correspondência de padrões sobre a AST
 
[tool.ruff.format]
quote-style = "double"     # reimpressão determinística, sem correspondência de padrões

Mecânicas e Interações

Um verificador de tipos como mypy ou pyright é um tipo de ferramenta completamente diferente, e confundi-lo com "um linter mais rigoroso" é o mal-entendido mais comum nesse espaço. Onde um linter avalia cada padrão em grande parte em contexto local, um verificador de tipos executa inferência de tipos em todo o grafo de chamadas alcançável: ele lê cada assinatura de função e anotação, propaga os tipos inferidos através de atribuições e retornos, e verifica se cada operação é consistente com os tipos que derivou - capturando um None passado onde um str era esperado, mesmo quando as duas linhas envolvidas estão em arquivos completamente diferentes. Esse raciocínio de programa completo também é o motivo pelo qual a verificação de tipos é mais lenta do que o linting em uma base de código comparável, e por que geralmente é executada como uma etapa de CI separada com seu próprio cache em vez de ser incorporada na mesma passagem do Ruff.

Os três mecanismos interagem através da configuração muito mais do que através de lógica compartilhada, e a maior parte do atrito que as equipes encontram vem dessa interação, em vez de qualquer ferramenta isolada. O exemplo clássico é o comprimento da linha: um formatador impõe um comportamento de quebra de linha de forma determinística, então uma regra de lint que também sinaliza linhas longas (E501) às vezes discordará do que o formatador acabou de produzir, razão pela qual a própria orientação de configuração do Ruff desabilita E501 e deixa o formatador ser o único responsável pelo comprimento da linha em vez de executar duas autoridades sobre a mesma questão. A ordenação de imports mostra o mesmo padrão ao contrário - é genuinamente uma preocupação de linting (há uma ordem correta e verificável) que as regras I do Ruff absorveram da ferramenta independente isort, obscurecendo a linha entre "linter" e "formatador" para esse comportamento específico e estreito sem alterar o que cada mecanismo fundamentalmente faz.

Shift-left descreve onde no loop de desenvolvimento cada uma dessas verificações é realmente executada, e é uma estratégia genuína em vez de repetição redundante: uma integração de editor (um servidor de linguagem) exibe um erro de lint ou tipo enquanto você digita, um hook de pre-commit captura qualquer coisa que passou despercebida antes de chegar ao controle de versão, e CI é o portão final e inegociável que executa as mesmas verificações em um ambiente limpo que nenhuma máquina local pode desviar. Cada camada existe porque as anteriores são opcionais ou podem ser contornadas (um hook pode ser pulado com --no-verify, uma extensão de editor pode ser desativada) - CI é o que realmente impõe o padrão, e as camadas anteriores existem puramente para tornar a falha desse gate rara e barata de corrigir.

Considerações Avançadas e Aplicações

A colocação importa mais do que a escolha da ferramenta quando um pipeline escala além de um punhado de arquivos, porque cada mecanismo tem um perfil de custo diferente que determina onde ele pertence. Formatação e regras de lint rápidas são baratas o suficiente para serem executadas a cada pressionamento de tecla em um editor e em cada commit em um hook; a análise de programa completo da verificação de tipos geralmente é muito lenta para um hook de pre-commit em uma base de código grande e pertence ao CI com seu próprio cache incremental, executada com menos frequência, mas nunca pulada.

Violações corrigíveis automaticamente e violações estruturais também exigem caminhos de remediação diferentes, e pipelines que não os distinguem criam falsa confiança: uma regra com correção automática segura (import não utilizado, estilo de citação) pode ser corrigida mecanicamente e verificada novamente na mesma execução, enquanto uma violação estrutural (uma incompatibilidade de tipo real, um bug real que as regras de "bugbear" do linter pegaram) requer que um humano altere a lógica real, e nenhum sinalizador --fix jamais a resolverá. A adoção gradual de regras mais rigorosas - mover uma base de código legada de check_untyped_defs para strict = true completo no mypy, por exemplo - é realmente uma afirmação sobre ruído tolerável: habilitar todas as regras de uma vez em um código não tipado produz milhares de diagnósticos que ensinam os engenheiros a ignorar a ferramenta completamente, enquanto uma implementação em fases mantém a relação sinal-ruído alta o suficiente para que as pessoas realmente ajam sobre ela.

Mecanismo	Força	Fraqueza	Melhor Ajuste
Linting (Ruff, pylint)	Rápido, captura padrões ruins conhecidos, muitos corrigíveis automaticamente	Apenas tão bom quanto seu conjunto de regras; perde erros de lógica de programa completo	Cada commit e execução de CI, feedback de alta frequência
Formatação (Ruff format, Black)	Debate de estilo zero, sempre idempotente	Não tem opinião sobre correção, apenas aparência	Cada commit; nunca deve ser uma discussão de revisão manual
Verificação de tipos (mypy, pyright)	Captura bugs de lógica reais entre arquivos (segurança contra None, formas incorretas)	Lenta, análise de programa completo; barulhenta em código legado não tipado	Gate de CI, executado separadamente com cache incremental

Conceitos Errôneos Comuns

"Um verificador de tipos é apenas um linter com mais regras." Ele executa inferência de tipos de programa completo em todo o seu grafo de chamadas, não correspondência de padrões local - esse é um tipo de análise fundamentalmente diferente (e mais lenta), não uma extensão da mesma.
"Se o formatador e o linter discordarem, um deles está quebrado." Eles estão respondendo a perguntas diferentes por design; o desacordo sobre algo como o comprimento da linha geralmente significa que a mesma preocupação está configurada em ambos os lugares e precisa ser de responsabilidade de um deles.
"Executar a mesma regra de lint no editor, pre-commit e CI é redundante." Cada camada existe porque as anteriores podem ser puladas - CI é a única camada que realmente impõe algo; as camadas anteriores existem para tornar a falha do CI rara.
"100% livre de lint e tipo significa que o código está correto." Ambas as ferramentas verificam a consistência interna contra padrões conhecidos ou tipos declarados - nenhuma delas verifica se a sua lógica de negócios faz a coisa certa, que é para o que os testes servem.
"Habilitar o modo estrito em todos os lugares imediatamente é a escolha responsável." Em uma base de código legada não tipada ou não lintada, ele produz tantos diagnósticos que a ferramenta é ignorada; a estrita gradual e em fases mantém o sinal utilizável.

FAQs

Qual é a diferença real entre o que um linter e um formatador fazem?

Um linter procura na AST padrões conhecidos como ruins e relata (ou corrige automaticamente) violações; um formatador reimprime a mesma AST em um estilo determinístico fixo, sem noção de "problemas".

Por que executar um formatador duas vezes no mesmo arquivo não produz alterações?

A idempotência é uma propriedade definidora do formatador - como ele sempre regenera espaços em branco e quebras de linha a partir das mesmas regras fixas, formatar um código já formatado é uma operação nula por construção.

A ordenação de imports é uma preocupação de linting ou de formatação?

É genuinamente uma preocupação de linting (há uma ordem correta verificável), razão pela qual as regras I do Ruff absorveram o comportamento da ferramenta independente isort em vez de incorporá-lo ao formatador.

Por que um verificador de tipos é mais lento do que um linter na mesma base de código?

Um linter avalia principalmente padrões em contexto local; um verificador de tipos executa inferência em todo o grafo de chamadas alcançável, propagando tipos através de cada atribuição e retorno - esse raciocínio de programa completo é inerentemente mais caro.

Por que desabilitar `E501` (linha muito longa) junto com um formatador faz sentido?

Porque o formatador já é o responsável pela quebra de linha de forma determinística; uma regra de lint separada para a mesma preocupação pode discordar do que o formatador acabou de produzir, então a maioria das configurações do Ruff deixa uma autoridade ser responsável pelo comprimento da linha.

Por que executar as mesmas regras de lint em um editor, um hook de pre-commit e CI em vez de apenas CI?

Cada camada anterior é um loop de feedback mais barato e rápido que também pode ser pulado - o editor captura problemas enquanto você digita, o hook captura qualquer coisa antes de ser commitada, e CI é a única camada que ninguém pode contornar, então juntos eles tornam a falha do CI rara em vez de duplicar o esforço.

Uma regra de lint e um verificador de tipos podem sinalizar o mesmo bug?

Ocasionalmente, mas geralmente não - regras de "bugbear" de um linter capturam padrões perigosos conhecidos localmente (como um argumento padrão mutável), enquanto um verificador de tipos captura inconsistências entre arquivos que uma regra de correspondência de padrões não tem como ver.

Por que adotar `strict = true` no mypy de uma vez geralmente dá errado em uma base de código existente?

Ele expõe todas as lacunas de tipagem não verificadas anteriormente simultaneamente, muitas vezes milhares de diagnósticos em uma base de código não tipada grande, o que ensina os engenheiros a ignorar a ferramenta em vez de corrigir os problemas gradualmente.

Uma violação de lint corrigível automaticamente significa que o problema subjacente é trivial?

Nem sempre - uma correção automática (como remover um import não utilizado) é segura porque é mecânica, mas uma violação estrutural que o mesmo linter sinaliza (um bug de lógica real capturado pelo bugbear) ainda requer que um humano altere o código real.

Uma base de código totalmente lintada, formatada e verificada por tipo é garantida como correta?

Não - todas as três ferramentas verificam a consistência interna (estilo, formatação, tipos declarados), não se a lógica de negócios faz a coisa certa; isso é especificamente o que um conjunto de testes serve.

Por que os hooks de pre-commit às vezes passam localmente, mas falham no CI?

Geralmente uma incompatibilidade de versão ou cache entre o hook instalado localmente e a versão fixada que o CI executa, ou um hook que foi pulado localmente (--no-verify) - o CI executando em um ambiente limpo é exatamente o que o torna o gate autoritativo.

A verificação de tipos deve ser executada em arquivos de teste da mesma forma que em código de aplicação?

Muitas equipes relaxam as regras de verificação de tipos para tests/ (via um override do mypy), pois o código de teste tem necessidades ergonômicas diferentes do código de produção, enquanto ainda mantêm o código de aplicação sob estrita conformidade total.

Relacionados

Configuração do Ruff - configurando diretamente o mecanismo de lint e formato baseado em AST
Black / Ruff Format - o mecanismo de reimpressão determinística em profundidade
Regras Essenciais de Lint - quais categorias de regras carregam sinal real
mypy & pyright no CI - o mecanismo de inferência de tipos de programa completo
Hooks de Pre-commit - a camada de shift-left antes do controle de versão
Linting em CI/CD - a camada de imposição não contornável

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+.