jupyter_server.extension package

Submodules

An extension application.

class jupyter_server.extension.application.ExtensionApp(**kwargs)

Bases: JupyterApp

Base class for configurable Jupyter Server Extension Applications.

ExtensionApp subclasses can be initialized two ways:

  • Extension is listed as a jpserver_extension, and ServerApp calls its load_jupyter_server_extension classmethod. This is the classic way of loading a server extension.

  • Extension is launched directly by calling its launch_instance class method. This method can be set as a entry_point in the extensions setup.py.

classes: ClassesType = [<class 'jupyter_server.serverapp.ServerApp'>]
property config_file_paths

Look on the same path as our parent for config files

current_activity()

Return a list of activity happening in this extension.

default_url

A trait for unicode strings.

extension_url = '/'
file_url_prefix

A trait for unicode strings.

classmethod get_extension_package()

Get an extension package.

classmethod get_extension_point()

Get an extension point.

handlers: List[tuple[t.Any, ...]]

Handlers appended to the server.

initialize()

Initialize the extension app. The corresponding server app and webapp should already be initialized by this step.

  • Appends Handlers to the ServerApp,

  • Passes config and settings from ExtensionApp to the Tornado web application

  • Points Tornado Webapp to templates and static assets.

initialize_handlers()

Override this method to append handlers to a Jupyter Server.

classmethod initialize_server(argv=None, load_other_extensions=True, **kwargs)

Creates an instance of ServerApp and explicitly sets this extension to enabled=True (i.e. superseding disabling found in other config from files).

The launch_instance method uses this method to initialize and start a server.

initialize_settings()

Override this method to add handling of settings.

initialize_templates()

Override this method to add handling of template files.

classmethod launch_instance(argv=None, **kwargs)

Launch the extension like an application. Initializes+configs a stock server and appends the extension to the server. Then starts the server and routes to extension’s landing page.

classmethod load_classic_server_extension(serverapp)

Enables extension to be loaded as classic Notebook (jupyter/notebook) extension.

load_other_extensions = True
classmethod make_serverapp(**kwargs)

Instantiate the ServerApp

Override to customize the ServerApp before it loads any configuration

Return type:

ServerApp

name: str | Unicode[str, str] = 'ExtensionApp'
open_browser

Whether to open in a browser after starting. The specific browser used is platform dependent and determined by the python standard library webbrowser module, unless it is overridden using the –browser (ServerApp.browser) configuration option.

serverapp: ServerApp | None

A trait which allows any value.

serverapp_class

alias of ServerApp

serverapp_config: dict[str, t.Any] = {}
settings

Settings that will passed to the server.

start()

Start the underlying Jupyter server.

Server should be started after extension is initialized.

static_paths

paths to search for serving static files.

This allows adding javascript/css to be available from the notebook server machine, or overriding individual files in the IPython

static_url_prefix

Url where the static assets for the extension are served.

stop()

Stop the underlying Jupyter server.

async stop_extension()

Cleanup any resources managed by this extension.

template_paths

Paths to search for serving jinja templates.

Can be used to override templates from notebook.templates.

class jupyter_server.extension.application.ExtensionAppJinjaMixin(*args, **kwargs)

Bases: HasTraits

Use Jinja templates for HTML templates on top of an ExtensionApp.

jinja2_options

Options to pass to the jinja2 environment for this

exception jupyter_server.extension.application.JupyterServerExtensionException

Bases: Exception

Exception class for raising for Server extensions errors.

Extension config.

class jupyter_server.extension.config.ExtensionConfigManager(**kwargs)

Bases: ConfigManager

A manager class to interface with Jupyter Server Extension config found in a config.d folder. It is assumed that all configuration files in this directory are JSON files.

disable(name)

Disable an extension by name.

enable(name)

Enable an extension by name.

enabled(name, section_name='jupyter_server_config', include_root=True)

Is the extension enabled?

get_jpserver_extensions(section_name='jupyter_server_config')

Return the jpserver_extensions field from all config files found.

An extension handler.

class jupyter_server.extension.handler.ExtensionHandlerJinjaMixin

Bases: object

