Guide Pyright : Vérification statique rapide du type pour le code Python

Les indications de type facilitent la compréhension et la maintenance du code Python. Cependant, il y a un hic : les indications seules ne permettent pas de détecter les erreurs. Il est nécessaire d'utiliser un vérificateur de types pour s'assurer que votre code respecte bien les types que vous avez déclarés.

J'ai utilisé à la fois Mypy et Pyright en production. L'avantage de Pyright en termes de rapidité est particulièrement évident pendant la phase de développement. Les erreurs de saisie apparaissent au fur et à mesure que vous tapez, plutôt qu'après l'enregistrement. Dans les bases de code volumineuses, cette boucle de rétroaction plus rapide fait une réelle différence.

Ce tutoriel couvre tous les aspects nécessaires pour commencer à utiliser Pyright de manière efficace. Je vais vous expliquer comment l'installer, le configurer pour votre projet et l'intégrer à VS Code. Je vais également mettre en évidence les différences entre Pyright et Mypy.

Qu'est-ce que Pyright ?

Pyright est un vérificateur de types statiques pour Python développé par Microsoft. Il lit votre code, analyse les annotations de type et signale les erreurs lorsque les types ne correspondent pas. Contrairement aux vérifications d'exécution qui détectent les erreurs lors de l'exécution du code, l'analyse statique les détecte avant toute exécution.

Alors que la plupart des outils Python sont développés en Python, Pyright est écrit en TypeScript et fonctionne sur Node.js. Choix inhabituel pour un outil Python, n'est-ce pas ? Cependant, c'est la raison pour laquelle Pyright est si rapide. Le moteur JavaScript V8 exécute les commandes beaucoup plus rapidement que CPython.

Vous rencontrerez Pyright de deux manières. Vous pouvez l'exécuter en tant qu'outil en ligne de commande dans les pipelines CI/CD afin de détecter les erreurs de type avant de procéder aux fusions. Ou peut-être l'utilisez-vous déjà sans le savoir. Il alimente Pylance, l'extension Python de Microsoft pour VS Code. Ces lignes rouges sous les erreurs de frappe ? C'est Pyright qui opère en coulisses.

Cet outil est fourni avec des stubs de type groupés pour la bibliothèque standard Python et les paquets courants. Il n'est pas nécessaire d'installer quoi que ce soit de supplémentaire pour vérifier le code qui utilise os, json ou typing. Pour les paquets tiers, Pyright utilise des stubs gérés par la communauté provenant de typeshed ou des stubs spécifiques au paquet que vous installez séparément.

Comment installer Pyright

Maintenant, installons Pyright sur votre système. Vous avez deux options d'installation : npm (l'approche native) ou pip (le wrapper Python).

Installation de Pyright avec npm

L'installation recommandée utilise npm, car Pyright fonctionne sur Node.js. Vous aurez besoin de Node.js version 14.0.0 ou supérieure.

# Global installation
npm install -g pyright

# Run without installing globally
npx pyright

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

J'utilise l'installation globale pour les vérifications rapides et l'installation locale pour les projets où je souhaite fixer la version. L'approche npx est utile pour les cas ponctuels sans ajouter à vos packages globaux.

Installation de Pyright via le wrapper Python

Si votre équipe travaille exclusivement en Python et ne souhaite pas intégrer Node.js dans sa chaîne d'outils, un wrapper PyPI est disponible :

# Standard installation
pip install pyright

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

Le wrapper vérifie la présence de Node.js sur votre système. S'il est manquant, le wrapper télécharge automatiquement une version autonome. L'extension [nodejs] utilise une méthode de téléchargement plus fiable que celle par défaut.

Veuillez noter qu'il existe des compromis. La première exécution prend plus de temps pendant le téléchargement des dépendances. Les environnements CI avec un accès réseau restreint peuvent rencontrer des difficultés. De plus, la version PyPI est parfois en retard de quelques jours par rapport aux versions npm.

Pour la plupart des équipes Python, le wrapper fonctionne correctement. Cependant, si vous rencontrez des difficultés, veuillez revenir à l'installation npm. C'est plus fiable.

Exécution de Pyright sur un projet Python

Une fois installé, l'exécution de Pyright est simple. Veuillez accéder au répertoire de votre projet et exécuter :

pyright

C'est tout, vraiment. Pyright recherche les fichiers Python, les analyse et signale toute erreur de type qu'il détecte. Aucune configuration complexe n'est nécessaire.

Ce que Pyright vérifie par défaut

Que recherche Pyright ? Sans aucune configuration, il effectue plusieurs vérifications. Il valide les annotations de type qui correspondent à l'utilisation réelle. Il détecte les variables non définies et le code inaccessible. Il vérifie correctement les importations. Il signale les incompatibilités de types évidentes, telles que le passage d'une chaîne de caractères là où un entier est attendu.

