pytest_notebook.execution module

Execution of notebooks.

exception pytest_notebook.execution.CoverageError

Bases: Exception

Exception for errors involving coverage.

classmethod from_cell_output(phase, output)

Instantiate from a code cell output.

classmethod from_exec_reply(phase, reply)

Instantiate from an execution reply.

class pytest_notebook.execution.CoverageNotebookClient(**kwargs: Any)

Bases: NotebookClient

A NotebookClient that records coverage data.

Code coverage is recorded using coverage.py:

• Before running any cells, we run a mock cell, containing coverage setup code.

• After execution, we run a mock cell, containing code to teardown the coverage, and print the coverage data to /cell/output/0/text.

• Coverage data is then saved in resources[“coverage_data”]

Raises:

CoverageError – If a coverage cell execution errors.

_all_trait_default_generators: dict[str, t.Any] = {'_display_id_map': <bound method TraitType.default of <traitlets.traitlets.Dict object>>, 'allow_error_names': <bound method TraitType.default of <traitlets.traitlets.List object>>, 'allow_errors': <bound method TraitType.default of <traitlets.traitlets.Bool object>>, 'config': <bound method TraitType.default of <traitlets.traitlets.Instance object>>, 'cov_config_file': <bound method TraitType.default of <traitlets.traitlets.Unicode object>>, 'cov_source': <bound method TraitType.default of <traitlets.traitlets.List object>>, 'coverage': <bound method TraitType.default of <traitlets.traitlets.Bool object>>, 'display_data_priority': <bound method TraitType.default of <traitlets.traitlets.List object>>, 'extra_arguments': <bound method TraitType.default of <traitlets.traitlets.List object>>, 'force_raise_errors': <bound method TraitType.default of <traitlets.traitlets.Bool object>>, 'interrupt_on_timeout': <bound method TraitType.default of <traitlets.traitlets.Bool object>>, 'iopub_timeout': <bound method TraitType.default of <traitlets.traitlets.Int object>>, 'ipython_hist_file': <bound method TraitType.default of <traitlets.traitlets.Unicode object>>, 'kernel_manager_class': <traitlets.traitlets.DefaultHandler object>, 'kernel_name': <bound method TraitType.default of <traitlets.traitlets.Unicode object>>, 'log': <traitlets.traitlets.DefaultHandler object>, 'on_cell_complete': <bound method TraitType.default of <traitlets.traitlets.Callable object>>, 'on_cell_error': <bound method TraitType.default of <traitlets.traitlets.Callable object>>, 'on_cell_execute': <bound method TraitType.default of <traitlets.traitlets.Callable object>>, 'on_cell_start': <bound method TraitType.default of <traitlets.traitlets.Callable object>>, 'on_notebook_complete': <bound method TraitType.default of <traitlets.traitlets.Callable object>>, 'on_notebook_error': <bound method TraitType.default of <traitlets.traitlets.Callable object>>, 'on_notebook_start': <bound method TraitType.default of <traitlets.traitlets.Callable object>>, 'parent': <bound method TraitType.default of <traitlets.traitlets.Instance object>>, 'raise_on_iopub_timeout': <bound method TraitType.default of <traitlets.traitlets.Bool object>>, 'record_timing': <bound method TraitType.default of <traitlets.traitlets.Bool object>>, 'resources': <bound method TraitType.default of <traitlets.traitlets.Dict object>>, 'shell_timeout_interval': <bound method TraitType.default of <traitlets.traitlets.Int object>>, 'shutdown_kernel': <bound method TraitType.default of <traitlets.traitlets.Enum object>>, 'skip_cells_with_tag': <bound method TraitType.default of <traitlets.traitlets.Unicode object>>, 'startup_timeout': <bound method TraitType.default of <traitlets.traitlets.Int object>>, 'store_widget_state': <bound method TraitType.default of <traitlets.traitlets.Bool object>>, 'timeout': <bound method TraitType.default of <traitlets.traitlets.Int object>>, 'timeout_func': <bound method TraitType.default of <traitlets.traitlets.Any object>>}

