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.13.0'#
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.13.0'#
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.13.0'#
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#