Guia Pyright: Verificação rápida de tipos estáticos para código Python

As dicas de tipo tornam o código Python mais fácil de entender e manter. Mas tem um porém: só com dicas não dá pra pegar os erros. Você precisa de um verificador de tipos para garantir que seu código realmente segue os tipos que você declarou.

Já usei o Mypy e o Pyright na produção. A vantagem da velocidade do Pyright fica mais clara durante o desenvolvimento. Os erros de digitação aparecem enquanto você digita, em vez de aparecerem depois de salvar. Em grandes bases de código, esse ciclo de feedback mais rápido faz uma diferença real.

Este tutorial aborda tudo o que você precisa para começar a usar o Pyright de forma eficaz. Vou te mostrar como instalar, configurar para o seu projeto e integrar com o VS Code. Também vou explicar as diferenças entre o Pyright e o Mypy.

O que é Pyright?

Pyright é um verificador de tipos estáticos para Python desenvolvido pela Microsoft. Ele lê seu código, analisa as anotações de tipo e mostra os erros quando os tipos não batem. Diferente das verificações em tempo de execução, que detectam erros quando o código é executado, a análise estática os detecta antes mesmo de você executar qualquer coisa.

Embora a maioria das ferramentas Python seja escrita em Python, o Pyright é escrito em TypeScript e funciona no Node.js. Escolha estranha para uma ferramenta Python, né? Mas é por isso que o Pyright é tão rápido. O motor JavaScript V8 é bem mais rápido do que o CPython.

Você vai encontrar o Pyright de duas maneiras. Você pode executá-lo como uma ferramenta de linha de comando em pipelines de CI/CD para detectar erros de tipo antes de fazer mesclagens. Ou talvez você já esteja usando sem saber. Ele alimenta o Pylance, a extensão Python da Microsoft para o VS Code. Aquelas ondulações vermelhas sob os erros de digitação? É o Pyright trabalhando nos bastidores.

A ferramenta vem com stubs de tipos agrupados para a biblioteca padrão do Python e pacotes comuns. Você não precisa instalar nada extra para verificar o código que usa os, json ou typing. Para pacotes de terceiros, o Pyright usa stubs mantidos pela comunidade do typeshed ou stubs específicos do pacote que você instala separadamente.

Como instalar o Pyright

Agora vamos colocar o Pyright pra funcionar no seu sistema. Você tem duas opções de instalação: npm (a abordagem nativa) ou pip (o wrapper Python).

Instalando o Pyright com o npm

A instalação recomendada usa o npm porque o Pyright roda no Node.js. Você vai precisar do Node.js versão 14.0.0 ou superior.

# Global installation
npm install -g pyright

# Run without installing globally
npx pyright

# Local project installation
npm install --save-dev pyright

Eu uso a instalação global para verificações rápidas e a instalação local para projetos em que quero fixar a versão. A abordagem npx é útil para casos pontuais, sem adicionar nada aos seus pacotes globais.

Instalando o Pyright através do wrapper Python

Se sua equipe trabalha só com Python e não quer o Node.js na cadeia de ferramentas, tem um wrapper PyPI:

# Standard installation
pip install pyright

# Recommended: includes Node.js automatically
pip install pyright[nodejs]

O wrapper verifica se o Node.js está instalado no seu sistema. Se estiver faltando, o wrapper baixa uma versão independente automaticamente. O complemento [nodejs] usa um método de download mais confiável do que o padrão.

Lembre-se de que há prós e contras. A primeira execução demora mais tempo enquanto as dependências são baixadas. Ambientes CI com acesso restrito à rede podem apresentar falhas. E a versão PyPI às vezes fica alguns dias atrás dos lançamentos do npm.

Para a maioria das equipes Python, o wrapper funciona bem. Mas se você tiver problemas, volte para a instalação do npm. É mais confiável.

Executando o Pyright em um projeto Python

Depois de instalar, é bem fácil usar o Pyright. Vá até a pasta do seu projeto e execute:

pyright

É isso mesmo, na verdade. O Pyright procura arquivos Python, dá uma olhada neles e avisa se achar algum erro de tipo. Não precisa de nenhuma configuração complicada.

O que o Pyright verifica por padrão

O que o Pyright procura? Sem precisar de nenhuma configuração, ele faz várias verificações. Ele valida anotações de tipo que correspondem ao uso real. Ele detecta variáveis indefinidas e código inacessível. Ele verifica as importações direitinho. Ele sinaliza incompatibilidades de tipo óbvias, como passar uma string onde se espera um inteiro.

Aqui está um exemplo de saída de um projeto com erros:

