Python API for working with notebook files

Reading and writing

nbformat.read(fp, as_version, **kwargs)

Read a notebook from a file as a NotebookNode of the given version.

The string can contain a notebook of any version. The notebook will be returned as_version, converting, if necessary.

Notebook format errors will be logged.

Parameters:
  • fp (file or str) – A file-like object with a read method that returns unicode (use io.open() in Python 2), or a path to a file.
  • as_version (int) – The version of the notebook format to return. The notebook will be converted, if necessary. Pass nbformat.NO_CONVERT to prevent conversion.
Returns:

nb – The notebook that was read.
Return type:

NotebookNode
nbformat.reads(s, as_version, **kwargs)

Read a notebook from a string and return the NotebookNode object as the given version.

The string can contain a notebook of any version. The notebook will be returned as_version, converting, if necessary.

Notebook format errors will be logged.

Parameters:
  • s (unicode) – The raw unicode string to read the notebook from.
  • as_version (int) – The version of the notebook format to return. The notebook will be converted, if necessary. Pass nbformat.NO_CONVERT to prevent conversion.
Returns:

nb – The notebook that was read.
Return type:

NotebookNode

The reading functions require you to pass the as_version parameter. Your code should specify the notebook format that it knows how to work with: for instance, if your code handles version 4 notebooks:

nb = nbformat.read('path/to/notebook.ipynb', as_version=4)

This will automatically upgrade or downgrade notebooks in other versions of the notebook format to the structure your code knows about.

nbformat.write(nb, fp, version=nbformat.NO_CONVERT, **kwargs)

Write a notebook to a file in a given nbformat version.

The file-like object must accept unicode input.

Parameters:
  • nb (NotebookNode) – The notebook to write.
  • fp (file or str) – Any file-like object with a write method that accepts unicode, or a path to write a file.
  • version (int, optional) – The nbformat version to write. If nb is not this version, it will be converted. If unspecified, or specified as nbformat.NO_CONVERT, the notebook’s own version will be used and no conversion performed.
nbformat.writes(nb, version=nbformat.NO_CONVERT, **kwargs)

Write a notebook to a string in a given format in the given nbformat version.

Any notebook format errors will be logged.

Parameters:
  • nb (NotebookNode) – The notebook to write.
  • version (int, optional) – The nbformat version to write. If unspecified, or specified as nbformat.NO_CONVERT, the notebook’s own version will be used and no conversion performed.
Returns:

s – The notebook as a JSON string.
Return type:

unicode
nbformat.NO_CONVERT

This special value can be passed to the reading and writing functions, to indicate that the notebook should be loaded/saved in the format it’s supplied.

nbformat.current_nbformat
nbformat.current_nbformat_minor

These integers represent the current notebook format version that the nbformat module knows about.

NotebookNode objects

The functions in this module work with NotebookNode objects, which are like dictionaries, but allow attribute access (nb.cells). The structure of these objects matches the notebook format described in The Notebook file format.

class nbformat.NotebookNode(*args, **kw)

A dict-like node with attribute-access

nbformat.from_dict(d)

Convert dict to dict-like NotebookNode

Recursively converts any dict in the container to a NotebookNode. This does not check that the contents of the dictionary make a valid notebook or part of a notebook.

Other functions

nbformat.convert(nb, to_version)

Convert a notebook node object to a specific version. Assumes that all the versions starting from 1 to the latest major X are implemented. In other words, there should never be a case where v1 v2 v3 v5 exist without a v4. Also assumes that all conversions can be made in one step increments between major versions and ignores minor revisions.

Parameters:
  • nb (NotebookNode) –
  • to_version (int) – Major revision to convert the notebook to. Can either be an upgrade or a downgrade.
nbformat.validate(nbjson, ref=None, version=None, version_minor=None)

Checks whether the given notebook JSON conforms to the current notebook format schema.

Raises ValidationError if not valid.

class nbformat.ValidationError(message, validator=<unset>, path=(), cause=None, context=(), validator_value=<unset>, instance=<unset>, schema=<unset>, schema_path=(), parent=None)