nbqol.process.reformat#

Notebook conversion utilities for extending nbconvert functionality.

This module provides extended notebook conversion capabilities beyond standard nbconvert, including VSCode-compatible interactive Python scripts, cleaning options to remove non-essential content, and output conversion utilities.

Functions

clean_notebook([notebook_path_str, ...])

Clean a Jupyter notebook by removing specified elements.

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.

notebook_path()

Get the path to the current notebook.

Classes

CleaningPreprocessor(**kwargs)

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

HTMLExporter(**kwargs)

Exports a basic HTML document.

MarkdownExporter(**kwargs)

Exports to a markdown document (.md)

NotebookNode(*args, **kw)

A dict-like node with attribute-access

Path(*args, **kwargs)

PurePath subclass that can make system calls.

Preprocessor(**kwargs)

A configurable preprocessor

PythonExporter(**kwargs)

Exports a Python code file.

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.
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()
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_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'
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 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

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