Pyright-gids: snelle statische typechecking voor Python-code

Type hints maken Python-code makkelijker te begrijpen en te onderhouden. Maar hier zit de crux: alleen hints vinden geen fouten. Je hebt een typechecker nodig om te verifiëren dat je code daadwerkelijk de gedeclareerde types volgt.

Ik heb zowel Mypy als Pyright in productie gebruikt. Pyright's snelheidsvoordeel is vooral tijdens development duidelijk. Typefouten verschijnen terwijl je typt in plaats van pas na het opslaan. In grote codebases maakt die snellere feedbacklus echt verschil.

Deze tutorial behandelt alles wat je nodig hebt om Pyright effectief te gebruiken. Ik laat zien hoe je het installeert, configureert voor jouw project en integreert met VS Code. Ook licht ik de verschillen tussen Pyright en Mypy toe.

Wat is Pyright?

Pyright is een statische typechecker voor Python, ontwikkeld door Microsoft. Het leest je code, analyseert typeannotaties en meldt fouten wanneer types niet overeenkomen. In tegenstelling tot runtime-checks die fouten detecteren tijdens uitvoering, vindt statische analyse ze voordat je iets draait.

Hoewel de meeste Python-tools in Python zijn geschreven, is Pyright in TypeScript geschreven en draait het op Node.js. Een vreemde keuze voor een Python-tool, toch? Maar het is de reden dat Pyright zo snel is. De V8 JavaScript-engine voert veel sneller uit dan CPython zou doen.

Je komt Pyright op twee manieren tegen. Je kunt het als commandlinetool draaien in CI/CD-pijplijnen om typefouten te vangen voordat je merge't. Of je gebruikt het misschien al zonder het te weten. Het drijft Pylance aan, Microsofts Python-extensie voor VS Code. Die rode kringeltjes onder typefouten? Dat is Pyright achter de schermen.

De tool wordt geleverd met ingebouwde type-stubs voor de Python-standaardbibliotheek en veelgebruikte pakketten. Je hoeft niets extra's te installeren om code te checken die os, json of typing gebruikt te checken. Voor third-party pakketten gebruikt Pyright community-onderhouden stubs uit typeshed of pakket-specifieke stubs die je los installeert.

Pyright installeren

Laten we Pyright op je systeem aan de praat krijgen. Je hebt twee installatieopties: npm (de native aanpak) of pip (de Python-wrapper).

Pyright installeren met npm

De aanbevolen installatie gebruikt npm omdat Pyright op Node.js draait. Je hebt Node.js versie 14.0.0 of hoger nodig.

# Global installation
npm install -g pyright

# Run without installing globally
npx pyright

# Local project installation
npm install --save-dev pyrightMogelijk gemaakt door

Ik gebruik de globale installatie voor snelle checks en lokale installatie voor projecten waar ik de versie wil vastzetten. De npx aanpak is handig voor eenmalige runs zonder je globale packages uit te breiden.

Pyright installeren via Python-wrapper

Als je team exclusief in Python werkt en geen Node.js in de toolchain wil, bestaat er een PyPI-wrapper:

# Standard installation
pip install pyright

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

De wrapper controleert of Node.js op je systeem staat. Als het ontbreekt, downloadt de wrapper automatisch een standalone-versie. De [nodejs] extra gebruikt een betrouwbaardere downloadmethode dan de standaard.

Houd rekening met trade-offs. De eerste run duurt langer terwijl dependencies worden gedownload. CI-omgevingen met beperkte netwerktoegang kunnen falen. En de PyPI-versie loopt soms een paar dagen achter op npm-releases.

Voor de meeste Python-teams werkt de wrapper prima. Maar als je problemen tegenkomt, val terug op de npm-installatie. Die is betrouwbaarder.

Pyright draaien op een Python-project

Eenmaal geïnstalleerd is Pyright draaien simpel. Navigeer naar je projectmap en voer uit:

pyrightMogelijk gemaakt door

Dat is het echt. Pyright scant Python-bestanden, analyseert ze en rapporteert typefouten die het vindt. Geen complexe setup nodig.

Wat Pyright standaard controleert

Waar let Pyright op? Zonder enige configuratie voert het meerdere checks uit. Het valideert typeannotaties tegen feitelijk gebruik. Het vangt niet-gedefinieerde variabelen en onbereikbare code. Het verifieert imports correct. Het markeert duidelijke typemismatches, zoals een string doorgeven waar een integer verwacht wordt.

