LSP Types

https://github.com/sublimelsp/lsp-python-types
Admin
LSP Types is a Python package that generates Language Server Protocol type definitions and data...
Tokens:4,190
Snippets:20
Trust Score:9.8
License:MIT
Update:7 months ago
Show doc for...
Tokens:
Raw
### Install Dependencies with UV

Source: https://github.com/sublimelsp/lsp-python-types/blob/main/README.md

This command uses the UV package manager to create a virtual environment for the project. Ensure UV is installed and accessible in your PATH.

```sh
uv venv
```

--------------------------------

### Generate Types and Format Code

Source: https://github.com/sublimelsp/lsp-python-types/blob/main/README.md

This sequence of commands first generates Python types using `generate.py` and then formats the code using `ruff format`. Both scripts are executed within the UV-managed virtual environment. Ensure `generate.py` and `ruff` are correctly installed as dependencies.

```sh
uv run generate.py
uv run ruff format
```

--------------------------------

### Download JSON Schemas

Source: https://github.com/sublimelsp/lsp-python-types/blob/main/README.md

Executes the `download_schemas.py` script using UV to fetch the latest JSON schemas required for type generation. This script relies on network access to download the schema files.

```sh
uv run download_schemas.py
```

--------------------------------

### Python Project Integration of LSP Types

Source: https://context7.com/sublimelsp/lsp-python-types/llms.txt

Example of how to import and use the generated LSP types within a Python project. It shows importing enumerations, type aliases, structures (TypedDict), and request/response types.

```python
from lsp_types import (
    # Enumerations
    SymbolKind, DiagnosticSeverity, CompletionItemKind, 
    SemanticTokenTypes, CodeActionKind, ErrorCodes,

    # Type aliases
    DocumentUri, Definition, ProgressToken,

    # Structures (TypedDict)
    Position, Range, Location, TextEdit,
    Diagnostic, CompletionItem, Hover,
    InitializeParams, InitializeResult,
    ServerCapabilities, TextDocumentIdentifier
)

from custom import (
    # Request/Response types
    InitializeRequest, InitializeResponse,
    CompletionRequest, CompletionResponse,
    DefinitionRequest, DefinitionResponse,

    # Union types for routing
    ClientRequest, ServerRequest,
    ClientResponse, ServerResponse,
    ClientNotification, ServerNotification
)
```

--------------------------------

### Bash Workflow for LSP Type Generation

Source: https://context7.com/sublimelsp/lsp-python-types/llms.txt

A bash script outlining the workflow for setting up a virtual environment, downloading LSP schemas, generating Python types, formatting the code, and copying the generated files to a project.

```bash
# Step 1: Set up virtual environment with uv
uv venv

# Step 2: Download latest LSP schemas
uv run download_schemas.py

# Step 3: Generate Python types
uv run generate.py

# Step 4: Format generated code
uv run ruff format

# Step 5: Copy generated files to your project
cp generated/lsp_types.py /path/to/your/project/
cp generated/custom.py /path/to/your/project/
```

--------------------------------

### Python LSP Type-Safe Handlers

Source: https://context7.com/sublimelsp/lsp-python-types/llms.txt

Demonstrates type-safe handling of LSP requests like initialization, completion, and diagnostic creation using Python type hints. These functions ensure that parameters and return values conform to the expected LSP types.

```python
from lsprotocol.types import (InitializeParams, InitializeResult, ServerCapabilities, TextDocumentSyncKind, CompletionOptions, CompletionItemKind, CompletionItem, DocumentUri, Position, Diagnostic, DiagnosticSeverity, Range)

# Type-safe initialization response
def handle_initialize(params: InitializeParams) -> InitializeResult:
    return InitializeResult(
        capabilities=ServerCapabilities(
            textDocumentSync=TextDocumentSyncKind.Incremental,
            completionProvider=CompletionOptions(
                triggerCharacters=['.', ':'],
                resolveProvider=True
            ),
            definitionProvider=True,
            hoverProvider=True
        )
    )

# Type-safe completion handler
def handle_completion(uri: DocumentUri, position: Position) -> list[CompletionItem]:
    return [
        CompletionItem(
            label='print',
            kind=CompletionItemKind.Function,
            detail='Print to stdout',
            insertText='print($1)',
            insertTextFormat=2  # Snippet
        ),
        CompletionItem(
            label='len',
            kind=CompletionItemKind.Function,
            detail='Return length of object'
        )
    ]

# Type-safe diagnostic creation
def create_diagnostic(line: int, message: str) -> Diagnostic:
    return Diagnostic(
        range=Range(
            start=Position(line=line, character=0),
            end=Position(line=line, character=100)
        ),
        severity=DiagnosticSeverity.Error,
        source='my-lsp-server',
        message=message
    )
```

