Guida a Pyright: controllo statico dei tipi veloce per il codice Python

Le type hint rendono il codice Python più facile da capire e mantenere. Ma c’è un problema: da sole non intercettano gli errori. Ti serve un type checker per verificare che il tuo codice rispetti davvero i tipi che hai dichiarato.

Ho usato sia Mypy che Pyright in produzione. Il vantaggio di velocità di Pyright è più evidente durante lo sviluppo. Gli errori di tipo compaiono mentre scrivi, non dopo il salvataggio. Su codebase grandi, questo ciclo di feedback più rapido fa davvero la differenza.

Questo tutorial copre tutto ciò che ti serve per iniziare a usare Pyright in modo efficace. Ti mostrerò come installarlo, configurarlo per il tuo progetto e integrarlo con VS Code. Metterò anche in luce le differenze tra Pyright e Mypy.

Cos’è Pyright?

Pyright è un type checker statico per Python sviluppato da Microsoft. Legge il tuo codice, analizza le annotazioni di tipo e segnala errori quando i tipi non corrispondono. A differenza dei controlli a runtime, che intercettano gli errori quando il codice viene eseguito, l’analisi statica li trova prima ancora di lanciare qualcosa.

Mentre la maggior parte degli strumenti Python è scritta in Python, Pyright è scritto in TypeScript e gira su Node.js. Una scelta insolita per uno strumento Python, giusto? Ma è il motivo per cui Pyright è così veloce. Il motore JavaScript V8 esegue molto più rapidamente di quanto farebbe CPython.

Troverai Pyright in due modi. Puoi eseguirlo da riga di comando nelle pipeline CI/CD per intercettare errori di tipo prima dei merge. Oppure potresti già usarlo senza saperlo. Alimenta Pylance, l’estensione Python di Microsoft per VS Code. Quei segnetti rossi sotto gli errori di tipo? È Pyright che lavora dietro le quinte.

Lo strumento include stub di tipo integrati per la libreria standard di Python e pacchetti comuni. Non devi installare altro per controllare codice che usa os, json o typing. Per i pacchetti di terze parti, Pyright usa stub mantenuti dalla community (typeshed) oppure stub specifici del pacchetto che installi a parte.

Come installare Pyright

Vediamo ora come far funzionare Pyright sul tuo sistema. Hai due opzioni di installazione: npm (l’approccio nativo) o pip (il wrapper Python).

Installare Pyright con npm

L’installazione consigliata usa npm perché Pyright gira su Node.js. Ti servirà Node.js versione 14.0.0 o superiore.

# Global installation
npm install -g pyright

# Run without installing globally
npx pyright

# Local project installation
npm install --save-dev pyrightOfferto da

Io uso l’installazione globale per controlli veloci e quella locale per i progetti in cui voglio fissare la versione. L’approccio con npx è utile per esecuzioni una tantum senza aggiungere pacchetti globali.

Installare Pyright tramite wrapper Python

Se il tuo team lavora esclusivamente in Python e non vuole Node.js nella toolchain, esiste un wrapper su PyPI:

# Standard installation
pip install pyright

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

Il wrapper controlla se Node.js è presente sul sistema. Se manca, scarica automaticamente una versione standalone. L’extra [nodejs] usa un metodo di download più affidabile rispetto al default.

Tieni a mente i compromessi. La prima esecuzione impiega più tempo per scaricare le dipendenze. Gli ambienti CI con accesso di rete limitato potrebbero fallire. E la versione su PyPI a volte è in ritardo di qualche giorno rispetto alle release su npm.

Per la maggior parte dei team Python, il wrapper va benissimo. Ma se incontri problemi, torna all’installazione via npm. È più affidabile.

Eseguire Pyright su un progetto Python

Una volta installato, eseguire Pyright è semplice. Vai nella directory del tuo progetto ed esegui:

pyrightOfferto da

Tutto qui, davvero. Pyright cerca i file Python, li analizza e segnala eventuali errori di tipo. Nessun setup complicato richiesto.

Cosa controlla Pyright di default

