How To Add Notebook Support to a Language Server

Help Wanted!

This guide is incomplete and needs to be expanded upon to provide more details to cover topics including:

  • The fallback sync mechanism for notebook documents vs “proper” document synchronization

  • Accessing other details of a notebook document, such as metadata and execution results

  • Reconstructing the JSON representation of a notebook document - see thie issue comment

If this is something you would like to help with, please open an issue or pull request (even if it is a draft!) on our GitHub, so that we don’t accicdentally duplicate your work.

See also

notebookDocument/synchronization

The section of the LSP specification describing how notebook documents are handled

This guide explains how to add support for notebook documents to your language server.

  • A notebook’s structure, metadata etc. is represented using the NotebookDocument class from lsprotocol.

  • The contents of a single notebook cell is represented using a standard TextDocument

In order to receive notebook documents from the client, your language server must provide an instance of NotebookDocumentSyncOptions which declares the kind of notebooks it is interested in

server = LanguageServer(
    name="example-server",
    version="v0.1",
    notebook_document_sync=types.NotebookDocumentSyncOptions(
        notebook_selector=[
            types.NotebookDocumentFilterWithCells(
                cells=[
                    types.NotebookCellLanguage(
                        language="python"
                    ),
                ],
            ),
        ],
    ),
)

To access the contents of a notebook cell you would call the workspace’s get_text_document() method as normal.

cell_doc = ls.workspace.get_text_document(cell_uri)

To access the notebook itself call the workspace’s get_notebook_document() method with either the uri of the notebook or the uri of any of its cells.

notebook_doc = ls.workspace.get_notebook_document(notebook_uri=notebook_uri)

# -- OR --

notebook_doc = ls.workspace.get_notebook_document(cell_uri=cell_uri)