Voici un exemple de résultat provenant d'un projet contenant des erreurs :

/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

Chaque erreur affiche le chemin d'accès au fichier, le numéro de ligne, la colonne et une description. Le nom de la règle entre parenthèses (par exemple reportArgumentType) vous indique précisément quelle vérification a déclenché l'erreur. Ceci est important lorsque vous souhaitez désactiver certaines règles. Nous aborderons ce sujet sous peu.

Comprendre les codes de sortie

Pyright renvoie différents codes de sortie en fonction durésultat :

Dans les pipelines CI, vous souhaitez généralement que la compilation échoue avec le code de sortie 1. Les codes de sortie 2 à 4 indiquent qu'un problème est survenu avec l'outil lui-même, et non avec votre code.

Configuration de Pyright

Bien que Pyright soit prêt à l'emploi, les projets réels nécessitent une personnalisation. Il est recommandé de préciser les fichiers à vérifier, la version Python à cibler et le niveau de rigueur de l'analyse. Veuillez examiner les options de configuration clés.

Modes de vérification des types

Pyright propose quatre niveaux de rigueur. Le mode que vous sélectionnez détermine le nombre de règles activées.

Quel mode devriez-vous sélectionner ? Pour les nouveaux projets, veuillez commencer par le modestandard d' . Il détecte les véritables bogues sans vous submerger d'erreurs. Vous travaillez avec du code existant ? Le mode d' e de base est plus efficace lorsque vous adoptez progressivement la dactylographie. Veuillez réserver le modestrict d' s aux bibliothèques et aux infrastructures critiques pour lesquelles une sécurité maximale est requise.

Avertissement : le passage de la norme standard à la norme stricte est significatif. Le mode strict active environ 30 règles supplémentaires, notamment des exigences relatives aux annotations de type sur tous les paramètres de fonction et les valeurs de retour. Veuillez vous attendre à une multiplication par dix du nombre d'erreurs signalées lors du changement. J'ai appris cela de manière difficile.

Le mode strict exige des annotations de type complètes. Image par l'auteur

Fichiers de configuration

Pyright lit la configuration à partir de pyrightconfig.json ou pyproject.toml. Si les deux existent, pyrightconfig.json est prioritaire.

Voici un exemple minimaliste pyrightconfig.json:

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

L'équivalent en pyproject.toml:

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

Le fichier de configuration contrôle le comportement de Pyright. Image fournie par l'auteur.

Voici un détail important qui surprend de nombreuses personnes : si vous définissez manuellement exclude, cela remplace complètement les valeurs par défaut. Veuillez toujours inclure node_modules, __pycache__ et votre environnement virtuel dans les modèles d'exclusion personnalisés. Dans le cas contraire, Pyright tente d'analyser vos dépendances, ce qui entraîne des ralentissements importants. Croyez-moi, vous ne souhaitez pas attendre 10 minutes pour une vérification de type.

Configuration de l'environnement virtuel

Comment Pyright identifie-t-il les paquets installés sur votre système ? Il est nécessaire de lui indiquer où chercher. Veuillez configurer ceci avec venvPath et venv:

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

Cela indique à Pyright de rechercher les paquets dans ./.venv. Si vous utilisez un autre emplacement d'environnement virtuel, veuillez procéder aux ajustements nécessaires. Sans cela, Pyright ne peut pas trouver vos dépendances installées et signale des erreurs d'importation manquantes pour tout.

Suppression des diagnostics

Parfois, Pyright est techniquement correct, mais il est nécessaire de corriger certaines erreurs de toute façon. Il se peut que vous travailliez avec du code hérité ou que vous ayez une meilleure connaissance que le vérificateur de types dans un cas particulier. Vous pouvez supprimer les erreurs à trois niveaux.

Suppression du niveau de configuration

Désactiver les règles de manière globale :

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

Suppression au niveau des fichiers

Veuillez ajouter un commentaire en haut du fichier :

# pyright: basic
# pyright: reportPrivateUsage=false

Suppression du niveau de ligne

Supprimer une seule ligne :

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

La syntaxe spécifique de la règle ([reportAssignmentType]) est utile lorsque vous souhaitez désactiver une vérification sans désactiver les autres sur la même ligne.

Maintenant que la configuration est terminée, examinons comment Pyright s'intègre à votre environnement de développement.

Pyright dans VS Code et les IDE

Si vous êtes comme la plupart des développeurs Python, vous découvrirez Pyright via Pylance plutôt que via la ligne de commande. Comprendre cette relation vous aide à configurer correctement votre éditeur et à éviter les erreurs courantes.