/src/utils.py:12:15 - error: Argument of type "str" cannot be assigned 
   to parameter "count" of type "int" in function "process_items"
   "str" is not assignable to "int" (reportArgumentType)
/src/main.py:45:9 - error: "user" is possibly unbound (reportPossiblyUnbound)
2 errors, 0 warnings, 0 informations

Cada erro mostra o caminho do arquivo, o número da linha, a coluna e uma descrição. O nome da regra entre parênteses (como reportArgumentType) mostra exatamente qual verificação causou o erro. Isso é importante quando você quer suprimir regras específicas. Vamos falar sobre isso daqui a pouco.

Entendendo os códigos de saída

O Pyright retorna códigos de saída diferentes dependendo doresultado:

Nos pipelines de CI, você normalmente quer que a compilação falhe no código de saída 1. Os códigos de saída 2-4 mostram que rolou algum problema com a ferramenta em si, não com o seu código.

Configurando o Pyright

Embora o Pyright funcione direto da caixa, projetos reais precisam de personalização. Você vai querer especificar quais arquivos verificar, qual versão do Python usar e o nível de rigor da análise. Vamos dar uma olhada nas principais opções de configuração.

Modos de verificação de tipos

A Pyright tem quatro níveis de rigor. O modo que você escolher determina quantas regras são ativadas.

Qual modo você deve escolher? Para novos projetos, comece como padrão no modo. Ele pega bugs reais sem te encher de erros. Trabalhando com código antigo? O modo básico " " funciona melhor quando você está começando a digitar aos poucos. Guarde o modoestrito para bibliotecas e infraestruturas críticas onde você quer segurança máxima.

Aviso: a mudança do padrão para o rigoroso é bem grande. O modo estrito ativa cerca de 30 regras adicionais, incluindo requisitos para anotações de tipo em todos os parâmetros de função e valores de retorno. Espere um aumento de 10 vezes nos erros relatados ao mudar. Aprendi isso da maneira mais difícil.

O modo estrito exige anotações de tipo completas. Imagem do autor

Arquivos de configuração

O Pyright lê a configuração em pyrightconfig.json ou pyproject.toml. Se ambos existirem, pyrightconfig.json tem prioridade.

Aqui está um exemplo básico pyrightconfig.json:

{
  "include": ["src"],
  "exclude": ["**/node_modules", "**/__pycache__", "**/.venv"],
  "pythonVersion": "3.12",
  "typeCheckingMode": "standard"
}

O equivalente em pyproject.toml:

[tool.pyright]
include = ["src"]
exclude = ["**/node_modules", "**/__pycache__", "**/.venv"]
pythonVersion = "3.12"
typeCheckingMode = "standard"

O arquivo de configuração controla o comportamento do Pyright. Imagem do autor.

Aqui está um detalhe importante que confunde muita gente: se você definir manualmente um exclude, ele substitui os padrões por completo. Sempre inclua node_modules, __pycache__ e seu ambiente virtual nos padrões de exclusão personalizados. Caso contrário, o Pyright tenta analisar suas dependências, causando lentidão significativa. Acredite, você não vai querer esperar 10 minutos por uma verificação de tipo.

Configuração do ambiente virtual

Como o Pyright encontra os pacotes que você instalou? Você precisa dizer a ele onde procurar. Configure isso com venvPath e venv:

{
  "venvPath": ".",
  "venv": ".venv"
}

Isso diz ao Pyright para procurar pacotes em ./.venv. Se você usar um local diferente para o ambiente virtual, ajuste conforme necessário. Sem isso, o Pyright não consegue encontrar suas dependências instaladas e mostra erros de importação faltando para tudo.

Suprimindo diagnósticos

Às vezes, o Pyright está tecnicamente certo, mas você precisa silenciar erros específicos de qualquer maneira. Talvez você esteja trabalhando com código legado ou saiba mais do que o verificador de tipos em um caso específico. Você pode suprimir erros em três níveis.

Supressão do nível de configuração

Desative as regras globalmente:

{
  "reportMissingTypeStubs": "none",
  "reportUnusedVariable": "warning"
}

Supressão no nível do arquivo

Adicione um comentário no topo do arquivo:

# pyright: basic
# pyright: reportPrivateUsage=false

Supressão de nível de linha

Suprimir uma única linha:

x: int = "hello"  # type: ignore
x: int = "hello"  # pyright: ignore
x: int = "hello"  # pyright: ignore[reportAssignmentType]

A sintaxe específica da regra ([reportAssignmentType]) é útil quando você quer silenciar uma verificação sem desativar as outras na mesma linha.

