{"id":3546,"library":"lsprotocol","title":"lsprotocol","description":"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.","status":"active","version":"2025.0.0","language":"en","source_language":"en","source_url":"https://github.com/microsoft/lsprotocol","tags":["lsp","language server protocol","types","protocol","json-rpc"],"install":[{"cmd":"pip install lsprotocol","lang":"bash","label":"Install latest stable version"}],"dependencies":[{"reason":"Used for defining classes and data structures.","package":"attrs","optional":false},{"reason":"Used for structuring and unstructuring (serializing/deserializing) LSP types.","package":"cattrs","optional":false}],"imports":[{"note":"Older LSP client libraries like pygls (before v1.0) used their own type definitions. lsprotocol is now the canonical source.","wrong":"from pygls.lsp import types","symbol":"types","correct":"from lsprotocol import types"},{"note":"Used for serializing and deserializing LSP objects to/from JSON.","symbol":"converters","correct":"from lsprotocol import converters"}],"quickstart":{"code":"import json\nfrom lsprotocol import converters, types\n\n# Create an LSP Position object\nposition = types.Position(line=10, character=3)\nprint(f\"Created Position object: {position}\")\n\n# Get a converter instance\nconverter = converters.get_converter()\n\n# Unstructure (serialize) the object to a dictionary (suitable for JSON)\nlsp_dict = converter.unstructure(position, unstructure_as=types.Position)\nprint(f\"Unstructured to dictionary: {lsp_dict}\")\n\n# Convert to JSON string\njson_output = json.dumps(lsp_dict)\nprint(f\"JSON output: {json_output}\")\n\n# Structure (deserialize) a dictionary back into an LSP object\ndata_from_json = {'line': 5, 'character': 0}\nstructured_position = converter.structure(data_from_json, types.Position)\nprint(f\"Structured back to object: {structured_position}\")","lang":"python","description":"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."},"warnings":[{"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.","message":"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.","severity":"breaking","affected_versions":">=2024.0.0a2"},{"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.","message":"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.","severity":"breaking","affected_versions":">=2025.0.0"},{"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.","message":"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.","severity":"gotcha","affected_versions":"All versions"},{"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.","message":"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.","severity":"gotcha","affected_versions":"All versions"}],"env_vars":null,"last_verified":"2026-04-11T00:00:00.000Z","next_check":"2026-07-10T00:00:00.000Z"}