LSP Types

Publish the excellent work of Sublime LSP as a PyPI package.

LSP Types is a Python package that aims to provide a fully typed interface to Language Server Protocol (LSP) interactions. It can be used to simply utilize the types, or to interact with an LSP server over stdio.

The library has minimal dependencies (tomli-w for TOML config serialization).

Installation

pip install lsp-types

Usage

Using the LSP types:

import lsp_types

# Use the types

Using an LSP process through stdio:

[!TIP] Recommend using basedpyright for extended features.

from lsp_types.process import LSPProcess, ProcessLaunchInfo

process_info = ProcessLaunchInfo(cmd=[
    "pyright-langserver", "--stdio"
])

async with LSPProcess(process_info) as process:
    # Initialize the process
    ...

    # Grab a typed listener
    diagnostics_listener = process.notify.on_publish_diagnostics(timeout=1.0)

    # Send a notification (`await` is optional. It ensures messages have been drained)
    await process.notify.did_open_text_document(...)

    # Wait for diagnostics to come in
    diagnostics = await diagnostics_listener

LSPProcess.stop() is terminal — including the implicit stop() when the async with block exits. Calling start() on a stopped process raises RuntimeError instead of relaunching the server, and requests and notifications sent through it raise RuntimeError too (notifications are no longer dropped with a warning). The messages name the state they came from (LSP process has been stopped vs. LSP process has not been started). Construct a new LSPProcess when you need to restart a server.

LSPs

The following LSPs are available out of the box:

Pyright
Pyrefly
ty - Astral's fast Python type checker
Zuban - Rust-based type checker + LSP by the author of Jedi

Pyrefly CLI tools

This library drives Pyrefly's LSP server (pyrefly lsp), but Pyrefly also ships a broader standalone CLI worth knowing about (verified with Pyrefly 1.2.0):

Command	What it does
`pyrefly init`	Scaffold a `pyrefly.toml` (or `[tool.pyrefly]` in `pyproject.toml`), or migrate an existing mypy/pyright config to Pyrefly
`pyrefly check`	Full type check of a file or project
`pyrefly snippet <CODE>`	Type-check an inline code snippet
`pyrefly infer`	Automatically add inferred type annotations to a file or directory
`pyrefly coverage`	Type-coverage reporting commands
`pyrefly suppress`	Add ignore comments for existing errors, or remove unused ignores
`pyrefly stubgen`	Generate `.pyi` stub files from Python source
`pyrefly dump-config`	Print Pyrefly's resolved configuration
`pyrefly tsp`	Start a TSP (Type Server Protocol) server (new in 1.2.x)

Run pyrefly <command> --help for details, or see the Pyrefly docs.

Feature Support Matrix

Legend

Symbol	Meaning
:white_check_mark:	Fully supported
:warning:	Partial support (see notes)
:x:	Not supported
:grey_question:	Not tested / Not exposed in API

Features by Backend

Last verified: Pyrefly 1.2.0, ty 0.0.75, Zuban 0.9.2 (basedpyright: CI only, unpinned npm install -g basedpyright)

Feature	Pyright	Pyrefly	ty	Zuban	Notes
Diagnostics	:white_check_mark:	:white_check_mark:	:white_check_mark:	:white_check_mark:
Hover	:white_check_mark:	:white_check_mark:	:white_check_mark:	:white_check_mark:	ty shows type only, not variable name
Completion	:white_check_mark:	:white_check_mark:	:white_check_mark:	:white_check_mark:
Completion Resolution	:white_check_mark:	:x:	:x:	:white_check_mark:	Pyrefly: no-op (returns item unchanged); ty: not supported (`-32601`)
Signature Help	:white_check_mark:	:white_check_mark:	:white_check_mark:	:white_check_mark:
Rename	:white_check_mark:	:white_check_mark:	:white_check_mark:	:white_check_mark:
Semantic Tokens	:white_check_mark:*	:white_check_mark:**	:white_check_mark:	:white_check_mark:	basedpyright recommended; *Pyrefly: legend not advertised (see docs)
Go to Definition	:grey_question:	:grey_question:	:grey_question:	:grey_question:	Not exposed in Session API
Find References	:grey_question:	:grey_question:	:grey_question:	:grey_question:	Not exposed in Session API
Code Actions	:grey_question:	:grey_question:	:grey_question:	:grey_question:	Not exposed in Session API
Formatting	:grey_question:	:grey_question:	:grey_question:	:grey_question:	Not exposed in Session API

See Feature Verification Guide for methodology on maintaining this table.

For detailed documentation:

Semantic Tokens Reference - Token types and modifiers for Monaco/editor integration
Pyrefly Known Limitations
ty Known Limitations
Zuban Known Limitations