_descriptors = [<traitlets.traitlets.ObserveHandler object>, <traitlets.traitlets.Dict object>, <traitlets.traitlets.DefaultHandler object>, <traitlets.traitlets.DefaultHandler object>, <traitlets.traitlets.ValidateHandler object>, <traitlets.traitlets.List object>, <traitlets.traitlets.Bool object>, <traitlets.traitlets.Instance object>, <traitlets.traitlets.Unicode object>, <traitlets.traitlets.List object>, <traitlets.traitlets.Bool object>, <traitlets.traitlets.List object>, <traitlets.traitlets.List object>, <traitlets.traitlets.Bool object>, <traitlets.traitlets.Bool object>, <traitlets.traitlets.Int object>, <traitlets.traitlets.Unicode object>, <traitlets.traitlets.Type object>, <traitlets.traitlets.Unicode object>, <traitlets.traitlets.Any object>, <traitlets.traitlets.Callable object>, <traitlets.traitlets.Callable object>, <traitlets.traitlets.Callable object>, <traitlets.traitlets.Callable object>, <traitlets.traitlets.Callable object>, <traitlets.traitlets.Callable object>, <traitlets.traitlets.Callable object>, <traitlets.traitlets.Instance object>, <traitlets.traitlets.Bool object>, <traitlets.traitlets.Bool object>, <traitlets.traitlets.Dict object>, <traitlets.traitlets.Int object>, <traitlets.traitlets.Enum object>, <traitlets.traitlets.Unicode object>, <traitlets.traitlets.Int object>, <traitlets.traitlets.Bool object>, <traitlets.traitlets.Int object>, <traitlets.traitlets.Any object>]

_instance_inits = [<bound method ObserveHandler.instance_init of <traitlets.traitlets.ObserveHandler object>>, <bound method BaseDescriptor.instance_init of <traitlets.traitlets.DefaultHandler object>>, <bound method BaseDescriptor.instance_init of <traitlets.traitlets.DefaultHandler object>>, <bound method ValidateHandler.instance_init of <traitlets.traitlets.ValidateHandler object>>, <bound method Instance.instance_init of <traitlets.traitlets.Instance object>>, <bound method Type.instance_init of <traitlets.traitlets.Type object>>, <bound method BaseDescriptor.instance_init of <traitlets.traitlets.Callable object>>, <bound method BaseDescriptor.instance_init of <traitlets.traitlets.Callable object>>, <bound method BaseDescriptor.instance_init of <traitlets.traitlets.Callable object>>, <bound method BaseDescriptor.instance_init of <traitlets.traitlets.Callable object>>, <bound method BaseDescriptor.instance_init of <traitlets.traitlets.Callable object>>, <bound method BaseDescriptor.instance_init of <traitlets.traitlets.Callable object>>, <bound method BaseDescriptor.instance_init of <traitlets.traitlets.Callable object>>, <bound method Instance.instance_init of <traitlets.traitlets.Instance object>>]

_static_immutable_initial_values: dict[str, t.Any] = {'allow_errors': False, 'cov_config_file': None, 'coverage': False, 'force_raise_errors': False, 'interrupt_on_timeout': False, 'iopub_timeout': 4, 'ipython_hist_file': ':memory:', 'kernel_name': '', 'parent': None, 'raise_on_iopub_timeout': False, 'record_timing': True, 'shell_timeout_interval': 5, 'skip_cells_with_tag': 'skip-execution', 'startup_timeout': 60, 'store_widget_state': True, 'timeout': None, 'timeout_func': None}

_trait_default_generators = {}