Cosa verifica Pyright? Senza alcuna configurazione, effettua diversi controlli. Valida che le annotazioni di tipo corrispondano all’uso reale. Intercetta variabili non definite e codice irraggiungibile. Verifica correttamente gli import. Segnala incongruenze evidenti, come passare una stringa dove è atteso un intero.

Ecco un esempio di output da un progetto con errori:

/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 informationsOfferto da

Ogni errore mostra percorso del file, riga, colonna e descrizione. Il nome della regola tra parentesi (ad esempio reportArgumentType) indica esattamente quale controllo ha generato l’errore. Questo conta quando vuoi sopprimere regole specifiche. Lo vediamo tra poco.

Capire i codici di uscita

Pyright restituisce codici di uscita diversi a seconda del risultato:

Nelle pipeline CI, di solito vuoi che la build fallisca con il codice di uscita 1. I codici 2-4 indicano che è successo qualcosa allo strumento stesso, non al tuo codice.

Configurare Pyright

Sebbene Pyright funzioni subito, i progetti reali richiedono personalizzazione. Vorrai specificare quali file controllare, quale versione di Python targettizzare e quanto rigorosa debba essere l’analisi. Vediamo le opzioni chiave di configurazione.

Modalità di type checking

Pyright offre quattro livelli di rigidità. La modalità che scegli determina quante regole sono attive.

Quale modalità scegliere? Per i nuovi progetti, inizia con la modalità standard. Intercetta bug reali senza sommergerti di errori. Lavori con codice legacy? La modalità basic funziona meglio quando adotti la tipizzazione gradualmente. Riserva la modalità strict a librerie e infrastrutture critiche dove vuoi la massima sicurezza.

Avviso: il salto da standard a strict è notevole. La modalità strict abilita circa 30 regole aggiuntive, tra cui l’obbligo di annotazioni di tipo per tutti i parametri e i valori di ritorno delle funzioni. Aspettati un aumento di errori segnalati di 10 volte quando passi a strict. L’ho imparato a mie spese.

La modalità strict richiede annotazioni di tipo complete. Immagine dell’autore

File di configurazione

Pyright legge la configurazione da pyrightconfig.json o pyproject.toml. Se entrambi esistono, pyrightconfig.json ha la precedenza.

Ecco un pyrightconfig.json minimale:

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

L’equivalente in pyproject.toml:

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

Il file di configurazione controlla il comportamento di Pyright. Immagine dell’autore.

Un dettaglio critico che inganna molti: se definisci exclude manualmente, sostituisce interamente i default. Includi sempre node_modules, __pycache__ e il tuo ambiente virtuale nei pattern di exclude personalizzati. Altrimenti Pyright proverà ad analizzare le dipendenze, causando enormi rallentamenti. Fidati, non vuoi aspettare 10 minuti per un type check.

Configurazione dell’ambiente virtuale

Come trova Pyright i pacchetti installati? Devi dirgli dove cercare. Configuralo con venvPath e venv:

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

Questo dice a Pyright di cercare i pacchetti in ./.venv. Se usi un percorso diverso per l’ambiente virtuale, adegua di conseguenza. Senza questo, Pyright non trova le dipendenze installate e segnala errori di import mancanti per tutto.

Sopprimere le diagnostiche

A volte Pyright ha tecnicamente ragione ma hai comunque bisogno di silenziare errori specifici. Magari lavori con codice legacy, o in un caso specifico sai più tu del type checker. Puoi sopprimere gli errori su tre livelli.

Soppressione a livello di configurazione

Disattiva regole globalmente:

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

Soppressione a livello di file

Aggiungi un commento all’inizio del file:

# pyright: basic
# pyright: reportPrivateUsage=falseOfferto da

Soppressione a livello di riga

Sopprimi una singola riga:

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

La sintassi con regola specifica ([reportAssignmentType]) è utile quando vuoi silenziare un solo controllo senza disabilitare gli altri sulla stessa riga.

Vista la configurazione, vediamo come Pyright si integra con il tuo ambiente di sviluppo.

Pyright in VS Code e IDE