Pyright Example

from lsp_types import Session
from lsp_types.pyright.backend import PyrightBackend

async def test_pyright_session():
    code = """\
def greet(name: str) -> str:
    return 123
"""

    session = await Session.create(PyrightBackend(), initial_code=code)
    diagnostics = await session.get_diagnostics()

    assert diagnostics != []

    code = """\
def greet(name: str) -> str:
    return f"Hello, {name}"
"""

    await session.update_code(code)
    diagnostics = await session.get_diagnostics()
    assert diagnostics == []

    await session.shutdown()

After shutdown(), a session's operational methods raise RuntimeError; its captured server and semantic-token metadata remain readable. Calling shutdown() while other operations are in flight is safe: it waits up to five seconds for them to finish, and if any are still running it stops the language server process instead of returning it to the pool, keeping stale operations out of the next session's protocol stream. (One narrow exception: cancelling an operation ends its in-flight accounting even if a notification write it already queued is still being flushed.)

Development

Requires Python 3.12+.
Requires uv for dev dependencies.

Generate latest types in one go:

make generate-latest-types

Download the latest json schema:

make download-schemas

Generate the types:

make generate-types

Copy the lsp_types/types.py file to your project.

NOTE: Do not import types that begin with __. These types are internal types and are not meant to be used.

TODOs

Support server request handlers.

Metadata

Release files for lsp-types 0.22.1

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for lsp-types 0.22.1
File	Size	Uploaded
lsp_types-0.22.1.tar.gz	91.4 kB	Aug 30, 2026	Details

Built distribution (wheel)

Table of built distributions (wheels) for lsp-types 0.22.1
File	Interpreter	ABI	Platform	Reset
lsp_types-0.22.1-py3-none-any.whl 99.6 kB Aug 30, 2026	Python 3	none	any	Details

Total release size: 191.0 kB

Release files / lsp_types-0.22.1.tar.gz

Download URL	lsp_types-0.22.1.tar.gz
Size	91.4 kB
Tags	Source
SHA-256 checksum How to use checksums	`3862d87068034ba9aa63fa5c8f9f5176967e91602b6b90a1aeb3c6fb4d920a94`
BLAKE2b-256 checksum How to use checksums	`84835cca5939f63edd3200479f1f02ef77d928a82f043bab2606cd7091eba9b4`
Upload date	Aug 30, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	Yes
Uploaded via	`twine/7.0.0 CPython/3.13.14`

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Identity

Publishing platform: GitHub Actions
Publishing repository: github.com/Mazyod/lsp-python-types
Publishing commit: github.com/Mazyod/lsp-python-types/tree/53a7fa4e58c122e93976b6481a584efe9c170512

Workflow

Publishing configuration: github.com/Mazyod/lsp-python-types/blob/53a7fa4e58c122e93976b6481a584efe9c170512/.github/workflows/publish.yml
Publishing logs: github.com/Mazyod/lsp-python-types/actions/runs/33333320511/attempts/1

Artifact

Subject: lsp_types-0.22.1.tar.gz
SHA-256 checksum: 3862d87068034ba9aa63fa5c8f9f5176967e91602b6b90a1aeb3c6fb4d920a94 Verifying attestations

Release files / lsp_types-0.22.1-py3-none-any.whl

Download URL	lsp_types-0.22.1-py3-none-any.whl
Size	99.6 kB
Tags	Python 3
SHA-256 checksum How to use checksums	`3c66c8de2f843be423cebb4915ccb6f978852971c74e402f8b981f717cf01489`
BLAKE2b-256 checksum How to use checksums	`7b44cb3755ce4ae5a4c28c591437cdabcdb2be4245a94e0b403bc63162b7c301`
Upload date	Aug 30, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	Yes
Uploaded via	`twine/7.0.0 CPython/3.13.14`

Provenance

Identity

Publishing platform: GitHub Actions
Publishing repository: github.com/Mazyod/lsp-python-types
Publishing commit: github.com/Mazyod/lsp-python-types/tree/53a7fa4e58c122e93976b6481a584efe9c170512

Workflow

Publishing configuration: github.com/Mazyod/lsp-python-types/blob/53a7fa4e58c122e93976b6481a584efe9c170512/.github/workflows/publish.yml
Publishing logs: github.com/Mazyod/lsp-python-types/actions/runs/33333320511/attempts/1

Artifact

Subject: lsp_types-0.22.1-py3-none-any.whl
SHA-256 checksum: 3c66c8de2f843be423cebb4915ccb6f978852971c74e402f8b981f717cf01489 Verifying attestations