Preprocessors#
See also
- Configuration options
Configurable options for the nbconvert application
- class nbconvert.preprocessors.Preprocessor(**kwargs: Any)#
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 orpreprocess()
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: Any)#
Converts all of the outputs in a notebook from one format to another.
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.
Metadata and header control#
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 torun_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