Se sei come la maggior parte degli sviluppatori Python, userai Pyright tramite Pylance più che da riga di comando. Capire questa relazione ti aiuta a configurare correttamente l’editor ed evitare tranelli comuni.

Pyright vs. Pylance

Pylance è l’estensione di Microsoft per VS Code che include il motore di type checking di Pyright. Quando installi Pylance, ottieni automaticamente Pyright. Ma Pylance aggiunge funzionalità non presenti nell’open source Pyright:

• Evidenziazione semantica: variabili colorate in base al tipo
• Auto-import avanzato: suggerimenti di import più intelligenti
• Navigazione del codice: "Trova tutti i riferimenti" in tutto lo workspace

Queste funzioni sono closed-source e disponibili solo in VS Code. Se usi Neovim, Emacs o un altro editor, hai le funzionalità core di Pyright ma non questi extra.

Pylance evidenzia gli errori di tipo nell’editor. Immagine dell’autore.

Impostazioni essenziali di VS Code

Configura Pylance dalle impostazioni di VS Code:

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

L’impostazione diagnosticMode influisce sulle prestazioni. "openFilesOnly" analizza solo i file aperti. "workspace" analizza tutto ma usa più memoria e CPU.

Trappole di configurazione comuni

La scelta dell’interprete conta. Pylance usa l’interprete Python selezionato per trovare i pacchetti installati. Se compaiono all’improvviso errori per pacchetti che sai di aver installato, verifica che in basso nella status bar di VS Code sia selezionato l’interprete giusto.

La selezione dell’interprete influisce sui percorsi di discovery dei pacchetti. Immagine dell’autore.

I default del CLI e di Pylance differiscono. Pylance imposta typeCheckingMode su "off" mentre il CLI usa "standard". Pylance aggiunge automaticamente src ai percorsi di ricerca; il CLI no. Per un comportamento coerente tra editor e CI, imposta esplicitamente tutte le opzioni in pyproject.toml.

Il fenomeno del "codice in grigio". Pylance sbiadisce il codice irraggiungibile in base all’analisi dei tipi. Se del codice appare in grigio inaspettatamente, controlla la funzione chiamata subito prima. Una funzione tipizzata come che restituisce NoReturn fa sembrare irraggiungibile tutto ciò che segue.

Pyright vs. Mypy: quando usare l’uno o l’altro

Ti starai chiedendo: dovrei usare Pyright o restare con Mypy? Entrambi gli strumenti sono pronti per la produzione, e la scelta dipende dal tuo workflow e dai requisiti. Ti riassumo le differenze chiave.

Velocità e reattività

Pyright è circa 3-5 volte più veloce di Mypy nelle scansioni complete del progetto ed è praticamente istantaneo per i controlli incrementali. Questo conta soprattutto durante lo sviluppo, quando vuoi feedback immediato.

Mypy ha una modalità demone (dmypy) che migliora le prestazioni, ma resta più lento e talvolta ha problemi di cache che richiedono riavvii.

Differenze nell’inferenza dei tipi

Qui le cose si fanno interessanti. Gli strumenti inferiscono i tipi in modo diverso. Considera questo codice:

coordinates = (10, 20)Offerto da

Pyright inferisce tuple[Literal[10], Literal[20]], preservando i valori esatti perché le tuple sono immutabili. Mypy inferisce tuple[int, int], generalizzando i tipi.

L’approccio di Pyright intercetta più errori ma a volte crea attrito quando le funzioni si aspettano tipi generali. In pratica conta poco perché Literal[10] è un sottotipo valido di int.

Analisi del codice non annotato

Questa è la differenza pratica più grande ed è un game changer per le codebase legacy. Mypy salta le funzioni non annotate di default. Pyright le analizza comunque, intercettando errori evidenti anche senza type hint.

Per codebase legacy con annotazioni scarse, Pyright funge da potente linter che intercetta variabili non definite e chiamate di metodi impossibili. Mypy tratta quelle funzioni come "dinamiche" e le ignora.

Supporto ai plugin

Mypy supporta plugin per framework come Django e SQLAlchemy. Questi plugin comprendono la magia degli ORM e forniscono tipi accurati per attributi generati dinamicamente.