Com a configuração pronta, vamos ver como o Pyright se integra ao seu ambiente de desenvolvimento.

Pyright no VS Code e IDEs

Se você é como a maioria dos desenvolvedores Python, vai experimentar o Pyright através do Pylance, em vez da linha de comando. Entender essa relação ajuda você a configurar seu editor corretamente e evitar erros comuns.

Pyright contra. Pylance

O Pylance é uma extensão do VS Code da Microsoft que vem com o mecanismo de verificação de tipos do Pyright. Quando você instala o Pylance, você recebe o Pyright automaticamente. Mas o Pylance traz recursos que não estão no Pyright de código aberto:

• Destaque semântico: variáveis coloridas de acordo com seu tipo
• Importação automática avançada: sugestões de importação mais inteligentes
• Navegação no código: Encontre todas as referências no seu espaço de trabalho

Esses recursos são de código fechado e só estão disponíveis no VS Code. Se você usa o Neovim, Emacs ou outro editor, você tem as funcionalidades principais do Pyright, mas não esses extras.

O Pylance destaca erros de tipo no editor. Imagem do autor.

Configurações essenciais do VS Code

Configure o Pylance nas configurações do VS Code:

{
  "python.languageServer": "Pylance",
  "python.analysis.typeCheckingMode": "standard",
  "python.analysis.diagnosticMode": "openFilesOnly"
}

A configuração “ diagnosticMode ” (Analisar todos os arquivos) afeta o desempenho. A opção “ "openFilesOnly" ” (Analisar apenas os arquivos abertos) analisa apenas os arquivos que você tem abertos. A opção “ "workspace" ” ( Analisar tudo) analisa tudo, mas usa mais memória e CPU.

Problemas comuns de configuração

A escolha do intérprete é importante. O Pylance usa o interpretador Python que você escolheu para encontrar os pacotes instalados. Se aparecerem erros de repente em pacotes que você sabe que estão instalados, veja se o interpretador certo está selecionado na barra de status do VS Code.

A escolha do interpretador afeta os caminhos de descoberta de pacotes. Imagem do autor.

Os padrões do CLI e do Pylance são diferentes. O Pylance usa como padrão typeCheckingMode para "off", enquanto a CLI usa como padrão "standard". O Pylance também adiciona automaticamente src aos caminhos de pesquisa; a CLI não faz isso. Para garantir um comportamento consistente entre o seu editor e o CI, defina explicitamente todas as opções em pyproject.toml.

O fenômeno do “código esmaecido”. O Pylance deixa o código inacessível em cinza com base na análise de tipo. Se o código aparecer esmaecido de repente, dá uma olhada na função chamada logo antes dele. Uma função definida como retornando um NoReturn e faz com que tudo depois dela pareça inacessível.

Pyright contra. Mypy: Quando usar cada um

Você pode estar se perguntando: devo usar o Pyright ou continuar com o Mypy? As duas ferramentas estão prontas pra produção, e a escolha depende do seu fluxo de trabalho e dos seus requisitos. Deixa eu explicar as principais diferenças.

Velocidade e capacidade de resposta

O Pyright é tipo 3 a 5 vezes mais rápido que o Mypy pra varreduras completas de projetos e é praticamente instantâneo pra verificações incrementais. Isso é mais importante durante o desenvolvimento, quando você quer um feedback imediato.

O Mypy tem um modo daemon (dmypy) que melhora o desempenho, mas ainda é mais lento e, às vezes, tem problemas de cache que exigem reinicializações.

Diferenças na inferência de tipos

É aqui que as coisas ficam interessantes. As ferramentas inferem os tipos de forma diferente. Olha só esse código:

coordinates = (10, 20)

Pyright faz uma inferência de tuple[Literal[10], Literal[20]], mantendo os valores exatos porque as tuplas são imutáveis. O Mypy chama o tuple[int, int], ampliando para tipos gerais.

A abordagem de Pyright detecta mais erros, mas às vezes causa atrito quando as funções esperam tipos gerais. Isso raramente importa na prática, porque Literal[10] é um subtipo válido de int.

Análise de código sem anotações

Essa é a maior diferença prática e é um divisor de águas para bases de código legadas. O Mypy ignora funções sem anotações por padrão. O Pyright analisa mesmo assim, pegando erros óbvios mesmo sem dicas de tipo.

Para bases de código antigas com poucas anotações, o Pyright funciona como um linter poderoso que detecta variáveis indefinidas e chamadas de método impossíveis. O Mypy trata essas funções como “dinâmicas” e as ignora.

Suporte a plugins