--------------------------------

### Download LSP Schema Files (Python)

Source: https://context7.com/sublimelsp/lsp-python-types/llms.txt

This script downloads the latest LSP JSON schema and meta model from Microsoft's official repository. It fetches both the schema definition and the protocol specification, saving them as `lsp.schema.json` and `lsp.json` respectively in the `lsprotocol` directory. This is a prerequisite for generating type definitions.

```python
#!/usr/bin/env python3
from pathlib import Path
from urllib.request import urlopen

REPO_URL = 'https://raw.githubusercontent.com/microsoft/vscode-languageserver-node'

# Download the meta model schema (defines structure of the JSON)
with urlopen(f'{REPO_URL}/main/protocol/metaModel.schema.json') as url:
    Path('./lsprotocol/lsp.schema.json').write_text(url.read().decode('utf-8'))

# Download the LSP specification (contains all type definitions)
with urlopen(f'{REPO_URL}/main/protocol/metaModel.json') as url:
    Path('./lsprotocol/lsp.json').write_text(url.read().decode('utf-8'))

# Output: Creates lsprotocol/lsp.schema.json and lsprotocol/lsp.json

```

--------------------------------

### Generate LSP Type Definitions (Python)

Source: https://context7.com/sublimelsp/lsp-python-types/llms.txt

This script is the main entry point for generating the `lsp_types.py` file. It reads the downloaded LSP JSON specification, processes enumerations, type aliases, and structures, and writes the complete, typed Python code. It supports modern typing features like TypedDict, Literal, Union, and NotRequired, and includes overrides for specific enum types.

```python
from pathlib import Path
from typing import cast
import json

from utils.generate_enumerations import generate_enumerations
from utils.generate_structures import generate_structures
from utils.generate_type_aliases import generate_type_aliases
from utils.helpers import get_new_literal_structures, reset_new_literal_structures

# Enum type overrides for specific LSP enums
ENUM_OVERRIDES = {
    'CodeActionKind': 'StrEnum',
    'SemanticTokenTypes': 'StrEnum',
    'SemanticTokenModifiers': 'StrEnum',
    'MarkupKind': 'StrEnum',
    'WatchKind': 'IntFlag',
}

ALIAS_OVERRIDES = {
    'LSPArray': "Sequence['LSPAny']",
    'LSPObject': 'Mapping[str, Any]'
}

def generate_protocol(output: str) -> None:
    reset_new_literal_structures()

    schema = Path('./lsprotocol/lsp.json').read_text(encoding='utf-8')
    lsp_json = json.loads(schema)
    specification_version = lsp_json.get('metaData')['version']

    # Build header with imports
    content = '\n'.join([
        '# Code generated. DO NOT EDIT.',
        f'# LSP v{specification_version}\n',
        'from __future__ import annotations',
        'from enum import IntEnum, IntFlag, StrEnum',
        'from typing import Any, Dict, List, Literal, TypedDict, Union',
        'from typing_extensions import NotRequired, TypeAlias\n',
        'URI = str',
        'DocumentUri = str',
        'Uint = int',
    ])

    # Generate all types
    content += '\n\n' + '\n\n'.join(generate_enumerations(lsp_json['enumerations'], ENUM_OVERRIDES))
    content += '\n' + '\n'.join(generate_type_aliases(lsp_json['typeAliases'], ALIAS_OVERRIDES))
    content += '\n\n' + '\n\n'.join(generate_structures(lsp_json['structures']))
    content += '\n' + '\n'.join(get_new_literal_structures())

    Path(output).write_text(content, encoding='utf-8')

generate_protocol(output='./generated/lsp_types.py')
# Output: Creates generated/lsp_types.py with ~5000 lines of type definitions

```

--------------------------------

### Format LSP Types to Python Annotations

Source: https://context7.com/sublimelsp/lsp-python-types/llms.txt

