Servers

class pygls.server.LanguageServer(name, version, loop=None, protocol_cls=<class 'pygls.protocol.language_server.LanguageServerProtocol'>, converter_factory=<function default_converter>, text_document_sync_kind=TextDocumentSyncKind.Incremental, notebook_document_sync=None, max_workers=2)

The default LanguageServer

This class can be extended and it can be passed as a first argument to registered commands/features.

Parameters:

name (str) – Name of the server, used to populate InitializeResultServerInfoType which is sent to the client during initialization
version (str) – Version of the server, used to populate InitializeResultServerInfoType which is sent to the client during initialization
protocol_cls (Type[LanguageServerProtocol]) – The LanguageServerProtocol class definition, or any subclass of it.
max_workers (int) – Maximum number of workers for ThreadPool and ThreadPoolExecutor
text_document_sync_kind (TextDocumentSyncKind) –
Text document synchronization method

None
No synchronization

Full
Send entire document text with each update

Incremental
Send only the region of text that changed with each update
notebook_document_sync (Optional[NotebookDocumentSyncOptions]) – Advertise NotebookDocument support to the client.

apply_edit(edit, label=None)

Sends apply edit request to the client.

Parameters:

edit (WorkspaceEdit) –
label (Optional[str]) –

Return type:

WorkspaceApplyEditResponse

apply_edit_async(edit, label=None)

Sends apply edit request to the client. Should be called with await

Parameters:

edit (WorkspaceEdit) –
label (Optional[str]) –

Return type:

WorkspaceApplyEditResponse

command(command_name)

Decorator used to register custom commands.

Example

@ls.command('myCustomCommand')
def my_cmd(ls, a, b, c):
    pass

Parameters:: command_name (str) –
Return type:: Callable[[F], F]

feature(feature_name, options=None)

Decorator used to register LSP features.

Example

@ls.feature('textDocument/completion', CompletionOptions(trigger_characters=['.']))
def completions(ls, params: CompletionParams):
    return CompletionList(is_incomplete=False, items=[CompletionItem("Completion 1")])

Parameters:

feature_name (str) –
options (Optional[Any]) –

Return type:

Callable[[F], F]

get_configuration(params, callback=None)

Gets the configuration settings from the client.

Parameters:

params (ConfigurationParams) –
callback (Optional[Callable[[List[Any]], None]]) –

Return type:

Future

get_configuration_async(params)

Gets the configuration settings from the client. Should be called with await

Parameters:: params (ConfigurationParams) –
Return type:: Future

log_trace(message, verbose=None)

Sends trace notification to the client.

Parameters:

message (str) –
verbose (Optional[str]) –

Return type:

None

publish_diagnostics(uri, diagnostics=None, version=None, **kwargs)

Sends diagnostic notification to the client.

Parameters:

uri (str) –
diagnostics (Optional[List[Diagnostic]]) –
version (Optional[int]) –

register_capability(params, callback=None)

Register a new capability on the client.

Parameters:

params (RegistrationParams) –
callback (Optional[Callable[[], None]]) –

Return type:

Future

register_capability_async(params)

Register a new capability on the client. Should be called with await

Parameters:: params (RegistrationParams) –
Return type:: Future

report_server_error(error, source)

Sends error to the client for displaying.

By default this fucntion does not handle LSP request errors. This is because LSP requests require direct responses and so already have a mechanism for including unexpected errors in the response body.

All other errors are “out of band” in the sense that the client isn’t explicitly waiting for them. For example diagnostics are returned as notifications, not responses to requests, and so can seemingly be sent at random. Also for example consider JSON RPC serialization and deserialization, if a payload cannot be parsed then the whole request/response cycle cannot be completed and so one of these “out of band” error messages is sent.

These “out of band” error messages are not a requirement of the LSP spec. Pygls simply offers this behaviour as a recommended default. It is perfectly reasonble to override this default.

Parameters:

error (Exception) –
source (Union[PyglsError, JsonRpcException, Type[JsonRpcInternalError], Type[FeatureNotificationError], Type[FeatureRequestError]]) –

semantic_tokens_refresh(callback=None)

Request a refresh of all semantic tokens.

Parameters:: callback (Optional[Callable[[], None]]) –
Return type:: Future

semantic_tokens_refresh_async()

Request a refresh of all semantic tokens. Should be called with await

Return type:: Future

send_notification(method, params=None)

Sends notification to the client.

Parameters:

method (str) –
params (object) –

Return type:

None

show_document(params, callback=None)

Display a particular document in the user interface.

Parameters:

params (ShowDocumentParams) –
callback (Optional[Callable[[ShowDocumentResult], None]]) –

Return type:

Future

show_document_async(params)

Display a particular document in the user interface. Should be called with await

Parameters:: params (ShowDocumentParams) –
Return type:: Future

show_message(message, msg_type=MessageType.Info)

Sends message to the client to display message.

Return type:: None

show_message_log(message, msg_type=MessageType.Log)

Sends message to the client’s output channel.

Return type:: None

thread()

Decorator that mark function to execute it in a thread.

Return type:: Callable[[F], F]

unregister_capability(params, callback=None)

Unregister a new capability on the client.

Parameters:

params (UnregistrationParams) –
callback (Optional[Callable[[], None]]) –

Return type:

Future

unregister_capability_async(params)

Unregister a new capability on the client. Should be called with await

Parameters:: params (UnregistrationParams) –
Return type:: Future

property client_capabilities: ClientCapabilities: The client’s capabilities.

default_error_message = "Unexpected error in LSP server, see server's logs for details": The default error message sent to the user’s editor when this server encounters an uncaught exception.

property progress: Progress: Gets the object to manage client’s progress bar.

property server_capabilities: ServerCapabilities: Return server capabilities.

property workspace: Workspace: Returns in-memory workspace.

class pygls.server.Server(protocol_cls, converter_factory, loop=None, max_workers=2, sync_kind=TextDocumentSyncKind.Incremental)

Base server class

Parameters:

protocol_cls (Type[JsonRPCProtocol]) – Protocol implementation that must be derive from JsonRPCProtocol
converter_factory (Callable[[], Converter]) – Factory function to use when constructing a cattrs converter.
loop (Optional[AbstractEventLoop]) – The asyncio event loop
max_workers (int) – Maximum number of workers for ThreadPool and ThreadPoolExecutor
sync_kind (TextDocumentSyncKind) –

shutdown(): Shutdown server.

start_io(stdin=None, stdout=None)

Starts IO server.

Parameters:

stdin (Optional[TextIO]) –
stdout (Optional[TextIO]) –

start_tcp(host, port)

Starts TCP server.

Parameters:

host (str) –
port (int) –

Return type:

None

start_ws(host, port)

Starts WebSocket server.

Parameters:

host (str) –
port (int) –

Return type:

None

property thread_pool: ThreadPool: Returns thread pool instance (lazy initialization).

property thread_pool_executor: ThreadPoolExecutor: Returns thread pool instance (lazy initialization).