Preprocessors#

Specialized preprocessors#

Converting and extracting figures#

class nbconvert.preprocessors.ConvertFiguresPreprocessor(**kwargs: Any)#: Converts all of the outputs in a notebook from one format to another.

class nbconvert.preprocessors.SVG2PDFPreprocessor(**kwargs: Any)#: Converts all of the outputs in a notebook from SVG to PDF.

class nbconvert.preprocessors.ExtractOutputPreprocessor(**kwargs: Any)#: Extracts all of the outputs from the notebook file. The extracted outputs are returned in the ‘resources’ dictionary.

Converting text#

class nbconvert.preprocessors.LatexPreprocessor(**kwargs: Any)#

Preprocessor for latex destined documents.

Populates the latex key in the resources dict, adding definitions for pygments highlight styles.

Sets the authors, date and title of the latex document, overriding the values given in the metadata.

class nbconvert.preprocessors.HighlightMagicsPreprocessor(**kwargs: Any)#: Detects and tags code cells that use a different languages than Python.

Metadata and header control#

class nbconvert.preprocessors.ClearMetadataPreprocessor(**kwargs: Any)#: Removes all the metadata from all code cells in a notebook.

class nbconvert.preprocessors.CSSHTMLHeaderPreprocessor(**kwargs: Any)#: Preprocessor used to pre-process notebook for HTML output. Adds IPython notebook front-end CSS and Pygments CSS to HTML output.

Removing cells, inputs, and outputs#

class nbconvert.preprocessors.ClearOutputPreprocessor(**kwargs: Any)#: Removes the output from all code cells in a notebook.

class nbconvert.preprocessors.RegexRemovePreprocessor(**kwargs: Any)#

Removes cells from a notebook that match one or more regular expression.

For each cell, the preprocessor checks whether its contents match the regular expressions in the patterns traitlet which is a list of unicode strings. If the contents match any of the patterns, the cell is removed from the notebook.

To modify the list of matched patterns, modify the patterns traitlet. For example, execute the following command to convert a notebook to html and remove cells containing only whitespace:

jupyter nbconvert --RegexRemovePreprocessor.patterns="['\s*\Z']" mynotebook.ipynb

The command line argument sets the list of patterns to '\s*\Z' which matches an arbitrary number of whitespace characters followed by the end of the string.

See https://regex101.com/ for an interactive guide to regular expressions (make sure to select the python flavor). See https://docs.python.org/library/re.html for the official regular expression documentation in python.

class nbconvert.preprocessors.TagRemovePreprocessor(**kwargs: Any)#

Removes inputs, outputs, or cells from a notebook that have tags that designate they are to be removed prior to exporting the notebook.

remove_cell_tags: removes cells tagged with these values
remove_all_outputs_tags: removes entire output areas on cells tagged with these values
remove_single_output_tags: removes individual output objects on outputs tagged with these values
remove_input_tags: removes inputs tagged with these values

Executing Notebooks#

class nbconvert.preprocessors.ExecutePreprocessor(**kwargs: Any)#

Executes all the cells in a notebook

preprocess(nb: NotebookNode, resources: Any = None, km: jupyter_client.manager.KernelManager | None = None) → tuple[nbformat.notebooknode.NotebookNode, dict[str, Any]]#

Preprocess notebook executing each code cell.

The input argument nb is modified in-place.

Note that this function recalls NotebookClient.__init__, which may look wrong. However since the preprocess call acts line an init on execution state it’s expected. Therefore, we need to capture it here again to properly reset because traitlet assignments are not passed. There is a risk if traitlets apply any side effects for dual init. The risk should be manageable, and this approach minimizes side-effects relative to other alternatives.

One alternative but rejected implementation would be to copy the client’s init internals which has already gotten out of sync with nbclient 0.5 release before nbconvert 6.0 released.

Parameters

nb (NotebookNode) – Notebook being executed.
resources (dictionary (optional)) – Additional resources used in the conversion process. For example, passing {'metadata': {'path': run_path}} sets the execution path to run_path.
km (KernelManager (optional)) – Optional kernel manager. If none is provided, a kernel manager will be created.

Returns

nb (NotebookNode) – The executed notebook.
resources (dictionary) – Additional resources used in the conversion process.

preprocess_cell(cell, resources, index)#

Override if you want to apply some preprocessing to each cell. Must return modified cell and resource dictionary.

Parameters

cell (NotebookNode cell) – Notebook cell being processed
resources (dictionary) – Additional resources used in the conversion process. Allows preprocessors to pass variables into the Jinja engine.
index (int) – Index of the cell being processed

class nbconvert.preprocessors.CellExecutionError(traceback: str, ename: str, evalue: str)#: 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.

nbconvert.preprocessors.coalesce_streams(cell, resources, index)#

Merge consecutive sequences of stream output into single stream to prevent extra newlines inserted at flush calls

Parameters

cell (NotebookNode cell) – Notebook cell being processed
resources (dictionary) – Additional resources used in the conversion process. Allows transformers to pass variables into the Jinja engine.
index (int) – Index of the cell being processed