Hier is voorbeeldoutput van een project met fouten:

/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 informationsMogelijk gemaakt door

Elke fout toont het bestandspad, regelnr., kolom en een beschrijving. De regelanaam tussen haakjes (zoals reportArgumentType) vertelt je precies welke check de fout veroorzaakte. Dit is belangrijk wanneer je specifieke regels wilt onderdrukken. Dat behandelen we zo.

Exitcodes begrijpen

Pyright geeft verschillende exitcodes terug afhankelijk van het resultaat:

In CI-pijplijnen wil je meestal dat de build faalt bij exitcode 1. Exitcodes 2-4 duiden erop dat er iets misging met de tool zelf, niet met jouw code.

Pyright configureren

Hoewel Pyright out-of-the-box werkt, hebben echte projecten maatwerk nodig. Je wilt aangeven welke bestanden je checkt, welke Python-versie je target en hoe strikt de analyse moet zijn. Laten we de belangrijkste configuratieopties bekijken.

Typechecking-modi

Pyright biedt vier strictness-levels. De modus die je kiest bepaalt hoeveel regels ingeschakeld zijn.

Welke modus kies je? Voor nieuwe projecten: begin met standard. Die vangt echte bugs zonder je te overladen met fouten. Werk je met legacycode? Basic werkt beter als je typen geleidelijk adopteert. Bewaar strict voor libraries en kritieke infrastructuur waar je maximale zekerheid wilt.

Waarschuwing: de sprong van standard naar strict is fors. Strict zet zo'n 30 extra regels aan, waaronder eisen voor typeannotaties op alle functieparameters en returnwaarden. Reken op 10x meer gemelde fouten bij de overstap. Ik heb dit op de harde manier geleerd.

Strict vereist volledige typeannotaties. Afbeelding door auteur

Configuratiebestanden

Pyright leest configuratie uit pyrightconfig.json of pyproject.toml. Als beide bestaan, heeft pyrightconfig.json voorrang.

Hier is een minimale pyrightconfig.json:

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

Het equivalent in pyproject.toml:

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

Configuratiebestand bepaalt het gedrag van Pyright. Afbeelding door auteur.

Een belangrijk detail waar veel mensen op stuklopen: als je exclude handmatig definieert, vervangt het de defaults volledig. Neem altijd node_modules, __pycache__ en je virtuele omgeving op in je aangepaste exclude-patronen. Anders probeert Pyright je dependencies te analyseren, wat enorme vertragingen veroorzaakt. Geloof me, je wilt niet 10 minuten wachten op een typecheck.

Configuratie van de virtuele omgeving

Hoe vindt Pyright je geïnstalleerde pakketten? Je moet aangeven waar het moet zoeken. Configureer dit met venvPath en venv:

{
  "venvPath": ".",
  "venv": ".venv"
}Mogelijk gemaakt door

Dit vertelt Pyright om pakketten te zoeken in ./.venv. Gebruik je een andere locatie voor je virtuele omgeving, pas dit dan aan. Zonder dit kan Pyright je geïnstalleerde dependencies niet vinden en rapporteert het voor alles ontbrekende imports.

Diagnostiek onderdrukken

Soms heeft Pyright technisch gezien gelijk, maar wil je specifieke fouten toch het zwijgen opleggen. Misschien werk je met legacycode, of weet je in een specifiek geval beter dan de typechecker. Je kunt fouten op drie niveaus onderdrukken.

Onderdrukken op configniveau

Schakel regels globaal uit:

{
  "reportMissingTypeStubs": "none",
  "reportUnusedVariable": "warning"
}Mogelijk gemaakt door

Onderdrukken op bestandsniveau

Voeg bovenaan het bestand een comment toe:

# pyright: basic
# pyright: reportPrivateUsage=falseMogelijk gemaakt door

Onderdrukken op regelniveau

Onderdruk één regel:

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

De specifieke regelsyntaxis ([reportAssignmentType]) is handig wanneer je één check wil dempen zonder andere checks op dezelfde regel uit te schakelen.

Met de configuratie op orde, kijken we hoe Pyright integreert met je ontwikkelomgeving.

Pyright in VS Code en IDE's

