lsprotocol

library2025.0.0pypypi✓ verified 23d ago

lsprotocol is a Python library that provides generated type definitions for the Language Server Protocol (LSP). It allows developers to build language servers and clients by providing a robust and easy-to-use type generation system, staying up-to-date with the latest LSP specification. The library follows a yearly major release cadence.

serialization type-stubs

pip install lsprotocol

github ↗package ↗

INSTALL

IMPORT

SIG · LSPROTOCOL

lsprotocol

serializationpythonv2025.0.0

Install

1.8s avg

Import

1246ms

Disk

19MB

Pass rate

10/ 10

Env Coverage10 / 10

glibc

3.9–3.13

musl

3.9–3.13

Install & Compatibility

Where this runs

tested against v2025.0.0 · pip install

no network on importno background threads

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

py 3.10–3.95 runs

installs and imports cleanly · install 0.0s · import 1.318s · 20.3MB

glibc

py 3.10–3.95 runs

installs and imports cleanly · install 1.8s · import 1.174s · 21MB

19MB installed

● package 19MB

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

types

✓ from lsprotocol import types

✗ from pygls.lsp import types

Older LSP client libraries like pygls (before v1.0) used their own type definitions. lsprotocol is now the canonical source.

converters

✓ from lsprotocol import converters

Used for serializing and deserializing LSP objects to/from JSON.

This quickstart demonstrates how to create LSP type objects, and how to use the built-in converters to serialize (unstructure) and deserialize (structure) these objects to and from Python dictionaries, typically for JSON communication.

import json from lsprotocol import converters, types # Create an LSP Position object position = types.Position(line=10, character=3) print(f"Created Position object: {position}") # Get a converter instance converter = converters.get_converter() # Unstructure (serialize) the object to a dictionary (suitable for JSON) lsp_dict = converter.unstructure(position, unstructure_as=types.Position) print(f"Unstructured to dictionary: {lsp_dict}") # Convert to JSON string json_output = json.dumps(lsp_dict) print(f"JSON output: {json_output}") # Structure (deserialize) a dictionary back into an LSP object data_from_json = {'line': 5, 'character': 0} structured_position = converter.structure(data_from_json, types.Position) print(f"Structured back to object: {structured_position}")

Debug

Known issues

breakingBreaking changes in type names were introduced due to updates to the latest LSP specification. Starting with versions like `2024.0.0a2`, many type names were standardized, often prefixing methods/types with `TextDocument` or similar.

fix

Review your code for `lsprotocol.types` imports and object instantiations. Refer to the `pygls` migration guides (v1.0 and v2.0) for examples of renamed types, as `pygls` also adopted `lsprotocol`'s types.

affects: >=2024.0.0a2

breakingFurther type name standardization occurred around `2025.x` versions, aiming to remove overly specific or long type names (e.g., `NotebookDocumentSyncRegistrationOptionsNotebookSelectorType2CellsType`) in favor of more consistent naming.

fix

Inspect release notes and `pygls` v2.0 migration guides for renamed types and adjust your code accordingly. This specifically affects users leveraging the newer LSP specification features.

affects: >=2025.0.0

gotchaOptional fields in LSP types, when not explicitly set, might be unstructured as `None` in the resulting dictionary/JSON, rather than being omitted entirely. Some LSP servers might not tolerate `null` for optional parameters and expect them to be absent.

fix

If an LSP server you're interacting with rejects `null` values for optional fields, you may need to manually filter out `None` values from the unstructured dictionary before serialization to JSON.

affects: All versions

gotchalsprotocol updates regularly to align with new versions of the Language Server Protocol specification. Using a specific version of `lsprotocol` means you are bound to the LSP spec it implements. New LSP features or changes in existing types are introduced with spec updates.

fix

Always check the `lsprotocol` release notes to understand which LSP specification version it targets. Ensure your client or server implementation is compatible with that specific LSP spec version to avoid unexpected behavior or missing capabilities.

affects: All versions

Errors

Common errors & fixes

ModuleNotFoundError: No module named 'lsprotocol'

The `lsprotocol` package is not installed in the Python environment where the code is being executed or where a tool (like a language server or IDE extension) is attempting to import it.

fix

Install the `lsprotocol` library using pip: `python -m pip install lsprotocol`

Import "lsprotocol.types" could not be resolved (reportMissingImports)

This is a type-checking error (e.g., from Pyright) indicating that the type checker cannot find the `lsprotocol.types` module, often due to an incorrectly configured Python environment for the type checker or a missing installation.

fix

Ensure `lsprotocol` is installed in the Python environment used by your type checker. If using an IDE, verify that the correct Python interpreter and environment are selected and that the type checker's configuration includes the relevant site-packages.

ImportError: cannot import name 'AttrsInstance' from 'attr'

This error typically indicates an incompatibility between the `lsprotocol` library and the installed version of its `attrs` dependency. `AttrsInstance` was likely removed or changed in a specific `attrs` version, leading to a conflict if `lsprotocol` expects a different one.

fix

Ensure both `lsprotocol` and its `attrs` dependency are up-to-date and compatible. It's often best to install them in a fresh virtual environment. If this occurs within a VS Code extension, look for an `importStrategy` setting (e.g., `"black-formatter.importStrategy": "useBundled"`) to ensure the extension uses its internal, compatible dependencies.

RecursionError: maximum recursion depth exceeded

This runtime error can occur within `lsprotocol`'s internal type resolution or conversion mechanisms, especially with complex or deeply nested Language Server Protocol (LSP) types, or due to bugs in older library versions.

fix

Update `lsprotocol` to the latest version, as such issues are often addressed in new releases. If the problem persists, consider simplifying the data structures being processed or, as a last resort, temporarily increasing Python's recursion limit (e.g., `sys.setrecursionlimit(2000)`).

Upgrade

Version history

2025.0.0latest on PyPI · released Jun 17, 2025

Audit

Dependencies

attrsrequiredUsed for defining classes and data structures.

cattrsrequiredUsed for structuring and unstructuring (serializing/deserializing) LSP types.

Agent activity

29 hits · last 30 days

node

OpenAI (training)

Resources

githubhttps://github.com/microsoft/lsprotocol ↗

packagehttps://pypi.org/project/lsprotocol/ ↗