nbclient package

nbclient package#

Subpackages#

Submodules#

nbclient.client module#

nbclient implementation.

class nbclient.client.NotebookClient(**kwargs: Any)#

Bases: LoggingConfigurable

Encompasses a Client for executing cells in a notebook

allow_error_names#: List of error names which won’t stop the execution. Use this if the allow_errors option it too general and you want to allow only specific kinds of errors.

allow_errors#: If False (default), when a cell raises an error the execution is stopped and a CellExecutionError is raised, except if the error name is in allow_error_names. If True, execution errors are ignored and the execution is continued until the end of the notebook. Output from exceptions is included in the cell output in both cases.

async async_execute(reset_kc: bool = False, **kwargs: Any) → 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: NotebookNode, cell_index: int, execution_count: int | None = None, store_history: bool = True) → 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: Any) → AsyncGenerator[None, None]#

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: Any) → 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() → 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: NotebookNode | None = None) → dict[str, Any] | None#: Wait for a message reply.

clear_display_id_mapping(cell_index: int) → None#: Clear a display id mapping for a cell.

clear_output(outs: list[NotebookNode], msg: dict[str, Any], cell_index: int) → None#: Clear output.

coalesce_streams#: Merge all stream outputs with shared names into single streams.

create_kernel_manager() → KernelManager#

Creates a new kernel manager.

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

display_data_priority#: An ordered list of preferred output type, the first encountered will usually be used when converting discarding the others.

error_on_timeout#

If a cell execution was interrupted after a timeout, don’t wait for the execute_reply from the kernel (e.g. KeyboardInterrupt error). Instead, return an execute_reply with the given error, which should be of the following form:

{
    'ename': str,  # Exception name, as a string
    'evalue': str,  # Exception value, as a string
    'traceback': list(str),  # traceback frames, as strings
}

execute(**kwargs: Any) → Any#

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: Any) → Any#

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#: An instance of a Python list.

force_raise_errors#: If False (default), errors from executing the notebook can be allowed with a raises-exception tag on a single cell, or the allow_errors or allow_error_names configurable options for all cells. An allowed error will be recorded in notebook output, and execution will continue. If an error occurs when it is not explicitly allowed, a CellExecutionError will be raised. If True, CellExecutionError will be raised for any error that occurs while executing the notebook. This overrides the allow_errors and allow_error_names options and the raises-exception cell tag.

handle_comm_msg(outs: list[NotebookNode], msg: dict[str, Any], cell_index: int) → None#: Handle a comm message.

interrupt_on_timeout#: If execution of a cell times out, interrupt the kernel and continue executing other cells rather than throwing an error and stopping.

iopub_timeout#: The time to wait (in seconds) for IOPub output. This generally doesn’t need to be set, but on some slow networks (such as CI systems) the default timeout might not be long enough to get all messages.

ipython_hist_file#

Path to file to use for SQLite history database for an IPython kernel.

The specific value :memory: (including the colon at both end but not the back ticks), avoids creating a history file. Otherwise, IPython will create a history file for each kernel.

When running kernels simultaneously (e.g. via multiprocessing) saving history a single SQLite file can result in database errors, so using :memory: is recommended in non-interactive contexts.

kernel_manager_class#: The kernel manager class to use.

kernel_name#: Name of kernel to use to execute the cells. If not set, use the kernel_spec embedded in the notebook.

on_cell_complete#: A callable which executes after a cell execution is complete. It is called even when a cell results in a failure. Called with kwargs cell and cell_index.

on_cell_error#: A callable which executes when a cell execution results in an error. This is executed even if errors are suppressed with cell_allows_errors. Called with kwargs cell`, ``cell_index and execute_reply.

on_cell_execute#: A callable which executes just before a code cell is executed. Called with kwargs cell and cell_index.

on_cell_executed#: A callable which executes just after a code cell is executed, whether or not it results in an error. Called with kwargs cell, cell_index and execute_reply.

on_cell_start#: A callable which executes before a cell is executed and before non-executing cells are skipped. Called with kwargs cell and cell_index.

on_comm_open_jupyter_widget(msg: dict[str, Any]) → Any | None#: Handle a jupyter widget comm open.

on_notebook_complete#: A callable which executes after the kernel is cleaned up. Called with kwargs notebook.

on_notebook_error#: A callable which executes when the notebook encounters an error. Called with kwargs notebook.

on_notebook_start#: A callable which executes after the kernel manager and kernel client are setup, and cells are about to execute. Called with kwargs notebook.

output(outs: list[NotebookNode], msg: dict[str, Any], display_id: str, cell_index: int) → NotebookNode | None#: Handle output.

process_message(msg: dict[str, Any], cell: NotebookNode, cell_index: int) → NotebookNode | None#

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:

NotebookNode

Raises:

CellExecutionComplete – Once a message arrives which indicates computation completeness.

raise_on_iopub_timeout#: If False (default), then the kernel will continue waiting for iopub messages until it receives a kernel idle message, or until a timeout occurs, at which point the currently executing cell will be skipped. If True, then an error will be raised after the first timeout. This option generally does not need to be used, but may be useful in contexts where there is the possibility of executing notebooks with memory-consuming infinite loops.

