Server Extensions#

A Jupyter Server extension is typically a module or package that extends to Server’s REST API/endpoints—i.e. adds extra request handlers to Server’s Tornado Web Application.

For examples of jupyter server extensions, see the homepage.

To get started writing your own extension, see the simple examples in the examples folder in the GitHub jupyter_server repository.

Authoring a basic server extension#

The simplest way to write a Jupyter Server extension is to write an extension module with a _load_jupyter_server_extension function. This function should take a single argument, an instance of the ServerApp.

def _load_jupyter_server_extension(serverapp: jupyter_server.serverapp.ServerApp):
    """
    This function is called when the extension is loaded.
    """
    pass

Adding extension endpoints#

The easiest way to add endpoints and handle incoming requests is to subclass the JupyterHandler (which itself is a subclass of Tornado’s RequestHandler).

from jupyter_server.base.handlers import JupyterHandler
import tornado


class MyExtensionHandler(JupyterHandler):
    @tornado.web.authenticated
    def get(self):
        ...

    @tornado.web.authenticated
    def post(self):
        ...

Note

It is best practice to wrap each handler method with the authenticated decorator to ensure that each request is authenticated by the server.

Then add this handler to Jupyter Server’s Web Application through the _load_jupyter_server_extension function.

def _load_jupyter_server_extension(serverapp: jupyter_server.serverapp.ServerApp):
    """
    This function is called when the extension is loaded.
    """
    handlers = [("/myextension/hello", MyExtensionHandler)]
    serverapp.web_app.add_handlers(".*$", handlers)

Starting asynchronous tasks from an extension#

Added in version 2.15.0.

Jupyter Server offers a simple API for starting asynchronous tasks from a server extension. This is useful for calling async tasks after the event loop is running.

The function should be named _start_jupyter_server_extension and found next to the _load_jupyter_server_extension function.

Here is basic example:

import asyncio

async def _start_jupyter_server_extension(serverapp: jupyter_server.serverapp.ServerApp):
    """
    This function is called after the server's event loop is running.
    """
    await asyncio.sleep(.1)

Note

The server startup banner (displaying server info and access URLs) is printed before starting asynchronous tasks, so those tasks might still be running even after the banner appears.

Making an extension discoverable#

To make this extension discoverable to Jupyter Server, first define a _jupyter_server_extension_points() function at the root of the module/ package. This function returns metadata describing how to load the extension. Usually, this requires a module key with the import path to the extension’s _load_jupyter_server_extension function.

def _jupyter_server_extension_points():
    """
    Returns a list of dictionaries with metadata describing
    where to find the `_load_jupyter_server_extension` function.
    """
    return [{"module": "my_extension"}]

Second, add the extension to the ServerApp’s jpserver_extensions trait. This can be manually added by users in their jupyter_server_config.py file,

c.ServerApp.jpserver_extensions = {"my_extension": True}

or loaded from a JSON file in the jupyter_server_config.d directory under one of Jupyter’s paths. (See the Distributing a server extension section for details on how to automatically enabled your extension when users install it.)

{"ServerApp": {"jpserver_extensions": {"my_extension": true}}}

Authoring a configurable extension application#

Some extensions are full-fledged client applications that sit on top of the Jupyter Server. For example, JupyterLab is a server extension. It can be launched from the command line, configured by CLI or config files, and serves+loads static assets behind the server (i.e. html templates, Javascript, etc.)

Jupyter Server offers a convenient base class, ExtensionsApp, that handles most of the boilerplate code for building such extensions.

Anatomy of an `ExtensionApp`#

An ExtensionApp:

has traits.

is configurable (from file or CLI)

has a name (see the name trait).

has an entrypoint, jupyter <name>.

can serve static content from the /static/<name>/ endpoint.

can add new endpoints to the Jupyter Server.

can start asynchronous tasks after the server has started.

The basic structure of an ExtensionApp is shown below:

from jupyter_server.extension.application import ExtensionApp


