Show More
@@ -0,0 +1,278 b'' | |||||
|
1 | .. _nbformat: | |||
|
2 | ||||
|
3 | =========================== | |||
|
4 | The Jupyter Notebook Format | |||
|
5 | =========================== | |||
|
6 | ||||
|
7 | Introduction | |||
|
8 | ============ | |||
|
9 | ||||
|
10 | Jupyter (née IPython) notebook files are simple JSON documents, | |||
|
11 | containing text, source code, rich media output, and metadata. | |||
|
12 | each segment of the document is stored in a cell. | |||
|
13 | ||||
|
14 | Some general points about the notebook format: | |||
|
15 | ||||
|
16 | .. note:: | |||
|
17 | ||||
|
18 | *All* metadata fields are optional. | |||
|
19 | While the type and values of some metadata are defined, | |||
|
20 | no metadata values are required to be defined. | |||
|
21 | ||||
|
22 | ||||
|
23 | Top-level structure | |||
|
24 | =================== | |||
|
25 | ||||
|
26 | At the highest level, a Jupyter notebook is a dictionary with a few keys: | |||
|
27 | ||||
|
28 | - metadata (dict) | |||
|
29 | - nbformat (int) | |||
|
30 | - nbformat_minor (int) | |||
|
31 | - cells (list) | |||
|
32 | ||||
|
33 | .. sourcecode:: python | |||
|
34 | ||||
|
35 | { | |||
|
36 | "metadata" : { | |||
|
37 | "signature": "hex-digest", # used for authenticating unsafe outputs on load | |||
|
38 | "kernel_info": { | |||
|
39 | # if kernel_info is defined, its name and language fields are required. | |||
|
40 | "name" : "the name of the kernel", | |||
|
41 | "language" : "the programming language of the kernel", | |||
|
42 | "codemirror_mode": "The name of the codemirror mode to use [optional]" | |||
|
43 | }, | |||
|
44 | }, | |||
|
45 | "nbformat": 4, | |||
|
46 | "nbformat_minor": 0, | |||
|
47 | "cells" : [ | |||
|
48 | # list of cell dictionaries, see below | |||
|
49 | ], | |||
|
50 | } | |||
|
51 | ||||
|
52 | ||||
|
53 | Cell Types | |||
|
54 | ========== | |||
|
55 | ||||
|
56 | There are a few basic cell types for encapsulating code and text. | |||
|
57 | All cells have the following basic structure: | |||
|
58 | ||||
|
59 | .. sourcecode:: python | |||
|
60 | ||||
|
61 | { | |||
|
62 | "cell_type" : "name", | |||
|
63 | "metadata" : {}, | |||
|
64 | "source" : "single string or [list, of, strings]", | |||
|
65 | } | |||
|
66 | ||||
|
67 | ||||
|
68 | Markdown cells | |||
|
69 | -------------- | |||
|
70 | ||||
|
71 | Markdown cells are used for body-text, and contain markdown, | |||
|
72 | as defined in `GitHub-flavored markdown`_, and implemented in marked_. | |||
|
73 | ||||
|
74 | .. _GitHub-flavored markdown: https://help.github.com/articles/github-flavored-markdown | |||
|
75 | .. _marked: https://github.com/chjj/marked | |||
|
76 | ||||
|
77 | .. sourcecode:: python | |||
|
78 | ||||
|
79 | { | |||
|
80 | "cell_type" : "markdown", | |||
|
81 | "metadata" : {}, | |||
|
82 | "source" : ["some *markdown*"], | |||
|
83 | } | |||
|
84 | ||||
|
85 | ||||
|
86 | Heading cells | |||
|
87 | ------------- | |||
|
88 | ||||
|
89 | Heading cells are single lines describing a section header (mapping onto h1-h6 tags in HTML). | |||
|
90 | These cells indicate structure of the document, | |||
|
91 | and are used for things like outline-views and automatically generating HTML anchors | |||
|
92 | within the page for quick navigation. | |||
|
93 | They have a ``level`` field, with an integer value from 1-6 (inclusive). | |||
|
94 | ||||
|
95 | .. sourcecode:: python | |||
|
96 | ||||
|
97 | { | |||
|
98 | "cell_type" : "markdown", | |||
|
99 | "metadata" : {}, | |||
|
100 | "level" : 1, # An integer on [1-6] | |||
|
101 | "source" : ["A simple heading"], | |||
|
102 | } | |||
|
103 | ||||
|
104 | ||||
|
105 | Code cells | |||
|
106 | ---------- | |||
|
107 | ||||
|
108 | Code cells are the primary content of Jupyter notebooks. | |||
|
109 | They contain source code int e language of the document's associated kernel, | |||
|
110 | and a list of outputs associated with executing. | |||
|
111 | They also have a prompt_number, which must be an integer or ``null``. | |||
|
112 | ||||
|
113 | .. sourcecode:: python | |||
|
114 | ||||
|
115 | { | |||
|
116 | "cell_type" : "code", | |||
|
117 | "prompt_number": 1, # integer or null | |||
|
118 | "metadata" : { | |||
|
119 | "collapsed" : True, # whether the output of the cell is collapsed | |||
|
120 | "autoscroll": False, # any of true, false or "auto" | |||
|
121 | }, | |||
|
122 | "source" : ["some code"], | |||
|
123 | "outputs": [{ | |||
|
124 | # list of output dicts (described below) | |||
|
125 | "output_type": "stream", | |||
|
126 | ... | |||
|
127 | }], | |||
|
128 | } | |||
|
129 | ||||
|
130 | .. versionchanged:: 4.0 | |||
|
131 | ||||
|
132 | ``input`` was renamed to ``source``, for consistency among cell types. | |||
|
133 | ||||
|
134 | Code cell outputs | |||
|
135 | ----------------- | |||
|
136 | ||||
|
137 | A code cell can have a variety of outputs (stream data or rich mime-type output). | |||
|
138 | These correspond to :ref:`messages <messaging>` produced as a result of executing the cell. | |||
|
139 | ||||
|
140 | All outputs have an ``output_type`` field, | |||
|
141 | which is a string defining what type of output it is. | |||
|
142 | ||||
|
143 | ||||
|
144 | stream output | |||
|
145 | ************* | |||
|
146 | ||||
|
147 | .. sourcecode:: python | |||
|
148 | ||||
|
149 | { | |||
|
150 | "output_type" : "stream", | |||
|
151 | "name" : "stdout", # or stderr | |||
|
152 | "data" : ["multiline stream text"], | |||
|
153 | } | |||
|
154 | ||||
|
155 | .. versionchanged:: 4.0 | |||
|
156 | ||||
|
157 | The keys ``stream`` and ``text`` were changed to ``name`` and ``data`` to match | |||
|
158 | the stream message specification. | |||
|
159 | ||||
|
160 | ||||
|
161 | display_data | |||
|
162 | ************ | |||
|
163 | ||||
|
164 | Rich display messages (as created by ``display_data`` messages) | |||
|
165 | contain data keyed by mime-type. All mime-type data should | |||
|
166 | The metadata of these messages may be keyed by mime-type as well. | |||
|
167 | ||||
|
168 | ||||
|
169 | .. sourcecode:: python | |||
|
170 | ||||
|
171 | { | |||
|
172 | "output_type" : "display_data", | |||
|
173 | "text/plain" : ["multiline text data"], | |||
|
174 | "image/png": ["base64-encoded-png-data"], | |||
|
175 | "application/json": { | |||
|
176 | # JSON data is included as-is | |||
|
177 | "json": "data", | |||
|
178 | }, | |||
|
179 | "metadata" : { | |||
|
180 | "image/png": { | |||
|
181 | "width": 640, | |||
|
182 | "height": 480, | |||
|
183 | }, | |||
|
184 | }, | |||
|
185 | } | |||
|
186 | ||||
|
187 | ||||
|
188 | .. versionchanged:: 4.0 | |||
|
189 | ||||
|
190 | ``application/json`` output is no longer double-serialized into a string. | |||
|
191 | ||||
|
192 | .. versionchanged:: 4.0 | |||
|
193 | ||||
|
194 | mime-types are used for keys, instead of a combination of short names (``text``) | |||
|
195 | and mime-types. | |||
|
196 | ||||
|
197 | ||||
|
198 | execute_result | |||
|
199 | ************** | |||
|
200 | ||||
|
201 | Results of executing a cell (as created by ``displayhook`` in Python) | |||
|
202 | are stored in ``execute_result`` outputs. | |||
|
203 | `execute_result` outputs are identical to ``display_data``, | |||
|
204 | adding only a ``prompt_number`` field, which must be an integer. | |||
|
205 | ||||
|
206 | .. sourcecode:: python | |||
|
207 | ||||
|
208 | { | |||
|
209 | "output_type" : "execute_result", | |||
|
210 | "prompt_number": 42, | |||
|
211 | "text/plain" : ["multiline text data"], | |||
|
212 | "image/png": ["base64-encoded-png-data"], | |||
|
213 | "application/json": { | |||
|
214 | # JSON data is included as-is | |||
|
215 | "json": "data", | |||
|
216 | }, | |||
|
217 | "metadata" : { | |||
|
218 | "image/png": { | |||
|
219 | "width": 640, | |||
|
220 | "height": 480, | |||
|
221 | }, | |||
|
222 | }, | |||
|
223 | } | |||
|
224 | ||||
|
225 | .. versionchanged:: 4.0 | |||
|
226 | ||||
|
227 | ``pyout`` renamed to ``execute_result`` | |||
|
228 | ||||
|
229 | ||||
|
230 | error | |||
|
231 | ***** | |||
|
232 | ||||
|
233 | Failed execution may show a traceback | |||
|
234 | ||||
|
235 | .. sourcecode:: python | |||
|
236 | ||||
|
237 | { | |||
|
238 | 'ename' : str, # Exception name, as a string | |||
|
239 | 'evalue' : str, # Exception value, as a string | |||
|
240 | ||||
|
241 | # The traceback will contain a list of frames, | |||
|
242 | # represented each as a string. | |||
|
243 | 'traceback' : list, | |||
|
244 | } | |||
|
245 | ||||
|
246 | .. versionchanged:: 4.0 | |||
|
247 | ||||
|
248 | ``pyerr`` renamed to ``error`` | |||
|
249 | ||||
|
250 | ||||
|
251 | Raw NBConvert cells | |||
|
252 | ------------------- | |||
|
253 | ||||
|
254 | A raw cell is defined as content that should be included *unmodified* in :ref:`nbconvert <nbconvert>` output. | |||
|
255 | For example, this cell could include raw LaTeX for nbconvert to pdf via latex, | |||
|
256 | or restructured text for use in Sphinx documentation. | |||
|
257 | ||||
|
258 | The notebook authoring environment does not render raw cells. | |||
|
259 | ||||
|
260 | The only logic in a raw cell is the `format` metadata field. | |||
|
261 | If defined, it specifies which nbconvert output format is the intended target | |||
|
262 | for the raw cell. When outputting to any other format, | |||
|
263 | the raw cell's contents will be excluded. | |||
|
264 | In the default case when this value is undefined, | |||
|
265 | a raw cell's contents will be included in any nbconvert output, | |||
|
266 | regardless of format. | |||
|
267 | ||||
|
268 | .. sourcecode:: python | |||
|
269 | ||||
|
270 | { | |||
|
271 | "cell_type" : "raw", | |||
|
272 | "metadata" : { | |||
|
273 | # the mime-type of the target nbconvert format. | |||
|
274 | # nbconvert to formats other than this will exclude this cell. | |||
|
275 | "format" : "mime/type" | |||
|
276 | }, | |||
|
277 | "source" : ["some nbformat mime-type data"] | |||
|
278 | } |
General Comments 0
You need to be logged in to leave comments.
Login now