##// END OF EJS Templates
fix gender on Jupyter...
MinRK -
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Γ©e 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 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