Preprocessors

See also

Configuration options

Configurable options for the nbconvert application

class nbconvert.preprocessors.Preprocessor(**kwargs)

A configurable preprocessor

Inherit from this class if you wish to have configurability for your preprocessor.

Any configurable traitlets this class exposed will be configurable in profiles using c.SubClassName.attribute = value

You can overwrite preprocess_cell() to apply a transformation independently on each cell or preprocess() if you prefer your own logic. See corresponding docstring for information.

Disabled by default and can be enabled via the config by

‘c.YourPreprocessorName.enabled = True’

__init__(**kw)

Public constructor

Parameters
  • config (Config) – Configuration file structure

  • **kw – Additional keyword arguments passed to parent

preprocess(nb, resources)

Preprocessing to apply on each notebook.

Must return modified nb, resources.

If you wish to apply your preprocessing to each cell, you might want to override preprocess_cell method instead.

Parameters
  • nb (NotebookNode) – Notebook being converted

  • resources (dictionary) – Additional resources used in the conversion process. Allows preprocessors to pass variables into the Jinja engine.

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

Specialized preprocessors

Converting and extracting figures

class nbconvert.preprocessors.ConvertFiguresPreprocessor(**kwargs)

Converts all of the outputs in a notebook from one format to another.

class nbconvert.preprocessors.SVG2PDFPreprocessor(**kwargs)

Converts all of the outputs in a notebook from SVG to PDF.

class nbconvert.preprocessors.ExtractOutputPreprocessor(**kwargs)

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)

Preprocessor for latex destined documents.

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

class nbconvert.preprocessors.HighlightMagicsPreprocessor(**kwargs)

Detects and tags code cells that use a different languages than Python.

Metadata and header control

class nbconvert.preprocessors.ClearMetadataPreprocessor(**kwargs)

Removes all the metadata from all code cells in a notebook.

class nbconvert.preprocessors.CSSHTMLHeaderPreprocessor(**kwargs)

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)

Removes the output from all code cells in a notebook.

class nbconvert.preprocessors.RegexRemovePreprocessor(**kwargs)

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)

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)

Executes all the cells in a notebook

preprocess(nb, resources=None, km=None)

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