nbqol.process.analyze#

Analysis utilities for Jupyter notebooks.

This module provides tools for notebook execution, comparing notebook outputs, analyzing cell dependencies, and verifying notebook content.

Functions

check_notebook_runs(notebook_path_str[, ...])

Check if a notebook runs without errors.

compare_notebooks(notebook1_path, notebook2_path)

Compare two notebooks and return differences.

execute_notebook([notebook_path_str, ...])

Execute a notebook and save the result with outputs.

notebook_cell_dependencies(notebook_path_str)

Analyze a notebook to find dependencies between cells.

notebook_path()

Get the path to the current notebook.

run_notebook_as_script(notebook_path_str[, ...])

Convert a notebook to a Python script and run it as a standalone script.

verify_notebook_variables(notebook_path_str, ...)

Execute a notebook and verify that certain variables are defined and non-None.

Classes

NotebookNode(*args, **kw)

A dict-like node with attribute-access

Path(*args, **kwargs)

PurePath subclass that can make system calls.
execute_notebook(notebook_path_str: str | None = None, output_path: str | None = None, timeout: int = 600, allow_errors: bool = False, kernel_name: str | None = None) → str[source]#

Execute a notebook and save the result with outputs.

Parameters:

  • notebook_path_str – Path to the notebook file. If None, uses the current notebook.

  • output_path – Path to save the executed notebook. If None, uses a ‘_executed’ suffix on the original name.

  • timeout – Execution timeout in seconds.

  • allow_errors – If True, continue execution even if cells raise exceptions.

  • kernel_name – Name of the kernel to use. If None, uses the default kernel.

Returns:

Path to the saved executed notebook.

Examples

>>> execute_notebook('my_notebook.ipynb', allow_errors=True)
'my_notebook_executed.ipynb'
compare_notebooks(notebook1_path: str, notebook2_path: str, ignore_outputs: bool = False, ignore_metadata: bool = True) → Dict[str, Any][source]#

Compare two notebooks and return differences.

Parameters:

  • notebook1_path – Path to the first notebook file.

  • notebook2_path – Path to the second notebook file.

  • ignore_outputs – If True, don’t compare cell outputs.

  • ignore_metadata – If True, don’t compare notebook metadata.

Returns:

Dictionary of differences with cells that differ.

Examples

>>> diff = compare_notebooks('notebook1.ipynb', 'notebook2.ipynb')
>>> print(f"Found {len(diff['cells'])} different cells")
check_notebook_runs(notebook_path_str: str, timeout: int = 600, kernel_name: str | None = None) → Tuple[bool, str][source]#

Check if a notebook runs without errors.

Parameters:

  • notebook_path_str – Path to the notebook file.

  • timeout – Execution timeout in seconds.

  • kernel_name – Name of the kernel to use. If None, uses the default kernel.

Returns:

bool, message: str) indicating if the notebook ran successfully.

Return type:

Tuple of (success

Examples

>>> success, msg = check_notebook_runs('my_notebook.ipynb')
>>> if success:
...     print("Notebook runs successfully")
... else:
...     print(f"Notebook failed: {msg}")
verify_notebook_variables(notebook_path_str: str, variables: List[str], timeout: int = 600) → Dict[str, Any][source]#

Execute a notebook and verify that certain variables are defined and non-None.

Parameters:

  • notebook_path_str – Path to the notebook file.

  • variables – List of variable names to check.

  • timeout – Execution timeout in seconds.

Returns:

Dictionary mapping variable names to their status.

Examples

>>> results = verify_notebook_variables('my_notebook.ipynb',
...                                    ['df', 'model', 'accuracy'])
>>> for var, status in results.items():
...     print(f"{var}: {status['exists']}, {status.get('type', 'N/A')}")
run_notebook_as_script(notebook_path_str: str, args: List[str] | None = None, env: Dict[str, str] | None = None) → Tuple[int, str, str][source]#

Convert a notebook to a Python script and run it as a standalone script.

Parameters:

  • notebook_path_str – Path to the notebook file.

  • args – Command line arguments to pass to the script.

  • env – Environment variables to set for the script execution.

Returns:

Tuple of (return_code, stdout, stderr).

Examples

>>> code, stdout, stderr = run_notebook_as_script('my_notebook.ipynb')
>>> if code == 0:
...     print("Script ran successfully")
... else:
...     print(f"Script failed with error: {stderr}")
notebook_cell_dependencies(notebook_path_str: str) → Dict[int, Set[int]][source]#

Analyze a notebook to find dependencies between cells.

This function looks for variable definitions and usage to determine which cells depend on each other.

Parameters:

notebook_path_str – Path to the notebook file.

Returns:

Dictionary mapping cell indices to sets of indices they depend on.

Examples

>>> deps = notebook_cell_dependencies('my_notebook.ipynb')
>>> for cell_idx, dependencies in deps.items():
...     print(f"Cell {cell_idx} depends on cells: {dependencies}")