Servers¶

class pygls.lsp.server.LanguageServer(name, version, text_document_sync_kind=TextDocumentSyncKind.Incremental, notebook_document_sync=None, *args, **kwargs)¶

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 ServerInfo which is sent to the client during initialization
version (str) – Version of the server, used to populate ServerInfo which is sent to the client during initialization
protocol_cls – The LanguageServerProtocol class definition, or any subclass of it.
max_workers – Maximum number of workers for ThreadPool and ThreadPoolExecutor
text_document_sync_kind (types.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 (types.NotebookDocumentSyncOptions | None) – Advertise NotebookDocument support to the client.

cancel_request(params)¶

Send a $/cancelRequest notification.

Parameters:: params (CancelParams)
Return type:: None

client_register_capability(params, callback=None)¶

Make a client/registerCapability request.

The client/registerCapability request is sent from the server to the client to register a new capability handler on the client side.

Parameters:

params (types.RegistrationParams)
callback (Optional[Callable[[None], None]])

Return type:

Future[None]

async client_register_capability_async(params)¶

Make a client/registerCapability request.

The client/registerCapability request is sent from the server to the client to register a new capability handler on the client side.

Parameters:: params (RegistrationParams)
Return type:: None

client_unregister_capability(params, callback=None)¶

Make a client/unregisterCapability request.

The client/unregisterCapability request is sent from the server to the client to unregister a previously registered capability handler on the client side.

Parameters:

params (types.UnregistrationParams)
callback (Optional[Callable[[None], None]])

Return type:

Future[None]

async client_unregister_capability_async(params)¶

Make a client/unregisterCapability request.

The client/unregisterCapability request is sent from the server to the client to unregister a previously registered capability handler on the client side.

Parameters:: params (UnregistrationParams)
Return type:: None

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 (Any | None)

Return type:

Callable[[F], F]

log_trace(params)¶

Send a $/logTrace notification.

Parameters:: params (LogTraceParams)
Return type:: None

progress(params)¶

Send a $/progress notification.

Parameters:: params (ProgressParams)
Return type:: None

report_server_error(error, source)¶

Sends error to the client for displaying.

By default this function 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 (ServerErrors)

shutdown()¶: Shutdown server.

start_io(stdin=None, stdout=None)¶

Starts an IO server.

Parameters:

stdin (Optional[BinaryIO])
stdout (Optional[BinaryIO])

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

telemetry_event(params)¶

Send a telemetry/event notification.

The telemetry event notification is sent from the server to the client to ask the client to log telemetry data.

Parameters:: params (Any | None)
Return type:: None

text_document_publish_diagnostics(params)¶

Send a textDocument/publishDiagnostics notification.

Diagnostics notification are sent from the server to the client to signal results of validation runs.

Parameters:: params (PublishDiagnosticsParams)
Return type:: None

thread()¶

Decorator that mark function to execute it in a thread.

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

window_log_message(params)¶

Send a window/logMessage notification.

The log message notification is sent from the server to the client to ask the client to log a particular message.

Parameters:: params (LogMessageParams)
Return type:: None

window_show_document(params, callback=None)¶

Make a window/showDocument request.

A request to show a document. This request might open an external program depending on the value of the URI to open. For example a request to open https://code.visualstudio.com/ will very likely open the URI in a WEB browser.

LSP v3.16.0

Parameters:

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

Return type:

Future[types.ShowDocumentResult]

async window_show_document_async(params)¶

Make a window/showDocument request.

LSP v3.16.0

Parameters:: params (ShowDocumentParams)
Return type:: ShowDocumentResult

window_show_message(params)¶

Send a window/showMessage notification.

The show message notification is sent from a server to a client to ask the client to display a particular message in the user interface.

Parameters:: params (ShowMessageParams)
Return type:: None

window_show_message_request(params, callback=None)¶

Make a window/showMessageRequest request.

The show message request is sent from the server to the client to show a message and a set of options actions to the user.

Parameters:

params (types.ShowMessageRequestParams)
callback (Optional[Callable[[Optional[types.MessageActionItem]], None]])

Return type:

Future[Optional[types.MessageActionItem]]

async window_show_message_request_async(params)¶

Make a window/showMessageRequest request.

The show message request is sent from the server to the client to show a message and a set of options actions to the user.

Parameters:: params (types.ShowMessageRequestParams)
Return type:: Optional[types.MessageActionItem]

window_work_done_progress_create(params, callback=None)¶

Make a window/workDoneProgress/create request.

The window/workDoneProgress/create request is sent from the server to the client to initiate progress reporting from the server.

Parameters:

params (types.WorkDoneProgressCreateParams)
callback (Optional[Callable[[None], None]])

Return type:

Future[None]

async window_work_done_progress_create_async(params)¶

Make a window/workDoneProgress/create request.

The window/workDoneProgress/create request is sent from the server to the client to initiate progress reporting from the server.

Parameters:: params (WorkDoneProgressCreateParams)
Return type:: None

workspace_apply_edit(params, callback=None)¶

Make a workspace/applyEdit request.

A request sent from the server to the client to modified certain resources.

Parameters:

params (types.ApplyWorkspaceEditParams)
callback (Optional[Callable[[types.ApplyWorkspaceEditResult], None]])

Return type:

Future[types.ApplyWorkspaceEditResult]

async workspace_apply_edit_async(params)¶

Make a workspace/applyEdit request.

A request sent from the server to the client to modified certain resources.

Parameters:: params (ApplyWorkspaceEditParams)
Return type:: ApplyWorkspaceEditResult

workspace_code_lens_refresh(params, callback=None)¶

Make a workspace/codeLens/refresh request.

A request to refresh all code actions

LSP v3.16.0

Parameters:

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

Return type:

Future[None]

async workspace_code_lens_refresh_async(params)¶

Make a workspace/codeLens/refresh request.

A request to refresh all code actions

LSP v3.16.0

Parameters:: params (None)
Return type:: None

workspace_configuration(params, callback=None)¶

Make a workspace/configuration request.

The ‘workspace/configuration’ request is sent from the server to the client to fetch a certain configuration setting.

This pull model replaces the old push model were the client signaled configuration change via an event. If the server still needs to react to configuration changes (since the server caches the result of workspace/configuration requests) the server should register for an empty configuration change event and empty the cache if such an event is received.

Parameters:

params (types.ConfigurationParams)
callback (Optional[Callable[[Sequence[Optional[Any]]], None]])

Return type:

Future[Sequence[Optional[Any]]]

async workspace_configuration_async(params)¶

Make a workspace/configuration request.

The ‘workspace/configuration’ request is sent from the server to the client to fetch a certain configuration setting.

Parameters:: params (types.ConfigurationParams)
Return type:: Sequence[Optional[Any]]

workspace_diagnostic_refresh(params, callback=None)¶

Make a workspace/diagnostic/refresh request.

The diagnostic refresh request definition.

LSP v3.17.0

Parameters:

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

Return type:

Future[None]

async workspace_diagnostic_refresh_async(params)¶

Make a workspace/diagnostic/refresh request.

The diagnostic refresh request definition.

LSP v3.17.0

Parameters:: params (None)
Return type:: None

workspace_folding_range_refresh(params, callback=None)¶

Make a workspace/foldingRange/refresh request.

LSP v3.18.0 @proposed

Parameters:

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

Return type:

Future[None]

async workspace_folding_range_refresh_async(params)¶

Make a workspace/foldingRange/refresh request.

LSP v3.18.0 @proposed

Parameters:: params (None)
Return type:: None

workspace_inlay_hint_refresh(params, callback=None)¶

Make a workspace/inlayHint/refresh request.

LSP v3.17.0

Parameters:

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

Return type:

Future[None]

async workspace_inlay_hint_refresh_async(params)¶

Make a workspace/inlayHint/refresh request.

LSP v3.17.0

Parameters:: params (None)
Return type:: None

workspace_inline_value_refresh(params, callback=None)¶

Make a workspace/inlineValue/refresh request.

LSP v3.17.0

Parameters:

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

Return type:

Future[None]

async workspace_inline_value_refresh_async(params)¶

Make a workspace/inlineValue/refresh request.

LSP v3.17.0

Parameters:: params (None)
Return type:: None

workspace_semantic_tokens_refresh(params, callback=None)¶

Make a workspace/semanticTokens/refresh request.

LSP v3.16.0

Parameters:

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

Return type:

Future[None]

async workspace_semantic_tokens_refresh_async(params)¶

Make a workspace/semanticTokens/refresh request.

LSP v3.16.0

Parameters:: params (None)
Return type:: None

workspace_text_document_content_refresh(params, callback=None)¶

Make a workspace/textDocumentContent/refresh request.

The workspace/textDocumentContent request is sent from the server to the client to refresh the content of a specific text document.

LSP v3.18.0 @proposed

Parameters:

params (types.TextDocumentContentRefreshParams)
callback (Optional[Callable[[None], None]])

Return type:

Future[None]

async workspace_text_document_content_refresh_async(params)¶

Make a workspace/textDocumentContent/refresh request.

The workspace/textDocumentContent request is sent from the server to the client to refresh the content of a specific text document.

LSP v3.18.0 @proposed

Parameters:: params (TextDocumentContentRefreshParams)
Return type:: None

workspace_workspace_folders(params, callback=None)¶

Make a workspace/workspaceFolders request.

The workspace/workspaceFolders is sent from the server to the client to fetch the open workspace folders.

Parameters:

params (None)
callback (Optional[Callable[[Optional[Sequence[types.WorkspaceFolder]]], None]])

Return type:

Future[Optional[Sequence[types.WorkspaceFolder]]]

async workspace_workspace_folders_async(params)¶

Make a workspace/workspaceFolders request.

The workspace/workspaceFolders is sent from the server to the client to fetch the open workspace folders.

Parameters:: params (None)
Return type:: Optional[Sequence[types.WorkspaceFolder]]

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

property server_capabilities: ServerCapabilities¶: The server’s capabilities.

property thread_pool: ThreadPoolExecutor¶: Returns thread pool instance (lazy initialization).

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

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

pygls.cli.start_server(server, args=None)¶

A helper function that implements a simple cli wrapper for a pygls server allowing the user to select between the supported transports.

Parameters:

server (JsonRPCServer)
args (list[str] | None)

class pygls.progress.Progress(lsp)¶

A class for working with client’s progress bar.

Parameters:: lsp (LanguageServerProtocol)

_lsp¶

Language server protocol instance

Type:: LanguageServerProtocol

tokens¶

Holds futures for work done progress tokens that are already registered. These futures will be cancelled if the client sends a cancel work done process notification.

Type:: dict

begin(token, value)¶

Notify beginning of work.

Parameters:

token (int | str)
value (WorkDoneProgressBegin)

Return type:

None

create(token, callback=None)¶

Create a server initiated work done progress.

Parameters:: token (int | str)
Return type:: Future

async create_async(token)¶

Create a server initiated work done progress.

Parameters:: token (int | str)
Return type:: Future

end(token, value)¶

Notify end of work.

Parameters:

token (int | str)
value (WorkDoneProgressEnd)

Return type:

None

report(token, value)¶

Notify progress of work.

Parameters:

token (int | str)
value (WorkDoneProgressReport)

Return type:

None

class pygls.server.JsonRPCServer(protocol_cls, converter_factory, max_workers=None)¶

Base server class

Parameters:

protocol_cls (Type[JsonRPCProtocol]) – Protocol implementation that should derive from JsonRPCProtocol
converter_factory (Callable[[], cattrs.Converter]) – Factory function to use when constructing a cattrs converter.
max_workers (int | None) – Maximum number of workers for ThreadPoolExecutor

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 (Any | None)

Return type:

Callable[[F], F]

report_server_error(error, source)¶

Default error reporter.

Parameters:

error (Exception)
source (ServerErrors)

shutdown()¶: Shutdown server.

start_io(stdin=None, stdout=None)¶

Starts an IO server.

Parameters:

stdin (Optional[BinaryIO])
stdout (Optional[BinaryIO])

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

thread()¶

Decorator that mark function to execute it in a thread.

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

property thread_pool: ThreadPoolExecutor¶: Returns thread pool instance (lazy initialization).