Skip to main content
`Ctrl`+`K`

# jupyter_client.provisioning package

## Submodules

Kernel Provisioner Classes

class jupyter_client.provisioning.factory.KernelProvisionerFactory(**kwargs)

  Bases: `SingletonConfigurable`

  `KernelProvisionerFactory` is responsible for creating provisioner instances.

  A singleton instance, KernelProvisionerFactory is also used by the `KernelSpecManager` to validate kernel_provisioner references found in kernel specifications to confirm their availability (in cases where the kernel specification references a kernel provisioner that has not been installed into the current Python environment).

  It’s `default_provisioner_name` attribute can be used to specify the default provisioner to use when a kernel_spec is found to not reference a provisioner. It’s value defaults to “local-provisioner” which identifies the local provisioner implemented by `LocalProvisioner`.

  GROUP_NAME = 'jupyter_client.kernel_provisioners'
  create_provisioner_instance(kernel_id, kernel_spec, parent)

    Reads the associated `kernel_spec` to see if it has a kernel_provisioner stanza. If one exists, it instantiates an instance. If a kernel provisioner is not specified in the kernel specification, a default provisioner stanza is fabricated and instantiated corresponding to the current value of `default_provisioner_name` trait. The instantiated instance is returned.

    If the provisioner is found to not exist (not registered via entry_points), ModuleNotFoundError is raised.

    Return type:

      `KernelProvisionerBase`

  default_provisioner_name

    Indicates the name of the provisioner to use when no kernel_provisioner entry is present in the kernelspec.

  default_provisioner_name_env = 'JUPYTER_DEFAULT_PROVISIONER_NAME'
  get_provisioner_entries()

    Returns a dictionary of provisioner entries.

    The key is the provisioner name for its entry point. The value is the colon-separated string of the entry point’s module name and object name.

    Return type:

      `Dict`[`str`, `str`]

  is_provisioner_available(kernel_spec)

    Reads the associated `kernel_spec` to determine the provisioner and returns whether it exists as an entry_point (True) or not (False). If the referenced provisioner is not in the current cache or cannot be loaded via entry_points, a warning message is issued indicating it is not available.

    Return type:

      `bool`

  provisioners: `Dict`[`str`, `EntryPoint`] = {}

Kernel Provisioner Classes

class jupyter_client.provisioning.local_provisioner.LocalProvisioner(**kwargs)

  Bases: `KernelProvisionerBase`

  `LocalProvisioner` is a concrete class of ABC `KernelProvisionerBase` and is the out-of-box default implementation used when no kernel provisioner is specified in the kernel specification (`kernel.json`). It provides functional parity to existing applications by launching the kernel locally and using `subprocess.Popen` to manage its lifecycle.

  This class is intended to be subclassed for customizing local kernel environments and serve as a reference implementation for other custom provisioners.

  async cleanup(restart=False)

    Clean up the resources used by the provisioner and optionally restart.

    Return type:

      `None`

  async get_provisioner_info()

    Captures the base information necessary for persistence relative to this instance.

    Return type:

      `Dict`

  property has_process: bool

    Returns true if this provisioner is currently managing a process.

    This property is asserted to be True immediately following a call to the provisioner’s `launch_kernel()` method.

  ip = None
  async kill(restart=False)

    Kill the provisioner and optionally restart.

    Return type:

      `None`

  async launch_kernel(cmd, **kwargs)

    Launch a kernel with a command.

    Return type:

      `Dict`[`str`, `Union`[`int`, `str`, `bytes`]]

  async load_provisioner_info(provisioner_info)

    Loads the base information necessary for persistence relative to this instance.

    Return type:

      `None`

  pgid = None
  pid = None
  async poll()

    Poll the provisioner.

    Return type:

      `Optional`[`int`]

  ports_cached = False
  async pre_launch(**kwargs)

    Perform any steps in preparation for kernel process launch.

    This includes applying additional substitutions to the kernel launch command and env. It also includes preparation of launch parameters.

    Returns the updated kwargs.

    Return type:

      `Dict`[`str`, `Any`]

  process = None
  async send_signal(signum)

    Sends a signal to the process group of the kernel (this usually includes the kernel and any subprocesses spawned by the kernel).

    Note that since only SIGTERM is supported on Windows, we will check if the desired signal is for interrupt and apply the applicable code on Windows in that case.

    Return type:

      `None`

  async terminate(restart=False)

    Terminate the provisioner and optionally restart.

    Return type:

      `None`

  async wait()

    Wait for the provisioner process.

    Return type:

      `Optional`[`int`]

Kernel Provisioner Classes

