nbclient package¶

Subpackages¶

nbclient.tests package

Submodules¶

nbclient.client module¶

class nbclient.client.NotebookClient(**kwargs)¶

Bases: traitlets.config.configurable.LoggingConfigurable

Encompasses a Client for executing cells in a notebook

allow_error_names: List[str]¶: An instance of a Python list.

allow_errors: bool¶: A boolean (True, False) trait.

async async_execute(reset_kc: bool = False, **kwargs) → nbformat.notebooknode.NotebookNode¶

Executes each code cell.

Parameters

kwargs –

Any option for self.kernel_manager_class.start_kernel(). Because that defaults to AsyncKernelManager, this will likely include options accepted by jupyter_client.AsyncKernelManager.start_kernel(), which includes cwd.

reset_kc if True, the kernel client will be reset and a new one will be created (default: False).

Returns

nb – The executed notebook.

Return type

NotebookNode

async async_execute_cell(cell: nbformat.notebooknode.NotebookNode, cell_index: int, execution_count: Optional[int] = None, store_history: bool = True) → nbformat.notebooknode.NotebookNode¶

Executes a single code cell.

To execute all cells see execute().

Parameters

cell (nbformat.NotebookNode) – The cell which is currently being processed.
cell_index (int) – The position of the cell within the notebook object.
execution_count (int) – The execution count to be assigned to the cell (default: Use kernel response)
store_history (bool) – Determines if history should be stored in the kernel (default: False). Specific to ipython kernels, which can store command histories.

Returns

output – The execution output payload (or None for no output).

Return type

dict

Raises

CellExecutionError – If execution failed and should raise an exception, this will be raised with defaults about the failure.

Returns

cell – The cell which was just processed.

Return type

NotebookNode

async_setup_kernel(**kwargs) → AsyncGenerator¶

Context manager for setting up the kernel to execute a notebook.

This assigns the Kernel Manager (self.km) if missing and Kernel Client(self.kc).

When control returns from the yield it stops the client’s zmq channels, and shuts down the kernel.

Handlers for SIGINT and SIGTERM are also added to cleanup in case of unexpected shutdown.

async async_start_new_kernel(**kwargs) → None ¶

Creates a new kernel.

Parameters: kwargs – Any options for self.kernel_manager_class.start_kernel(). Because that defaults to AsyncKernelManager, this will likely include options accepted by AsyncKernelManager.start_kernel(), which includes cwd.

async async_start_new_kernel_client() → jupyter_client.client.KernelClient¶

Creates a new kernel client.

Returns: kc – Kernel client as created by the kernel manager km.
Return type: KernelClient

async async_wait_for_reply(msg_id: str, cell: Optional[nbformat.notebooknode.NotebookNode] = None) → Optional[Dict]¶

clear_display_id_mapping(cell_index: int) → None ¶

clear_output(outs: List, msg: Dict, cell_index: int) → None ¶

create_kernel_manager() → jupyter_client.manager.KernelManager¶

Creates a new kernel manager.

Returns: km – Kernel manager whose client class is asynchronous.
Return type: KernelManager

display_data_priority: List¶: An instance of a Python list.

execute(**kwargs)¶

Executes each code cell.

Parameters

kwargs –

reset_kc if True, the kernel client will be reset and a new one will be created (default: False).

Returns

nb – The executed notebook.

Return type

NotebookNode

execute_cell(**kwargs)¶

Executes a single code cell.

To execute all cells see execute().

Parameters

cell (nbformat.NotebookNode) – The cell which is currently being processed.
cell_index (int) – The position of the cell within the notebook object.
execution_count (int) – The execution count to be assigned to the cell (default: Use kernel response)
store_history (bool) – Determines if history should be stored in the kernel (default: False). Specific to ipython kernels, which can store command histories.

Returns

output – The execution output payload (or None for no output).

Return type

dict

Raises

CellExecutionError – If execution failed and should raise an exception, this will be raised with defaults about the failure.

Returns

cell – The cell which was just processed.

Return type

NotebookNode

extra_arguments: List¶: An instance of a Python list.

force_raise_errors: bool¶: A boolean (True, False) trait.

handle_comm_msg(outs: List, msg: Dict, cell_index: int) → None ¶

interrupt_on_timeout: bool¶: A boolean (True, False) trait.

iopub_timeout: int¶: An int trait.

ipython_hist_file: str¶: A trait for unicode strings.

kernel_manager_class: jupyter_client.manager.KernelManager¶: A trait whose value must be a subclass of a specified class.

kernel_name: str¶: A trait for unicode strings.