Pyright non ha un sistema di plugin. Si affida interamente agli stub di tipo. Nel 2026, la maggior parte delle librerie principali ha stub di alta qualità, quindi conta meno di un tempo. Ma se usi un framework con pesante metaprogrammazione, verifica che esistano buoni stub prima di impegnarti con Pyright.

Usa Pylance (Pyright) durante lo sviluppo per feedback istantaneo, e valuta di eseguire sia Pyright che Mypy in CI se il tuo progetto usa plugin di framework.

Problemi comuni con Pyright

Quando Pyright segnala errori inaspettati, di solito la causa è una di queste.

Stub di tipo mancanti

Ti è mai capitato questo errore? Pyright si lamenta quando non trova informazioni di tipo per un pacchetto:

Import "requests" could not be resolved (reportMissingImports)Offerto da

Stub mancanti generano avvisi di import. Immagine dell’autore.

Per prima cosa, verifica che il pacchetto sia installato nel tuo ambiente virtuale e che Pyright sappia dove trovarlo (usando le impostazioni venvPath e venv viste prima).

Se il pacchetto è installato ma manca di informazioni di tipo, installa gli stub della community:

pip install types-requests types-PyYAML types-redisOfferto da

Per i pacchetti senza stub disponibili, hai due opzioni. Puoi disattivare l’avviso con "reportMissingTypeStubs": "none" nella configurazione. Oppure generare tu stesso degli stub di bozza:

pyright --createstub some_packageOfferto da

Questo crea un file scheletro .pyi che puoi riempire con i metodi che usi davvero.

Errori nei pre-commit hook

Pyright funziona in locale ma fallisce nei pre-commit hook? Di solito il problema è l’isolamento dell’ambiente. Pre-commit esegue gli hook in ambienti isolati che non vedono i pacchetti installati del tuo progetto.

Risolvi puntando l’hook al tuo ambiente virtuale:

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

Errori inaspettati in modalità strict

Hai attivato la modalità strict e vedi all’improvviso migliaia di errori? Niente panico. È normale. La modalità strict richiede annotazioni di tipo complete. Parti da basic o standard, aggiungi annotazioni gradualmente e abilita strict solo sui moduli completamente tipizzati.

Usa commenti per file per mantenere il codice legacy in una modalità permissiva:

# pyright: basicOfferto da

Questo ti permette di applicare controlli rigorosi al codice nuovo mentre migri gradualmente quello vecchio.

Oltre al troubleshooting, ecco alcune strategie per rendere l’esperienza con Pyright più fluida fin da subito.

Best practice per usare Pyright

Dopo aver lavorato con Pyright su diversi progetti, ho imparato alcune cose che ne facilitano l’adozione. Adottare queste best practice di coding garantisce che il type checking resti un aiuto, non un ostacolo.

Inizia con la modalità standard. Come detto, intercetta bug reali senza richiedere annotazioni complete. Potrai sempre inasprire le regole in seguito.

Fissa la versione di Pyright. Pyright rilascia spesso nuove versioni e a volte le nuove rilasciano segnalazioni su codice che prima passava. In CI, un pip install pyright non fissato può causare fallimenti del build il lunedì mattina per release uscite nel weekend. Ci sono passato. Non è divertente.

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

# In requirements-dev.txt
pyright==1.1.408Offerto da

Correggi gli errori in modo incrementale. Non provare a eliminare 10.000 errori in una volta. Usa l’array strict per applicare controlli severi solo a directory specifiche:

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

Usa presto i file di configurazione. Anche per progetti piccoli, una configurazione esplicita evita sorprese. Dedica cinque minuti a documentare la tua versione di Python, il percorso dell’ambiente virtuale e il livello di rigore scelto. Il te del futuro ti ringrazierà.

Non puntare alla perfezione subito. Usa # pyright: ignore liberamente all’inizio. Segna così il debito tecnico in modo visibile, da ripulire nel tempo senza bloccare i progressi. Il meglio è nemico del bene, soprattutto quando adotti nuovi strumenti.