Mixin class for ExtensionApp handlers that use jinja templating for template rendering.

get_template(name)

Return the jinja template object for a given name

Return type:

str

class jupyter_server.extension.handler.ExtensionHandlerMixin

Bases: object

Base class for Jupyter server extension handlers.

Subclasses can serve static files behind a namespaced endpoint: “<base_url>/static/<name>/”

This allows multiple extensions to serve static files under their own namespace and avoid intercepting requests for other extensions.

property base_url: str
property config: Config
property extensionapp: ExtensionApp
initialize(name, *args, **kwargs)
Return type:

None

property log: Logger
property server_config: Config
property serverapp: ServerApp
settings: dict[str, Any]
property static_path: str
static_url(path, include_host=None, **kwargs)

Returns a static URL for the given relative static file path. This method requires you set the {name}_static_path setting in your extension (which specifies the root directory of your static files). This method returns a versioned url (by default appending ?v=<signature>), which allows the static files to be cached indefinitely. This can be disabled by passing include_version=False (in the default implementation; other static file implementations are not required to support this, but they may support other options). By default this method returns URLs relative to the current host, but if include_host is true the URL returned will be absolute. If this handler has an include_host attribute, that value will be used as the default for all static_url calls that do not pass include_host as a keyword argument.

Return type:

str

property static_url_prefix: str

The extension manager.

class jupyter_server.extension.manager.ExtensionManager(**kwargs)

Bases: LoggingConfigurable

High level interface for findind, validating, linking, loading, and managing Jupyter Server extensions.

Usage: m = ExtensionManager(config_manager=…)

add_extension(extension_name, enabled=False)

Try to add extension to manager, return True if successful. Otherwise, return False.

any_activity()

Check for any activity currently happening across all extension applications.

config_manager

A trait whose value must be an instance of a specified class.

The value can also be an instance of a subclass of the specified class.

Subclasses can declare default classes by overriding the klass attribute

property extension_apps

Return mapping of extension names and sets of ExtensionApp objects.

property extension_points

Return mapping of extension point names and ExtensionPoint objects.

extensions

Dictionary with extension package names as keys and ExtensionPackage objects as values.

from_config_manager(config_manager)

Add extensions found by an ExtensionConfigManager

from_jpserver_extensions(jpserver_extensions)

Add extensions from ‘jpserver_extensions’-like dictionary.

Link all enabled extensions to an instance of ServerApp

Link an extension by name.

linked_extensions

Dictionary with extension names as keys

values are True if the extension is linked, False if not.

load_all_extensions()

Load all enabled extensions and append them to the parent ServerApp.

load_extension(name)

Load an extension by name.

serverapp

A trait which allows any value.

property sorted_extensions

Returns an extensions dictionary, sorted alphabetically.

async stop_all_extensions()

Call the shutdown hooks in all extensions.

async stop_extension(name, apps)

Call the shutdown hooks in the specified apps.

class jupyter_server.extension.manager.ExtensionPackage(**kwargs: Any)

Bases: LoggingConfigurable

An API for interfacing with a Jupyter Server extension package.

Usage:

ext_name = “my_extensions” extpkg = ExtensionPackage(name=ext_name)

enabled

Whether the extension package is enabled.

extension_points

An instance of a Python dict.

One or more traits can be passed to the constructor to validate the keys and/or values of the dict. If you need more detailed validation, you may use a custom validator method.

Changed in version 5.0: Added key_trait for validating dict keys.

Changed in version 5.0: Deprecated ambiguous trait, traits args in favor of value_trait, per_key_traits.

Link all extension points.

Link an extension point.

load_all_points(serverapp)

Load all extension points.

load_point(point_name, serverapp)

Load an extension point.

metadata

Extension metadata loaded from the extension package.

module

The module for this extension package. None if not enabled

name

Name of the an importable Python package.

validate()

Validate all extension points in this package.

version

The version of this extension package, if it can be found. Otherwise, an empty string.

class jupyter_server.extension.manager.ExtensionPoint(*args, **kwargs)

Bases: HasTraits

A simple API for connecting to a Jupyter Server extension point defined by metadata and importable from a Python package.