class MyExtensionApp(ExtensionApp):
    # -------------- Required traits --------------
    name = "myextension"
    default_url = "/myextension"
    load_other_extensions = True
    file_url_prefix = "/render"

    # --- ExtensionApp traits you can configure ---
    static_paths = [...]
    template_paths = [...]
    settings = {...}
    handlers = [...]

    # ----------- add custom traits below ---------
    ...

    def initialize_settings(self):
        ...
        # Update the self.settings trait to pass extra
        # settings to the underlying Tornado Web Application.
        self.settings.update({"<trait>": ...})

    def initialize_handlers(self):
        ...
        # Extend the self.handlers trait
        self.handlers.extend(...)

    def initialize_templates(self):
        ...
        # Change the jinja templating environment

    async def _start_jupyter_server_extension(self):
        ...
        # Extend this method to start any (e.g. async) tasks
        # after the main Server's Event Loop is running.

    async def stop_extension(self):
        ...
        # Perform any required shut down steps

The ExtensionApp uses the following methods and properties to connect your extension to the Jupyter server. You do not need to define a _load_jupyter_server_extension function for these apps. Instead, overwrite the pieces below to add your custom settings, handlers and templates:

Methods

initialize_settings(): adds custom settings to the Tornado Web Application.
initialize_handlers(): appends handlers to the Tornado Web Application.
initialize_templates(): initialize the templating engine (e.g. jinja2) for your frontend.
_start_jupyter_server_extension(): enables the extension to start (async) tasks _after_ the server’s main Event Loop has started.
stop_extension(): called on server shut down.

Properties

name: the name of the extension
default_url: the default URL for this extension—i.e. the landing page for this extension when launched from the CLI.
load_other_extensions: a boolean enabling/disabling other extensions when launching this extension directly.
file_url_prefix: the prefix URL added when opening a document directly from the command line. For example, classic Notebook uses /notebooks to open a document at http://localhost:8888/notebooks/path/to/notebook.ipynb.

`ExtensionApp` request handlers#

ExtensionApp Request Handlers have a few extra properties.

config: the ExtensionApp’s config object.
server_config: the ServerApp’s config object.
name: the name of the extension to which this handler is linked.
static_url(): a method that returns the url to static files (prefixed with /static/<name>).

Jupyter Server provides a convenient mixin class for adding these properties to any JupyterHandler. For example, the basic server extension handler in the section above becomes:

from jupyter_server.base.handlers import JupyterHandler
from jupyter_server.extension.handler import ExtensionHandlerMixin
import tornado


class MyExtensionHandler(ExtensionHandlerMixin, JupyterHandler):
    @tornado.web.authenticated
    def get(self):
        ...

    @tornado.web.authenticated
    def post(self):
        ...

Jinja templating from frontend extensions#

Many Jupyter frontend applications use Jinja for basic HTML templating. Since this is common enough, Jupyter Server provides some extra mixin that integrate Jinja with Jupyter server extensions.

Use ExtensionAppJinjaMixin to automatically add a Jinja templating environment to an ExtensionApp. This adds a <name>_jinja2_env setting to Tornado Web Server’s settings that will be used by request handlers.

from jupyter_server.extension.application import ExtensionApp, ExtensionAppJinjaMixin


class MyExtensionApp(ExtensionAppJinjaMixin, ExtensionApp):
    ...

Pair the example above with ExtensionHandlers that also inherit the ExtensionHandlerJinjaMixin mixin. This will automatically load HTML templates from the Jinja templating environment created by the ExtensionApp.

from jupyter_server.base.handlers import JupyterHandler
from jupyter_server.extension.handler import (
    ExtensionHandlerMixin,
    ExtensionHandlerJinjaMixin,
)
import tornado


class MyExtensionHandler(
    ExtensionHandlerMixin, ExtensionHandlerJinjaMixin, JupyterHandler
):
    @tornado.web.authenticated
    def get(self):
        ...

    @tornado.web.authenticated
    def post(self):
        ...

Note

The mixin classes in this example must come before the base classes, ExtensionApp and ExtensionHandler.

Making an `ExtensionApp` discoverable#

To make an ExtensionApp discoverable by Jupyter Server, add the app key+value pair to the _jupyter_server_extension_points() function example above:

from myextension import MyExtensionApp


def _jupyter_server_extension_points():
    """
    Returns a list of dictionaries with metadata describing
    where to find the `_load_jupyter_server_extension` function.
    """
    return [{"module": "myextension", "app": MyExtensionApp}]

Launching an `ExtensionApp`#

To launch the application, simply call the ExtensionApp’s launch_instance method.

launch_instance = MyFrontend.launch_instance
launch_instance()

