Type Server Protocol (TSP) Released for Python Type Analysis Data

Introduction to Type Server Protocol

The Type Server Protocol (TSP) has been released as a JSON-RPC protocol specifically for type servers to deliver Python analysis data. A type server manages the type-analysis state for a workspace and responds to requests for protocol version, snapshots, Python search paths, import resolution, and various type queries, including computed, declared, and expected types.

Protocol Design and Conventions

TSP incorporates data shapes and conventions from the Language Server Protocol (LSP) where beneficial, such as `Position` and `Range` objects, and represents URIs as strings. All TSP methods are prefixed with `typeServer/`. The authoritative definitions for the protocol are found in `typeServerProtocol.ts` (TypeScript interfaces), `tsp.json` (machine-readable model), and `tsp.schema.json` (JSON schema).

Client-Server Communication

Clients initiate communication with a type server over a main JSON-RPC connection, utilizing transports like stdio or Node IPC. For stdio, stdout is reserved for JSON-RPC messages. Type servers are expected to receive sufficient workspace and document state to fulfill TSP requests, often using standard LSP initialization and document synchronization. TSP also supports optional read-only connections, negotiated during initialization, with the original connection retaining control over state changes and synchronization.

Compatibility and Session Flow

TSP employs semantic versioning for client/server compatibility. During its 0.x development phase, minor version changes may introduce breaking changes, while patch versions maintain backward compatibility within the same minor line. A typical session involves the client starting the server, initializing shared workspace state (often via LSP messages), verifying protocol compatibility, obtaining a snapshot identifier, and then sending type-query, import-resolution, or search-path requests that include the current snapshot.