This code provides utility functions to convert LSP schema type definitions into Python type annotations. It handles base types, references, arrays, maps, unions, and literal types. The `format_type` function recursively processes type definitions, and `format_base_types` maps LSP base type names to their Python equivalents. The code uses TypedDict and Enum for type safety and clarity.

```python
from enum import Enum
from typing import TypedDict, Any

class StructureKind(Enum):
    Class = 1
    Function = 2

class FormatTypeContext(TypedDict):
    root_symbol_name: str

def format_type(typ: dict, context: FormatTypeContext, preferred_structure_kind: StructureKind) -> str:
    """Convert LSP type definition to Python type annotation string."""
    if typ['kind'] == 'base':
        return format_base_types(typ)
    if typ['kind'] == 'reference':
        return f"'{typ['name']}'"
    if typ['kind'] == 'array':
        element = format_type(typ['element'], context, preferred_structure_kind)
        return f'List[{element}]'
    if typ['kind'] == 'map':
        key = format_base_types(typ['key'])
        value = format_type(typ['value'], {'root_symbol_name': key}, preferred_structure_kind)
        return f'Dict[{key}, {value}]'
    if typ['kind'] == 'or':
        union = [format_type(item, context, preferred_structure_kind) for item in typ['items']]
        return f'Union[{", ".join(union)}]'
    if typ['kind'] == 'stringLiteral':
        return f"Literal['{typ['value']}']"
    if typ['kind'] in ('integerLiteral', 'booleanLiteral'):
        return f"Literal[{typ['value']}]"
    return 'Any'

def format_base_types(base_type: dict) -> str:
    """Map LSP base type names to Python types."""
    mapping = {
        'integer': 'int',
        'uinteger': 'Uint',
        'decimal': 'float',
        'string': 'str',
        'boolean': 'bool',
        'null': 'None',
    }
    return mapping.get(base_type['name'], base_type['name'])
```

--------------------------------

### Use Generated Types in LSP Server (Python)

Source: https://context7.com/sublimelsp/lsp-python-types/llms.txt

This code snippet demonstrates how to use the generated type definitions in a type-safe LSP server implementation. It imports various types from the generated module, including request and response types, and uses them to build the server's functionality. This approach ensures type safety and improves code readability and maintainability.

```python
from generated.lsp_types import (
    InitializeParams, InitializeResult, ServerCapabilities,
    TextDocumentSyncKind, CompletionOptions, Position, Range,
    Diagnostic, DiagnosticSeverity, Location, DocumentUri,
    CompletionItem, CompletionItemKind, TextEdit
)
from generated.custom import (
    InitializeRequest, CompletionRequest, DefinitionRequest,
    ClientRequest, ServerResponse
)
```

--------------------------------

### Generate LSP Notification Types in Python

Source: https://context7.com/sublimelsp/lsp-python-types/llms.txt

This code defines functions to generate Python TypedDict classes for LSP notification messages. It processes a list of notification definitions, categorizes them by message direction (clientToServer, serverToClient, or both), and creates corresponding type aliases for client and server notifications. The generated types include method and params fields, reflecting the structure of LSP notifications.

```python
from utils.helpers import format_type, indentation, StructureKind

def generate_notifications(notifications: list) -> list[str]:
    client_notification_names, server_notification_names = [], []
    definitions = []

    for notification in notifications:
        direction = notification['messageDirection']
        name, definition = generate_notification(notification)

        if direction == 'clientToServer':
            client_notification_names.append(name)
        elif direction == 'serverToClient':
            server_notification_names.append(name)
        else:  # 'both'
            client_notification_names.append(name)
            server_notification_names.append(name)
        definitions.append(definition)

    return [
        *definitions,
        f'ClientNotification: TypeAlias = Union[{", ".join(client_notification_names)}]',
        f'ServerNotification: TypeAlias = Union[{", ".join(server_notification_names)}]',
    ]

def generate_notification(notification) -> tuple[str, str]:
    method = notification['method']
    params = notification.get('params')
    name = notification['typeName']

    definition = f'class {name}(TypedDict):\n'
    definition += f"{indentation}method: Literal['{method}']\n"
    if params:
        definition += f'{indentation}params: {format_type(params, {{"root_symbol_name": ""}}, StructureKind.Class)}'
    else:
        definition += f'{indentation}params: None'
    return (name, definition)
```

