Warning

This documentation is for an old version of IPython. You can find docs for newer versions here.

Module: nbformat

The IPython notebook format

Use this module to read or write notebook files as particular nbformat versions.

3 Classes

class IPython.nbformat.NBFormatError

Bases: ValueError

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

Bases: IPython.utils.ipstruct.Struct

A dict-like node with attribute-access

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

Bases: jsonschema.exceptions._Error

7 Functions

IPython.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.

IPython.nbformat.from_dict(d)

Convert dict to dict-like NotebookNode

Recursively converts any dict in the container to a NotebookNode

IPython.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

Any file-like object with a read method, 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 : NotebookNode

The notebook that was read.

IPython.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 : NotebookNode

The notebook that was read.

IPython.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.

IPython.nbformat.write(nb, fp, version=<object object>, **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.

IPython.nbformat.writes(nb, version=<object object>, **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 : unicode

The notebook as a JSON string.