class jupyter_client.provisioning.provisioner_base.KernelProvisionerBase(**kwargs)

  Bases: `ABC`, `LoggingConfigurable`

  Abstract base class defining methods for KernelProvisioner classes.

  A majority of methods are abstract (requiring implementations via a subclass) while some are optional and others provide implementations common to all instances. Subclasses should be aware of which methods require a call to the superclass.

  Many of these methods model those of `subprocess.Popen` for parity with previous versions where the kernel process was managed directly.

  abstract async cleanup(restart=False)

    Cleanup any resources allocated on behalf of the kernel provisioner.

    This method is called from KernelManager.cleanup_resources() as part of its shutdown kernel sequence.

    restart is True if this operation precedes a start launch_kernel request.

    Return type:

      `None`

  connection_info: `Dict`[`str`, `Union`[`int`, `str`, `bytes`]] = {}
  async get_provisioner_info()

    Captures the base information necessary for persistence relative to this instance.

    This enables applications that subclass KernelManager to persist a kernel provisioner’s relevant information to accomplish functionality like disaster recovery or high availability by calling this method via the kernel manager’s provisioner attribute.

    NOTE: The superclass method must always be called first to ensure proper serialization.

    Return type:

      `Dict`[`str`, `Any`]

  get_shutdown_wait_time(recommended=5.0)

    Returns the time allowed for a complete shutdown. This may vary by provisioner.

    This method is called from KernelManager.finish_shutdown() during the graceful phase of its kernel shutdown sequence.

    The recommended value will typically be what is configured in the kernel manager.

    Return type:

      `float`

  get_stable_start_time(recommended=10.0)

    Returns the expected upper bound for a kernel (re-)start to complete. This may vary by provisioner.

    The recommended value will typically be what is configured in the kernel restarter.

    Return type:

      `float`

  abstract property has_process: bool

    Returns true if this provisioner is currently managing a process.

    This property is asserted to be True immediately following a call to the provisioner’s `launch_kernel()` method.

  kernel_id: `Union`[`str`, `Unicode`]

    A trait for unicode strings.

  kernel_spec: `Any`

    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

  abstract async kill(restart=False)

    Kill the kernel process.

    This is typically accomplished via a SIGKILL signal, which cannot be caught. This method is called from KernelManager.kill_kernel() when terminating a kernel immediately.

    restart is True if this operation will precede a subsequent launch_kernel request.

    Return type:

      `None`

  abstract async launch_kernel(cmd, **kwargs)

    Launch the kernel process and return its connection information.

    This method is called from KernelManager.launch_kernel() during the kernel manager’s start kernel sequence.

    Return type:

      `Dict`[`str`, `Union`[`int`, `str`, `bytes`]]

  async load_provisioner_info(provisioner_info)

    Loads the base information necessary for persistence relative to this instance.

    The inverse of get_provisioner_info(), this enables applications that subclass KernelManager to re-establish communication with a provisioner that is managing a (presumably) remote kernel from an entirely different process that the original provisioner.

    NOTE: The superclass method must always be called first to ensure proper deserialization.

    Return type:

      `None`

  abstract async poll()

    Checks if kernel process is still running.

    If running, None is returned, otherwise the process’s integer-valued exit code is returned. This method is called from `KernelManager.is_alive()`.

    Return type:

      `Optional`[`int`]

  async post_launch(**kwargs)

    Perform any steps following the kernel process launch.

    This method is called from KernelManager.post_start_kernel() as part of its start kernel sequence.

    Return type:

      `None`

  async pre_launch(**kwargs)

    Perform any steps in preparation for kernel process launch.

    This includes applying additional substitutions to the kernel launch command and environment. It also includes preparation of launch parameters.

    NOTE: Subclass implementations are advised to call this method as it applies environment variable substitutions from the local environment and calls the provisioner’s `_finalize_env()` method to allow each provisioner the ability to cleanup the environment variables that will be used by the kernel.

    This method is called from KernelManager.pre_start_kernel() as part of its start kernel sequence.

    Returns the (potentially updated) keyword arguments that are passed to `launch_kernel()`.

    Return type:

      `Dict`[`str`, `Any`]

  abstract async send_signal(signum)

    Sends signal identified by signum to the kernel process.

    This method is called from KernelManager.signal_kernel() to send the kernel process a signal.

    Return type:

      `None`

  async shutdown_requested(restart=False)

    Allows the provisioner to determine if the kernel’s shutdown has been requested.

    This method is called from KernelManager.request_shutdown() as part of its shutdown sequence.

    This method is optional and is primarily used in scenarios where the provisioner may need to perform other operations in preparation for a kernel’s shutdown.

    Return type:

      `None`

  abstract async terminate(restart=False)

    Terminates the kernel process.

    This is typically accomplished via a SIGTERM signal, which can be caught, allowing the kernel provisioner to perform possible cleanup of resources. This method is called indirectly from KernelManager.finish_shutdown() during a kernel’s graceful termination.

    restart is True if this operation precedes a start launch_kernel request.

    Return type:

      `None`

  abstract async wait()

    Waits for kernel process to terminate.

    This method is called from KernelManager.finish_shutdown() and KernelManager.kill_kernel() when terminating a kernel gracefully or immediately, respectively.

    Return type:

      `Optional`[`int`]

class jupyter_client.provisioning.provisioner_base.KernelProvisionerMeta(name, bases, classdict, **kwds)

  Bases: `ABCMeta`, `MetaHasTraits`

## Module contents