# kernel provisioner apis

See also

Customizing the kernel’s runtime environment

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

  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.

  kernel_spec

    The kernel specification associated with the provisioned kernel (see Kernel specs).

  kernel_id

    The provisioned kernel’s ID.

  connection_info

    The provisioned kernel’s connection information.

  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.

  abstract async poll() → int | None

    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()`.

  abstract async wait() → int | None

    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.

  abstract async send_signal(signum: int) → None

    Sends signal identified by signum to the kernel process.

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

  abstract async kill(restart: bool = False) → None

    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.

  abstract async terminate(restart: bool = False) → None

    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.

  abstract async launch_kernel(cmd: List[str], **kwargs: Any) → Dict[str, int | str | bytes]

    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.

  abstract async cleanup(restart: bool = False) → None

    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.

  async shutdown_requested(restart: bool = False) → None

    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.

  async pre_launch(**kwargs: Any) → Dict[str, Any]

    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()`.

  async post_launch(**kwargs: Any) → None

    Perform any steps following the kernel process launch.

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

  async get_provisioner_info() → Dict[str, Any]

    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.

  async load_provisioner_info(provisioner_info: Dict) → None

    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.

  get_shutdown_wait_time(recommended: float = 5.0) → float

    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.

  _finalize_env(env: Dict[str, str]) → None

    Ensures env is appropriate prior to launch.

    This method is called from KernelProvisionerBase.pre_launch() during the kernel’s start sequence.

    NOTE: Subclasses should be sure to call super()._finalize_env(env)

  __apply_env_substitutions(substitution_values: Dict[str, str]) → Dict[str, str]

    Walks entries in the kernelspec’s env stanza and applies substitutions from current env.

    This method is called from KernelProvisionerBase.pre_launch() during the kernel’s start sequence.

    Returns the substituted list of env entries.

    NOTE: This method is private and is not intended to be overridden by provisioners.

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

  `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.

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

  `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`.

  default_provisioner_name

    Indicates the name of the provisioner to use when no kernel_provisioner entry is present in the kernel specification. This value can also be specified via the environment variable `JUPYTER_DEFAULT_PROVISIONER_NAME`.

  is_provisioner_available(kernel_spec: Any) → bool

    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.

  create_provisioner_instance(kernel_id: str, kernel_spec: Any, parent: Any) → KernelProvisionerBase

    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.