Skip to main content
`Ctrl`+`K`

# 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 = [<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:

      `Template`

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
  render_template(name, **ns)

    Override render template to handle static_paths

    If render_template is called with a template from the base environment (e.g. default error pages) make sure our extension-specific static_url is _not_ used.

    Return type:

      `str`

  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 finding, 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 start_all_extensions()

    Start all enabled extensions.

  async start_extension(name)

    Start an extension by name.

  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.

  async start_all_points(serverapp)

    Load all extension points.

  async start_point(point_name, serverapp)

    Load an extension point.

  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.

  log

    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

  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.

  async start(serverapp)

    Call’s the extensions ‘start’ hook where it can start (possibly async) tasks _after_ the event loop is running.

  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 = {'config': 'JupyterApp.config_file', 'log-level': 'Application.log_level'}
  property config_dir: str

    A trait for unicode strings.

  flags = {'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 = '2.20.0'

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

  Bases: `ToggleServerExtensionApp`

  An App that disables Server Extensions

  description = '\n Disable a server extension in configuration.\n\n Usage\n jupyter server extension disable [--system|--sys-prefix]\n '
  name = 'jupyter server extension disable'

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

  Bases: `ToggleServerExtensionApp`

  An App that enables (and validates) Server Extensions

  description = '\n Enable a server extension in configuration.\n\n Usage\n jupyter server extension enable [--system|--sys-prefix]\n '
  name = 'jupyter server extension enable'

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

  Bases: `BaseExtensionApp`

  An App that lists (and validates) Server Extensions

  description = '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 = 'jupyter server extension list'
  start()

    Perform the App’s actions as configured

    Return type:

      `None`

  version = '2.20.0'

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

  Bases: `BaseExtensionApp`

  Root level server extension app

  description: str = 'Work with Jupyter server extensions'
  examples = '\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 = '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 = '2.20.0'

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

  Bases: `BaseExtensionApp`

  A base class for enabling/disabling extensions

  description = 'Enable/disable a server extension using frontend configuration files.'
  flags = {'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 = '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