Als je bent zoals de meeste Python-developers, ervaar je Pyright via Pylance in plaats van via de commandline. Inzicht in die relatie helpt je editor correct te configureren en valkuilen te vermijden.

Pyright vs. Pylance

Pylance is Microsofts VS Code-extensie die Pyright's typechecking-engine bundelt. Als je Pylance installeert, krijg je Pyright automatisch. Maar Pylance voegt features toe die niet in de open-source Pyright zitten:

• Semantische highlighting: variabelen gekleurd op basis van hun type
• Geavanceerde auto-import: slimmere importsuggesties
• Code-navigatie: "Find All References" in je workspace

Deze features zijn closed-source en alleen beschikbaar in VS Code. Gebruik je Neovim, Emacs of een andere editor, dan krijg je de kernfunctionaliteit van Pyright maar niet deze extra's.

Pylance markeert typefouten in de editor. Afbeelding door auteur.

Essentiële VS Code-instellingen

Configureer Pylance via de instellingen van VS Code:

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

De instelling diagnosticMode beïnvloedt de performance. "openFilesOnly" analyseert alleen geopende bestanden. "workspace" analyseert alles maar gebruikt meer geheugen en CPU.

Veelvoorkomende configuratie-valkuilen

Interpreterselectie is belangrijk. Pylance gebruikt je geselecteerde Python-interpreter om geïnstalleerde pakketten te vinden. Als er ineens fouten verschijnen voor pakketten waarvan je weet dat ze geïnstalleerd zijn, check dan of de juiste interpreter is geselecteerd in de VS Code-statusbalk.

Interpreterselectie beïnvloedt paden voor pakketdetectie. Afbeelding door auteur.

CLI- en Pylance-defaults verschillen. Pylance zet typeCheckingMode standaard op "off" terwijl de CLI standaard "standard" gebruikt. Pylance voegt ook automatisch src toe aan zoekpaden; de CLI niet. Voor consistent gedrag tussen je editor en CI stel je alle opties expliciet in pyproject.toml in.

Het "grijze code"-fenomeen. Pylance grijst onbereikbare code uit op basis van typeanalyse. Als code onverwacht grijs wordt weergegeven, check dan de functie die direct ervoor wordt aangeroepen. Een functie getypt als retournerend NoReturn zorgt ervoor dat alles erna onbereikbaar lijkt.

Pyright vs. Mypy: wanneer gebruik je welke

Je vraagt je misschien af: moet ik Pyright gebruiken of bij Mypy blijven? Beide tools zijn production-ready, en je keuze hangt af van je workflow en eisen. Hier zijn de belangrijkste verschillen.

Snelheid en responsiviteit

Pyright is ongeveer 3–5x sneller dan Mypy voor volledige projectscans en feitelijk instant voor incrementele checks. Dit telt vooral tijdens development wanneer je directe feedback wilt.

Mypy heeft een daemon-modus (dmypy) die de performance verbetert, maar het is nog steeds trager en heeft af en toe cacheproblemen die herstarten vereisen.

Verschillen in type-inferentie

Hier wordt het interessant. De tools leiden types verschillend af. Bekijk deze code:

coordinates = (10, 20)Mogelijk gemaakt door

Pyright leidt tuple[Literal[10], Literal[20]] af, met behoud van de exacte waarden omdat tuples immutable zijn. Mypy leidt tuple[int, int] af, en verruimt naar algemene types.

Pyright's aanpak vangt meer fouten maar veroorzaakt soms frictie wanneer functies algemene types verwachten. Dit doet zelden ter zake in de praktijk omdat Literal[10] een geldige subtype van int is.

Analyse van niet-geannoteerde code

Dit is het grootste praktische verschil en een gamechanger voor legacycodebases. Mypy slaat niet-geannoteerde functies standaard over. Pyright analyseert ze toch en vangt duidelijke fouten zelfs zonder type hints.

Voor legacycodebases met spaarzame annotaties fungeert Pyright als een krachtige linter die niet-gedefinieerde variabelen en onmogelijke method calls vangt. Mypy behandelt die functies als "dynamisch" en negeert ze.

Plugin-ondersteuning

Mypy ondersteunt plugins voor frameworks als Django en SQLAlchemy. Deze plugins begrijpen ORM-magic en bieden accurate types voor dynamisch gegenereerde attributen.

