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_extensions()#: Link all enabled extensions to an instance of ServerApp

link_extension(name)#: 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_points(serverapp)#: Link all extension points.

link_point(point_name, serverapp)#: 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(serverapp)#

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.

jupyter_server.extension package#

Submodules#

Module contents#