Note

This documentation is for a development version of IPython. There may be significant differences from the latest stable release.

Module: nbformat.current

The official API for working with notebooks in the current format version.

2 Classes

class IPython.nbformat.current.NBFormatError

Bases: exceptions.ValueError

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

Bases: IPython.utils.ipstruct.Struct

20 Functions

IPython.nbformat.current.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.current.new_author(name=None, email=None, affiliation=None, url=None)

Create a new author.

IPython.nbformat.current.new_code_cell(input=None, prompt_number=None, outputs=None, language=u'python', collapsed=False, metadata=None)

Create a new code cell with input and output

IPython.nbformat.current.new_heading_cell(source=None, level=1, rendered=None, metadata=None)

Create a new section cell with a given integer level.

IPython.nbformat.current.new_metadata(name=None, authors=None, license=None, created=None, modified=None, gistid=None)

Create a new metadata node.

IPython.nbformat.current.new_notebook(name=None, metadata=None, worksheets=None)

Create a notebook by name, id and a list of worksheets.

IPython.nbformat.current.new_output(output_type, output_text=None, output_png=None, output_html=None, output_svg=None, output_latex=None, output_json=None, output_javascript=None, output_jpeg=None, prompt_number=None, ename=None, evalue=None, traceback=None, stream=None, metadata=None)

Create a new output, to go in the cell.outputs list of a code cell.

IPython.nbformat.current.new_text_cell(cell_type, source=None, rendered=None, metadata=None)

Create a new text cell.

IPython.nbformat.current.new_worksheet(name=None, cells=None, metadata=None)

Create a worksheet by name with with a list of cells.

IPython.nbformat.current.parse_filename(fname)

Parse a notebook filename.

This function takes a notebook filename and returns the notebook format (json/py) and the notebook name. This logic can be summarized as follows:

• notebook.ipynb -> (notebook.ipynb, notebook, json)
• notebook.json -> (notebook.json, notebook, json)
• notebook.py -> (notebook.py, notebook, py)
• notebook -> (notebook.ipynb, notebook, json)

Parameters:

fname : unicode

The notebook filename. The filename can use a specific filename extention (.ipynb, .json, .py) or none, in which case .ipynb will be assumed.

Returns:

(fname, name, format) : (unicode, unicode, unicode)

The filename, notebook name and format.

IPython.nbformat.current.parse_py(s, **kwargs)

Parse a string into a (nbformat, string) tuple.

IPython.nbformat.current.read(fp, format='DEPRECATED', **kwargs)

Read a notebook from a file and return the NotebookNode object.

This function properly handles notebooks of any version. The notebook returned will always be in the current version’s format.

Parameters:

fp : file

Any file-like object with a read method.

Returns:

nb : NotebookNode

The notebook that was read.

IPython.nbformat.current.reads(s, format='DEPRECATED', version=3, **kwargs)

Read a notebook from a string and return the NotebookNode object.

This function properly handles notebooks of any version. The notebook returned will always be in the current version’s format.

Parameters:

s : unicode

The raw unicode string to read the notebook from.

Returns:

nb : NotebookNode

The notebook that was read.

IPython.nbformat.current.reads_json(nbjson, **kwargs)

DEPRECATED, use reads

IPython.nbformat.current.reads_py(s, **kwargs)

DEPRECATED: use nbconvert

IPython.nbformat.current.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.current.write(nb, fp, format='DEPRECATED', **kwargs)

Write a notebook to a file in a given format in the current nbformat version.

This function always writes the notebook in the current nbformat version.

Parameters:

nb : NotebookNode

The notebook to write.

fp : file

Any file-like object with a write method.

IPython.nbformat.current.writes(nb, format='DEPRECATED', version=3, **kwargs)

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

This function always writes the notebook in the current nbformat version.

Parameters:

nb : NotebookNode

The notebook to write.

version : int

The nbformat version to write. Used for downgrading notebooks.

Returns:

s : unicode

The notebook string.

IPython.nbformat.current.writes_json(nb, **kwargs)

DEPRECATED, use writes

IPython.nbformat.current.writes_py(nb, **kwargs)

DEPRECATED: use nbconvert