Pyright contre Pylance

Pylance est une extension VS Code de Microsoft qui intègre le moteur de vérification de types de Pyright. Lorsque vous installez Pylance, vous obtenez automatiquement Pyright. Cependant, Pylance ajoute des fonctionnalités qui ne sont pas disponibles dans la version open source Pyright :

• Mise en évidence sémantique: variables colorées en fonction de leur type
• Importation automatique avancée: suggestions d'importation plus intelligentes
• Navigation dans le code: Recherchez toutes les références dans votre espace de travail.

Ces fonctionnalités sont à code source fermé et uniquement disponibles dans VS Code. Si vous utilisez Neovim, Emacs ou un autre éditeur, vous bénéficiez des fonctionnalités de base de Pyright, mais pas de ces fonctionnalités supplémentaires.

Pylance signale les erreurs de type dans l'éditeur. Image fournie par l'auteur.

Paramètres essentiels de VS Code

Veuillez configurer Pylance via les paramètres de VS Code :

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

Le paramètre « diagnosticMode » (Analyser tous les fichiers) a une incidence sur les performances. L'option « "openFilesOnly" » (Analyser uniquement les fichiers ouverts) analyse uniquement les fichiers que vous avez ouverts. L'option « "workspace" » ( Analyser tout) analyse tous les fichiers, mais utilise davantage de mémoire et de ressources CPU.

Configuration courante : points à prendre en considération

Le choix de l'interprète est important. Pylance utilise l'interpréteur Python que vous avez sélectionné pour rechercher les paquets installés. Si des erreurs apparaissent soudainement pour des paquets que vous savez être installés, veuillez vérifier que l'interpréteur approprié est sélectionné dans la barre d'état de VS Code.

Le choix de l'interpréteur influe sur les chemins de recherche des paquets. Image fournie par l'auteur.

Les paramètres par défaut de CLI et Pylance diffèrent. Pylance définit par défaut typeCheckingMode sur "off", tandis que l'interface CLI utilise par défaut "standard". Pylance ajoute également automatiquement src aux chemins de recherche, ce que ne fait pas l'interface CLI. Afin d'assurer la cohérence entre votre éditeur et CI, veuillez définir explicitement toutes les options dans pyproject.toml.

Le phénomène du « code grisé ». Pylance grise le code inaccessible en fonction de l'analyse de type. Si le code apparaît grisé de manière inattendue, veuillez vérifier la fonction appelée immédiatement avant celle-ci. Une fonction définie comme renvoyant un type d'NoReturn s fait que tout ce qui suit apparaît comme inaccessible.

Pyright contre Mypy : Quand utiliser chacun

Vous vous demandez peut-être : dois-je utiliser Pyright ou continuer à utiliser Mypy ? Les deux outils sont prêts à l'emploi, et votre choix dépendra de votre flux de travail et de vos exigences. Permettez-moi de vous expliquer les principales différences.

Rapidité et réactivité

Pyright est environ 3 à 5 fois plus rapide que Mypy pour les analyses complètes de projets et pratiquement instantané pour les vérifications incrémentielles. Ceci est particulièrement important pendant le développement, lorsque vous souhaitez obtenir un retour immédiat.

Mypy dispose d'un mode démon (dmypy) qui améliore les performances, mais il reste plus lent et rencontre parfois des problèmes de mise en cache qui nécessitent un redémarrage.

Différences dans l'inférence de types

C'est ici que les choses deviennent intéressantes. Les outils déduisent les types différemment. Veuillez examiner ce code :

coordinates = (10, 20)

Pyright déduit l'tuple[Literal[10], Literal[20]], en conservant les valeurs exactes car les tuples sont immuables. Mypy déduit l' tuple[int, int], en élargissant aux types généraux.

L'approche de Pyright détecte davantage d'erreurs, mais peut parfois entraîner des conflits lorsque les fonctions attendent des types généraux. Cela n'a généralement pas d'importance dans la pratique, car Literal[10] est un sous-type valide de int.

Analyse de code non annoté

Il s'agit de la plus grande différence pratique, et cela change la donne pour les bases de code existantes. Mypy ignore par défaut les fonctions non annotées. Pyright les analyse tout de même, détectant les erreurs évidentes même sans indications de type.

Pour les bases de code héritées comportant peu d'annotations, Pyright agit comme un puissant linter qui détecte les variables non définies et les appels de méthodes impossibles. Mypy considère ces fonctions comme « dynamiques » et les ignore.

Assistance pour les plugins

Mypy prend en charge les plugins pour les frameworks tels que Django et SQLAlchemy. Ces plugins comprennent la magie ORM et fournissent des types précis pour les attributs générés dynamiquement.