on_comm_open_jupyter_widget(msg: Dict)¶

output(outs: List, msg: Dict, display_id: str, cell_index: int) → Optional[List]¶

process_message(msg: Dict, cell: nbformat.notebooknode.NotebookNode, cell_index: int) → Optional[List]¶

Processes a kernel message, updates cell state, and returns the resulting output object that was appended to cell.outputs.

The input argument cell is modified in-place.

Parameters

msg (dict) – The kernel message being processed.
cell (nbformat.NotebookNode) – The cell which is currently being processed.
cell_index (int) – The position of the cell within the notebook object.

Returns

output – The execution output payload (or None for no output).

Return type

dict

Raises

CellExecutionComplete – Once a message arrives which indicates computation completeness.

raise_on_iopub_timeout: bool¶: A boolean (True, False) trait.

record_timing: bool¶: A boolean (True, False) trait.

register_output_hook(msg_id: str, hook: nbclient.output_widget.OutputWidget) → None ¶

Registers an override object that handles output/clear_output instead.

Multiple hooks can be registered, where the last one will be used (stack based)

remove_output_hook(msg_id: str, hook: nbclient.output_widget.OutputWidget) → None ¶: Unregisters an override object that handles output/clear_output instead

reset_execution_trackers() → None ¶: Resets any per-execution trackers.

resources: Dict¶

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.

set_widgets_metadata() → None ¶

setup_kernel(**kwargs) → Generator¶

Context manager for setting up the kernel to execute a notebook.

The assigns the Kernel Manager (self.km) if missing and Kernel Client(self.kc).

When control returns from the yield it stops the client’s zmq channels, and shuts down the kernel.

shell_timeout_interval: int¶: An int trait.

shutdown_kernel¶: An enum whose value must be in a given sequence.

start_new_kernel(**kwargs)¶

Creates a new kernel.

Parameters: kwargs – Any options for self.kernel_manager_class.start_kernel(). Because that defaults to AsyncKernelManager, this will likely include options accepted by AsyncKernelManager.start_kernel(), which includes cwd.

start_new_kernel_client(**kwargs)¶

Creates a new kernel client.

Returns: kc – Kernel client as created by the kernel manager km.
Return type: KernelClient

startup_timeout: int¶: An int trait.

store_widget_state: bool¶: A boolean (True, False) trait.

timeout: int¶: An int trait.

timeout_func: Any¶: A trait which allows any value.

wait_for_reply(**kwargs)¶

nbclient.client.execute(nb: nbformat.notebooknode.NotebookNode, cwd: Optional[str] = None, km: Optional[jupyter_client.manager.KernelManager] = None, **kwargs) → nbclient.client.NotebookClient ¶

Execute a notebook’s code, updating outputs within the notebook object.

This is a convenient wrapper around NotebookClient. It returns the modified notebook object.

Parameters

nb (NotebookNode) – The notebook object to be executed
cwd (str, optional) – If supplied, the kernel will run in this directory
km (AsyncKernelManager, optional) – If supplied, the specified kernel manager will be used for code execution.
kwargs – Any other options for NotebookClient, e.g. timeout, kernel_name

nbclient.client.timestamp() → str ¶

nbclient.exceptions module¶

exception nbclient.exceptions.CellControlSignal¶

Bases: Exception

A custom exception used to indicate that the exception is used for cell control actions (not the best model, but it’s needed to cover existing behavior without major refactors).

exception nbclient.exceptions.CellExecutionComplete¶

Bases: nbclient.exceptions.CellControlSignal

Used as a control signal for cell execution across execute_cell and process_message function calls. Raised when all execution requests are completed and no further messages are expected from the kernel over zeromq channels.

exception nbclient.exceptions.CellExecutionError(traceback: str, ename: str, evalue: str)¶

Bases: nbclient.exceptions.CellControlSignal

Custom exception to propagate exceptions that are raised during notebook execution to the caller. This is mostly useful when using nbconvert as a library, since it allows to deal with failures gracefully.

classmethod from_cell_and_msg(cell: nbformat.notebooknode.NotebookNode, msg: Dict)¶: Instantiate from a code cell object and a message contents (message is either execute_reply or error)

exception nbclient.exceptions.CellTimeoutError¶

Bases: TimeoutError, nbclient.exceptions.CellControlSignal

A custom exception to capture when a cell has timed out during execution.

classmethod error_from_timeout_and_cell(msg: str, timeout: int, cell: nbformat.notebooknode.NotebookNode)¶

exception nbclient.exceptions.DeadKernelError¶: Bases: RuntimeError

Module contents¶

Reference nbclient.tests package