##// END OF EJS Templates
describe what constitutes a minor revision to nbformat
Min RK -
Show More
@@ -1,342 +1,358
1 .. _nbformat:
1 .. _nbformat:
2
2
3 ===========================
3 ===========================
4 The Jupyter Notebook Format
4 The Jupyter Notebook Format
5 ===========================
5 ===========================
6
6
7 Introduction
7 Introduction
8 ============
8 ============
9
9
10 Jupyter (nΓ© IPython) notebook files are simple JSON documents,
10 Jupyter (nΓ© IPython) notebook files are simple JSON documents,
11 containing text, source code, rich media output, and metadata.
11 containing text, source code, rich media output, and metadata.
12 each segment of the document is stored in a cell.
12 each segment of the document is stored in a cell.
13
13
14 Some general points about the notebook format:
14 Some general points about the notebook format:
15
15
16 .. note::
16 .. note::
17
17
18 *All* metadata fields are optional.
18 *All* metadata fields are optional.
19 While the type and values of some metadata are defined,
19 While the type and values of some metadata are defined,
20 no metadata values are required to be defined.
20 no metadata values are required to be defined.
21
21
22
22
23 Top-level structure
23 Top-level structure
24 ===================
24 ===================
25
25
26 At the highest level, a Jupyter notebook is a dictionary with a few keys:
26 At the highest level, a Jupyter notebook is a dictionary with a few keys:
27
27
28 - metadata (dict)
28 - metadata (dict)
29 - nbformat (int)
29 - nbformat (int)
30 - nbformat_minor (int)
30 - nbformat_minor (int)
31 - cells (list)
31 - cells (list)
32
32
33 .. sourcecode:: python
33 .. sourcecode:: python
34
34
35 {
35 {
36 "metadata" : {
36 "metadata" : {
37 "signature": "hex-digest", # used for authenticating unsafe outputs on load
37 "signature": "hex-digest", # used for authenticating unsafe outputs on load
38 "kernel_info": {
38 "kernel_info": {
39 # if kernel_info is defined, its name field is required.
39 # if kernel_info is defined, its name field is required.
40 "name" : "the name of the kernel"
40 "name" : "the name of the kernel"
41 },
41 },
42 "language_info": {
42 "language_info": {
43 # if language_info is defined, its name field is required.
43 # if language_info is defined, its name field is required.
44 "name" : "the programming language of the kernel",
44 "name" : "the programming language of the kernel",
45 "version": "the version of the language",
45 "version": "the version of the language",
46 "codemirror_mode": "The name of the codemirror mode to use [optional]"
46 "codemirror_mode": "The name of the codemirror mode to use [optional]"
47 }
47 }
48 },
48 },
49 "nbformat": 4,
49 "nbformat": 4,
50 "nbformat_minor": 0,
50 "nbformat_minor": 0,
51 "cells" : [
51 "cells" : [
52 # list of cell dictionaries, see below
52 # list of cell dictionaries, see below
53 ],
53 ],
54 }
54 }
55
55
56 Some fields, such as code input and text output, are characteristically multi-line strings.
56 Some fields, such as code input and text output, are characteristically multi-line strings.
57 When these fields are written to disk, they **may** be written as a list of strings,
57 When these fields are written to disk, they **may** be written as a list of strings,
58 which should be joined with ``''`` when reading back into memory.
58 which should be joined with ``''`` when reading back into memory.
59 In programmatic APIs for working with notebooks (Python, Javascript),
59 In programmatic APIs for working with notebooks (Python, Javascript),
60 these are always re-joined into the original multi-line string.
60 these are always re-joined into the original multi-line string.
61 If you intend to work with notebook files directly,
61 If you intend to work with notebook files directly,
62 you must allow multi-line string fields to be either a string or list of strings.
62 you must allow multi-line string fields to be either a string or list of strings.
63
63
64
64
65 Cell Types
65 Cell Types
66 ==========
66 ==========
67
67
68 There are a few basic cell types for encapsulating code and text.
68 There are a few basic cell types for encapsulating code and text.
69 All cells have the following basic structure:
69 All cells have the following basic structure:
70
70
71 .. sourcecode:: python
71 .. sourcecode:: python
72
72
73 {
73 {
74 "cell_type" : "name",
74 "cell_type" : "name",
75 "metadata" : {},
75 "metadata" : {},
76 "source" : "single string or [list, of, strings]",
76 "source" : "single string or [list, of, strings]",
77 }
77 }
78
78
79
79
80 Markdown cells
80 Markdown cells
81 --------------
81 --------------
82
82
83 Markdown cells are used for body-text, and contain markdown,
83 Markdown cells are used for body-text, and contain markdown,
84 as defined in `GitHub-flavored markdown`_, and implemented in marked_.
84 as defined in `GitHub-flavored markdown`_, and implemented in marked_.
85
85
86 .. _GitHub-flavored markdown: https://help.github.com/articles/github-flavored-markdown
86 .. _GitHub-flavored markdown: https://help.github.com/articles/github-flavored-markdown
87 .. _marked: https://github.com/chjj/marked
87 .. _marked: https://github.com/chjj/marked
88
88
89 .. sourcecode:: python
89 .. sourcecode:: python
90
90
91 {
91 {
92 "cell_type" : "markdown",
92 "cell_type" : "markdown",
93 "metadata" : {},
93 "metadata" : {},
94 "source" : ["some *markdown*"],
94 "source" : ["some *markdown*"],
95 }
95 }
96
96
97 .. versionchanged:: nbformat 4.0
97 .. versionchanged:: nbformat 4.0
98
98
99 Heading cells have been removed, in favor of simple headings in markdown.
99 Heading cells have been removed, in favor of simple headings in markdown.
100
100
101
101
102 Code cells
102 Code cells
103 ----------
103 ----------
104
104
105 Code cells are the primary content of Jupyter notebooks.
105 Code cells are the primary content of Jupyter notebooks.
106 They contain source code in the language of the document's associated kernel,
106 They contain source code in the language of the document's associated kernel,
107 and a list of outputs associated with executing that code.
107 and a list of outputs associated with executing that code.
108 They also have an execution_count, which must be an integer or ``null``.
108 They also have an execution_count, which must be an integer or ``null``.
109
109
110 .. sourcecode:: python
110 .. sourcecode:: python
111
111
112 {
112 {
113 "cell_type" : "code",
113 "cell_type" : "code",
114 "execution_count": 1, # integer or null
114 "execution_count": 1, # integer or null
115 "metadata" : {
115 "metadata" : {
116 "collapsed" : True, # whether the output of the cell is collapsed
116 "collapsed" : True, # whether the output of the cell is collapsed
117 "autoscroll": False, # any of true, false or "auto"
117 "autoscroll": False, # any of true, false or "auto"
118 },
118 },
119 "source" : ["some code"],
119 "source" : ["some code"],
120 "outputs": [{
120 "outputs": [{
121 # list of output dicts (described below)
121 # list of output dicts (described below)
122 "output_type": "stream",
122 "output_type": "stream",
123 ...
123 ...
124 }],
124 }],
125 }
125 }
126
126
127 .. versionchanged:: nbformat 4.0
127 .. versionchanged:: nbformat 4.0
128
128
129 ``input`` was renamed to ``source``, for consistency among cell types.
129 ``input`` was renamed to ``source``, for consistency among cell types.
130
130
131 .. versionchanged:: nbformat 4.0
131 .. versionchanged:: nbformat 4.0
132
132
133 ``prompt_number`` renamed to ``execution_count``
133 ``prompt_number`` renamed to ``execution_count``
134
134
135 Code cell outputs
135 Code cell outputs
136 -----------------
136 -----------------
137
137
138 A code cell can have a variety of outputs (stream data or rich mime-type output).
138 A code cell can have a variety of outputs (stream data or rich mime-type output).
139 These correspond to :ref:`messages <messaging>` produced as a result of executing the cell.
139 These correspond to :ref:`messages <messaging>` produced as a result of executing the cell.
140
140
141 All outputs have an ``output_type`` field,
141 All outputs have an ``output_type`` field,
142 which is a string defining what type of output it is.
142 which is a string defining what type of output it is.
143
143
144
144
145 stream output
145 stream output
146 *************
146 *************
147
147
148 .. sourcecode:: python
148 .. sourcecode:: python
149
149
150 {
150 {
151 "output_type" : "stream",
151 "output_type" : "stream",
152 "name" : "stdout", # or stderr
152 "name" : "stdout", # or stderr
153 "text" : ["multiline stream text"],
153 "text" : ["multiline stream text"],
154 }
154 }
155
155
156 .. versionchanged:: nbformat 4.0
156 .. versionchanged:: nbformat 4.0
157
157
158 The keys ``stream`` key was changed to ``name`` to match
158 The keys ``stream`` key was changed to ``name`` to match
159 the stream message.
159 the stream message.
160
160
161
161
162 display_data
162 display_data
163 ************
163 ************
164
164
165 Rich display outputs, as created by ``display_data`` messages,
165 Rich display outputs, as created by ``display_data`` messages,
166 contain data keyed by mime-type. This is often called a mime-bundle,
166 contain data keyed by mime-type. This is often called a mime-bundle,
167 and shows up in various locations in the notebook format and message spec.
167 and shows up in various locations in the notebook format and message spec.
168 The metadata of these messages may be keyed by mime-type as well.
168 The metadata of these messages may be keyed by mime-type as well.
169
169
170
170
171
171
172 .. sourcecode:: python
172 .. sourcecode:: python
173
173
174 {
174 {
175 "output_type" : "display_data",
175 "output_type" : "display_data",
176 "data" : {
176 "data" : {
177 "text/plain" : ["multiline text data"],
177 "text/plain" : ["multiline text data"],
178 "image/png": ["base64-encoded-png-data"],
178 "image/png": ["base64-encoded-png-data"],
179 "application/json": {
179 "application/json": {
180 # JSON data is included as-is
180 # JSON data is included as-is
181 "json": "data",
181 "json": "data",
182 },
182 },
183 },
183 },
184 "metadata" : {
184 "metadata" : {
185 "image/png": {
185 "image/png": {
186 "width": 640,
186 "width": 640,
187 "height": 480,
187 "height": 480,
188 },
188 },
189 },
189 },
190 }
190 }
191
191
192
192
193 .. versionchanged:: nbformat 4.0
193 .. versionchanged:: nbformat 4.0
194
194
195 ``application/json`` output is no longer double-serialized into a string.
195 ``application/json`` output is no longer double-serialized into a string.
196
196
197 .. versionchanged:: nbformat 4.0
197 .. versionchanged:: nbformat 4.0
198
198
199 mime-types are used for keys, instead of a combination of short names (``text``)
199 mime-types are used for keys, instead of a combination of short names (``text``)
200 and mime-types, and are stored in a ``data`` key, rather than the top-level.
200 and mime-types, and are stored in a ``data`` key, rather than the top-level.
201 i.e. ``output.data['image/png']`` instead of ``output.png``.
201 i.e. ``output.data['image/png']`` instead of ``output.png``.
202
202
203
203
204 execute_result
204 execute_result
205 **************
205 **************
206
206
207 Results of executing a cell (as created by ``displayhook`` in Python)
207 Results of executing a cell (as created by ``displayhook`` in Python)
208 are stored in ``execute_result`` outputs.
208 are stored in ``execute_result`` outputs.
209 `execute_result` outputs are identical to ``display_data``,
209 `execute_result` outputs are identical to ``display_data``,
210 adding only a ``execution_count`` field, which must be an integer.
210 adding only a ``execution_count`` field, which must be an integer.
211
211
212 .. sourcecode:: python
212 .. sourcecode:: python
213
213
214 {
214 {
215 "output_type" : "execute_result",
215 "output_type" : "execute_result",
216 "execution_count": 42,
216 "execution_count": 42,
217 "data" : {
217 "data" : {
218 "text/plain" : ["multiline text data"],
218 "text/plain" : ["multiline text data"],
219 "image/png": ["base64-encoded-png-data"],
219 "image/png": ["base64-encoded-png-data"],
220 "application/json": {
220 "application/json": {
221 # JSON data is included as-is
221 # JSON data is included as-is
222 "json": "data",
222 "json": "data",
223 },
223 },
224 },
224 },
225 "metadata" : {
225 "metadata" : {
226 "image/png": {
226 "image/png": {
227 "width": 640,
227 "width": 640,
228 "height": 480,
228 "height": 480,
229 },
229 },
230 },
230 },
231 }
231 }
232
232
233 .. versionchanged:: nbformat 4.0
233 .. versionchanged:: nbformat 4.0
234
234
235 ``pyout`` renamed to ``execute_result``
235 ``pyout`` renamed to ``execute_result``
236
236
237 .. versionchanged:: nbformat 4.0
237 .. versionchanged:: nbformat 4.0
238
238
239 ``prompt_number`` renamed to ``execution_count``
239 ``prompt_number`` renamed to ``execution_count``
240
240
241
241
242 error
242 error
243 *****
243 *****
244
244
245 Failed execution may show a traceback
245 Failed execution may show a traceback
246
246
247 .. sourcecode:: python
247 .. sourcecode:: python
248
248
249 {
249 {
250 'ename' : str, # Exception name, as a string
250 'ename' : str, # Exception name, as a string
251 'evalue' : str, # Exception value, as a string
251 'evalue' : str, # Exception value, as a string
252
252
253 # The traceback will contain a list of frames,
253 # The traceback will contain a list of frames,
254 # represented each as a string.
254 # represented each as a string.
255 'traceback' : list,
255 'traceback' : list,
256 }
256 }
257
257
258 .. versionchanged:: nbformat 4.0
258 .. versionchanged:: nbformat 4.0
259
259
260 ``pyerr`` renamed to ``error``
260 ``pyerr`` renamed to ``error``
261
261
262
262
263 .. _raw nbconvert cells:
263 .. _raw nbconvert cells:
264
264
265 Raw NBConvert cells
265 Raw NBConvert cells
266 -------------------
266 -------------------
267
267
268 A raw cell is defined as content that should be included *unmodified* in :ref:`nbconvert <nbconvert>` output.
268 A raw cell is defined as content that should be included *unmodified* in :ref:`nbconvert <nbconvert>` output.
269 For example, this cell could include raw LaTeX for nbconvert to pdf via latex,
269 For example, this cell could include raw LaTeX for nbconvert to pdf via latex,
270 or restructured text for use in Sphinx documentation.
270 or restructured text for use in Sphinx documentation.
271
271
272 The notebook authoring environment does not render raw cells.
272 The notebook authoring environment does not render raw cells.
273
273
274 The only logic in a raw cell is the `format` metadata field.
274 The only logic in a raw cell is the `format` metadata field.
275 If defined, it specifies which nbconvert output format is the intended target
275 If defined, it specifies which nbconvert output format is the intended target
276 for the raw cell. When outputting to any other format,
276 for the raw cell. When outputting to any other format,
277 the raw cell's contents will be excluded.
277 the raw cell's contents will be excluded.
278 In the default case when this value is undefined,
278 In the default case when this value is undefined,
279 a raw cell's contents will be included in any nbconvert output,
279 a raw cell's contents will be included in any nbconvert output,
280 regardless of format.
280 regardless of format.
281
281
282 .. sourcecode:: python
282 .. sourcecode:: python
283
283
284 {
284 {
285 "cell_type" : "raw",
285 "cell_type" : "raw",
286 "metadata" : {
286 "metadata" : {
287 # the mime-type of the target nbconvert format.
287 # the mime-type of the target nbconvert format.
288 # nbconvert to formats other than this will exclude this cell.
288 # nbconvert to formats other than this will exclude this cell.
289 "format" : "mime/type"
289 "format" : "mime/type"
290 },
290 },
291 "source" : ["some nbformat mime-type data"]
291 "source" : ["some nbformat mime-type data"]
292 }
292 }
293
293
294 Backwared-compatible changes
295 ============================
296
297 The notebook format is an evolving format. When backward-compatible changes are made,
298 the notebook format minor version is incremented. When backward-incompatible changes are made,
299 the major version is incremented.
300
301 As of nbformat 4.x, backward-compatible changes include:
302
303 - new fields in any cell or output or metadata
304 - new cell types
305 - new output types
306
307 New cell or output types will not be rendered in versions that do not recognize them,
308 but they will be preserved.
309
294 Metadata
310 Metadata
295 ========
311 ========
296
312
297 Metadata is a place that you can put arbitrary JSONable information about
313 Metadata is a place that you can put arbitrary JSONable information about
298 your notebook, cell, or output. Because it is a shared namespace,
314 your notebook, cell, or output. Because it is a shared namespace,
299 any custom metadata should use a sufficiently unique namespace,
315 any custom metadata should use a sufficiently unique namespace,
300 such as `metadata.kaylees_md.foo = "bar"`.
316 such as `metadata.kaylees_md.foo = "bar"`.
301
317
302 Metadata fields officially defined for Jupyter notebooks are listed here:
318 Metadata fields officially defined for Jupyter notebooks are listed here:
303
319
304 Notebook metadata
320 Notebook metadata
305 -----------------
321 -----------------
306
322
307 The following metadata keys are defined at the notebook level:
323 The following metadata keys are defined at the notebook level:
308
324
309 =========== =============== ==============
325 =========== =============== ==============
310 Key Value Interpretation
326 Key Value Interpretation
311 =========== =============== ==============
327 =========== =============== ==============
312 kernelspec dict A :ref:`kernel specification <kernelspecs>`
328 kernelspec dict A :ref:`kernel specification <kernelspecs>`
313 signature str A hashed :ref:`signature <notebook_security>` of the notebook
329 signature str A hashed :ref:`signature <notebook_security>` of the notebook
314 =========== =============== ==============
330 =========== =============== ==============
315
331
316
332
317 Cell metadata
333 Cell metadata
318 -------------
334 -------------
319
335
320 The following metadata keys are defined at the cell level:
336 The following metadata keys are defined at the cell level:
321
337
322 =========== =============== ==============
338 =========== =============== ==============
323 Key Value Interpretation
339 Key Value Interpretation
324 =========== =============== ==============
340 =========== =============== ==============
325 collapsed bool Whether the cell's output container should be collapsed
341 collapsed bool Whether the cell's output container should be collapsed
326 autoscroll bool or 'auto' Whether the cell's output is scrolled, unscrolled, or autoscrolled
342 autoscroll bool or 'auto' Whether the cell's output is scrolled, unscrolled, or autoscrolled
327 deletable bool If False, prevent deletion of the cell
343 deletable bool If False, prevent deletion of the cell
328 format 'mime/type' The mime-type of a :ref:`Raw NBConvert Cell <raw nbconvert cells>`
344 format 'mime/type' The mime-type of a :ref:`Raw NBConvert Cell <raw nbconvert cells>`
329 name str A name for the cell. Should be unique
345 name str A name for the cell. Should be unique
330 tags list of str A list of string tags on the cell. Commas are not allowed in a tag
346 tags list of str A list of string tags on the cell. Commas are not allowed in a tag
331 =========== =============== ==============
347 =========== =============== ==============
332
348
333 Output metadata
349 Output metadata
334 ---------------
350 ---------------
335
351
336 The following metadata keys are defined for code cell outputs:
352 The following metadata keys are defined for code cell outputs:
337
353
338 =========== =============== ==============
354 =========== =============== ==============
339 Key Value Interpretation
355 Key Value Interpretation
340 =========== =============== ==============
356 =========== =============== ==============
341 isolated bool Whether the output should be isolated into an IFrame
357 isolated bool Whether the output should be isolated into an IFrame
342 =========== =============== ==============
358 =========== =============== ==============
General Comments 0
You need to be logged in to leave comments. Login now