Type Server Protocol
Протокол Type Server Protocol (TSP) — это JSON-RPC-протокол, с помощью которого клиент запрашивает у сервера типов данные анализа Python. Сервер хранит состояние типового анализа рабочей области и отвечает на запросы о версии протокола, снимках состояния, путях поиска Python, разрешении импортов и типах (вычисленных, объявленных и ожидаемых). Протокол заимствует форматы и соглашения Language Server Protocol там, где это удобно, — например, Position и Range, а URI представляются строками; методы используют префикс typeServer/.
Авторитетные определения протокола — файлы typeServerProtocol.ts (интерфейсы TypeScript), tsp.json (машиночитаемая модель) и tsp.schema.json (JSON-схема). Версии семантические: в ветке 0.x минорные изменения могут ломать совместимость, патчи — нет. История: 0.1.0 — начальная, 0.2.0 — новые типы запросов и поля, 0.3.0 — более сложные формы типов, 0.4.0 — объединение Type и типовые нагрузки на основе заглушек, 0.4.1 — многосоединённая согласование и управляющий запрос typeServer/connection.
Клиент запускает сервер и общается по основному соединению JSON-RPC (stdio или Node IPC; при stdio stdout зарезервирован под протокол). Типичный старт: инициализация общего состояния (обычно через LSP initialize/initialized), вызов typeServer/getSupportedProtocolVersion со сверкой semver, затем typeServer/getSnapshot для первого идентификатора снимка, после чего идут запросы типов, импортов и путей поиска с указанием текущего снимка; при устаревании результатов сервер шлёт typeServer/snapshotChanged. Дополнительные соединения — необязательная оптимизация: они открываются только после согласования и обслуживают лишь read-only запросы, тогда как основное соединение владеет изменяемым состоянием. Ошибки кодируются стандартно: -32802 (ServerCancelled) при устаревшем снимке с возможностью повтора, -32602 (InvalidParams) при некорректных параметрах, -32603 (InternalError) при внутреннем сбое; сообщения не должны раскрывать секреты. Чек-лист совместимости требует корректного semver, сериализации по артефактам, неубывающих неотрицательных снимков, инвалидации при изменениях документов и конфигурации, retryable-ошибок на устаревшие снимки, нулевых UTF-16 координат LSP, корректных результатов разрешения импортов и типовых запросов, а также честного объявления многосоединённого режима с отклонением LSP-трафика и изменяющих состояние уведомлений на дополнительных соединениях.