record_timing#: If True (default), then the execution timings of each cell will be stored in the metadata of the notebook.

register_output_hook(msg_id: str, hook: 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: OutputWidget) → None#: Unregisters an override object that handles output/clear_output instead

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

resources: dict[str, Any]#: Additional resources used in the conversion process. For example, passing {'metadata': {'path': run_path}} sets the execution path to run_path.

set_widgets_metadata() → None#: Set with widget metadata.

setup_kernel(**kwargs: Any) → Generator[None, None, None]#

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#: The time to wait (in seconds) for Shell output before retrying. This generally doesn’t need to be set, but if one needs to check for dead kernels at a faster rate this can help.

shutdown_kernel#: If graceful (default), then the kernel is given time to clean up after executing all cells, e.g., to execute its atexit hooks. If immediate, then the kernel is signaled to immediately terminate.

skip_cells_with_tag#: Name of the cell tag to use to denote a cell that should be skipped.

start_new_kernel(**kwargs: Any) → Any#

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: Any) → Any#

Creates a new kernel client.

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

startup_timeout#: The time to wait (in seconds) for the kernel to start. If kernel startup takes longer, a RuntimeError is raised.

store_widget_state#: If True (default), then the state of the Jupyter widgets created at the kernel will be stored in the metadata of the notebook.

timeout#

The time to wait (in seconds) for output from executions. If a cell execution takes longer, a TimeoutError is raised.

None or -1 will disable the timeout. If timeout_func is set, it overrides timeout.

timeout_func: Callable[[...], int | None] | None#

A callable which, when given the cell source as input, returns the time to wait (in seconds) for output from cell executions. If a cell execution takes longer, a TimeoutError is raised.

Returning None or -1 will disable the timeout for the cell. Not setting timeout_func will cause the client to default to using the timeout trait for all cells. The timeout_func trait overrides timeout if it is not None.

wait_for_reply(**kwargs: Any) → Any#: Wait for a message reply.

nbclient.client.execute(nb: NotebookNode, cwd: str | None = None, km: KernelManager | None = None, **kwargs: Any) → NotebookNode#

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(msg: dict[str, Any] | None = None) → str#: Get the timestamp for a message.

nbclient.exceptions module#

Exceptions for nbclient.

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: 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: 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: NotebookNode, msg: dict[str, Any]) → CellExecutionError#: Instantiate from a code cell object and a message contents (message is either execute_reply or error)

exception nbclient.exceptions.CellTimeoutError#

Bases: TimeoutError, 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: NotebookNode) → CellTimeoutError#: Create an error from a timeout on a cell.

exception nbclient.exceptions.DeadKernelError#

Bases: RuntimeError

A dead kernel error.

Module contents#

class nbclient.NotebookClient(**kwargs: Any)#

Bases: LoggingConfigurable

Encompasses a Client for executing cells in a notebook

allow_error_names#: List of error names which won’t stop the execution. Use this if the allow_errors option it too general and you want to allow only specific kinds of errors.

allow_errors#: If False (default), when a cell raises an error the execution is stopped and a CellExecutionError is raised, except if the error name is in allow_error_names. If True, execution errors are ignored and the execution is continued until the end of the notebook. Output from exceptions is included in the cell output in both cases.

async async_execute(reset_kc: bool = False, **kwargs: Any) → NotebookNode#

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

async async_execute_cell(cell: NotebookNode, cell_index: int, execution_count: int | None = None, store_history: bool = True) → 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: Any) → AsyncGenerator[None, None]#

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: Any) → 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() → 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: NotebookNode | None = None) → dict[str, Any] | None#: Wait for a message reply.

clear_display_id_mapping(cell_index: int) → None#: Clear a display id mapping for a cell.

clear_output(outs: list[NotebookNode], msg: dict[str, Any], cell_index: int) → None#: Clear output.

coalesce_streams#: Merge all stream outputs with shared names into single streams.

comm_open_handlers: dict[str, Any]#

create_kernel_manager() → KernelManager#

Creates a new kernel manager.

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

display_data_priority#: An ordered list of preferred output type, the first encountered will usually be used when converting discarding the others.

error_on_timeout#

{
    'ename': str,  # Exception name, as a string
    'evalue': str,  # Exception value, as a string
    'traceback': list(str),  # traceback frames, as strings
}

execute(**kwargs: Any) → Any#

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: Any) → Any#

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#: An instance of a Python list.

force_raise_errors#: If False (default), errors from executing the notebook can be allowed with a raises-exception tag on a single cell, or the allow_errors or allow_error_names configurable options for all cells. An allowed error will be recorded in notebook output, and execution will continue. If an error occurs when it is not explicitly allowed, a CellExecutionError will be raised. If True, CellExecutionError will be raised for any error that occurs while executing the notebook. This overrides the allow_errors and allow_error_names options and the raises-exception cell tag.