property app

If the metadata includes an app field

property config

Return any configuration provided by this extension point.

Link the extension to a Jupyter ServerApp object.

This looks for a _link_jupyter_server_extension function in the extension’s module or ExtensionApp class.

property linked

Has this extension point been linked to the server.

Will pull from ExtensionApp’s trait, if this point is an instance of ExtensionApp.

load(serverapp)

Load the extension in a Jupyter ServerApp object.

This looks for a _load_jupyter_server_extension function in the extension’s module or ExtensionApp class.

metadata

An instance of a Python dict.

One or more traits can be passed to the constructor to validate the keys and/or values of the dict. If you need more detailed validation, you may use a custom validator method.

Changed in version 5.0: Added key_trait for validating dict keys.

Changed in version 5.0: Deprecated ambiguous trait, traits args in favor of value_trait, per_key_traits.

property module

The imported module (using importlib.import_module)

property module_name

Name of the Python package module where the extension’s _load_jupyter_server_extension can be found.

property name

Name of the extension.

If it’s not provided in the metadata, name is set to the extensions’ module name.

validate()

Check that both a linker and loader exists.

Utilities for installing extensions

exception jupyter_server.extension.serverextension.ArgumentConflict

Bases: ValueError

class jupyter_server.extension.serverextension.BaseExtensionApp(**kwargs)

Bases: JupyterApp

Base extension installer app

aliases: StrDict = {'config': 'JupyterApp.config_file', 'log-level': 'Application.log_level'}
property config_dir: str

A trait for unicode strings.

flags: StrDict = {'debug': ({'Application': {'log_level': 10}}, 'set log level to logging.DEBUG (maximize logging output)'), 'py': ({'BaseExtensionApp': {'python': True}}, 'Install from a Python package'), 'python': ({'BaseExtensionApp': {'python': True}}, 'Install from a Python package'), 'show-config': ({'Application': {'show_config': True}}, "Show the application's configuration (human-readable format)"), 'show-config-json': ({'Application': {'show_config_json': True}}, "Show the application's configuration (json format)"), 'sys-prefix': ({'BaseExtensionApp': {'sys_prefix': True}}, 'Use sys.prefix as the prefix for installing extensions (for environments, packaging)'), 'system': ({'BaseExtensionApp': {'sys_prefix': False, 'user': False}}, 'Apply the operation system-wide'), 'user': ({'BaseExtensionApp': {'user': True}}, 'Apply the operation only for the given user')}
python

Install from a Python package

sys_prefix

Use the sys.prefix as the prefix

user

Whether to do a user install

version: str | Unicode[str, str | bytes] = '2.14.2'
class jupyter_server.extension.serverextension.DisableServerExtensionApp(**kwargs)

Bases: ToggleServerExtensionApp

An App that disables Server Extensions

description: str | Unicode[str, str | bytes] = '\n    Disable a server extension in configuration.\n\n    Usage\n        jupyter server extension disable [--system|--sys-prefix]\n    '
name: str | Unicode[str, str | bytes] = 'jupyter server extension disable'
class jupyter_server.extension.serverextension.EnableServerExtensionApp(**kwargs)

Bases: ToggleServerExtensionApp

An App that enables (and validates) Server Extensions

description: str | Unicode[str, str | bytes] = '\n    Enable a server extension in configuration.\n\n    Usage\n        jupyter server extension enable [--system|--sys-prefix]\n    '
name: str | Unicode[str, str | bytes] = 'jupyter server extension enable'
class jupyter_server.extension.serverextension.ListServerExtensionsApp(**kwargs)

Bases: BaseExtensionApp

An App that lists (and validates) Server Extensions

description: str | Unicode[str, str | bytes] = 'List all server extensions known by the configuration system'
list_server_extensions()

List all enabled and disabled server extensions, by config path

Enabled extensions are validated, potentially generating warnings.

Return type:

None

name: str | Unicode[str, str | bytes] = 'jupyter server extension list'
start()

Perform the App’s actions as configured

Return type:

None

version: str | Unicode[str, str | bytes] = '2.14.2'
class jupyter_server.extension.serverextension.ServerExtensionApp(**kwargs)