Pyright ne dispose pas de système de plugins. Il repose entièrement sur des stubs de type. En 2026, la plupart des grandes bibliothèques disposent de stubs de haute qualité, ce qui rend cette question moins importante qu'auparavant. Cependant, si vous utilisez un framework avec une métaprogrammation intensive, veuillez vérifier si de bons stubs existent avant de vous engager à respecter Pyright.

Veuillez utiliser Pylance (Pyright) pendant le développement pour obtenir un retour instantané, et envisager d'exécuter à la fois Pyright et Mypy dans CI si votre projet utilise des plugins de framework.

Problèmes courants lors de l'utilisation de Pyright

Lorsque Pyright signale des erreurs inattendues, la cause est généralement l'un de ces problèmes.

Stubs de type manquants

Avez-vous déjà rencontré cette erreur ? Pyright signale une erreur lorsqu'il ne parvient pas à trouver les informations de type pour un paquet :

Import "requests" could not be resolved (reportMissingImports)

Les stubs manquants déclenchent des avertissements d'erreur d'importation. Image fournie par l'auteur.

Veuillez d'abord vérifier que le paquet est installé dans votre environnement virtuel et que Pyright sait où le trouver (en utilisant les paramètres venvPath et venv mentionnés précédemment).

Si le paquet est installé mais qu'il manque des informations de type, veuillez installer les stubs de la communauté :

pip install types-requests types-PyYAML types-redis

Pour les paquets sans stubs disponibles, vous avez deux options. Vous pouvez désactiver l'avertissement en utilisant l'option « "reportMissingTypeStubs": "none" » dans votre configuration. Ou générez vous-même des brouillons :

pyright --createstub some_package

Cela crée un fichier squelette .pyi que vous pouvez compléter avec les méthodes que vous utilisez réellement.

Échecs du hook pré-commit

Pyright fonctionne-t-il localement mais échoue-t-il dans les hooks pré-commit ? Le problème réside généralement dans l'isolement de l'environnement. Pre-commit exécute des hooks dans des environnements isolés qui n'ont pas accès aux paquets installés de votre projet.

Veuillez résoudre ce problème en dirigeant le crochet vers votre environnement virtuel :

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

Erreurs inattendues en mode strict

Vous avez activé le mode strict et rencontrez soudainement de nombreuses erreurs ? Veuillez ne pas vous inquiéter. Ceci est normal. Le mode strict exige des annotations de type complètes. Commencez par le mode basique ou standard, ajoutez progressivement des annotations et activez le mode strict uniquement sur les modules entièrement typés.

Veuillez utiliser les commentaires par fichier pour maintenir le code existant dans un mode tolérant :

# pyright: basic

Cela vous permet d'appliquer des contrôles rigoureux sur le nouveau code tout en migrant progressivement l'ancien code.

Au-delà du dépannage, voici quelques stratégies qui vous permettront de profiter pleinement de Pyright dès le début.

Meilleures pratiques pour l'utilisation de Pyright

Après avoir collaboré avec Pyright sur différents projets, j'ai acquis certaines connaissances qui facilitent l'adoption. L'adoption de ces bonnes pratiques de codage garantit que votre vérification de type reste une aide et non un obstacle.

Veuillez commencer par le mode standard. Comme indiqué précédemment, il détecte les véritables bogues sans nécessiter d'annotations complètes. Il est toujours possible de renforcer les règles ultérieurement.

Veuillez indiquer votre version de Pyright. Pyright publie fréquemment de nouvelles versions, et celles-ci signalent parfois des codes qui étaient auparavant acceptés. Dans CI, une pip install pyright non épinglée peut entraîner des échecs de compilation le lundi matin à partir des versions du week-end. J'ai déjà vécu cette situation. Ce n'est pas agréable.

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

# In requirements-dev.txt
pyright==1.1.408

Veuillez corriger les erreurs de manière progressive. Veuillez ne pas tenter d'éliminer 10 000 erreurs à la fois. Veuillez utiliser le tableau strict pour appliquer une vérification stricte uniquement sur des répertoires spécifiques :

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

Veuillez utiliser les fichiers de configuration dès le début. Même pour les projets de petite envergure, une configuration explicite permet d'éviter les surprises. Veuillez prendre cinq minutes pour noter votre version de Python, le chemin d'accès à votre environnement virtuel et le niveau de rigueur choisi. Votre futur vous en sera reconnaissant.

Ne visez pas immédiatement la perfection. Veuillez utiliser généreusement l'# pyright: ignore e au début. Cela permet de mettre en évidence la dette technique afin que vous puissiez la résoudre progressivement sans entraver la progression. La perfection est l'ennemie du bien, en particulier lors de l'adoption de nouveaux outils.