handle_comm_msg(outs: list[NotebookNode], msg: dict[str, Any], cell_index: int) → None#: Handle a comm message.

interrupt_on_timeout#: If execution of a cell times out, interrupt the kernel and continue executing other cells rather than throwing an error and stopping.

iopub_timeout#: The time to wait (in seconds) for IOPub output. This generally doesn’t need to be set, but on some slow networks (such as CI systems) the default timeout might not be long enough to get all messages.

ipython_hist_file#

Path to file to use for SQLite history database for an IPython kernel.

The specific value :memory: (including the colon at both end but not the back ticks), avoids creating a history file. Otherwise, IPython will create a history file for each kernel.

When running kernels simultaneously (e.g. via multiprocessing) saving history a single SQLite file can result in database errors, so using :memory: is recommended in non-interactive contexts.

kc: KernelClient | None#

kernel_manager_class#: The kernel manager class to use.

kernel_name#: Name of kernel to use to execute the cells. If not set, use the kernel_spec embedded in the notebook.

km: KernelManager | None#

nb: NotebookNode#

on_cell_complete#: A callable which executes after a cell execution is complete. It is called even when a cell results in a failure. Called with kwargs cell and cell_index.

on_cell_error#: A callable which executes when a cell execution results in an error. This is executed even if errors are suppressed with cell_allows_errors. Called with kwargs cell`, ``cell_index and execute_reply.

on_cell_execute#: A callable which executes just before a code cell is executed. Called with kwargs cell and cell_index.

on_cell_executed#: A callable which executes just after a code cell is executed, whether or not it results in an error. Called with kwargs cell, cell_index and execute_reply.

on_cell_start#: A callable which executes before a cell is executed and before non-executing cells are skipped. Called with kwargs cell and cell_index.

on_comm_open_jupyter_widget(msg: dict[str, Any]) → Any | None#: Handle a jupyter widget comm open.

on_notebook_complete#: A callable which executes after the kernel is cleaned up. Called with kwargs notebook.

on_notebook_error#: A callable which executes when the notebook encounters an error. Called with kwargs notebook.

on_notebook_start#: A callable which executes after the kernel manager and kernel client are setup, and cells are about to execute. Called with kwargs notebook.

output(outs: list[NotebookNode], msg: dict[str, Any], display_id: str, cell_index: int) → NotebookNode | None#: Handle output.

owns_km: bool#

process_message(msg: dict[str, Any], cell: NotebookNode, cell_index: int) → NotebookNode | None#

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:

NotebookNode

Raises:

CellExecutionComplete – Once a message arrives which indicates computation completeness.

raise_on_iopub_timeout#: If False (default), then the kernel will continue waiting for iopub messages until it receives a kernel idle message, or until a timeout occurs, at which point the currently executing cell will be skipped. If True, then an error will be raised after the first timeout. This option generally does not need to be used, but may be useful in contexts where there is the possibility of executing notebooks with memory-consuming infinite loops.

record_timing#: If True (default), then the execution timings of each cell will be stored in the metadata of the notebook.

register_output_hook(msg_id: str, hook: 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: OutputWidget) → None#: Unregisters an override object that handles output/clear_output instead

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

resources: dict[str, Any]#: Additional resources used in the conversion process. For example, passing {'metadata': {'path': run_path}} sets the execution path to run_path.

set_widgets_metadata() → None#: Set with widget metadata.

setup_kernel(**kwargs: Any) → Generator[None, None, None]#

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#: The time to wait (in seconds) for Shell output before retrying. This generally doesn’t need to be set, but if one needs to check for dead kernels at a faster rate this can help.

shutdown_kernel#: If graceful (default), then the kernel is given time to clean up after executing all cells, e.g., to execute its atexit hooks. If immediate, then the kernel is signaled to immediately terminate.

skip_cells_with_tag#: Name of the cell tag to use to denote a cell that should be skipped.

start_new_kernel(**kwargs: Any) → Any#

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: Any) → Any#

Creates a new kernel client.

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

startup_timeout#: The time to wait (in seconds) for the kernel to start. If kernel startup takes longer, a RuntimeError is raised.

store_widget_state#: If True (default), then the state of the Jupyter widgets created at the kernel will be stored in the metadata of the notebook.

timeout#

The time to wait (in seconds) for output from executions. If a cell execution takes longer, a TimeoutError is raised.

None or -1 will disable the timeout. If timeout_func is set, it overrides timeout.

timeout_func: Callable[[...], int | None] | None#

A callable which, when given the cell source as input, returns the time to wait (in seconds) for output from cell executions. If a cell execution takes longer, a TimeoutError is raised.

wait_for_reply(**kwargs: Any) → Any#: Wait for a message reply.

widget_registry: dict[str, dict[str, Any]]#

nbclient.execute(nb: NotebookNode, cwd: str | None = None, km: KernelManager | None = None, **kwargs: Any) → NotebookNode#

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 package

Contents

nbclient package#

Subpackages#

Submodules#

nbclient.client module#

nbclient.exceptions module#

Module contents#