nbqol.process#

Tools for processing and transforming Jupyter notebooks.

This module contains utilities for analyzing, cleaning, reformatting, and executing Jupyter notebooks.

Functions

`check_notebook_runs`(notebook_path_str[, ...])	Check if a notebook runs without errors.
`clean_notebook`([notebook_path_str, ...])	Clean a Jupyter notebook by removing specified elements.
`compare_notebooks`(notebook1_path, notebook2_path)	Compare two notebooks and return differences.
`convert_notebook`([notebook_path_str, ...])	Convert a Jupyter notebook to different formats with extended options.
`convert_to_vscode_script`([...])	Convert a Jupyter notebook to a VSCode-compatible Python script with cell markers.
`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.
`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

`CleaningPreprocessor`(**kwargs)	Notebook preprocessor that removes specified elements like markdown cells, intermediate executions, large outputs, or images.
`VSCodeCellExporter`(**kwargs)	Exporter that converts Jupyter notebooks to VSCode-compatible Python scripts with cell markers.
`WidgetConverter`(**kwargs)	Converts ipywidget outputs to other formats for better compatibility or static rendering.

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")

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'

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}")

convert_notebook(notebook_path_str: str | None = None, output_path: str | None = None, to_format: str = 'python', clean_options: dict | None = None, widget_format: str | None = None) → str[source]#

Convert a Jupyter notebook to different formats with extended options.

Parameters:

notebook_path_str – Path to the notebook file. If None, uses the current notebook.
output_path – Path to save the converted file. If None, determines based on format.
to_format – Target format (‘python’, ‘vscode_python’, ‘html’, ‘markdown’)
clean_options – Dictionary of cleaning options (see clean_notebook)
widget_format – How to convert ipywidgets (‘html’, ‘text’, or None to keep as-is)

Returns:

Path to the saved converted file.

Examples

>>> convert_notebook('my_notebook.ipynb', to_format='vscode_python',
...                 clean_options={'remove_markdown': True},
...                 widget_format='html')
'my_notebook.py'

clean_notebook(notebook_path_str: str | None = None, output_path: str | None = None, remove_markdown: bool = False, remove_intermediates: bool = False, remove_images: bool = False, remove_large_outputs: bool = False, large_output_threshold: int = 1000) → str[source]#

Clean a Jupyter notebook by removing specified elements.

Parameters:

notebook_path_str – Path to the notebook file. If None, uses the current notebook.
output_path – Path to save the cleaned notebook. If None, uses a ‘_clean’ suffix on the original name.
remove_markdown – If True, remove non-header markdown cells
remove_intermediates – If True, remove intermediate expressions
remove_images – If True, remove image outputs
remove_large_outputs – If True, remove outputs exceeding the threshold
large_output_threshold – Size threshold for large outputs in characters

Returns:

Path to the saved cleaned notebook.

Examples

>>> clean_notebook('my_notebook.ipynb', remove_markdown=True, remove_images=True)
'my_notebook_clean.ipynb'

convert_to_vscode_script(notebook_path_str: str | None = None, output_path: str | None = None) → str[source]#

Convert a Jupyter notebook to a VSCode-compatible Python script with cell markers.

Parameters:

notebook_path_str – Path to the notebook file. If None, uses the current notebook.
output_path – Path to save the converted script. If None, uses the same name as the notebook with a .py extension.

Returns:

Path to the saved Python script.

Examples

>>> convert_to_vscode_script('my_notebook.ipynb', 'my_script.py')
'my_script.py'

>>> # Convert current notebook
>>> script_path = convert_to_vscode_script()

class VSCodeCellExporter(**kwargs: Any)[source]#

Bases: PythonExporter

Exporter that converts Jupyter notebooks to VSCode-compatible Python scripts with cell markers.

This exporter creates Python files that can be executed cell-by-cell in VSCode using the #%% cell markers that VSCode recognizes for interactive execution.

from_notebook_node(nb, resources=None, **kwargs)[source]#

Convert a notebook to a string with VSCode cell markers.

Parameters:

nb – Notebook node
resources – Resources dict
**kwargs – Additional arguments

Returns:

Tuple containing the converted content and resources dict

class WidgetConverter(**kwargs: Any)[source]#

Bases: Preprocessor

Converts ipywidget outputs to other formats for better compatibility or static rendering.

__init__(widget_format: str = 'html', **kwargs)[source]#

Initialize the widget converter.

Parameters:

widget_format – Target format for widget conversion (‘html’, ‘image’, or ‘text’)
**kwargs – Additional arguments

preprocess_cell(cell, resources, index)[source]#

Process each cell, converting widget outputs to the specified format.

Parameters:

cell – The notebook cell to process
resources – Resources dict
index – Cell index

Returns:

Tuple of the processed cell and resources dict

class CleaningPreprocessor(**kwargs: Any)[source]#

Bases: Preprocessor

Notebook preprocessor that removes specified elements like markdown cells, intermediate executions, large outputs, or images.

__init__(remove_markdown: bool = False, remove_intermediates: bool = False, remove_images: bool = False, remove_large_outputs: bool = False, large_output_threshold: int = 1000, **kwargs)[source]#

Initialize the cleaning preprocessor.

Parameters:

remove_markdown – If True, remove all non-header markdown cells
remove_intermediates – If True, remove cells that don’t affect later execution
remove_images – If True, remove image outputs
remove_large_outputs – If True, remove outputs exceeding the threshold
large_output_threshold – Size threshold in characters for large outputs
**kwargs – Additional arguments

preprocess_cell(cell, resources, index)[source]#

Apply preprocessing to each cell based on configured options.

Parameters:

cell – The notebook cell to process
resources – Resources dict
index – Cell index

Returns:

Tuple of the processed cell and resources dict

Modules

`analyze`	Analysis utilities for Jupyter notebooks.
`reformat`	Notebook conversion utilities for extending nbconvert functionality.