nbformat.rst
336 lines
| 9.2 KiB
| text/x-rst
|
RstLexer
|
r18586 | .. _nbformat: | ||
=========================== | ||||
The Jupyter Notebook Format | ||||
=========================== | ||||
Introduction | ||||
============ | ||||
Jupyter (née IPython) notebook files are simple JSON documents, | ||||
containing text, source code, rich media output, and metadata. | ||||
each segment of the document is stored in a cell. | ||||
Some general points about the notebook format: | ||||
.. note:: | ||||
*All* metadata fields are optional. | ||||
While the type and values of some metadata are defined, | ||||
no metadata values are required to be defined. | ||||
Top-level structure | ||||
=================== | ||||
At the highest level, a Jupyter notebook is a dictionary with a few keys: | ||||
- metadata (dict) | ||||
- nbformat (int) | ||||
- nbformat_minor (int) | ||||
- cells (list) | ||||
.. sourcecode:: python | ||||
{ | ||||
"metadata" : { | ||||
"signature": "hex-digest", # used for authenticating unsafe outputs on load | ||||
"kernel_info": { | ||||
# if kernel_info is defined, its name and language fields are required. | ||||
"name" : "the name of the kernel", | ||||
"language" : "the programming language of the kernel", | ||||
"codemirror_mode": "The name of the codemirror mode to use [optional]" | ||||
}, | ||||
}, | ||||
"nbformat": 4, | ||||
"nbformat_minor": 0, | ||||
"cells" : [ | ||||
# list of cell dictionaries, see below | ||||
], | ||||
} | ||||
|
r18602 | Some fields, such as code input and text output, are characteristically multi-line strings. | ||
When these fields are written to disk, they **may** be written as a list of strings, | ||||
which should be joined with ``''`` when reading back into memory. | ||||
In programmatic APIs for working with notebooks (Python, Javascript), | ||||
these are always re-joined into the original multi-line string. | ||||
If you intend to work with notebook files directly, | ||||
you must allow multi-line string fields to be either a string or list of strings. | ||||
|
r18586 | |||
Cell Types | ||||
========== | ||||
There are a few basic cell types for encapsulating code and text. | ||||
All cells have the following basic structure: | ||||
.. sourcecode:: python | ||||
{ | ||||
"cell_type" : "name", | ||||
"metadata" : {}, | ||||
"source" : "single string or [list, of, strings]", | ||||
} | ||||
Markdown cells | ||||
-------------- | ||||
Markdown cells are used for body-text, and contain markdown, | ||||
as defined in `GitHub-flavored markdown`_, and implemented in marked_. | ||||
.. _GitHub-flavored markdown: https://help.github.com/articles/github-flavored-markdown | ||||
.. _marked: https://github.com/chjj/marked | ||||
.. sourcecode:: python | ||||
{ | ||||
"cell_type" : "markdown", | ||||
"metadata" : {}, | ||||
"source" : ["some *markdown*"], | ||||
} | ||||
|
r18602 | .. versionchanged:: nbformat 4.0 | ||
|
r18586 | |||
|
r18596 | Heading cells have been removed, in favor of simple headings in markdown. | ||
|
r18586 | |||
Code cells | ||||
---------- | ||||
Code cells are the primary content of Jupyter notebooks. | ||||
|
r18602 | They contain source code in the language of the document's associated kernel, | ||
and a list of outputs associated with executing that code. | ||||
|
r18593 | They also have an execution_count, which must be an integer or ``null``. | ||
|
r18586 | |||
.. sourcecode:: python | ||||
{ | ||||
"cell_type" : "code", | ||||
|
r18593 | "execution_count": 1, # integer or null | ||
|
r18586 | "metadata" : { | ||
"collapsed" : True, # whether the output of the cell is collapsed | ||||
"autoscroll": False, # any of true, false or "auto" | ||||
}, | ||||
"source" : ["some code"], | ||||
"outputs": [{ | ||||
# list of output dicts (described below) | ||||
"output_type": "stream", | ||||
... | ||||
}], | ||||
} | ||||
|
r18602 | .. versionchanged:: nbformat 4.0 | ||
|
r18586 | |||
``input`` was renamed to ``source``, for consistency among cell types. | ||||
|
r18602 | .. versionchanged:: nbformat 4.0 | ||
|
r18593 | |||
``prompt_number`` renamed to ``execution_count`` | ||||
|
r18586 | Code cell outputs | ||
----------------- | ||||
A code cell can have a variety of outputs (stream data or rich mime-type output). | ||||
These correspond to :ref:`messages <messaging>` produced as a result of executing the cell. | ||||
All outputs have an ``output_type`` field, | ||||
which is a string defining what type of output it is. | ||||
stream output | ||||
************* | ||||
.. sourcecode:: python | ||||
{ | ||||
"output_type" : "stream", | ||||
"name" : "stdout", # or stderr | ||||
"data" : ["multiline stream text"], | ||||
} | ||||
|
r18602 | .. versionchanged:: nbformat 4.0 | ||
|
r18586 | |||
The keys ``stream`` and ``text`` were changed to ``name`` and ``data`` to match | ||||
the stream message specification. | ||||
display_data | ||||
************ | ||||
Rich display messages (as created by ``display_data`` messages) | ||||
contain data keyed by mime-type. All mime-type data should | ||||
The metadata of these messages may be keyed by mime-type as well. | ||||
.. sourcecode:: python | ||||
{ | ||||
"output_type" : "display_data", | ||||
|
r18593 | "data" : { | ||
"text/plain" : ["multiline text data"], | ||||
"image/png": ["base64-encoded-png-data"], | ||||
"application/json": { | ||||
# JSON data is included as-is | ||||
"json": "data", | ||||
}, | ||||
|
r18586 | }, | ||
"metadata" : { | ||||
"image/png": { | ||||
"width": 640, | ||||
"height": 480, | ||||
}, | ||||
}, | ||||
} | ||||
|
r18602 | .. versionchanged:: nbformat 4.0 | ||
|
r18586 | |||
``application/json`` output is no longer double-serialized into a string. | ||||
|
r18602 | .. versionchanged:: nbformat 4.0 | ||
|
r18586 | |||
mime-types are used for keys, instead of a combination of short names (``text``) | ||||
|
r18593 | and mime-types, and are stored in a ``data`` key, rather than the top-level. | ||
i.e. ``output.data['image/png']`` instead of ``output.png``. | ||||
|
r18586 | |||
execute_result | ||||
************** | ||||
Results of executing a cell (as created by ``displayhook`` in Python) | ||||
are stored in ``execute_result`` outputs. | ||||
`execute_result` outputs are identical to ``display_data``, | ||||
|
r18602 | adding only a ``execution_count`` field, which must be an integer. | ||
|
r18586 | |||
.. sourcecode:: python | ||||
{ | ||||
"output_type" : "execute_result", | ||||
|
r18602 | "execution_count": 42, | ||
|
r18593 | "data" : { | ||
"text/plain" : ["multiline text data"], | ||||
"image/png": ["base64-encoded-png-data"], | ||||
"application/json": { | ||||
# JSON data is included as-is | ||||
"json": "data", | ||||
}, | ||||
|
r18586 | }, | ||
"metadata" : { | ||||
"image/png": { | ||||
"width": 640, | ||||
"height": 480, | ||||
}, | ||||
}, | ||||
} | ||||
|
r18602 | .. versionchanged:: nbformat 4.0 | ||
|
r18586 | |||
``pyout`` renamed to ``execute_result`` | ||||
|
r18602 | .. versionchanged:: nbformat 4.0 | ||
|
r18593 | |||
``prompt_number`` renamed to ``execution_count`` | ||||
|
r18586 | |||
error | ||||
***** | ||||
Failed execution may show a traceback | ||||
.. sourcecode:: python | ||||
{ | ||||
'ename' : str, # Exception name, as a string | ||||
'evalue' : str, # Exception value, as a string | ||||
# The traceback will contain a list of frames, | ||||
# represented each as a string. | ||||
'traceback' : list, | ||||
} | ||||
|
r18602 | .. versionchanged:: nbformat 4.0 | ||
|
r18586 | |||
``pyerr`` renamed to ``error`` | ||||
|
r18598 | .. _raw nbconvert cells: | ||
|
r18586 | Raw NBConvert cells | ||
------------------- | ||||
A raw cell is defined as content that should be included *unmodified* in :ref:`nbconvert <nbconvert>` output. | ||||
For example, this cell could include raw LaTeX for nbconvert to pdf via latex, | ||||
or restructured text for use in Sphinx documentation. | ||||
The notebook authoring environment does not render raw cells. | ||||
The only logic in a raw cell is the `format` metadata field. | ||||
If defined, it specifies which nbconvert output format is the intended target | ||||
for the raw cell. When outputting to any other format, | ||||
the raw cell's contents will be excluded. | ||||
In the default case when this value is undefined, | ||||
a raw cell's contents will be included in any nbconvert output, | ||||
regardless of format. | ||||
.. sourcecode:: python | ||||
{ | ||||
"cell_type" : "raw", | ||||
"metadata" : { | ||||
# the mime-type of the target nbconvert format. | ||||
# nbconvert to formats other than this will exclude this cell. | ||||
"format" : "mime/type" | ||||
}, | ||||
"source" : ["some nbformat mime-type data"] | ||||
} | ||||
|
r18598 | |||
Metadata | ||||
======== | ||||
Metadata is a place that you can put arbitrary JSONable information about | ||||
your notebook, cell, or output. Because it is a shared namespace, | ||||
any custom metadata should use a sufficiently unique namespace, | ||||
such as `metadata.kaylees_md.foo = "bar"`. | ||||
Metadata fields officially defined for Jupyter notebooks are listed here: | ||||
Notebook metadata | ||||
----------------- | ||||
The following metadata keys are defined at the notebook level: | ||||
=========== =============== ============== | ||||
Key Value Interpretation | ||||
=========== =============== ============== | ||||
|
r18602 | kernelspec dict A :ref:`kernel specification <kernelspecs>` | ||
signature str A hashed :ref:`signature <notebook_security>` of the notebook | ||||
|
r18598 | =========== =============== ============== | ||
Cell metadata | ||||
------------- | ||||
The following metadata keys are defined at the cell level: | ||||
=========== =============== ============== | ||||
Key Value Interpretation | ||||
=========== =============== ============== | ||||
collapsed bool Whether the cell's output container should be collapsed | ||||
autoscroll bool or 'auto' Whether the cell's output is scrolled, unscrolled, or autoscrolled | ||||
deletable bool If False, prevent deletion of the cell | ||||
format 'mime/type' The mime-type of a :ref:`Raw NBConvert Cell <raw nbconvert cells>` | ||||
name str A name for the cell. Should be unique | ||||
tags list of str A list of string tags on the cell. Commas are not allowed in a tag | ||||
=========== =============== ============== | ||||
Output metadata | ||||
--------------- | ||||
The following metadata keys are defined for code cell outputs: | ||||
=========== =============== ============== | ||||
Key Value Interpretation | ||||
=========== =============== ============== | ||||
isolated bool Whether the output should be isolated into an IFrame | ||||
=========== =============== ============== | ||||