--------------------------------

### Generate LSP Structures to Python TypedDict

Source: https://context7.com/sublimelsp/lsp-python-types/llms.txt

Converts LSP structure definitions into Python TypedDict classes. It handles inherited properties from mixins and extended types, and formats class properties with their respective documentation. Dependencies include helper functions for formatting and property retrieval.

```python
from utils.helpers import (
    format_class_properties, format_dict_properties, format_comment,
    get_formatted_properties, has_invalid_property_name, StructureKind, indentation
)

def generate_structures(structures: list) -> list[str]:
    def to_string(structure) -> str:
        kind = StructureKind.Function if has_invalid_property_name(structure['properties']) else StructureKind.Class
        return generate_structure(structure, structures, kind)
    return [to_string(s) for s in structures if not s['name'].startswith('_')]

def get_additional_properties(for_structure, structures, structure_kind):
    """Return properties from extended and mixin types."""
    result = []
    additional_structures = for_structure.get('extends', []) + for_structure.get('mixins', [])
    for additional_structure in additional_structures:
        if additional_structure['kind'] == 'reference':
            structure = next(s for s in structures if s['name'] == additional_structure['name'])
            if structure:
                properties = get_formatted_properties(structure['properties'], structure['name'], structure_kind)
                result.extend(properties)
    return result

def generate_structure(structure, structures, structure_kind) -> str:
    symbol_name = structure['name']
    properties = get_formatted_properties(structure['properties'], symbol_name, structure_kind)
    additional_properties = get_additional_properties(structure, structures, structure_kind)

    # Merge extended properties
    taken_names = [p['name'] for p in properties]
    for prop in additional_properties:
        if prop['name'] not in taken_names:
            properties.append(prop)

    if structure_kind == StructureKind.Class:
        documentation = format_comment(structure.get('documentation'), indentation)
        result = f'class {symbol_name}(TypedDict):\n'
        if documentation:
            result += f'{documentation}\n\n'
        result += f'{indentation}{format_class_properties(properties) or "pass"}'
    return result

# Example output:
# class Position(TypedDict):
#     """Position in a text document expressed as zero-based line and character offset."""
#     line: Uint
#     """Line position in a document (zero-based)."""
#     character: Uint
#     """Character offset on a line in a document (zero-based)."""

```

--------------------------------

### Generate LSP Enumerations to Python Enums

Source: https://context7.com/sublimelsp/lsp-python-types/llms.txt

Converts LSP enumeration definitions into Python Enum, IntEnum, StrEnum, or IntFlag classes. It handles different enumeration kinds (string or number) and applies documentation from the definitions. Dependencies include helper functions for formatting and capitalization.

```python
from enum import Enum
from typing import Literal
from utils.helpers import capitalize, format_comment, indentation

class EnumKind(Enum):
    Number = 1
    String = 2

def format_enumeration_values(values: list, kind: EnumKind) -> str:
    result = []
    for v in values:
        key = capitalize(v['name'])
        value = f"'{v['value']}'" if kind == EnumKind.String else v['value']
        documentation = format_comment(v.get('documentation'), indentation)
        result.append(f'{key} = {value}{documentation if documentation else ""}')
    return f'\n{indentation}'.join(result)

def generate_enumerations(enumerations: list, overrides: dict) -> list[str]:
    def to_string(enumeration) -> str:
        symbol_name = enumeration['name']
        documentation = format_comment(enumeration.get('documentation'), indentation)
        kind = EnumKind.String if enumeration['type']['name'] == 'string' else EnumKind.Number
        enum_class = overrides.get(symbol_name) or ('Enum' if kind == EnumKind.String else 'IntEnum')
        values = format_enumeration_values(enumeration['values'], kind)

        result = f'class {symbol_name}({enum_class}):\n'
        if documentation:
            result += f'{documentation}\n\n'
        result += f'{indentation}' + values
        return result

    return [to_string(e) for e in enumerations]

# Example output:
# class SymbolKind(IntEnum):
#     """A symbol kind."""
#     File = 1
#     Module = 2
#     Namespace = 3
#     Class = 5
#     Method = 6
#     Property = 7
#     Function = 12
#     Variable = 13

```
Tokens:
Raw