Guia Pyright: instalação, configuração e casos de uso

Você já quis uma verificação de tipo mais rápida para Python sem retardar seu fluxo de trabalho? Ferramentas como MyPy podem detectar erros de digitação, mas muitas vezes parecem lentas ou desconectadas da experiência do editor. É aqui que entra o Pyright. Pyright é um verificador de tipo estático baseado em padrões para Python, projetado para velocidade e suggestions rápido. Ele é executado como ferramenta de linha de comando e como servidor de linguagem, permitindo diagnósticos em tempo actual enquanto você escreve código. Ele se integra intimamente às ferramentas Python da Microsoft e funciona entre editores por meio do Language Server Protocol (LSP).

O que é direitos autorais?

Pyright usa um sistema de configuração baseado em projeto que outline quais arquivos serão analisados ​​e como as importações serão resolvidas. Ele também permite que as equipes especifiquem a versão alvo do Python e controlem o nível de rigor da verificação de tipo. Essa flexibilidade facilita o início com verificações básicas e a introdução gradual de regras mais rígidas à medida que a base de código amadurece. O Pyright se integra bem aos fluxos de trabalho de CI e se adapta de maneira eficaz a grandes projetos, permitindo que as equipes adotem digitação estática sem interromper as práticas de desenvolvimento existentes.

Se você quiser saber os fundamentos do Python para construir agentes de IA, confira nosso Curso GRATUITO sobre ABC de codificação para agentes de construção.

Objetivo e recursos principais

Pyright ajuda os desenvolvedores a detectar erros de tipo no início do código Python. Como a digitação do Python permanece opcional em tempo de execução, a análise estática ajuda a identificar problemas antes da execução, como tipos de argumentos incorretos, insegurança None acesso e atribuições inválidas. Pyright segue os padrões de digitação do Python e fornece suggestions rápido mesmo em grandes bases de código.

Pyright analisa o código usando um mecanismo para todo o projeto que analisa, vincula e verifica o tipo de arquivos sob regras configuráveis. Também se integra aos editores por meio de um servidor de linguagem, possibilitando diagnósticos em tempo actual durante o desenvolvimento.

Os principais recursos incluem:

• Análise de todo o projeto: os arquivos são analisados, vinculados e verificados por tipo em todo o projeto.
• Digitação sensível ao fluxo: os tipos são reduzidos com base no fluxo de controle.
• Suporte ao servidor de idiomas: Fornece diagnósticos em tempo actual nos editores.
• Digite verificações de integridade: ajuda a validar informações de tipo para bibliotecas.
• Portabilidade entre editores: implementado em TypeScript para suporte consistente de ferramentas.

Leia também: Um tutorial completo de Python para aprender ciência de dados do zero

Instalando direitos autorais

Pyright está disponível como ferramenta de linha de comando e como servidor de linguagem. A CLI é usada para verificações locais e de CI. O servidor de idiomas é usado pelos editores por meio do Language Server Protocol. Ambos usam o mesmo mecanismo principal.

O método de instalação mais comum é através do npm. Uma configuração típica é assim:

npm set up -g pyright 
pyright --version

Você pode então executar verificações de tipo com:

{
  "embrace": ("."),
  "exclude": ("**/__pycache__", "**/.venv", "**/.git"),
  "typeCheckingMode": "primary",
  "pythonVersion": "3.12"
}

Para iniciar o servidor de idiomas diretamente, use:

pyright-langserver --stdio 

Wrappers Python da comunidade também estão disponíveis. Eles instalam o Node e o pacote Pyright npm automaticamente. Eles não alteram o verificador em si.

Em Código do Visible Studioos desenvolvedores geralmente usam Direitos autorais através Pilânciaque executa o Pyright nos bastidores. Você pode controlar o comportamento de verificação de tipo por meio de configurações do espaço de trabalho, como python.evaluation.typeCheckingMode e python.evaluation.diagnosticMode. Se preferir executar o Pyright diretamente, você pode instalar o pacote separado Extensão de direitos autorais.

Em Neovimos desenvolvedores normalmente executam o Pyright por meio do servidor de linguagem. Muitas configurações usam nvim-lspconfig para configurá-lo. Neovim inicia o servidor com pyright-langservere você pode definir configurações de análise em settings.python.evaluation para controlar o rigor e o escopo do espaço de trabalho.

Outros clientes LSP

Pyright funciona em muitos editores porque funciona como um servidor de linguagem. Qualquer editor que suporte o Protocolo de servidor de linguagem (LSP) pode começar pyright-langserver. O servidor lê a configuração de pyrightconfig.json ou o device.pyright seção em pyproject.tomlque mantém o comportamento de verificação de tipo consistente em diferentes ferramentas.

Editores como Emacs e Texto chic conecte-se diretamente a pyright-langserver e lidar com tarefas como detecção de ambiente e inicialização de servidor. O próprio Pyright ainda realiza todas as verificações de tipo e diagnósticos.

Características principais:

• Funciona com qualquer Editor compatível com LSP
• Usos pyright-langserver como back-end
• Honras arquivos de configuração do projeto
• Fornece diagnósticos consistentes entre editores

Configuração com pyrightconfig.json

