Contents

nbclient 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_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 –

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

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