To make your extension executable from anywhere on your system, point an entry-point at the launch_instance method in the extension’s setup.py:

from setuptools import setup


setup(
    name="myfrontend",
    # ...
    entry_points={
        "console_scripts": ["jupyter-myextension = myextension:launch_instance"]
    },
)

`ExtensionApp` as a classic Notebook server extension#

An extension that extends ExtensionApp should still work with the old Tornado server from the classic Jupyter Notebook. The ExtensionApp class provides a method, load_classic_server_extension, that handles the extension initialization. Simply define a load_jupyter_server_extension reference pointing at the load_classic_server_extension method:

# This is typically defined in the root `__init__.py`
# file of the extension package.
load_jupyter_server_extension = MyExtensionApp.load_classic_server_extension

If the extension is enabled, the extension will be loaded when the server starts.

Starting asynchronous tasks from an ExtensionApp#

Added in version 2.15.0.

An ExtensionApp can start asynchronous tasks after Jupyter Server’s event loop is started by overriding its _start_jupyter_server_extension() method. This can be helpful for setting up e.g. background tasks.

Here is a basic (pseudo) code example:

import asyncio
import time


async def log_time_periodically(log, dt=1):
    """Log the current time from a periodic loop."""
    while True:
        current_time = time.time()
        log.info(current_time)
        await sleep(dt)


class MyExtension(ExtensionApp):
    ...

    async def _start_jupyter_server_extension(self):
        self.my_background_task = asyncio.create_task(
            log_time_periodically(self.log)
        )

    async def stop_extension(self):
        self.my_background_task.cancel()

Note

The server startup banner (displaying server info and access URLs) is printed before starting asynchronous tasks, so those tasks might still be running even after the banner appears.

Distributing a server extension#

Putting it all together, authors can distribute their extension following this steps:

Add a _jupyter_server_extension_points() function at the extension’s root.
This function should likely live in the __init__.py found at the root of the extension package. It will look something like this:
# Found in the __init__.py of package def _jupyter_server_extension_points(): return [{"module": "myextension.app", "app": MyExtensionApp}]
Create an extension by writing a _load_jupyter_server_extension() function or subclassing ExtensionApp.
This is where the extension logic will live (i.e. custom extension handlers, config, etc). See the sections above for more information on how to create an extension.
Add the following JSON config file to the extension package.
The file should be named after the extension (e.g. myextension.json) and saved in a subdirectory of the package with the prefix: jupyter-config/jupyter_server_config.d/. The extension package will have a similar structure to this example:
myextension ├── myextension/ │ ├── __init__.py │ └── app.py ├── jupyter-config/ │ └── jupyter_server_config.d/ │ └── myextension.json └── setup.py
The contents of the JSON file will tell Jupyter Server to load the extension when a user installs the package:
{ "ServerApp": { "jpserver_extensions": { "myextension": true } } }
When the extension is installed, this JSON file will be copied to the jupyter_server_config.d directory found in one of Jupyter’s paths.

Users can toggle the enabling/disableing of extension using the command:
jupyter server extension disable myextension
which will change the boolean value in the JSON file above.

Create a setup.py that automatically enables the extension.

Add a few extra lines the extension package’s setup function

from setuptools import setup

setup(
    name="myextension",
    # ...
    include_package_data=True,
    data_files=[
        (
            "etc/jupyter/jupyter_server_config.d",
            ["jupyter-config/jupyter_server_config.d/myextension.json"],
        ),
    ],
)

Migrating an extension to use Jupyter Server#

If you’re a developer of a classic Notebook Server extension, your extension should be able to work with both the classic notebook server and jupyter_server.

There are a few key steps to make this happen:

Point Jupyter Server to the load_jupyter_server_extension function with a new reference name.
The load_jupyter_server_extension function was the key to loading a server extension in the classic Notebook Server. Jupyter Server expects the name of this function to be prefixed with an underscore—i.e. _load_jupyter_server_extension. You can easily achieve this by adding a reference to the old function name with the new name in the same module.
def load_jupyter_server_extension(nb_server_app): ... # Reference the old function name with the new function name. _load_jupyter_server_extension = load_jupyter_server_extension

Add new data files to your extension package that enable it with Jupyter Server.

This new file can go next to your classic notebook server data files. Create a new sub-directory, jupyter_server_config.d, and add a new .json file there:

