Type Server Protocol = Abstract out type information

[rchiodo]

The goal of language servers and the LSP is to abstract out the language-dependent aspects of the editor experience, so that editors can be language-agnostic in many of their feature implementations. That is a much broader scope than the primary goal of a type checker, which is to verify that operations in a program are performed on compatible data types, reporting and/or preventing runtime errors caused by incompatible operations. This suggests that there may be language-dependent features that belong in a language server but not necessarily in a type checker. This begs the question of whether there could be an API similar to LSP but specifically for the functionality of type checkers, while there are language-specific features that can be implemented in a language server on top of this API that can be shared independent of the type checker used. This would mean type checkers could be maintained separately from language servers, whereas in the current scheme of things, each type checker (and they are proliferating, for Python) ends up implementing its own language server with different capabilities. This discussion is to talk about how that might be done and what this Type Server Protocol might look like.

Pylance's architecture can be simplified like so:

VS code talks to Pylance to do things like:

• Get completions
• Get hover text
• Find all references
• Goto definition

Internally Pylance is using Pyright to figure some of these things out. Pylance uses Pyright to:

• Get a type of a node in an AST (like in order to find the members available after hitting '.')
• Get the docstring for a node (to display in hover text)
• Compute the return type for a function (in order to determine the type of a variable)
• Get the declaration for a symbol (like for goto definition)

Pylance adds a number of features on top of this, such as:

Feature	Pyright Provides	Pylance Adds
Text/Notebook Document Sync	Document management	- Chain notebook cells together
Hover	Get Doc strings	- Format as Sphinx documentation - Apply to signature help - Provide links to documentation
Completion	Symbol-based resolution	- MRU List - Add code actions for things like 'auto import' - Rank suggestions based on context - Support for intellicode suggestions - Copilot completion context
Signature Help	Function arguments and types	- Highlight active parameter - Find associated docstring
Go to Definition	Find symbol declaration	- Convert declaration into LSP location - Support for goto def inside of strings
Go to Implementation	Find symbol declaration	- Search type hierarchy for implementations
Find References	Parse tree and symbol list	- Performing the actual search - Filter references by type
Document Highlight	x	- Contextual analysis
Document Symbol	Symbol list	- Indexing of symbols
Code Action	x	- Provide quick fixes - Suggest refactoring options
Formatting	x	- Apply formatting rules - Align code with style guides
Rename	x	- Update all references to renamed symbols - Prevent conflicts with existing names
Workspace Symbol	Provide symbols	- Search for symbols across the workspace - Display results with context information
Semantic Tokens	Provide token stream	- Analyze tokens to provide semantic information
Inlay Hints	Provide types	- Provide logic for which to skip and which to show
Interfacing with VS code	x	- Create appropriate edits and such to apply things like rename, refactor etc
MCP Server	x	- Expose different aspects of the Type Server to MCP
Environment resolution	Use config settings to find environment	- Picks up environment picked by Python extension
Editable install (not normally supported by static type checkers)	x	- Execution in a python sandbox to add editable install paths
Run in the browser	WASM or Javascript output	- File system abstraction to allow running in the browser

This separation might be generalized more like so:

Meaning Pylance (or other Python language servers) could be modified to talk any type checker in order to provide the information it needs.

There are a number of challenges that would have to be solved, such as:

• how to represent type information, AST nodes, locations in code...
• serializing this data across and API boundary in a way that does not result in a significant performance cost
• dealing with 'value-added' features specific to individual type checkers, so this doesn't end up being a least-common denominator
• where there is replicated information between the language server and the type checker, ensuring consistency

On the other hand, there are clear benefits to be obtained from this, as it free type checker authors from having to build LSP implementations while allowing multiple language servers to bloom that can add many features that type checker authors might like but not be motivated to implement. It also allows the type checker to more easily run out of proc, which can have benefits such as enabling easier support of async LSPs, overcoming memory limitations in extension hosts, etc. Another benefit is that the language servers and type checkers can be implemented in different languages; in some editors the language servers may run in-proc and be bound to the same runtime as the editor.

[kinto0]

Thanks for starting the discussion! We (Pyrefly maintainers) can talk with other typechecker maintainers at PyCon next week. There will be a typing summit - it would be great to get feedback there. @lolpack said that Pylance wont be there, so instead it could be raised at a typing meetup where we could get this in front of all of the typechecker maintainers at the same time.

Let us know if there are any updates on your side in the mean time. We are in agreement that this approach seems promising to get other type checkers like Pyrefly out to more customers fast.

[gramster]

We will have one of our PMs at the conference at least, and hope to have her get a chance to talk to Charlie et al. Enjoy PyCon and we will sync up afterwards!

[lolpack]

Sounds good! Definitely worth having them swing by the typing summit and perhaps we can pull more maintainers into the discussion for the type service provide.

[sideeffffect]

Interesting initiative! This may be of interest to other languages beyond Python.
/CC @tgodzik @jastice @agluszak @olafurpg @ckipp01

[rchiodo]

We have a working protocol that we're using in Pylance for semantic tokens (meaning this is used for out of proc calls to Pyright). Please feel free to comment on it:
https://github.com/microsoft/pylance-release/blob/main/docs/tsp/typeServerProtocol.ts

It follows most of the same patterns as the LSP.

I expect we'll be adding more methods and types to it in the coming weeks.

[kinto0]

Interesting - I will take a closer look soon. Are all of these requests necessary for semantic tokens?

[rchiodo]