O Mypy aceita plugins para frameworks como Django e SQLAlchemy. Esses plugins entendem a magia do ORM e fornecem tipos precisos para atributos gerados dinamicamente.

O Pyright não tem um sistema de plugins. Ele depende totalmente de stubs de tipo. Em 2026, a maioria das grandes bibliotecas tem esboços de alta qualidade, então isso importa menos do que antes. Mas se você usar uma estrutura com metaprogramação pesada, veja se tem bons stubs antes de fazer commitno Pyright.

Use o Pylance (Pyright) durante o desenvolvimento para obter feedback instantâneo e considere executar o Pyright e o Mypy na CI se o seu projeto usar plug-ins de estrutura.

Problemas comuns ao usar o Pyright

Quando o Pyright mostra erros inesperados, geralmente é por causa de um desses problemas.

Estubos de tipo ausentes

Já viu esse erro? O Pyright reclama quando não consegue encontrar informações de tipo para um pacote:

Import "requests" could not be resolved (reportMissingImports)

Os stubs ausentes geram erros de aviso de importação. Imagem do autor.

Primeiro, veja se o pacote está instalado no seu ambiente virtual e se o Pyright sabe onde encontrá-lo (usando as configurações venvPath e venv que falamos antes).

Se o pacote estiver instalado, mas não tiver informações de tipo, instale os stubs da comunidade:

pip install types-requests types-PyYAML types-redis

Para pacotes sem stubs disponíveis, você tem duas opções. Você pode desativar o aviso com "reportMissingTypeStubs": "none" na sua configuração. Ou crie você mesmo rascunhos de stubs:

pyright --createstub some_package

Isso cria um arquivo esqueleto .pyi que você pode preencher com os métodos que realmente usa.

Falhas no gancho pré-confirmação

O Pyright funciona localmente, mas não dá certo nos ganchos pré-confirmação? O problema geralmente é o isolamento do ambiente. O pré-confirme executa ganchos em ambientes isolados que não conseguem ver os pacotes instalados do seu projeto.

Resolva isso apontando o gancho para o seu ambiente virtual:

repos:
  - repo: https://github.com/RobertCraigie/pyright-python
    rev: v1.1.408
    hooks:
      - id: pyright
        args: ["--venvpath", ".", "--venv", ".venv"]

Erros inesperados no modo estrito

Ativou o modo estrito e de repente tá vendo milhares de erros? Não entre em pânico. Isso é normal. O modo estrito exige anotações de tipo completas. Comece com o modo básico ou padrão, adicione anotações aos poucos e só habilite o modo estrito em módulos totalmente tipados.

Use comentários por arquivo para manter o código legado em um modo mais flexível:

# pyright: basic

Isso permite que você faça uma verificação rigorosa do novo código enquanto migra gradualmente o código antigo.

Além da resolução de problemas, aqui estão algumas dicas que vão deixar sua experiência com o Pyright mais tranquila desde o começo.

Melhores práticas para usar o Pyright

Depois de trabalhar com a Pyright em vários projetos, aprendi algumas coisas que facilitam a adoção. Adotar essas práticas recomendadas de codificação garante que sua verificação de tipos continue sendo uma ajuda, e não um obstáculo.

Comece com o modo padrão. Como falamos antes, ele pega bugs reais sem precisar de anotações completas. Você sempre pode tornar as regras mais rígidas depois.

Marque sua versão do Pyright. A Pyright lança atualizações com frequência, e às vezes as novas versões sinalizam códigos que antes eram aprovados. No CI, um pip install pyright não fixado pode causar falhas na compilação na segunda-feira de manhã devido a lançamentos no fim de semana. Já passei por isso. Não é divertido.

[tool.pyright]
# In pyproject.toml
pythonVersion = "3.12"

# In requirements-dev.txt
pyright==1.1.408

Corrija os erros aos poucos. Não tente eliminar 10.000 erros de uma só vez. Use a matriz ` strict ` para fazer uma verificação rigorosa só em diretórios específicos:

{
  "typeCheckingMode": "standard",
  "strict": ["src/core", "src/api"]
}

Use os arquivos de configuração logo de cara. Mesmo em projetos pequenos, uma configuração clara evita surpresas. Reserve cinco minutos para documentar sua versão do Python, o caminho do ambiente virtual e o nível de rigor escolhido. Seu eu futuro vai te agradecer.

Não tente ser perfeito logo de cara. Use bastante o # pyright: ignore no começo. Isso deixa a dívida técnica bem visível, pra você poder resolver com o tempo, em vez de atrapalhar o progresso. Perfeito é inimigo do bom, principalmente quando a gente está adotando novas ferramentas.