_traits: dict[str, t.Any] = {'_display_id_map': <traitlets.traitlets.Dict object>, 'allow_error_names': <traitlets.traitlets.List object>, 'allow_errors': <traitlets.traitlets.Bool object>, 'config': <traitlets.traitlets.Instance object>, 'cov_config_file': <traitlets.traitlets.Unicode object>, 'cov_source': <traitlets.traitlets.List object>, 'coverage': <traitlets.traitlets.Bool object>, 'display_data_priority': <traitlets.traitlets.List object>, 'extra_arguments': <traitlets.traitlets.List object>, 'force_raise_errors': <traitlets.traitlets.Bool object>, 'interrupt_on_timeout': <traitlets.traitlets.Bool object>, 'iopub_timeout': <traitlets.traitlets.Int object>, 'ipython_hist_file': <traitlets.traitlets.Unicode object>, 'kernel_manager_class': <traitlets.traitlets.Type object>, 'kernel_name': <traitlets.traitlets.Unicode object>, 'log': <traitlets.traitlets.Any object>, 'on_cell_complete': <traitlets.traitlets.Callable object>, 'on_cell_error': <traitlets.traitlets.Callable object>, 'on_cell_execute': <traitlets.traitlets.Callable object>, 'on_cell_start': <traitlets.traitlets.Callable object>, 'on_notebook_complete': <traitlets.traitlets.Callable object>, 'on_notebook_error': <traitlets.traitlets.Callable object>, 'on_notebook_start': <traitlets.traitlets.Callable object>, 'parent': <traitlets.traitlets.Instance object>, 'raise_on_iopub_timeout': <traitlets.traitlets.Bool object>, 'record_timing': <traitlets.traitlets.Bool object>, 'resources': <traitlets.traitlets.Dict object>, 'shell_timeout_interval': <traitlets.traitlets.Int object>, 'shutdown_kernel': <traitlets.traitlets.Enum object>, 'skip_cells_with_tag': <traitlets.traitlets.Unicode object>, 'startup_timeout': <traitlets.traitlets.Int object>, 'store_widget_state': <traitlets.traitlets.Bool object>, 'timeout': <traitlets.traitlets.Int object>, 'timeout_func': <traitlets.traitlets.Any object>}

async async_execute(reset_kc: bool = False, **kwargs) → 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

cov_config_file

Determines what coverage configuration file to read.

cov_source

A list of file paths or package names to measure coverage for.

coverage

Record coverage data, with coverage.py.

async coverage_setup() → None

Set up coverage, by executing a code cell.

async coverage_teardown() → str

Tear down coverage, by executing a code cell.

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

class pytest_notebook.execution.ExecuteResult(exec_error: None | Exception, notebook: NotebookNode, resources: dict)

Bases: object

Result of notebook execution.

Parameters:

• exec_error (Optional[Exception]) – Execution exception. This value is accessible, after initialization, via the exec_error attribute.

• notebook (nbformat.notebooknode.NotebookNode) – Executed notebook. This value is accessible, after initialization, via the notebook attribute.

• resources (dict) – Resources dictionary. This value is accessible, after initialization, via the resources attribute.

coverage_data(debug=None, no_disk=True)

Return coverage.py coverage data as coverage.CoverageData.

property coverage_dict: dict

Return coverage.py coverage data as a dict.

exec_error: None | Exception

property has_coverage

Return whether coverage information is available.

notebook: NotebookNode

resources: dict

pytest_notebook.execution.coverage_code_setup(source: str | None, config_file: None | str | Path) → str

pytest_notebook.execution.coverage_code_teardown() → str

pytest_notebook.execution.execute_notebook(notebook: NotebookNode, *, resources: dict | None = None, cwd: str | None = None, timeout: int = 120, allow_errors: bool = False, with_coverage: bool = False, cov_config_file: str | None = None, cov_source: List[str] | None = None) → ExecuteResult

Execute a notebook.

Parameters:

• cwd – Path to the directory which the notebook will run in (default is temporary directory).

• timeout – The maximum time to wait (in seconds) for execution of each cell.

• allow_errors – If False, execution is stopped after the first unexpected exception (cells tagged raises-exception are expected)

• with_coverage – Record code coverage with coverage.py

• cov_config_file – Determines what coverage configuration file to read.

• cov_source – A list of file paths or package names to measure coverage for.

Returns:

(exception or None, new_notebook, resources)