myextension
├── myextension/
│   ├── __init__.py
│   └── app.py
├── jupyter-config/
│   └── jupyter_notebook_config.d/
│       └── myextension.json
│   └── jupyter_server_config.d/
│       └── myextension.json
└── setup.py

The new .json file should look something like this (you’ll notice the changes in the configured class and trait names):

{
    "ServerApp": {
        "jpserver_extensions": {
            "myextension": true
        }
    }
}

Update your extension package’s setup.py so that the data-files are moved into the jupyter configuration directories when users download the package.

from setuptools import setup

setup(
    name="myextension",
    # ...
    include_package_data=True,
    data_files=[
        (
            "etc/jupyter/jupyter_server_config.d",
            ["jupyter-config/jupyter_server_config.d/myextension.json"],
        ),
        (
            "etc/jupyter/jupyter_notebook_config.d",
            ["jupyter-config/jupyter_notebook_config.d/myextension.json"],
        ),
    ],
)

(Optional) Point extension at the new favicon location.

The favicons in the Jupyter Notebook have been moved to a new location in Jupyter Server. If your extension is using one of these icons, you’ll want to add a set of redirect handlers this. (In ExtensionApp, this is handled automatically).

This usually means adding a chunk to your load_jupyter_server_extension function similar to this:

def load_jupyter_server_extension(nb_server_app):
    web_app = nb_server_app.web_app
    host_pattern = ".*$"
    base_url = web_app.settings["base_url"]

    # Add custom extensions handler.
    custom_handlers = [
        # ...
    ]

    # Favicon redirects.
    favicon_redirects = [
        (
            url_path_join(base_url, "/static/favicons/favicon.ico"),
            RedirectHandler,
            {
                "url": url_path_join(
                    serverapp.base_url, "static/base/images/favicon.ico"
                )
            },
        ),
        (
            url_path_join(base_url, "/static/favicons/favicon-busy-1.ico"),
            RedirectHandler,
            {
                "url": url_path_join(
                    serverapp.base_url, "static/base/images/favicon-busy-1.ico"
                )
            },
        ),
        (
            url_path_join(base_url, "/static/favicons/favicon-busy-2.ico"),
            RedirectHandler,
            {
                "url": url_path_join(
                    serverapp.base_url, "static/base/images/favicon-busy-2.ico"
                )
            },
        ),
        (
            url_path_join(base_url, "/static/favicons/favicon-busy-3.ico"),
            RedirectHandler,
            {
                "url": url_path_join(
                    serverapp.base_url, "static/base/images/favicon-busy-3.ico"
                )
            },
        ),
        (
            url_path_join(base_url, "/static/favicons/favicon-file.ico"),
            RedirectHandler,
            {
                "url": url_path_join(
                    serverapp.base_url, "static/base/images/favicon-file.ico"
                )
            },
        ),
        (
            url_path_join(base_url, "/static/favicons/favicon-notebook.ico"),
            RedirectHandler,
            {
                "url": url_path_join(
                    serverapp.base_url, "static/base/images/favicon-notebook.ico"
                )
            },
        ),
        (
            url_path_join(base_url, "/static/favicons/favicon-terminal.ico"),
            RedirectHandler,
            {
                "url": url_path_join(
                    serverapp.base_url, "static/base/images/favicon-terminal.ico"
                )
            },
        ),
        (
            url_path_join(base_url, "/static/logo/logo.png"),
            RedirectHandler,
            {"url": url_path_join(serverapp.base_url, "static/base/images/logo.png")},
        ),
    ]

    web_app.add_handlers(host_pattern, custom_handlers + favicon_redirects)

Server Extensions#

Authoring a basic server extension#

Adding extension endpoints#

Starting asynchronous tasks from an extension#

Making an extension discoverable#

Authoring a configurable extension application#

Anatomy of an ExtensionApp#

ExtensionApp request handlers#

Jinja templating from frontend extensions#

Making an ExtensionApp discoverable#

Launching an ExtensionApp#

ExtensionApp as a classic Notebook server extension#

Starting asynchronous tasks from an ExtensionApp#

Distributing a server extension#

Migrating an extension to use Jupyter Server#

This Page

Anatomy of an `ExtensionApp`#

`ExtensionApp` request handlers#

Making an `ExtensionApp` discoverable#

Launching an `ExtensionApp`#

`ExtensionApp` as a classic Notebook server extension#