I can go into more details if your curious, but for example typeServer/getBoundMagicMethodInfo is used to colorize stuff like __eq__ operators.

[DetachHead]

honestly this sounds like a needlessly convoluted solution to a problem that shouldn't even exist in the first place. "we want our language server to be closed-source and not usable outside of vscode, but also we want it to be consistent with other editors and CI environments". it goes against the whole point of language servers, you can't have your cake and eat it too.

i hope other type checker maintainers are not on board with this, because as far as i can tell this only benefits microsoft and no one else. they want to reap the benefits of the upcoming open-source language servers like ty and pyrefly while still being able to offer exclusive features once one of them inevitably renders pyright/pylance obsolete, because otherwise the user will have too much freedom to switch between editors.

[gramster]

We're going to provide a way to switch between type checkers from
Within pylance; that is planned regardless of this proposal. But if we're going to do that, having a standard API that is public is a cleaner engineering approach that others can leverage too. There's value in that as the different type checkers are likely to prioritize different things. Pyrefly want performance on big monorepos, ty wants great diagnostics, and pyright prioritizes standards conformance.

The actual protocol is just going to be some custom messages added to LSP.

Nothing to stop you from using this too.

[rchiodo]

@kinto0's had some great review feedback and it's made us rethink how we might do TSP.

What if instead of a separate protocol, it was just extra messages in the LSP?

Something like so:

This would change a couple of things:

1. Pyright (or another type checker) would implement an LSP server. (Which most already do)
2. Pylance would forward all of the lifecycle messages to the language server.
3. An extra flag in the (experimental capabilities) would be passed to indicate 'Type Server' mode
4. Pyright (or another type checker) could then indicate in its returned server capabilities which LSP requests it wants to exclusively handle (like say completions)
5. Pyright (or another type checker) would add to the 'experimentalCapabilities' indicating it could handle type server requests.
6. Type server requests would be new custom messages used by Pylance to implement the features that the underlying LSP server decided it didn't support.

This would mean no extra configuration steps for a separate type server. Pyright (and others) would simply do what they do now to find settings, keep track of open documents etc, as the LSP lifecycle messages already handle that.

Additionally we can work out how to combine different requests if we don't want wholesale replacement by the underlying Type server or by Pylance. One such example might be completions. Pyright at the moment provides fewer completions than Pylance does. We'd combine the results from the two. How we specify the 'mode' for different features we can work out later. Perhaps the experimentalCapabilities provides a mode for every LS capability.

[rchiodo]

• GetSnapshot is like a marker in time. It really just means that the Type Server doesn't have to worry about a type that it returned that may no longer be a valid type because something changed. Snapshots do not need to persist, they are merely an indicator of whether or not data is still valid.

For example, user has code like so:

def foo():
     return 4
     
x = foo()

And Pylance asks for the type of foo. First it asks for the current snapshot and then asks for the type of foo within that snapshot.

Then the user changes the file to be like so:

def foo():
     return "four"
     
x = foo()

The Type server should have received the update to the file and then thrown out the old type for foo. Its current internal snapshot indicator would change to 1 (or whatever you want to track).

Pylance then might try to use the old type it received on snapshot 0. Let's say to find the parameters of foo. It would call GetTypeAttributes for Type foo and snapshot 0. The type server would just immediately return an error saying unknown or invalid snapshot and Pylance would have to requery for the type of foo again.

• GetDiagnosticsVersion - we were using this to determine if errors for things like code actions still match the current file. Internally this could just be the client version that comes from the LSP TextDocument/didChange TextDocument/didOpen notifications. At the moment we're not actually using it yet, so maybe we can just drop it.

• Multifolder support - this assumes that the Type Server supports multiple folders. Every request has a 'starting' point that indicates where the request is coming from. Right now I'm using that in Pyright to determine which workspace a request corresponds to. But it's similar to how you'd identify which folder any LSP request relates to. So yes multi-folder support is implicit. Maybe we should make each request more explicit in that it has an originating file uri or something like that?

[rchiodo]

An alternative for the snapshot idea might have been to embed the concept of still valid in the returned type and declaration handles, but it seemed more explicit with passing the snapshot everywhere.

[MichaReiser]

• GetSnapshot: Thanks, that makes sense and should work for ty. We use a global revision counter that we could use as "snapshot". I'm wondering if a slightly different terminology, e.g., server version or project version would be less confusing
• GetDiagnosticsVersion: I don't think we can use the client version because the diagnostics of a file can also change due to changes in another file. We would probably end up using our global revision instead. What's unclear to me is how pylance would match quick fixes and refactors to ty provided diagnostics?
• Multifolder support: That makes sense. That means almost every request has two implicit arguments: The URL it comes from (a file, a URl pointing to an unsaved file, a notebook cell), and the snapshot version.

[rchiodo]

What's unclear to me is how pylance would match quick fixes and reactors to ty provided diagnostics?

Hmm maybe we don't. We haven't started looking at how code actions interact with diagnostics yet. Maybe code actions always just come from the Type Server (given that it implements LSP too) and we don't provide them except in the cases where we recognize the error. It would be weird for us to put the Add import code action on anything but an import resolve failure. Unless we can identify that in the ty case too, seems like we should just skip adding it.

[MichaReiser]

It would be weird for us to put the Add import code action on anything but an import resolve failure. Unless we can identify that in the ty case too, seems like we should just skip adding it.

Perhaps that could be part of the diagnostic return type instead? Like, this is a missing import and x would need to be imported. But I agree. It might just be easier for the TSP to provide the code action too.