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() → Optional[int]

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() → Optional[int]

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, Union[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.