Bases: BaseExtensionApp

Root level server extension app

description: str = 'Work with Jupyter server extensions'
examples: str | Unicode[str, str | bytes] = '\njupyter server extension list                        # list all configured server extensions\njupyter server extension enable --py <packagename>   # enable all server extensions in a Python package\njupyter server extension disable --py <packagename>  # disable all server extensions in a Python package\n'
name: str | Unicode[str, str | bytes] = 'jupyter server extension'
start()

Perform the App’s actions as configured

Return type:

None

subcommands: dict[str, t.Any] = {'disable': (<class 'jupyter_server.extension.serverextension.DisableServerExtensionApp'>, 'Disable a server extension'), 'enable': (<class 'jupyter_server.extension.serverextension.EnableServerExtensionApp'>, 'Enable a server extension'), 'list': (<class 'jupyter_server.extension.serverextension.ListServerExtensionsApp'>, 'List server extensions')}
version: str | Unicode[str, str | bytes] = '2.14.2'
class jupyter_server.extension.serverextension.ToggleServerExtensionApp(**kwargs)

Bases: BaseExtensionApp

A base class for enabling/disabling extensions

description: str | Unicode[str, str | bytes] = 'Enable/disable a server extension using frontend configuration files.'
flags: StrDict = {'debug': ({'Application': {'log_level': 10}}, 'set log level to logging.DEBUG (maximize logging output)'), 'py': ({'ToggleServerExtensionApp': {'python': True}}, 'Install from a Python package'), 'python': ({'ToggleServerExtensionApp': {'python': True}}, 'Install from a Python package'), 'show-config': ({'Application': {'show_config': True}}, "Show the application's configuration (human-readable format)"), 'show-config-json': ({'Application': {'show_config_json': True}}, "Show the application's configuration (json format)"), 'sys-prefix': ({'ToggleServerExtensionApp': {'sys_prefix': True}}, 'Use sys.prefix as the prefix for installing server extensions'), 'system': ({'ToggleServerExtensionApp': {'sys_prefix': False, 'user': False}}, 'Perform the operation system-wide'), 'user': ({'ToggleServerExtensionApp': {'user': True}}, 'Perform the operation for the current user')}
name: str | Unicode[str, str | bytes] = 'jupyter server extension enable/disable'
start()

Perform the App’s actions as configured

Return type:

None

toggle_server_extension(import_name)

Change the status of a named server extension.

Uses the value of self._toggle_value.

Parameters:

import_name (str) – Importable Python module (dotted-notation) exposing the magic-named load_jupyter_server_extension function

Return type:

None

jupyter_server.extension.serverextension.toggle_server_extension_python(import_name, enabled=None, parent=None, user=False, sys_prefix=True)

Toggle the boolean setting for a given server extension in a Jupyter config file.

Return type:

None

Extension utilities.

exception jupyter_server.extension.utils.ExtensionLoadingError

Bases: Exception

An extension loading error.

exception jupyter_server.extension.utils.ExtensionMetadataError

Bases: Exception

An extension metadata error.

exception jupyter_server.extension.utils.ExtensionModuleNotFound

Bases: Exception

An extension module not found error.

exception jupyter_server.extension.utils.NotAnExtensionApp

Bases: Exception

An error raised when a module is not an extension.

jupyter_server.extension.utils.get_loader(obj, logger=None)

Looks for _load_jupyter_server_extension as an attribute of the object or module.

Adds backwards compatibility for old function name missing the underscore prefix.

jupyter_server.extension.utils.get_metadata(package_name, logger=None)

Find the extension metadata from an extension package.

This looks for a _jupyter_server_extension_points function that returns metadata about all extension points within a Jupyter Server Extension package.

If it doesn’t exist, return a basic metadata packet given the module name.

jupyter_server.extension.utils.validate_extension(name)

Raises an exception is the extension is missing a needed hook or metadata field. An extension is valid if: 1) name is an importable Python package. 1) the package has a _jupyter_server_extension_points function 2) each extension path has a _load_jupyter_server_extension function

If this works, nothing should happen.

Module contents