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 aCellExecutionError
is raised, except if the error name is inallow_error_names
. IfTrue
, 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 byjupyter_client.AsyncKernelManager.start_kernel()
, which includescwd
.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:
- 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 byAsyncKernelManager.start_kernel()
, which includescwd
.
- 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.
- 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 –
Any option for
self.kernel_manager_class.start_kernel()
. Because that defaults to AsyncKernelManager, this will likely include options accepted byjupyter_client.AsyncKernelManager.start_kernel()
, which includescwd
.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:
- 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 theallow_errors
orallow_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, aCellExecutionError
will be raised. If True,CellExecutionError
will be raised for any error that occurs while executing the notebook. This overrides theallow_errors
andallow_error_names
options and theraises-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
andcell_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 kwargscell`, ``cell_index
andexecute_reply
.
- on_cell_execute#
A callable which executes just before a code cell is executed. Called with kwargs
cell
andcell_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
andexecute_reply
.
- on_cell_start#
A callable which executes before a cell is executed and before non-executing cells are skipped. Called with kwargs
cell
andcell_index
.
- 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:
- 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. IfTrue
, 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
- resources: dict[str, Any]#
Additional resources used in the conversion process. For example, passing
{'metadata': {'path': run_path}}
sets the execution path torun_path
.
- 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 itsatexit
hooks. Ifimmediate
, 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 byAsyncKernelManager.start_kernel()
, which includescwd
.
- 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. Iftimeout_func
is set, it overridestimeout
.
- 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 settingtimeout_func
will cause the client to default to using thetimeout
trait for all cells. Thetimeout_func
trait overridestimeout
if it is notNone
.
- 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.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 aCellExecutionError
is raised, except if the error name is inallow_error_names
. IfTrue
, 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 byjupyter_client.AsyncKernelManager.start_kernel()
, which includescwd
.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:
- 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 byAsyncKernelManager.start_kernel()
, which includescwd
.
- 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.
- 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 –
Any option for
self.kernel_manager_class.start_kernel()
. Because that defaults to AsyncKernelManager, this will likely include options accepted byjupyter_client.AsyncKernelManager.start_kernel()
, which includescwd
.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:
- 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 theallow_errors
orallow_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, aCellExecutionError
will be raised. If True,CellExecutionError
will be raised for any error that occurs while executing the notebook. This overrides theallow_errors
andallow_error_names
options and theraises-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.
- 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
andcell_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 kwargscell`, ``cell_index
andexecute_reply
.
- on_cell_execute#
A callable which executes just before a code cell is executed. Called with kwargs
cell
andcell_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
andexecute_reply
.
- on_cell_start#
A callable which executes before a cell is executed and before non-executing cells are skipped. Called with kwargs
cell
andcell_index
.
- 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:
- 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. IfTrue
, 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
- resources: dict[str, Any]#
Additional resources used in the conversion process. For example, passing
{'metadata': {'path': run_path}}
sets the execution path torun_path
.
- 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 itsatexit
hooks. Ifimmediate
, 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 byAsyncKernelManager.start_kernel()
, which includescwd
.
- 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. Iftimeout_func
is set, it overridestimeout
.
- 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 settingtimeout_func
will cause the client to default to using thetimeout
trait for all cells. Thetimeout_func
trait overridestimeout
if it is notNone
.
- 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