TermiNexus
e9e4693333
4.0 KiB
Pyright Type Server
In addition to the command-line tool and the language server, Pyright ships a type server that speaks the Type Server Protocol (TSP). It is distributed as a separate npm package, pyright-typeserver, and is exposed through the pyright-typeserver executable.
What is the Type Server Protocol?
The Language Server Protocol (LSP) is designed around editor features (completions, hover, go-to-definition, and so on). Some tools instead need direct access to a Python type checker's type information — the inferred type of an expression, the declared type of a symbol, resolved imports, and search paths — without going through editor-oriented requests.
The Type Server Protocol is a JSON-RPC protocol, layered on top of the same transport as LSP, that exposes this type information directly. A client can open Python documents in the usual LSP way (textDocument/didOpen, textDocument/didChange, …) and then ask the type server questions such as:
typeServer/getComputedType— the inferred type at a parse node.typeServer/getDeclaredType— the declared type of a declaration.typeServer/getExpectedType— the expected (contextual) type at a node.typeServer/resolveImport— resolve an import to a file on disk.typeServer/getPythonSearchPaths— the search paths used for import resolution.typeServer/getSnapshot— the current analysis snapshot version, used to keep type queries consistent with the document state.
Running the type server
The type server communicates over stdio, just like the language server:
pyright-typeserver --stdio
It is not intended to be run interactively; it is started by a client (for example, an editor extension or a code-generation tool) that drives it over the protocol.
Notebook support
The type server understands Jupyter notebooks. When a client sends notebookDocument/didOpen, notebookDocument/didChange, and notebookDocument/didClose, the server models the notebook as a linear chain of chained cell source files so that names defined in earlier cells are visible in later cells, matching notebook execution semantics.
Virtual file redirection
The type server supports redirecting the contents of a file on disk to a virtual document supplied by the client. This is used, for example, by stub generators that synthesize a merged view of a module and want the type server to analyze the synthesized contents in place of the file on disk. Clients drive this through the pyright/setVirtualFileRedirect and pyright/removeVirtualFileRedirect notifications.
Relationship to Pyright
The type server is built on the same analyzer, binder, and type evaluator as the Pyright command-line tool and language server. It reuses Pyright's Service / Program / SourceFile infrastructure, so type results are identical to what Pyright's other front ends produce.
Code layout: two packages
The type server is split across two packages, following the same convention Pyright uses for its command-line tool and language server:
| Package | Role |
|---|---|
packages/pyright-internal/src/typeServer/ |
All of the actual code. The server, protocol definitions, notebook support, virtual-file redirection, the file system layer, and the tests all live here. This is the only package with real implementation. |
packages/pyright-typeserver/ |
The distributable wrapper. A thin bundling shim (rspack config, package.json, and a bin entry point) that packages the code above into the publishable pyright-typeserver npm package. It contains no logic — its nodeMain.ts simply calls main() from pyright-internal. |
This mirrors how pyright-internal holds all of the parser/checker/evaluator logic while the pyright package is just the thin CLI and language-server bundle. Keeping the code in pyright-internal means the type server shares the exact same vscode-languageserver copy and analyzer internals as the rest of Pyright, rather than pulling in a duplicate or mismatched set of dependencies.