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