Pyright fornece duas maneiras principais de definir a configuração do projeto. Você pode colocar um pyrightconfig.json arquivo na raiz do projeto ou defina um device.pyright seção dentro pyproject.toml. Se ambos existirem, pyrightconfig.json tem prioridade.

A configuração concentra-se em alguns aspectos essenciais de como o Pyright analisa um projeto.

Arquivos para analisar

• Controlado por embrace, excludee ignore
• Arquivos listados em exclude ainda poderão ser analisados ​​caso sejam importados
• Arquivos listados em ignore suprimir diagnósticos

Ambiente Python

• Definido por pythonVersion e pythonPlatform
• executionEnvironments permite vários alvos
• A resolução de importação pode usar extraPaths e venv configurações

Rigor de verificação de tipo

• typeCheckingMode outline o nível de linha de base
• Regras estritas podem ser habilitadas para arquivos ou pastas específicos

Configuração de diagnóstico

• Regras de relatórios individuais podem ser personalizadas
• Os níveis de gravidade podem ser none, information, warningou error

Exemplos de tipos de projetos comuns

Os exemplos a seguir mostram configurações comuns do Pyright. Eles são opinativos, mas práticos. Cada um usa opções documentadas. O objetivo é equilibrar sinal, desempenho e velocidade de adoção.

Script de arquivo único ou repositório estilo pocket book

Esta configuração favorece um suggestions rápido. Evita o rigor precoce. Funciona bem para experimentos e pequenas ferramentas.

• Ampla inclusão para capturar problemas óbvios
• Verificação básica de baixo atrito
• Versão explícita do Python

Repositório de pacotes com src/format e testes

Esta configuração estabiliza as importações. Reflete como o pacote é realmente executado. É comum para bibliotecas e serviços.

• Separar src e exams diretórios
• Use um nível de verificação de tipo padrão
• Configurar executionEnvironments para resolver caminhos de importação corretamente

{
  "embrace": ("src", "exams"),
  "exclude": ("**/__pycache__", "**/.venv", ".tox", "dist", "construct"),
  "typeCheckingMode": "customary",
  "pythonVersion": "3.12",
  "executionEnvironments": (
    {
      "root": "src",
      "extraPaths": ("src")
    }
  )
}

Esta configuração suporta escala. Centraliza as regras. Permite a adoção estrita e gradual por pacote.

• Configuração base compartilhada
• Substituições por pacote
• Verificação rigorosa apenas para novo código

Configuração raiz:

{
  "exclude": ("**/__pycache__", "**/.venv", "**/.git", "**/node_modules"),
  "pythonVersion": "3.12",
  "typeCheckingMode": "customary",
  "reportMissingImports": "error",
  "reportMissingTypeStubs": "none"
}

Configuração do pacote:

{
  "extends": "../../pyrightconfig.base.json",
  "embrace": ("src", "exams"),
  "strict": ("src/new_code"),
  "executionEnvironments": (
    { "root": "src", "extraPaths": ("src") }
  )
}

Aplicativo Django

Esta configuração reduz o ruído. Evita arquivos gerados. Ele mantém os tipos ausentes visíveis, mas sem bloqueá-los.

• Exclua migrações e arquivos estáticos
• Avisar sobre stubs faltantes
• Diretório de stub personalizado

{
  "embrace": ("."),
  "exclude": (
    "**/__pycache__",
    "**/.venv",
    "**/migrations/**",
    "static",
    "media"
  ),
  "typeCheckingMode": "customary",
  "reportMissingTypeStubs": "warning",
  "stubPath": "typings"
}

Serviço FastAPI

Esta configuração é uma ponte para a digitação estrita. Ele destaca incógnitas sem quebrar compilações.

• Verificação padrão
• Avisar sobre tipos desconhecidos
• Bom ajuste para estruturas dinâmicas

{
  "embrace": ("app", "exams"),
  "exclude": ("**/__pycache__", "**/.venv"),
  "typeCheckingMode": "customary",
  "reportUnknownParameterType": "warning",
  "reportUnknownVariableType": "warning"
}

Esses padrões são pontos de partida. Eles foram feitos para evoluir. O Pyright funciona melhor quando o rigor aumenta gradualmente.

Quando escolher o Pyright?

Leia também: Fundamentos de programação Python para iniciantes

Conclusão

Pyright oferece uma abordagem rápida e baseada em padrões para verificação de tipo estático em Python. Ele combina análise forte com integração responsiva de editor e um sistema flexível de configuração de projeto. Desde pequenos scripts até grandes monorepos, adapta-se às diferentes necessidades da equipe e níveis de rigor. Sua arquitetura de servidor de linguagem oferece diagnósticos consistentes em editores e ambientes de CI. Com opções de configuração claras e caminhos de adoção graduais, as equipes podem introduzir uma digitação mais forte sem interromper os fluxos de trabalho existentes. Para desenvolvedores que valorizam desempenho, escalabilidade e suporte de digitação moderna, Pyright fornece uma base prática para construir bases de código Python mais seguras e fáceis de manter.

Olá, sou Janvi, um entusiasta apaixonado pela ciência de dados que atualmente trabalha na Analytics Vidhya. Minha jornada no mundo dos dados começou com uma profunda curiosidade sobre como podemos extrair insights significativos de conjuntos de dados complexos.