Type Server Protocol

The Type Server Protocol (TSP) is a JSON-RPC protocol for asking a type server for Python analysis data. A type server maintains the type-analysis state for a workspace and answers requests for the protocol version, snapshots, Python search paths, import resolution, and type queries (computed, declared, and expected types). The protocol uses Language Server Protocol (LSP) data shapes and conventions where they are useful, such as Position and Range, and it represents URIs as strings the same way LSP does. TSP methods use the typeServer/ prefix. The protocol artifacts in this folder are the authoritative definitions: typeServerProtocol.ts defines the TypeScript interfaces and request types. tsp.json is the machine-readable protocol model. tsp.schema.json is the JSON schema for the protocol model. Version History TSP uses semantic version strings for client/server compatibility checks. While the protocol is in the 0.x line, minor version changes may be breaking. Patch version changes remain backward compatible within the same minor line. Version Changes 0.1.0 Initial protocol version. 0.2.0 Added request types and fields. 0.3.0 Switched to more complex type shapes. 0.4.0 Switched to the Type union and stub-based type payloads. 0.4.1 Added multi-connection negotiation and the typeServer/connection control request. Connection Model A client starts a type server and communicates with it over the main JSON-RPC connection using a transport the server supports, such as stdio or Node IPC. When using stdio, stdout must be reserved for JSON-RPC protocol messages. A type server is expected to receive enough workspace and document state to answer the TSP requests it supports. Clients commonly use normal LSP initialization and document synchronization for this state, then send typeServer/* requests on the same JSON-RPC connection. TSP also supports optional extra read-only connections. The original connection remains the main connection and owns initialization, workspace state, document synchronization, state-changing notifications, and connection control. Extra connections are opened only after client and server negotiate support during initialization. Startup Sequence A typical session follows this order: The client starts or connects to the type server. The client and server initialize any shared workspace state, commonly through the LSP initialize and initialized messages. The client calls typeServer/getSupportedProtocolVersion and verifies that the returned semver …