lsprotocol

Warnings

• breaking Breaking 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.
• breaking Further 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.
• gotcha Optional 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.
• gotcha lsprotocol 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.

Install

• pip install lsprotocol Install latest stable version

Imports

• types

  from lsprotocol 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.

Quickstart

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}")