43
nbconvert Documentation, Release 5.0.0.dev
3.3.2 Using different preprocessors
To extract the figures when using the HTML exporter, we will want to change which Preprocessors
we are using.
There are several preprocessors that come with nbconvert, including one called the
ExtractOutputPreprocessor.
The ExtractOutputPreprocessor is responsible for crawling the notebook, finding all of the figures, and
putting them into the resources directory, as well as choosing the key (i.e. filename_xx_y.extension) that
can replace the figure inside the template. To enable the ExtractOutputPreprocessor, we must add it to the
exporter’s list of preprocessors:
In [9]: # create a configuration object that changes the preprocessors
from traitlets.config import Config
c = Config()
c.HTMLExporter.preprocessors = ['nbconvert.preprocessors.ExtractOutputPreprocessor']
# create the new exporter using the custom config
html_exporter_with_figs = HTMLExporter(config=c)
html_exporter_with_figs.preprocessors
Out[9]: ['nbconvert.preprocessors.ExtractOutputPreprocessor']
We can compare the resultofconvertingthe notebook using the originalHTML exporterandour new customized one:
In [10]: (_, resources)
= html_exporter.from_notebook_node(jake_notebook)
(_, resources_with_fig) = html_exporter_with_figs.from_notebook_node(jake_notebook)
print("resources without figures:")
print(sorted(resources.keys()))
print("\nresources with extracted figures (notice that there's one more field called 'outputs'):")
print(sorted(resources_with_fig.keys()))
print("\nthe actual figures are:")
print(sorted(resources_with_fig['outputs'].keys()))
resources without figures:
['inlining', 'metadata', 'output_extension', 'raw_mimetypes']
resources with extracted figures (notice that there's one more field called 'outputs'):
['inlining', 'metadata', 'output_extension', 'outputs', 'raw_mimetypes']
the actual figures are:
['output_13_1.png', 'output_16_0.png', 'output_18_1.png', 'output_3_0.png', 'output_5_0.png']
3.4 Custom Preprocessors
There are an endless number of transformations that you may want to apply to a notebook. In particularly complicated
cases,youmay want to actually create yourown Preprocessor. Above,when we customized the list ofpreproces-
sors accepted by the HTMLExporter, we passed in a string – this can be any valid module name. So, if you create
your own preprocessor, you can include it in that same list and it will be used by the exporter.
Tocreateyourownpreprocessor,youwillneedtosubclass fromnbconvert.preprocessors.Preprocessor
and overwrite either the preprocess and/or preprocess_cell methods.
14
Chapter 3. Using nbconvert as a library