nbclient package¶
Subpackages¶
Submodules¶
nbclient.client module¶
-
class
nbclient.client.
NotebookClient
(**kwargs)¶ Bases:
traitlets.config.configurable.LoggingConfigurable
Encompasses a Client for executing cells in a notebook
-
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 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: 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
- 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 byAsyncKernelManager.start_kernel()
, which includescwd
.
-
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]¶
-
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 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)¶ 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
: List¶ An instance of a Python list.
-
kernel_manager_class
: jupyter_client.manager.KernelManager¶ A trait whose value must be a subclass of a specified class.
-
on_comm_open_jupyter_widget
(msg: Dict)¶
-
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
- Returns
output – The execution output payload (or None for no output).
- Return type
- Raises
CellExecutionComplete – Once a message arrives which indicates computation completeness.
-
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
-
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 ofvalue_trait
,per_key_traits
.
-
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.
-
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 byAsyncKernelManager.start_kernel()
, which includescwd
.
-
start_new_kernel_client
(**kwargs)¶ Creates a new kernel client.
- Returns
kc – Kernel client as created by the kernel manager
km
.- Return type
KernelClient
-
timeout_func
: Any¶ A trait which allows any value.
-
wait_for_reply
(**kwargs)¶
-
async
-
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.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)
-
classmethod
-
exception
nbclient.exceptions.
CellTimeoutError
¶ Bases:
TimeoutError
,nbclient.exceptions.CellControlSignal
A custom exception to capture when a cell has timed out during execution.
-
exception
nbclient.exceptions.
DeadKernelError
¶ Bases:
RuntimeError