Converting Notebooks to Other Formats¶
The nbconvert
tool allows you to convert an .ipynb
notebook
document file into various static formats. It can also execute notebooks
programmatically.
nbconvert
is both a python library and a command line tool (invoked as
jupyter nbconvert ...
).
The nbconvert
library is also used to implement the ‘Download as’ feature within the
Jupyter Notebook web app.
Contents:
Installing nbconvert¶
See also
- Installing Jupyter
- Nbconvert is part of the Jupyter ecosystem.
Nbconvert is packaged for both pip and conda, so you can install it with:
pip install nbconvert
# OR
conda install nbconvert
If you’re new to Python, we recommend installing Anaconda, a Python distribution which includes nbconvert and the other Jupyter components.
Pandoc¶
For converting markdown to formats other than HTML, nbconvert uses Pandoc (1.12.1 or later).
To install pandoc on Linux, you can generally use your package manager:
sudo apt-get install pandoc
On other platforms, you can get pandoc from their website.
Command-Line Usage¶
The command-line syntax to run the nbconvert
script is:
$ jupyter nbconvert --to FORMAT notebook.ipynb
This will convert the Jupyter document file notebook.ipynb
into the output
format given by the FORMAT
string.
The default output format is html, for which the --to
argument may be
omitted:
$ jupyter nbconvert notebook.ipynb
Jupyter provides a few templates for some output formats, and these can be
specified via an additional --template
argument.
The currently supported export formats are:
--to html
--template full
(default)A full static HTML render of the notebook. This looks very similar to the interactive view.
--template basic
Simplified HTML, useful for embedding in webpages, blogs, etc. This excludes HTML headers.
--to latex
Latex export. This generates
NOTEBOOK_NAME.tex
file, ready for export.--template article
(default)Latex article, derived from Sphinx’s howto template.
--template report
Latex report, providing a table of contents and chapters.
--template basic
Very basic latex output - mainly meant as a starting point for custom templates.
--to pdf
Generates a PDF via latex. Supports the same templates as
--to latex
.--to slides
This generates a Reveal.js HTML slideshow. It must be served by an HTTP server. The easiest way to do this is adding
--post serve
on the command-line. Theserve
post-processor proxies Reveal.js requests to a CDN if no local Reveal.js library is present. To make slides that don’t require an internet connection, just place the Reveal.js library in the same directory where your_talk.slides.html is located, or point to another directory using the--reveal-prefix
alias.--to markdown
Simple markdown output. Markdown cells are unaffected, and code cells indented 4 spaces.
--to rst
Basic reStructuredText output. Useful as a starting point for embedding notebooks in Sphinx docs.
--to script
Convert a notebook to an executable script. This is the simplest way to get a Python (or other language, depending on the kernel) script out of a notebook. If there were any magics in an Jupyter notebook, this may only be executable from an Jupyter session.
--to notebook
New in version 3.0.
This doesn’t convert a notebook to a different format per se, instead it allows the running of nbconvert preprocessors on a notebook, and/or conversion to other notebook formats. For example:
jupyter nbconvert --to notebook --execute mynotebook.ipynb
will open the notebook, execute it, capture new output, and save the result in
mynotebook.nbconvert.ipynb
. By default,nbconvert
will abort conversion if any exceptions occur during execution of a cell. If you specify--allow-errors
(in addition to the--execute
flag) then conversion will continue and the output from any exception will be included in the cell output.jupyter nbconvert --to notebook --nbformat 3 mynotebook
will create a copy of
mynotebook.ipynb
inmynotebook.v3.ipynb
in version 3 of the notebook format.If you want to convert a notebook in-place, you can specify the ouptut file to be the same as the input file:
jupyter nbconvert --to notebook mynb --output mynb
Be careful with that, since it will replace the input file.
Note
nbconvert uses pandoc to convert between various markup languages, so pandoc is a dependency when converting to latex or reStructuredText.
The output file created by nbconvert
will have the same base name as
the notebook and will be placed in the current working directory. Any
supporting files (graphics, etc) will be placed in a new directory with the
same base name as the notebook, suffixed with _files
:
$ jupyter nbconvert notebook.ipynb
$ ls
notebook.ipynb notebook.html notebook_files/
For simple single-file output, such as html, markdown, etc., the output may be sent to standard output with:
$ jupyter nbconvert --to markdown notebook.ipynb --stdout
Multiple notebooks can be specified from the command line:
$ jupyter nbconvert notebook*.ipynb
$ jupyter nbconvert notebook1.ipynb notebook2.ipynb
or via a list in a configuration file, say mycfg.py
, containing the text:
c = get_config()
c.NbConvertApp.notebooks = ["notebook1.ipynb", "notebook2.ipynb"]
and using the command:
$ jupyter nbconvert --config mycfg.py
Configuration options¶
These options can be set in ~/.jupyter/jupyter_nbconvert_config.py
, or
at the command line when you start it.
- Application.log_datefmt : Unicode
Default:
'%Y-%m-%d %H:%M:%S'
The date format used by logging formatters for %(asctime)s
- Application.log_format : Unicode
Default:
'[%(name)s]%(highlevel)s %(message)s'
The Logging format template
- Application.log_level : 0|10|20|30|40|50|’DEBUG’|’INFO’|’WARN’|’ERROR’|’CRITICAL’
Default:
30
Set the log level by value or name.
- JupyterApp.answer_yes : Bool
Default:
False
Answer yes to any prompts.
- JupyterApp.config_file : Unicode
Default:
u''
Full path of a config file.
- JupyterApp.config_file_name : Unicode
Default:
u''
Specify a config file to load.
- JupyterApp.generate_config : Bool
Default:
False
Generate default config file.
- NbConvertApp.export_format : Unicode
Default:
'html'
The export format to be used, either one of the built-in formats, or a dotted object name that represents the import path for an Exporter class
- NbConvertApp.from_stdin : Bool
Default:
False
read a single notebook from stdin.
- NbConvertApp.notebooks : List
Default:
[]
List of notebooks to convert. Wildcards are supported. Filenames passed positionally will be added to the list.
- NbConvertApp.output_base : Unicode
Default:
''
overwrite base name use for output files. can only be used when converting one notebook at a time.
- NbConvertApp.postprocessor_class : DottedOrNone
Default:
u''
PostProcessor class used to write the results of the conversion
- NbConvertApp.use_output_suffix : Bool
Default:
True
Whether to apply a suffix prior to the extension (only relevant when converting to notebook format). The suffix is determined by the exporter, and is usually ‘.nbconvert’.
- NbConvertApp.writer_class : DottedObjectName
Default:
'FilesWriter'
Writer class used to write the results of the conversion
- NbConvertBase.default_language : Unicode
Default:
'ipython'
DEPRECATED default highlight language, please use language_info metadata instead
- NbConvertBase.display_data_priority : List
Default:
['text/html', 'application/pdf', 'text/latex', 'image/svg+xml...
An ordered list of preferred output type, the first encountered will usually be used when converting discarding the others.
- Exporter.default_preprocessors : List
Default:
['nbconvert.preprocessors.ClearOutputPreprocessor', 'nbconver...
List of preprocessors available by default, by name, namespace, instance, or type.
- Exporter.file_extension : FilenameExtension
Default:
'.txt'
Extension of the file that should be written to disk
- Exporter.preprocessors : List
Default:
[]
List of preprocessors, by name or namespace, to enable.
- TemplateExporter.filters : Dict
Default:
{}
Dictionary of filters, by name and namespace, to add to the Jinja environment.
- TemplateExporter.raw_mimetypes : List
Default:
[]
formats of raw cells to be included in this Exporter’s output.
- TemplateExporter.template_extension : Unicode
Default:
'.tpl'
No description
- TemplateExporter.template_file : Unicode
Default:
u''
Name of the template file to use
- TemplateExporter.template_path : List
Default:
['.']
No description
- LatexExporter.template_extension : Unicode
Default:
'.tplx'
No description
- NotebookExporter.nbformat_version : 1|2|3|4
Default:
4
The nbformat version to write. Use this to downgrade notebooks.
- PDFExporter.bib_command : List
Default:
[u'bibtex', u'{filename}']
Shell command used to run bibtex.
- PDFExporter.latex_command : List
Default:
[u'pdflatex', u'{filename}']
Shell command used to compile latex.
- PDFExporter.latex_count : Integer
Default:
3
How many times latex will be called.
- PDFExporter.temp_file_exts : List
Default:
['.aux', '.bbl', '.blg', '.idx', '.log', '.out']
File extensions of temp files to remove after running.
- PDFExporter.verbose : Bool
Default:
False
Whether to display the output of latex commands.
- SlidesExporter.reveal_url_prefix : Unicode
Default:
u''
The URL prefix for reveal.js. This can be a a relative URL for a local copy of reveal.js, or point to a CDN.
For speaker notes to work, a local reveal.js prefix must be used.
- Preprocessor.enabled : Bool
Default:
False
No description
- CSSHTMLHeaderPreprocessor.highlight_class : Unicode
Default:
'.highlight'
CSS highlight class identifier
- ConvertFiguresPreprocessor.from_format : Unicode
Default:
u''
Format the converter accepts
- ConvertFiguresPreprocessor.to_format : Unicode
Default:
u''
Format the converter writes
- ExecutePreprocessor.allow_errors : Bool
Default:
False
If False (default), when a cell raises an error the execution is stoppped and a CellExecutionError is raised. If True, execution errors are ignored and the execution is continued until the end of the notebook. Output from exceptions is included in the cell output in both cases.
- ExecutePreprocessor.interrupt_on_timeout : Bool
Default:
False
If execution of a cell times out, interrupt the kernel and continue executing other cells rather than throwing an error and stopping.
- ExecutePreprocessor.kernel_name : Unicode
Default:
''
Name of kernel to use to execute the cells. If not set, use the kernel_spec embedded in the notebook.
- ExecutePreprocessor.timeout : Integer
Default:
30
The time to wait (in seconds) for output from executions. If a cell execution takes longer, an exception (TimeoutError on python 3+, RuntimeError on python 2) is raised.
- ExtractOutputPreprocessor.extract_output_types : Set
Default:
set(['image/png', 'application/pdf', 'image/jpeg', 'image/svg...
No description
- ExtractOutputPreprocessor.output_filename_template : Unicode
Default:
'{unique_key}_{cell_index}_{index}{extension}'
No description
- HighlightMagicsPreprocessor.languages : Dict
Default:
{}
Syntax highlighting for magic’s extension languages. Each item associates a language magic extension such as %%R, with a pygments lexer such as r.
- SVG2PDFPreprocessor.command : Unicode
Default:
u''
The command to use for converting SVG to PDF
This string is a template, which will be formatted with the keys to_filename and from_filename.
The conversion call must read the SVG from {from_flename}, and write a PDF to {to_filename}.
- SVG2PDFPreprocessor.inkscape : Unicode
Default:
u''
The path to Inkscape, if necessary
- WriterBase.files : List
Default:
[]
List of the files that the notebook references. Files will be included with written output.
- FilesWriter.build_directory : Unicode
Default:
''
Directory to write output to. Leave blank to output to the current directory
- FilesWriter.relpath : Unicode
Default:
''
When copying files that the notebook depends on, copy them in relation to this path, such that the destination filename will be os.path.relpath(filename, relpath). If FilesWriter is operating on a notebook that already exists elsewhere on disk, then the default will be the directory containing that notebook.
- ServePostProcessor.ip : Unicode
Default:
'127.0.0.1'
The IP address to listen on.
- ServePostProcessor.open_in_browser : Bool
Default:
True
Should the browser be opened automatically?
- ServePostProcessor.port : Int
Default:
8000
port for the server to listen on.
- ServePostProcessor.reveal_cdn : Unicode
Default:
'https://cdnjs.cloudflare.com/ajax/libs/reveal.js/3.1.0'
URL for reveal.js CDN.
- ServePostProcessor.reveal_prefix : Unicode
Default:
'reveal.js'
URL prefix for reveal.js
LaTeX citations¶
nbconvert
now has support for LaTeX citations. With this capability you
can:
- Manage citations using BibTeX.
- Cite those citations in Markdown cells using HTML data attributes.
- Have
nbconvert
generate proper LaTeX citations and run BibTeX.
For an example of how this works, please see the citations example in the nbconvert-examples repository.
Using external exporters¶
New in version 4.2: You can now use the --to
flag to use custom export formats defined in other
libraries.
The command-line syntax to run the nbconvert
script is:
$ jupyter nbconvert --to FORMAT notebook.ipynb
This will convert the Jupyter document file notebook.ipynb
into the output
format designated by the FORMAT
string as explained below.
A few built-in formats are available by default: html, pdf, script, latex. Each of these has its own _exporter_ with many configuration options that can be extended. Having the option to point to a different _exporter_ allows authors to create their own fully customized templates.
A custom _exporter_ must be a globally importable python object. We recommend that these be distributed as python libraries.
To export using an exporter from an external library, use the fully qualified
name of this exporter on the command line as the argument of the --to
flag:
$ jupyter nbconvert --to <full.qualified.name> notebook.ipynb
For example, assuming a library tcontrib has an exporter name TExporter, you would convert to this format using:
$ jupyter nbconvert --to tcontrib.TExporter notebook.ipynb
A library can therefore contain multiple exporters. All other flags of the command line should behave the same as for built-in exporters.
Parameters controlled by external exporter¶
An external exporter can control almost any parameter of the notebook conversion process, from simple parameters such as the output file extension, to more complex ones such as the execution of the notebook or a custom rendering template.
All external exporters can expose custom options using the traitlets
configurable API. Refer to the library that provides these exporters for
details on how these configuration options works.
You can use the Jupyter configuration files to configure an external exporter. As
for any nbconvert
exporters you can use either the configuration file syntax of
c.MyExporter.config_option=value
or the command line flag form
--MyExporter.config_option=value
.
Writing a custom Exporter
¶
Under the hood exporters are python classes that expose a certain interface. Any importable classes that expose this interface can be use as an exporter for nbconvert.
For simplicity we expose basic classes that implement all the relevant methods that you have to subclass and overwrite just the relevant methods to provide a custom exporter. Below we show you the step to create a custom exporter that provides a custom file extension, and a custom template that inserts before and after each markdown cell.
We will lay out files to be ready for Python packaging and distributing on PyPI, although the exact art of Python packaging is beyond the scope of this explanation.
We will use the following layout for our package to expose a custom exporter:
mypackage
├── LICENSE.md
├── setup.py
└── mypackage
├── __init__.py
└── templates
└── test_template.tpl
As you can see the layout is relatively simple, in the case where a template is not needed we would actually have only one file with an Exporter implementation. Of course you can change the layout of your package to have a more fine-grained structure of the subpackage. But lets see what a minimum example looks like.
We are going to write an exporter that:
- exports to html, so we will reuse the built-in html exporter
- changes the file extension to .test_ext
# file __init__.py
import os
import os.path
from traitlets.config import Config
from nbconvert.exporters.html import HTMLExporter
#-----------------------------------------------------------------------------
# Classes
#-----------------------------------------------------------------------------
class MyExporter(HTMLExporter):
"""
My custom exporter
"""
def _file_extension_default(self):
"""
The new file extension is `.test_ext`
"""
return '.test_ext'
@property
def template_path(self):
"""
We want to inherit from HTML template, and have template under
`./templates/` so append it to the search path. (see next section)
"""
return super().template_path+[os.path.join(os.path.dirname(__file__), "templates")]
def _template_file_default(self):
"""
We want to use the new template we ship with our library.
"""
return 'test_template' # full
And the template file, that inherits from the html full template and prepend/append text to each markdown cell (see Jinja2 docs for template syntax):
{% extends "full.tpl" %}
{% block markdowncell -%}
## this is a markdown cell
{super()}
## THIS IS THE END
{% endblock markdowncell %}
Assuming you install this package locally, or from PyPI, you can now use:
jupyter nbconvert --to mypackage.MyEporter notebook.ipynb
Customizing nbconvert¶
Under the hood, nbconvert uses Jinja templates to specify how the notebooks should be formatted. These templates can be fully customized, allowing you to use nbconvert to create notebooks in different formats with different styles as well.
Out of the box, nbconvert can be used to convert notebooks to plain
Python files. For example, the following command converts the
example.ipynb
notebook to Python and prints out the result:
In [1]:
!jupyter nbconvert --to python 'example.ipynb' --stdout
# coding: utf-8
# # Example notebook
# ### Markdown cells
#
# This is an example notebook that can be converted with `nbconvert` to different formats. This is an example of a markdown cell.
# ### LaTeX Equations
#
# Here is an equation:
#
# $$
# y = \sin(x)
# $$
# ### Code cells
# In[1]:
print("This is a code cell that produces some output")
# ### Inline figures
# In[2]:
get_ipython().magic('matplotlib inline')
import matplotlib.pyplot as plt
import numpy as np
x = np.linspace(0, 2 * np.pi, 100)
y = np.sin(x)
plt.plot(x, y)
[NbConvertApp] Converting notebook example.ipynb to python
From the code, you can see that non-code cells are also exported. As mentioned above, if you want to change this behavior, you can use a custom template. The custom template inherits from the Python template and overwrites the markdown blocks so that they are empty.
Below is an example of a custom template, which we write to a file
called simplepython.tpl
. This template removes markdown cells from
the output, and also changes how the execution count numbers are
formatted:
In [2]:
%%writefile simplepython.tpl
{% extends 'python.tpl'%}
## remove markdown cells
{% block markdowncell -%}
{% endblock markdowncell %}
## change the appearance of execution count
{% block in_prompt %}
# This was input cell with execution count: {{ cell.execution_count if cell.execution_count else ' ' }}
{%- endblock in_prompt %}
Overwriting simplepython.tpl
Using this template, we see that the resulting Python code does not contain anything that was previously in a markdown cell, and has special comments regarding the execution counts:
In [3]:
!jupyter nbconvert --to python 'example.ipynb' --stdout --template=simplepython.tpl
# coding: utf-8
# This was input cell with execution count: 1
print("This is a code cell that produces some output")
# This was input cell with execution count: 2
get_ipython().magic('matplotlib inline')
import matplotlib.pyplot as plt
import numpy as np
x = np.linspace(0, 2 * np.pi, 100)
y = np.sin(x)
plt.plot(x, y)
[NbConvertApp] Converting notebook example.ipynb to python
Template structure¶
Nbconvert templates consist of a set of nested blocks. When defining a new template, you extend an existing template by overriding some of the blocks.
All the templates shipped in nbconvert have the basic structure described here, though some may define additional blocks.
In [4]:
from IPython.display import HTML, display
with open('template_structure.html') as f:
display(HTML(f.read()))
Main page
Outputs
Extra HTML blocks (full.tpl)
<head>
</head>
Extra Latex blocks
A few gotchas¶
Jinja blocks use {% %}
by default which does not play nicely with
LaTeX, so those are replaced by ((* *))
in LaTeX templates.
Templates that use cell metadata¶
The notebook file format supports attaching arbitrary JSON metadata to each cell. Here, as an exercise, you will use the metadata to tag cells.
First you need to choose another notebook you want to convert to html,
and tag some of the cells with metadata. You can refer to the file
soln/celldiff.js
as an example or follow the Javascript tutorial to
figure out how do change cell metadata. Assuming you have a notebook
with some of the cells tagged as 'Easy'
, 'Medium'
, 'Hard'
,
or <None>
, the notebook can be converted specially using a custom
template. Design your template in the cells provided below.
Hint: if your tags are located at cell.metadata.example.difficulty
,
the following Python code would get the value of the tag:
cell['metadata'].get('example', {}).get('difficulty', '')
The following lines of code may be a helpful starting point:
In [5]:
%%writefile mytemplate.tpl
{% extends 'full.tpl'%}
{% block any_cell %}
<div style="border:thin solid red">
{{ super() }}
</div>
{% endblock any_cell %}
Overwriting mytemplate.tpl
Once you have tagged the cells appropriately and written your template using the cell above, try converting your notebook using the following command:
jupyter nbconvert --to html <your notebook.ipynb> --template=mytemplate.tpl
Executing notebooks¶
Jupyter notebooks are often saved with cleared output cells. nbconvert provides a helpful way to execute the input cells of an .ipynb notebook file and save the results, both input and output cells, as a .ipynb file.
In this section we show how to execute a .ipynb
notebook
document saving the result in notebook format.
If you need to export notebooks to other formats, such as reStructured Text
or Markdown (optionally executing them) see section Using nbconvert as a library.
Executing notebooks can be very helpful, for example, to run all notebooks in Python library in one step, or as a way to automate the data analysis in projects involving more than one notebook.
The same functionality of executing notebooks is exposed through a command line interface or a Python API interface. As an example, a notebook can be executed from the command line with:
jupyter nbconvert --to notebook --execute mynotebook.ipynb
This section will illustrate the Python API interface.
A Quick example¶
Let’s start with a complete quick example, leaving detailed explanations to the following sections.
First we import nbconvert and the ExecutePreprocessor
class:
import nbformat
from nbconvert.preprocessors import ExecutePreprocessor
Assuming that notebook_filename
contains the path of a notebook,
we can load it with:
with open(notebook_filename) as f:
nb = nbformat.read(f, as_version=4)
Next, we configure the notebook execution mode:
ep = ExecutePreprocessor(timeout=600, kernel_name='python3')
We specified two (optional) arguments timeout
and kernel_name
, which
define respectively the cell execution timeout and the execution kernel.
The option to specify kernel_name is new in nbconvert 4.2. When not specified or when using nbconvert <4.2, the default Python kernel is chosen.
To actually run the notebook we call the method preprocess
:
ep.preprocess(nb, {'metadata': {'path': 'notebooks/'}})
Hopefully, we will not get any errors during the notebook execution
(see the last section for error handling). Note that path
specifies
in which folder to execute the notebook.
Finally, save the resulting notebook with:
with open('executed_notebook.ipynb', 'wt') as f:
nbformat.write(nb, f)
That’s all. Your executed notebook will be saved in the current folder
in the file executed_notebook.ipynb
.
Execution arguments¶
The arguments passed to ExecutePreprocessor
are configuration options
called traitlets.
There are many cool things about traitlets, for example
they enforce the type of the input and they can be accessed/modified as
class attributes. Moreover, each traitlet is automatically exposed
as command-line options. For example, we can pass the timeout from the
command-line like this:
jupyter nbconvert --ExecutePreprocessor.timeout=600 --to notebook --execute mynotebook.ipynb
Let’s now discuss in more detail the two traitlets we used.
The timeout
traitlet defines the maximum time (in seconds) each notebook
cell is
allowed to run, if the execution takes longer an exception will be raised.
The default is 30 s, so in cases of long-running cells you may want to specify
an higher value.
The second traitlet, kernel_name
, allows specifying the name of the kernel
to be used for the execution. By default, the kernel name is obtained from the
notebook metadata. The traitlet kernel_name
allows to specify a user-defined
kernel, overriding the value in the notebook metadata. A common use case
is that of a Python 2/3 library which includes documentation/testing
notebooks. These notebooks will specify either a python2 or python3 kernel
in their metadata
(depending on the kernel used the last time the notebook was saved).
In reality, these notebooks will work on both Python 2/3 and, for testing,
it is important to be able to execute them programmatically on both
versions. Here the traitlet kernel_name
is helpful:
we can just run each notebook twice, specifying first “python2” and then
“python3” as kernel name.
Error Handling¶
In the previous sections we saw how to save an executed notebook, assuming there are no execution errors. But, what if there are errors?
An error during the notebook execution, by default, will stop the execution
and raise a CellExecutionError
. Conveniently, the source cell causing
the error and the original error name and message are also printed.
After an error, we can still save the notebook as before:
with open('executed_notebook.ipynb', mode='wt') as f:
nbformat.write(nb, f)
The saved notebook contains the output up until the failing cell, and includes a full stack-trace and error (which can help debugging). A useful pattern to execute notebooks while handling errors is the following:
try:
out = ep.preprocess(nb, {'metadata': {'path': run_path}})
except CellExecutionError:
msg = 'Error executing the notebook "%s".\n\n' % notebook_filename
msg += 'See notebook "%s" for the traceback.' % notebook_filename_out
print(msg)
raise
finally:
with open(notebook_filename_out, mode='wt') as f:
nbformat.write(nb, f)
This will save the executed notebook regardless of execution errors.
In case of errors, however, an additional message is printed and the
CellExecutionError
is raised. The message directs the user to
the saved notebook for further inspection.
As a last scenario, it is sometimes useful to execute notebooks which
raise exceptions, for example to show an error condition.
In this case, instead of stopping the execution on the first error,
we can keep executing the notebook using the traitlet allow_errors
(default False).
With allow_errors=True
,
the notebook is executed until the end, regardless of any error encountered
during the execution. The output notebook,
will contain the stack-traces and error messages for all the cells
raising exceptions.
Using nbconvert as a library¶
In this notebook, you will be introduced to the programmatic API of nbconvert and how it can be used in various contexts.
A great blog post by [@jakevdp](https://github.com/jakevdp) will be used to demonstrate. This notebook will not focus on using the command line tool. The attentive reader will point-out that no data is read from or written to disk during the conversion process. This is because nbconvert has been designed to work in memory so that it works well in a database or web-based environement too.
Quick overview¶
Credit: Jonathan Frederic (@jdfreder on github)
The main principle of nbconvert is to instantiate an Exporter
that
controls the pipeline through which notebooks are converted.
First, download @jakevdp’s notebook (if you do not have requests
,
install it by running pip install requests
, or if you don’t have pip
installed, you can find it on PYPI):
In [1]:
from urllib.request import urlopen
url = 'http://jakevdp.github.com/downloads/notebooks/XKCD_plots.ipynb'
response = urlopen(url).read().decode()
response[0:60] + ' ...'
Out[1]:
'{\n "metadata": {\n "name": "XKCD_plots"\n },\n "nbformat": 3,\n ...'
The response is a JSON string which represents a Jupyter notebook.
Next, we will read the response using nbformat. Doing this will guarantee that the notebook structure is valid. Note that the in-memory format and on disk format are slightly different. In particual, on disk, multiline strings might be split into a list of strings.
In [2]:
import nbformat
jake_notebook = nbformat.reads(response, as_version=4)
jake_notebook.cells[0]
Out[2]:
{'cell_type': 'markdown',
'metadata': {},
'source': '# XKCD plots in Matplotlib'}
The nbformat API returns a special type of dictionary. For this examle, you don’t need to worry about the details of the structure (if you are interested, please see the nbformat documentation).
The nbconvert API exposes some basic exporters for common formats and defaults. You will start by using one of them. First, you will import one of these exporters (specifically, the HTML exporter), then instantiate it using most of the defaults, and then you will use it to process the notebook we downloaded earlier.
In [3]:
from traitlets.config import Config
# 1. Import the exporter
from nbconvert import HTMLExporter
# 2. Instantiate the exporter. We use the `basic` template for now; we'll get into more details
# later about how to customize the exporter further.
html_exporter = HTMLExporter()
html_exporter.template_file = 'basic'
# 3. Process the notebook we loaded earlier
(body, resources) = html_exporter.from_notebook_node(jake_notebook)
The exporter returns a tuple containing the source of the converted notebook, as well as a resources dict. In this case, the source is just raw HTML:
In [4]:
print(body[:400] + '...')
<div class="cell border-box-sizing text_cell rendered">
<div class="prompt input_prompt">
</div>
<div class="inner_cell">
<div class="text_cell_render border-box-sizing rendered_html">
<h1 id="XKCD-plots-in-Matplotlib">XKCD plots in Matplotlib<a class="anchor-link" href="#XKCD-plots-in-Matplotlib">¶</a></h1>
</div>
</div>
</div>
<div class="cell border-box-sizing text_cell rendered">
<div cl...
If you understand HTML, you’ll notice that some common tags are ommited,
like the body
tag. Those tags are included in the default
HtmlExporter
, which is what would have been constructed if we had
not modified the template_file
.
The resource dict contains (among many things) the extracted .png
,
.jpg
, etc. from the notebook when applicable. The basic HTML
exporter leaves the figures as embedded base64, but you can configure it
to extract the figures. So for now, the resource dict should be mostly
empty, except for a key containing CSS and a few others whose content
will be obvious:
In [5]:
print("Resources:", resources.keys())
print("Metadata:", resources['metadata'].keys())
print("Inlining:", resources['inlining'].keys())
print("Extension:", resources['output_extension'])
Resources: dict_keys(['metadata', 'output_extension', 'raw_mimetypes', 'inlining'])
Metadata: dict_keys(['name'])
Inlining: dict_keys(['css'])
Extension: .html
Exporter
s are stateless, so you won’t be able to extract any
useful information beyond their configuration. You can re-use an
exporter instance to convert another notebook. In addition to the
from_notebook_node
used above, each exporter exposes from_file
and from_filename
methods.
Extracting Figures using the RST Exporter¶
When exporting, you may want to extract the base64 encoded figures as
files. While the HTML exporter does not do this by default, the
RstExporter
does:
In [6]:
# Import the RST exproter
from nbconvert import RSTExporter
# Instantiate it
rst_exporter = RSTExporter()
# Convert the notebook to RST format
(body, resources) = rst_exporter.from_notebook_node(jake_notebook)
print(body[:970] + '...')
print('[.....]')
print(body[800:1200] + '...')
XKCD plots in Matplotlib
========================
This notebook originally appeared as a blog post at `Pythonic
Perambulations <http://jakevdp.github.com/blog/2012/10/07/xkcd-style-plots-in-matplotlib/>`__
by Jake Vanderplas.
.. raw:: html
<!-- PELICAN_BEGIN_SUMMARY -->
*Update: the matplotlib pull request has been merged! See* `*This
post* <http://jakevdp.github.io/blog/2013/07/10/XKCD-plots-in-matplotlib/>`__
*for a description of the XKCD functionality now built-in to
matplotlib!*
One of the problems I've had with typical matplotlib figures is that
everything in them is so precise, so perfect. For an example of what I
mean, take a look at this figure:
.. code:: python
from IPython.display import Image
Image('http://jakevdp.github.com/figures/xkcd_version.png')
.. image:: output_3_0.png
Sometimes when showing schematic plots, this is the type of figure I
want to display. But drawing it by hand is a pain: I'd rather just use
matp...
[.....]
image:: output_3_0.png
Sometimes when showing schematic plots, this is the type of figure I
want to display. But drawing it by hand is a pain: I'd rather just use
matplotlib. The problem is, matplotlib is a bit too precise. Attempting
to duplicate this figure in matplotlib leads to something like this:
.. code:: python
Image('http://jakevdp.github.com/figures/mpl_version.png')
.. imag...
Notice that base64 images are not embeded, but instead there are
filename-like strings, such as output_3_0.png
. The strings actually
are (configurable) keys that map to the binary data in the resources
dict.
Note, if you write an RST Plugin, you are responsible for writing all the files to the disk (or uploading, etc...) in the right location. Of course, the naming scheme is configurable.
As an exercise, this notebook will show you how to get one of those
images. First, take a look at the 'outputs'
of the returned
resources dictionary. This is a dictionary that contains a key for each
extracted resource, with values corresponding to the actual base64
encoding:
In [7]:
sorted(resources['outputs'].keys())
Out[7]:
['output_13_1.png',
'output_16_0.png',
'output_18_1.png',
'output_3_0.png',
'output_5_0.png']
In this case, there are 5 extracted binary figures, all png
s. We
can use the Image display object to actually display one of the images:
In [8]:
from IPython.display import Image
Image(data=resources['outputs']['output_3_0.png'], format='png')
Out[8]:
Note that this image is being rendered without ever reading or writing to the disk.
Extracting Figures using the HTML Exporter¶
As mentioned above, by default, the HTML exporter does not extract images – it just leaves them as inline base64 encodings. However, this is not always what you might want. For example, here is a use case from @jakevdp:
I write an awesome blog using Jupyter notebooks converted to HTML, and I want the images to be cached. Having one html file with all of the images base64 encoded inside it is nice when sharing with a coworker, but for a website, not so much. I need an HTML exporter, and I want it to extract the figures!
Some theory¶
Before we get into actually extracting the figures, it will be helpful to give a high-level overview of the process of converting a notebook to a another format:
- Retrieve the notebook and it’s accompanying resources (you are responsible for this).
- Feed the notebook into the
Exporter
, which:- Sequentially feeds the notebook into an array of
Preprocessor
s. Preprocessors only act on the structure of the notebook, and have unrestricted access to it. - Feeds the notebook into the Jinja templating engine, which converts it to a particular format depending on which template is selected.
- Sequentially feeds the notebook into an array of
- The exporter returns the converted notebook and other relevant resources as a tuple.
- You write the data to the disk using the built-in
FilesWriter
(which writes the notebook and any extracted files to disk), or elsewhere using a customWriter
.
Using different preprocessors¶
To extract the figures when using the HTML exporter, we will want to
change which Preprocessor
s 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 result of converting the notebook using the original HTML exporter and our 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']
Custom Preprocessors¶
There are an endless number of transformations that you may want to
apply to a notebook. In particularly complicated cases, you may want to
actually create your own Preprocessor
. Above, when we customized the
list of preprocessors 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.
To create your own preprocessor, you will need to subclass from
nbconvert.preprocessors.Preprocessor
and overwrite either the
preprocess
and/or preprocess_cell
methods.
Example¶
The following demonstration, as requested in a GitHub issue, adds the ability to exclude a cell by index.
Note: injecting cells is similar, and won’t be covered here. If you want to inject static content at the beginning/end of a notebook, use a custom template.
In [11]:
from traitlets import Integer
from nbconvert.preprocessors import Preprocessor
class PelicanSubCell(Preprocessor):
"""A Pelican specific preprocessor to remove some of the cells of a notebook"""
# I could also read the cells from nb.metadata.pelican if someone wrote a JS extension,
# but for now I'll stay with configurable value.
start = Integer(0, config=True, help="first cell of notebook to be converted")
end = Integer(-1, config=True, help="last cell of notebook to be converted")
def preprocess(self, nb, resources):
self.log.info("I'll keep only cells from %d to %d", self.start, self.end)
nb.cells = nb.cells[self.start:self.end]
return nb, resources
/Users/benjaminrk/conda/lib/python3.5/site-packages/ipykernel/__main__.py:9: DeprecationWarning: metadata {'config': True} was set from the constructor. Metadata should be set using the .tag() method, e.g., Int().tag(key1='value1', key2='value2')
/Users/benjaminrk/conda/lib/python3.5/site-packages/ipykernel/__main__.py:10: DeprecationWarning: metadata {'config': True} was set from the constructor. Metadata should be set using the .tag() method, e.g., Int().tag(key1='value1', key2='value2')
Here a Pelican exporter is created that takes PelicanSubCell
preprocessors and a config
object as parameters. This may seem
redundant, but with the configuration system you can register an
inactive preprocessor on all of the exporters and activate it from
config files or the command line.
In [12]:
# Create a new config object that configures both the new preprocessor, as well as the exporter
c = Config()
c.PelicanSubCell.start = 4
c.PelicanSubCell.end = 6
c.RSTExporter.preprocessors = [PelicanSubCell]
# Create our new, customized exporter that uses our custom preprocessor
pelican = RSTExporter(config=c)
# Process the notebook
print(pelican.from_notebook_node(jake_notebook)[0])
Sometimes when showing schematic plots, this is the type of figure I
want to display. But drawing it by hand is a pain: I'd rather just use
matplotlib. The problem is, matplotlib is a bit too precise. Attempting
to duplicate this figure in matplotlib leads to something like this:
.. code:: python
Image('http://jakevdp.github.com/figures/mpl_version.png')
.. image:: output_5_0.png
Programatically creating templates¶
In [13]:
from jinja2 import DictLoader
dl = DictLoader({'full.tpl':
"""
{%- extends 'basic.tpl' -%}
{% block footer %}
FOOOOOOOOTEEEEER
{% endblock footer %}
"""})
exportHTML = HTMLExporter(extra_loaders=[dl])
(body, resources) = exportHTML.from_notebook_node(jake_notebook)
for l in body.split('\n')[-4:]:
print(l)
</div>
</div>
FOOOOOOOOTEEEEER
Real World Uses¶
@jakevdp uses Pelican and Jupyter Notebook to blog. Pelican will use nbconvert programatically to generate blog post. Have a look a Pythonic Preambulations for Jake’s blog post.
@damianavila wrote the Nikola Plugin to write blog post as Notebooks and is developping a js-extension to publish notebooks via one click from the web app.
As @Mbussonn requested... easieeeeer! Deploy your Nikola site with just a click in the IPython notebook! http://t.co/860sJunZvj cc @ralsina
— Damián Avila (@damian_avila) August 21, 2013
Python API for working with nbconvert¶
Contents:
NbConvertApp¶
See also
- Configuration options
- Configurable options for the nbconvert application
-
class
nbconvert.nbconvertapp.
NbConvertApp
(**kwargs)¶ Application used to convert from notebook file type (
*.ipynb
)-
init_notebooks
()¶ Construct the list of notebooks. If notebooks are passed on the command-line, they override notebooks specified in config files. Glob each notebook to replace notebook patterns with filenames.
-
convert_notebooks
()¶ Convert the notebooks in the self.notebook traitlet
-
convert_single_notebook
(notebook_filename, input_buffer=None)¶ Convert a single notebook. Performs the following steps:
- Initialize notebook resources
- Export the notebook to a particular format
- Write the exported notebook to file
- (Maybe) postprocess the written file
If input_buffer is not None, convertion is done using buffer as source into a file basenamed by the notebook_filename argument.
-
init_single_notebook_resources
(notebook_filename)¶ Step 1: Initialize resources
This intializes the resources dictionary for a single notebook. This method should return the resources dictionary, and MUST include the following keys:
- config_dir: the location of the Jupyter config directory
- unique_key: the notebook name
- output_files_dir: a directory where output files (not including the notebook itself) should be saved
-
export_single_notebook
(notebook_filename, resources, input_buffer=None)¶ Step 2: Export the notebook
Exports the notebook to a particular format according to the specified exporter. This function returns the output and (possibly modified) resources from the exporter.
notebook_filename: a filename input_buffer: a readable file like object returning unicode, if not None notebook_filename is ignored
-
write_single_notebook
(output, resources)¶ Step 3: Write the notebook to file
This writes output from the exporter to file using the specified writer. It returns the results from the writer.
-
postprocess_single_notebook
(write_results)¶ Step 4: Postprocess the notebook
This postprocesses the notebook after it has been written, taking as an argument the results of writing the notebook to file. This only actually does anything if a postprocessor has actually been specified.
-
Exporters¶
See also
- Configuration options
- Configurable options for the nbconvert application
-
class
nbconvert.exporters.
Exporter
(config=None, **kw)¶ Class containing methods that sequentially run a list of preprocessors on a NotebookNode object and then return the modified NotebookNode object and accompanying resources dict.
-
__init__
(config=None, **kw)¶ Public constructor
Parameters: - config (
Config
) – User configuration instance. - **kw – Additional keyword arguments passed to parent __init__
- config (
-
from_notebook_node
(nb, resources=None, **kw)¶ Convert a notebook from a notebook node instance.
Parameters: - nb (
NotebookNode
) – Notebook node (dict-like with attr-access) - resources (dict) – Additional resources that can be accessed read/write by preprocessors and filters.
- **kw – Ignored
- nb (
-
from_filename
(filename, resources=None, **kw)¶ Convert a notebook from a notebook file.
Parameters:
-
from_file
(file_stream, resources=None, **kw)¶ Convert a notebook from a notebook file.
Parameters: - file_stream (file-like object) – Notebook file-like object to convert.
- resources (dict) – Additional resources that can be accessed read/write by preprocessors and filters.
- **kw – Ignored
-
register_preprocessor
(preprocessor, enabled=False)¶ Register a preprocessor. Preprocessors are classes that act upon the notebook before it is passed into the Jinja templating engine. preprocessors are also capable of passing additional information to the Jinja templating engine.
Parameters: - preprocessor (
Preprocessor
) – A dotted module name, a type, or an instance - enabled (bool) – Mark the preprocessor as enabled
- preprocessor (
-
-
class
nbconvert.exporters.
TemplateExporter
(config=None, **kw)¶ Exports notebooks into other file formats. Uses Jinja 2 templating engine to output new formats. Inherit from this class if you are creating a new template type along with new filters/preprocessors. If the filters/ preprocessors provided by default suffice, there is no need to inherit from this class. Instead, override the template_file and file_extension traits via a config file.
- add_anchor
- add_prompts
- ansi2html
- ansi2latex
- ascii_only
- citation2latex
- comment_lines
- escape_latex
- filter_data_type
- get_lines
- get_metadata
- highlight2html
- highlight2latex
- html2text
- indent
- ipython2python
- markdown2html
- markdown2latex
- markdown2rst
- path2url
- posix_path
- prevent_list_blocks
- strip_ansi
- strip_dollars
- strip_files_prefix
- wrap_text
-
__init__
(config=None, **kw)¶ Public constructor
Parameters: - config (config) – User configuration instance.
- extra_loaders (list[of Jinja Loaders]) – ordered list of Jinja loader to find templates. Will be tried in order before the default FileSystem ones.
- template (str (optional, kw arg)) – Template to use when exporting.
-
from_notebook_node
(nb, resources=None, **kw)¶ Convert a notebook from a notebook node instance.
Parameters: - nb (
NotebookNode
) – Notebook node - resources (dict) – Additional resources that can be accessed read/write by preprocessors and filters.
- nb (
-
from_filename
(filename, resources=None, **kw)¶ Convert a notebook from a notebook file.
Parameters:
-
from_file
(file_stream, resources=None, **kw)¶ Convert a notebook from a notebook file.
Parameters: - file_stream (file-like object) – Notebook file-like object to convert.
- resources (dict) – Additional resources that can be accessed read/write by preprocessors and filters.
- **kw – Ignored
-
register_preprocessor
(preprocessor, enabled=False)¶ Register a preprocessor. Preprocessors are classes that act upon the notebook before it is passed into the Jinja templating engine. preprocessors are also capable of passing additional information to the Jinja templating engine.
Parameters: - preprocessor (
Preprocessor
) – A dotted module name, a type, or an instance - enabled (bool) – Mark the preprocessor as enabled
- preprocessor (
Specialized exporter classes¶
The NotebookExporter
inherits directly from
Exporter
, while the other exporters listed here
inherit either directly or indirectly from
TemplateExporter
.
-
class
nbconvert.exporters.
NotebookExporter
(config=None, **kw)¶ Exports to an IPython notebook.
-
class
nbconvert.exporters.
HTMLExporter
(config=None, **kw)¶ Exports a basic HTML document. This exporter assists with the export of HTML. Inherit from it if you are writing your own HTML template and need custom preprocessors/filters. If you don’t need custom preprocessors/ filters, just change the ‘template_file’ config option.
-
class
nbconvert.exporters.
SlidesExporter
(config=None, **kw)¶ Exports HTML slides with reveal.js
-
class
nbconvert.exporters.
LatexExporter
(config=None, **kw)¶ Exports to a Latex template. Inherit from this class if your template is LaTeX based and you need custom tranformers/filters. Inherit from it if you are writing your own HTML template and need custom tranformers/filters. If you don’t need custom tranformers/filters, just change the ‘template_file’ config option. Place your template in the special “/latex” subfolder of the ”../templates” folder.
-
class
nbconvert.exporters.
MarkdownExporter
(config=None, **kw)¶ Exports to a markdown document (.md)
-
class
nbconvert.exporters.
PDFExporter
(config=None, **kw)¶ Writer designed to write to PDF files
-
class
nbconvert.exporters.
PythonExporter
(config=None, **kw)¶ Exports a Python code file.
-
class
nbconvert.exporters.
RSTExporter
(config=None, **kw)¶ Exports restructured text documents.
Specialized exporter functions¶
These functions are essentially convenience functions that wrap the functionality of the classes documented in the previous section.
-
nbconvert.exporters.
export_custom
(*args, **kwargs)¶ Export a notebook object to custom format
- nb :
NotebookNode
- The notebook to export.
- config : config (optional, keyword arg)
- User configuration instance.
- resources : dict (optional, keyword arg)
- Resources used in the conversion process.
Returns: - output : str
- Jinja 2 output. This is the resulting converted notebook.
- resources : dictionary
- Dictionary of resources used prior to and during the conversion process.
- exporter_instance : Exporter
- Instance of the Exporter class used to export the document. Useful to caller because it provides a ‘file_extension’ property which specifies what extension the output should be saved as.
Return type: tuple Notes
WARNING: API WILL CHANGE IN FUTURE RELEASES OF NBCONVERT
- nb :
-
nbconvert.exporters.
export_html
(*args, **kwargs)¶ Export a notebook object to html format
- nb :
NotebookNode
- The notebook to export.
- config : config (optional, keyword arg)
- User configuration instance.
- resources : dict (optional, keyword arg)
- Resources used in the conversion process.
Returns: - output : str
- Jinja 2 output. This is the resulting converted notebook.
- resources : dictionary
- Dictionary of resources used prior to and during the conversion process.
- exporter_instance : Exporter
- Instance of the Exporter class used to export the document. Useful to caller because it provides a ‘file_extension’ property which specifies what extension the output should be saved as.
Return type: tuple Notes
WARNING: API WILL CHANGE IN FUTURE RELEASES OF NBCONVERT
- nb :
-
nbconvert.exporters.
export_slides
(*args, **kwargs)¶ Export a notebook object to slides format
- nb :
NotebookNode
- The notebook to export.
- config : config (optional, keyword arg)
- User configuration instance.
- resources : dict (optional, keyword arg)
- Resources used in the conversion process.
Returns: - output : str
- Jinja 2 output. This is the resulting converted notebook.
- resources : dictionary
- Dictionary of resources used prior to and during the conversion process.
- exporter_instance : Exporter
- Instance of the Exporter class used to export the document. Useful to caller because it provides a ‘file_extension’ property which specifies what extension the output should be saved as.
Return type: tuple Notes
WARNING: API WILL CHANGE IN FUTURE RELEASES OF NBCONVERT
- nb :
-
nbconvert.exporters.
export_latex
(*args, **kwargs)¶ Export a notebook object to latex format
- nb :
NotebookNode
- The notebook to export.
- config : config (optional, keyword arg)
- User configuration instance.
- resources : dict (optional, keyword arg)
- Resources used in the conversion process.
Returns: - output : str
- Jinja 2 output. This is the resulting converted notebook.
- resources : dictionary
- Dictionary of resources used prior to and during the conversion process.
- exporter_instance : Exporter
- Instance of the Exporter class used to export the document. Useful to caller because it provides a ‘file_extension’ property which specifies what extension the output should be saved as.
Return type: tuple Notes
WARNING: API WILL CHANGE IN FUTURE RELEASES OF NBCONVERT
- nb :
-
nbconvert.exporters.
export_pdf
(*args, **kwargs)¶ Export a notebook object to pdf format
- nb :
NotebookNode
- The notebook to export.
- config : config (optional, keyword arg)
- User configuration instance.
- resources : dict (optional, keyword arg)
- Resources used in the conversion process.
Returns: - output : str
- Jinja 2 output. This is the resulting converted notebook.
- resources : dictionary
- Dictionary of resources used prior to and during the conversion process.
- exporter_instance : Exporter
- Instance of the Exporter class used to export the document. Useful to caller because it provides a ‘file_extension’ property which specifies what extension the output should be saved as.
Return type: tuple Notes
WARNING: API WILL CHANGE IN FUTURE RELEASES OF NBCONVERT
- nb :
-
nbconvert.exporters.
export_markdown
(*args, **kwargs)¶ Export a notebook object to markdown format
- nb :
NotebookNode
- The notebook to export.
- config : config (optional, keyword arg)
- User configuration instance.
- resources : dict (optional, keyword arg)
- Resources used in the conversion process.
Returns: - output : str
- Jinja 2 output. This is the resulting converted notebook.
- resources : dictionary
- Dictionary of resources used prior to and during the conversion process.
- exporter_instance : Exporter
- Instance of the Exporter class used to export the document. Useful to caller because it provides a ‘file_extension’ property which specifies what extension the output should be saved as.
Return type: tuple Notes
WARNING: API WILL CHANGE IN FUTURE RELEASES OF NBCONVERT
- nb :
-
nbconvert.exporters.
export_python
(*args, **kwargs)¶ Export a notebook object to python format
- nb :
NotebookNode
- The notebook to export.
- config : config (optional, keyword arg)
- User configuration instance.
- resources : dict (optional, keyword arg)
- Resources used in the conversion process.
Returns: - output : str
- Jinja 2 output. This is the resulting converted notebook.
- resources : dictionary
- Dictionary of resources used prior to and during the conversion process.
- exporter_instance : Exporter
- Instance of the Exporter class used to export the document. Useful to caller because it provides a ‘file_extension’ property which specifies what extension the output should be saved as.
Return type: tuple Notes
WARNING: API WILL CHANGE IN FUTURE RELEASES OF NBCONVERT
- nb :
-
nbconvert.exporters.
export_rst
(*args, **kwargs)¶ Export a notebook object to rst format
- nb :
NotebookNode
- The notebook to export.
- config : config (optional, keyword arg)
- User configuration instance.
- resources : dict (optional, keyword arg)
- Resources used in the conversion process.
Returns: - output : str
- Jinja 2 output. This is the resulting converted notebook.
- resources : dictionary
- Dictionary of resources used prior to and during the conversion process.
- exporter_instance : Exporter
- Instance of the Exporter class used to export the document. Useful to caller because it provides a ‘file_extension’ property which specifies what extension the output should be saved as.
Return type: tuple Notes
WARNING: API WILL CHANGE IN FUTURE RELEASES OF NBCONVERT
- nb :
-
nbconvert.exporters.
export_script
(*args, **kwargs)¶ Export a notebook object to script format
- nb :
NotebookNode
- The notebook to export.
- config : config (optional, keyword arg)
- User configuration instance.
- resources : dict (optional, keyword arg)
- Resources used in the conversion process.
Returns: - output : str
- Jinja 2 output. This is the resulting converted notebook.
- resources : dictionary
- Dictionary of resources used prior to and during the conversion process.
- exporter_instance : Exporter
- Instance of the Exporter class used to export the document. Useful to caller because it provides a ‘file_extension’ property which specifies what extension the output should be saved as.
Return type: tuple Notes
WARNING: API WILL CHANGE IN FUTURE RELEASES OF NBCONVERT
- nb :
-
nbconvert.exporters.
export_by_name
(*args, **kwargs)¶ Export a notebook object to a template type by its name. Reflection (Inspect) is used to find the template’s corresponding explicit export method defined in this module. That method is then called directly.
Parameters: format_name (str) – Name of the template style to export to. - nb :
NotebookNode
- The notebook to export.
- config : config (optional, keyword arg)
- User configuration instance.
- resources : dict (optional, keyword arg)
- Resources used in the conversion process.
Returns: - output : str
- Jinja 2 output. This is the resulting converted notebook.
- resources : dictionary
- Dictionary of resources used prior to and during the conversion process.
- exporter_instance : Exporter
- Instance of the Exporter class used to export the document. Useful to caller because it provides a ‘file_extension’ property which specifies what extension the output should be saved as.
Return type: tuple Notes
WARNING: API WILL CHANGE IN FUTURE RELEASES OF NBCONVERT
- nb :
Preprocessors¶
See also
- Configuration options
- Configurable options for the nbconvert application
-
class
nbconvert.preprocessors.
Preprocessor
(**kw)¶ 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 informations.- 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¶
-
class
nbconvert.preprocessors.
ConvertFiguresPreprocessor
(**kw)¶ Converts all of the outputs in a notebook from one format to another.
-
class
nbconvert.preprocessors.
SVG2PDFPreprocessor
(**kw)¶ Converts all of the outputs in a notebook from SVG to PDF.
-
class
nbconvert.preprocessors.
ExtractOutputPreprocessor
(**kw)¶ Extracts all of the outputs from the notebook file. The extracted outputs are returned in the ‘resources’ dictionary.
-
class
nbconvert.preprocessors.
LatexPreprocessor
(**kw)¶ Preprocessor for latex destined documents.
Mainly populates the latex key in the resources dict, adding definitions for pygments highlight styles.
-
class
nbconvert.preprocessors.
CSSHTMLHeaderPreprocessor
(*pargs, **kwargs)¶ Preprocessor used to pre-process notebook for HTML output. Adds IPython notebook front-end CSS and Pygments CSS to HTML output.
-
class
nbconvert.preprocessors.
HighlightMagicsPreprocessor
(config=None, **kw)¶ Detects and tags code cells that use a different languages than Python.
-
class
nbconvert.preprocessors.
ClearOutputPreprocessor
(**kw)¶ Removes the output from all code cells in a notebook.
-
class
nbconvert.preprocessors.
ExecutePreprocessor
(**kw)¶ Executes all the cells in a notebook
-
preprocess
(nb, resources)¶ Preprocess notebook executing each code cell.
The input argument nb is modified in-place.
Parameters: - nb (NotebookNode) – Notebook being executed.
- resources (dictionary) – Additional resources used in the conversion process. For example,
passing
{'metadata': {'path': run_path}}
sets the execution path torun_path
.
Returns: - nb (NotebookNode) – The executed notebook.
- resources (dictionary) – Additional resources used in the conversion process.
-
preprocess_cell
(cell, resources, cell_index)¶ Executes a single code cell. See base.py for details.
To execute all cells see
preprocess()
.
-
-
nbconvert.preprocessors.
coalesce_streams
(nb, resources)¶ 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
Filters¶
Filters are for use with the TemplateExporter
exporter.
They provide a way for you transform notebook contents to a particular format depending
on the template you are using. For example, when converting to HTML, you would want to
use the ansi2html()
function to convert ANSI colors (from
e.g. a terminal traceback) to HTML colors.
See also
- Exporters
- API documentation for the various exporter classes
-
nbconvert.filters.
add_anchor
(html)¶ Add an anchor-link to an html header
For use on markdown headings
-
nbconvert.filters.
add_prompts
(code, first='>>> ', cont='... ')¶ Add prompts to code snippets
-
nbconvert.filters.
ansi2html
(text)¶ Convert ansi colors to html colors.
Parameters: text (str) – Text containing ansi colors to convert to html
-
nbconvert.filters.
ansi2latex
(text)¶ Converts ansi formated text to latex version
based on https://bitbucket.org/birkenfeld/sphinx-contrib/ansi.py
-
nbconvert.filters.
ascii_only
(s)¶ ensure a string is ascii
-
nbconvert.filters.
citation2latex
(s)¶ Parse citations in Markdown cells.
This looks for HTML tags having a data attribute names data-cite and replaces it by the call to LaTeX cite command. The tranformation looks like this:
<cite data-cite=”granger”>(Granger, 2013)</cite>
Becomes
cite{granger}
Any HTML tag can be used, which allows the citations to be formatted in HTML in any manner.
-
nbconvert.filters.
comment_lines
(text, prefix='# ')¶ Build a Python comment line from input text.
Parameters:
-
nbconvert.filters.
escape_latex
(text)¶ Escape characters that may conflict with latex.
Parameters: text (str) – Text containing characters that may conflict with Latex
-
class
nbconvert.filters.
DataTypeFilter
(**kw)¶ Returns the preferred display format
-
nbconvert.filters.
get_lines
(text, start=None, end=None)¶ Split the input text into separate lines and then return the lines that the caller is interested in.
Parameters: - text (str) – Text to parse lines from.
- start (int, optional) – First line to grab from.
- end (int, optional) – Last line to grab from.
-
class
nbconvert.filters.
Highlight2HTML
(pygments_lexer=None, **kwargs)¶
-
class
nbconvert.filters.
Highlight2Latex
(pygments_lexer=None, **kwargs)¶
-
nbconvert.filters.
html2text
(element)¶ extract inner text from html
Analog of jQuery’s $(element).text()
-
nbconvert.filters.
indent
(instr, nspaces=4, ntabs=0, flatten=False)¶ Indent a string a given number of spaces or tabstops.
indent(str,nspaces=4,ntabs=0) -> indent str by ntabs+nspaces.
Parameters: - instr (basestring) – The string to be indented.
- nspaces (int (default: 4)) – The number of spaces to be indented.
- ntabs (int (default: 0)) – The number of tabs to be indented.
- flatten (bool (default: False)) – Whether to scrub existing indentation. If True, all lines will be aligned to the same indentation. If False, existing indentation will be strictly increased.
Returns: str|unicode
Return type: string indented by ntabs and nspaces.
-
nbconvert.filters.
ipython2python
(code)¶ Transform IPython syntax to pure Python syntax
Parameters: code (str) – IPython code, to be transformed to pure Python
-
nbconvert.filters.
markdown2html
(source)¶ Convert a markdown string to HTML using mistune
-
nbconvert.filters.
markdown2latex
(source, markup='markdown', extra_args=None)¶ Convert a markdown string to LaTeX via pandoc.
This function will raise an error if pandoc is not installed. Any error messages generated by pandoc are printed to stderr.
Parameters: - source (string) – Input string, assumed to be valid markdown.
- markup (string) – Markup used by pandoc’s reader default : pandoc extended markdown (see http://johnmacfarlane.net/pandoc/README.html#pandocs-markdown)
Returns: out – Output as returned by pandoc.
Return type:
-
nbconvert.filters.
markdown2rst
(source, extra_args=None)¶ Convert a markdown string to ReST via pandoc.
This function will raise an error if pandoc is not installed. Any error messages generated by pandoc are printed to stderr.
Parameters: source (string) – Input string, assumed to be valid markdown. Returns: out – Output as returned by pandoc. Return type: string
-
nbconvert.filters.
path2url
(path)¶ Turn a file path into a URL
-
nbconvert.filters.
posix_path
(path)¶ Turn a path into posix-style path/to/etc
Mainly for use in latex on Windows, where native Windows paths are not allowed.
-
nbconvert.filters.
prevent_list_blocks
(s)¶ Prevent presence of enumerate or itemize blocks in latex headings cells
-
nbconvert.filters.
strip_ansi
(source)¶ Remove ansi escape codes from text.
Parameters: source (str) – Source to remove the ansi from
-
nbconvert.filters.
strip_dollars
(text)¶ Remove all dollar symbols from text
Parameters: text (str) – Text to remove dollars from
Writers¶
See also
- Configuration options
- Configurable options for the nbconvert application
-
class
nbconvert.writers.
WriterBase
(config=None, **kw)¶ Consumes output from nbconvert export...() methods and writes to a useful location.
-
__init__
(config=None, **kw)¶ Constructor
-
write
(output, resources, **kw)¶ Consume and write Jinja output.
Parameters:
-
Specialized writers¶
-
class
nbconvert.writers.
DebugWriter
(config=None, **kw)¶ Consumes output from nbconvert export...() methods and writes usefull debugging information to the stdout. The information includes a list of resources that were extracted from the notebook(s) during export.
-
class
nbconvert.writers.
FilesWriter
(**kw)¶ Consumes nbconvert output and produces files.
-
class
nbconvert.writers.
StdoutWriter
(config=None, **kw)¶ Consumes output from nbconvert export...() methods and writes to the stdout stream.
Postprocessors¶
See also
- Configuration options
- Configurable options for the nbconvert application
Changes in nbconvert¶
- allow nbconvert reading from stdin with “–stdin” option (write into “notebook” basename)
4.1¶
- setuptools fixes for entrypoints on Windows
- various fixes for exporters, including slides, latex, and PDF
- fixes for exceptions met during execution
- include markdown outputs in markdown/html exports