Pyright heeft geen pluginsysteem. Het vertrouwt volledig op type-stubs. In 2026 hebben de meeste grote libraries hoogwaardige stubs, dus dit is minder belangrijk dan vroeger. Maar als je een framework gebruikt met zware metaprogrammering, check dan of er goede stubs bestaan voordat je je vastlegt op Pyright.

Gebruik Pylance (Pyright) tijdens development voor directe feedback, en overweeg zowel Pyright als Mypy in CI te draaien als je project framework-plugins gebruikt.

Veelvoorkomende issues bij het gebruik van Pyright

Wanneer Pyright onverwachte fouten meldt, is de oorzaak meestal een van deze issues.

Ontbrekende type-stubs

Deze fout al gezien? Pyright klaagt wanneer het geen type-informatie voor een pakket kan vinden:

Import "requests" could not be resolved (reportMissingImports)Mogelijk gemaakt door

Ontbrekende stubs veroorzaken import-waarschuwingen. Afbeelding door auteur.

Controleer eerst of het pakket in je virtuele omgeving is geïnstalleerd en of Pyright weet waar het het kan vinden (met de instellingen venvPath en venv die we eerder bespraken).

Als het pakket is geïnstalleerd maar geen type-informatie heeft, installeer community-stubs:

pip install types-requests types-PyYAML types-redisMogelijk gemaakt door

Voor pakketten zonder beschikbare stubs heb je twee opties. Je kunt de waarschuwing uitschakelen met "reportMissingTypeStubs": "none" in je config. Of zelf concept-stubs genereren:

pyright --createstub some_packageMogelijk gemaakt door

Dit maakt een skelet-.pyi-bestand aan dat je kunt invullen met de methodes die je daadwerkelijk gebruikt.

Pre-commit hook-failures

Werkt Pyright lokaal maar faalt het in pre-commit hooks? Het probleem is meestal omgevingsisolatie. Pre-commit draait hooks in geïsoleerde omgevingen die je projectpakketten niet zien.

Los dit op door de hook naar je virtuele omgeving te laten wijzen:

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

Onverwachte strict-mode-fouten

Strict ingeschakeld en ineens duizenden fouten? Niet in paniek raken. Dit is normaal. Strict vereist volledige typeannotaties. Begin met basic of standard, voeg annotaties stapsgewijs toe en zet strict alleen aan voor volledig getypte modules.

Gebruik per-bestand comments om legacycode op een soepele modus te houden:

# pyright: basicMogelijk gemaakt door

Zo kun je strikte checks afdwingen op nieuwe code terwijl je oude code geleidelijk migreert.

Naast troubleshooting, hier zijn strategieën die je Pyright-ervaring vanaf het begin soepeler maken.

Best practices voor het gebruik van Pyright

Na met Pyright in verschillende projecten te hebben gewerkt, heb ik een paar dingen geleerd die adoptie soepeler maken. Door deze coding best practices te volgen, blijft je typechecking een hulp en geen hindernis.

Begin met standard. Zoals eerder besproken vangt het echte bugs zonder volledige annotaties te vereisen. Je kunt de regels later altijd aanscherpen.

Zet je Pyright-versie vast. Pyright brengt vaak releases uit en nieuwe versies markeren soms eerder passerende code. In CI kan een niet-vastgezette pip install pyright maandagochtend build-failures veroorzaken door weekendreleases. Ik spreek uit ervaring. Niet leuk.

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

# In requirements-dev.txt
pyright==1.1.408Mogelijk gemaakt door

Los fouten incrementeel op. Probeer niet in één keer 10.000 fouten te elimineren. Gebruik de strict array om strikte checks alleen op specifieke mappen af te dwingen:

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

Gebruik vroeg configuratiebestanden. Ook voor kleine projecten voorkomt expliciete configuratie verrassingen. Neem vijf minuten om je Python-versie, pad naar de virtuele omgeving en gekozen strictness-level vast te leggen. Je toekomstige zelf zal je dankbaar zijn.

Streef niet meteen naar perfectie. Gebruik # pyright: ignore in het begin gerust vaak. Zo markeer je technische schuld zichtbaar zodat je die over tijd kunt opruimen in plaats van voortgang te blokkeren. Perfect is de vijand van goed, zeker bij nieuwe tooling.