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

jupyter_client.provisioning package#

Submodules#

Module contents#