##// END OF EJS Templates
Document how to install kernel spec files...
Jan Schulz -
Show More
@@ -1,482 +1,502 b''
1 .. _htmlnotebook:
1 .. _htmlnotebook:
2
2
3 The IPython Notebook
3 The IPython Notebook
4 ====================
4 ====================
5
5
6 Introduction
6 Introduction
7 ------------
7 ------------
8
8
9 The notebook extends the console-based approach to interactive computing in
9 The notebook extends the console-based approach to interactive computing in
10 a qualitatively new direction, providing a web-based application suitable for
10 a qualitatively new direction, providing a web-based application suitable for
11 capturing the whole computation process: developing, documenting, and
11 capturing the whole computation process: developing, documenting, and
12 executing code, as well as communicating the results. The IPython notebook
12 executing code, as well as communicating the results. The IPython notebook
13 combines two components:
13 combines two components:
14
14
15 **A web application**: a browser-based tool for interactive authoring of
15 **A web application**: a browser-based tool for interactive authoring of
16 documents which combine explanatory text, mathematics, computations and their
16 documents which combine explanatory text, mathematics, computations and their
17 rich media output.
17 rich media output.
18
18
19 **Notebook documents**: a representation of all content visible in the web
19 **Notebook documents**: a representation of all content visible in the web
20 application, including inputs and outputs of the computations, explanatory
20 application, including inputs and outputs of the computations, explanatory
21 text, mathematics, images, and rich media representations of objects.
21 text, mathematics, images, and rich media representations of objects.
22
22
23 .. seealso::
23 .. seealso::
24
24
25 See the :ref:`installation documentation <installnotebook>` for directions
25 See the :ref:`installation documentation <installnotebook>` for directions
26 on how to install the notebook and its dependencies.
26 on how to install the notebook and its dependencies.
27
27
28
28
29 Main features of the web application
29 Main features of the web application
30 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
30 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
31
31
32 * In-browser editing for code, with automatic syntax highlighting,
32 * In-browser editing for code, with automatic syntax highlighting,
33 indentation, and tab completion/introspection.
33 indentation, and tab completion/introspection.
34
34
35 * The ability to execute code from the browser, with the results of
35 * The ability to execute code from the browser, with the results of
36 computations attached to the code which generated them.
36 computations attached to the code which generated them.
37
37
38 * Displaying the result of computation using rich media representations, such
38 * Displaying the result of computation using rich media representations, such
39 as HTML, LaTeX, PNG, SVG, etc. For example, publication-quality figures
39 as HTML, LaTeX, PNG, SVG, etc. For example, publication-quality figures
40 rendered by the matplotlib_ library, can be included inline.
40 rendered by the matplotlib_ library, can be included inline.
41
41
42 * In-browser editing for rich text using the Markdown_ markup language, which
42 * In-browser editing for rich text using the Markdown_ markup language, which
43 can provide commentary for the code, is not limited to plain text.
43 can provide commentary for the code, is not limited to plain text.
44
44
45 * The ability to easily include mathematical notation within markdown cells
45 * The ability to easily include mathematical notation within markdown cells
46 using LaTeX, and rendered natively by MathJax_.
46 using LaTeX, and rendered natively by MathJax_.
47
47
48
48
49
49
50 .. _MathJax: http://www.mathjax.org/
50 .. _MathJax: http://www.mathjax.org/
51
51
52
52
53 Notebook documents
53 Notebook documents
54 ~~~~~~~~~~~~~~~~~~
54 ~~~~~~~~~~~~~~~~~~
55 Notebook documents contains the inputs and outputs of a interactive session as
55 Notebook documents contains the inputs and outputs of a interactive session as
56 well as additional text that accompanies the code but is not meant for
56 well as additional text that accompanies the code but is not meant for
57 execution. In this way, notebook files can serve as a complete computational
57 execution. In this way, notebook files can serve as a complete computational
58 record of a session, interleaving executable code with explanatory text,
58 record of a session, interleaving executable code with explanatory text,
59 mathematics, and rich representations of resulting objects. These documents
59 mathematics, and rich representations of resulting objects. These documents
60 are internally JSON_ files and are saved with the ``.ipynb`` extension. Since
60 are internally JSON_ files and are saved with the ``.ipynb`` extension. Since
61 JSON is a plain text format, they can be version-controlled and shared with
61 JSON is a plain text format, they can be version-controlled and shared with
62 colleagues.
62 colleagues.
63
63
64 .. _JSON: http://en.wikipedia.org/wiki/JSON
64 .. _JSON: http://en.wikipedia.org/wiki/JSON
65
65
66 Notebooks may be exported to a range of static formats, including HTML (for
66 Notebooks may be exported to a range of static formats, including HTML (for
67 example, for blog posts), reStructuredText, LaTeX, PDF, and slide shows, via
67 example, for blog posts), reStructuredText, LaTeX, PDF, and slide shows, via
68 the new :ref:`nbconvert <nbconvert>` command.
68 the new :ref:`nbconvert <nbconvert>` command.
69
69
70 Furthermore, any ``.ipynb`` notebook document available from a public
70 Furthermore, any ``.ipynb`` notebook document available from a public
71 URL can be shared via the `IPython Notebook Viewer <nbviewer>`_ (nbviewer_).
71 URL can be shared via the `IPython Notebook Viewer <nbviewer>`_ (nbviewer_).
72 This service loads the notebook document from the URL and renders it as a
72 This service loads the notebook document from the URL and renders it as a
73 static web page. The results may thus be shared with a colleague, or as a
73 static web page. The results may thus be shared with a colleague, or as a
74 public blog post, without other users needing to install IPython themselves.
74 public blog post, without other users needing to install IPython themselves.
75 In effect, nbviewer_ is simply :ref:`nbconvert <nbconvert>` as a web service,
75 In effect, nbviewer_ is simply :ref:`nbconvert <nbconvert>` as a web service,
76 so you can do your own static conversions with nbconvert, without relying on
76 so you can do your own static conversions with nbconvert, without relying on
77 nbviewer.
77 nbviewer.
78
78
79
79
80
80
81 .. seealso::
81 .. seealso::
82
82
83 :ref:`Details on the notebook JSON file format <nbformat>`
83 :ref:`Details on the notebook JSON file format <nbformat>`
84
84
85
85
86 Starting the notebook server
86 Starting the notebook server
87 ----------------------------
87 ----------------------------
88
88
89 You can start running a notebook server from the command line using the
89 You can start running a notebook server from the command line using the
90 following command::
90 following command::
91
91
92 ipython notebook
92 ipython notebook
93
93
94 This will print some information about the notebook server in your console,
94 This will print some information about the notebook server in your console,
95 and open a web browser to the URL of the web application (by default,
95 and open a web browser to the URL of the web application (by default,
96 ``http://127.0.0.1:8888``).
96 ``http://127.0.0.1:8888``).
97
97
98 The landing page of the IPython notebook web application, the **dashboard**,
98 The landing page of the IPython notebook web application, the **dashboard**,
99 shows the notebooks currently available in the notebook directory (by default,
99 shows the notebooks currently available in the notebook directory (by default,
100 the directory from which the notebook server was started).
100 the directory from which the notebook server was started).
101
101
102 You can create new notebooks from the dashboard with the ``New Notebook``
102 You can create new notebooks from the dashboard with the ``New Notebook``
103 button, or open existing ones by clicking on their name. You can also drag
103 button, or open existing ones by clicking on their name. You can also drag
104 and drop ``.ipynb`` notebooks and standard ``.py`` Python source code files
104 and drop ``.ipynb`` notebooks and standard ``.py`` Python source code files
105 into the notebook list area.
105 into the notebook list area.
106
106
107 When starting a notebook server from the command line, you can also open a
107 When starting a notebook server from the command line, you can also open a
108 particular notebook directly, bypassing the dashboard, with ``ipython notebook
108 particular notebook directly, bypassing the dashboard, with ``ipython notebook
109 my_notebook.ipynb``. The ``.ipynb`` extension is assumed if no extension is
109 my_notebook.ipynb``. The ``.ipynb`` extension is assumed if no extension is
110 given.
110 given.
111
111
112 When you are inside an open notebook, the `File | Open...` menu option will
112 When you are inside an open notebook, the `File | Open...` menu option will
113 open the dashboard in a new browser tab, to allow you to open another notebook
113 open the dashboard in a new browser tab, to allow you to open another notebook
114 from the notebook directory or to create a new notebook.
114 from the notebook directory or to create a new notebook.
115
115
116
116
117 .. note::
117 .. note::
118
118
119 You can start more than one notebook server at the same time, if you want
119 You can start more than one notebook server at the same time, if you want
120 to work on notebooks in different directories. By default the first
120 to work on notebooks in different directories. By default the first
121 notebook server starts on port 8888, and later notebook servers search for
121 notebook server starts on port 8888, and later notebook servers search for
122 ports near that one. You can also manually specify the port with the
122 ports near that one. You can also manually specify the port with the
123 ``--port`` option.
123 ``--port`` option.
124
124
125 Creating a new notebook document
125 Creating a new notebook document
126 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
126 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
127
127
128 A new notebook may be created at any time, either from the dashboard, or using
128 A new notebook may be created at any time, either from the dashboard, or using
129 the `File | New` menu option from within an active notebook. The new notebook
129 the `File | New` menu option from within an active notebook. The new notebook
130 is created within the same directory and will open in a new browser tab. It
130 is created within the same directory and will open in a new browser tab. It
131 will also be reflected as a new entry in the notebook list on the dashboard.
131 will also be reflected as a new entry in the notebook list on the dashboard.
132
132
133
133
134 Opening notebooks
134 Opening notebooks
135 ~~~~~~~~~~~~~~~~~
135 ~~~~~~~~~~~~~~~~~
136 An open notebook has **exactly one** interactive session connected to an
136 An open notebook has **exactly one** interactive session connected to an
137 :ref:`IPython kernel <ipythonzmq>`, which will execute code sent by the user
137 :ref:`IPython kernel <ipythonzmq>`, which will execute code sent by the user
138 and communicate back results. This kernel remains active if the web browser
138 and communicate back results. This kernel remains active if the web browser
139 window is closed, and reopening the same notebook from the dashboard will
139 window is closed, and reopening the same notebook from the dashboard will
140 reconnect the web application to the same kernel. In the dashboard, notebooks
140 reconnect the web application to the same kernel. In the dashboard, notebooks
141 with an active kernel have a ``Shutdown`` button next to them, whereas
141 with an active kernel have a ``Shutdown`` button next to them, whereas
142 notebooks without an active kernel have a ``Delete`` button in its place.
142 notebooks without an active kernel have a ``Delete`` button in its place.
143
143
144 Other clients may connect to the same underlying IPython kernel.
144 Other clients may connect to the same underlying IPython kernel.
145 The notebook server always prints to the terminal the full details of
145 The notebook server always prints to the terminal the full details of
146 how to connect to each kernel, with messages such as the following::
146 how to connect to each kernel, with messages such as the following::
147
147
148 [NotebookApp] Kernel started: 87f7d2c0-13e3-43df-8bb8-1bd37aaf3373
148 [NotebookApp] Kernel started: 87f7d2c0-13e3-43df-8bb8-1bd37aaf3373
149
149
150 This long string is the kernel's ID which is sufficient for getting the
150 This long string is the kernel's ID which is sufficient for getting the
151 information necessary to connect to the kernel. You can also request this
151 information necessary to connect to the kernel. You can also request this
152 connection data by running the ``%connect_info`` :ref:`magic
152 connection data by running the ``%connect_info`` :ref:`magic
153 <magics_explained>`. This will print the same ID information as well as the
153 <magics_explained>`. This will print the same ID information as well as the
154 content of the JSON data structure it contains.
154 content of the JSON data structure it contains.
155
155
156 You can then, for example, manually start a Qt console connected to the *same*
156 You can then, for example, manually start a Qt console connected to the *same*
157 kernel from the command line, by passing a portion of the ID::
157 kernel from the command line, by passing a portion of the ID::
158
158
159 $ ipython qtconsole --existing 87f7d2c0
159 $ ipython qtconsole --existing 87f7d2c0
160
160
161 Without an ID, ``--existing`` will connect to the most recently
161 Without an ID, ``--existing`` will connect to the most recently
162 started kernel. This can also be done by running the ``%qtconsole``
162 started kernel. This can also be done by running the ``%qtconsole``
163 :ref:`magic <magics_explained>` in the notebook.
163 :ref:`magic <magics_explained>` in the notebook.
164
164
165 .. seealso::
165 .. seealso::
166
166
167 :ref:`ipythonzmq`
167 :ref:`ipythonzmq`
168
168
169 Notebook user interface
169 Notebook user interface
170 -----------------------
170 -----------------------
171
171
172 When you create a new notebook document, you will be presented with the
172 When you create a new notebook document, you will be presented with the
173 **notebook name**, a **menu bar**, a **toolbar** and an empty **code
173 **notebook name**, a **menu bar**, a **toolbar** and an empty **code
174 cell**.
174 cell**.
175
175
176 **notebook name**: The name of the notebook document is displayed at the top
176 **notebook name**: The name of the notebook document is displayed at the top
177 of the page, next to the ``IP[y]: Notebook`` logo. This name reflects the name
177 of the page, next to the ``IP[y]: Notebook`` logo. This name reflects the name
178 of the ``.ipynb`` notebook document file. Clicking on the notebook name
178 of the ``.ipynb`` notebook document file. Clicking on the notebook name
179 brings up a dialog which allows you to rename it. Thus, renaming a notebook
179 brings up a dialog which allows you to rename it. Thus, renaming a notebook
180 from "Untitled0" to "My first notebook" in the browser, renames the
180 from "Untitled0" to "My first notebook" in the browser, renames the
181 ``Untitled0.ipynb`` file to ``My first notebook.ipynb``.
181 ``Untitled0.ipynb`` file to ``My first notebook.ipynb``.
182
182
183 **menu bar**: The menu bar presents different options that may be used to
183 **menu bar**: The menu bar presents different options that may be used to
184 manipulate the way the notebook functions.
184 manipulate the way the notebook functions.
185
185
186 **toolbar**: The tool bar gives a quick way of performing the most-used
186 **toolbar**: The tool bar gives a quick way of performing the most-used
187 operations within the notebook, by clicking on an icon.
187 operations within the notebook, by clicking on an icon.
188
188
189 **code cell**: the default type of cell, read on for an explanation of cells
189 **code cell**: the default type of cell, read on for an explanation of cells
190
190
191
191
192 Structure of a notebook document
192 Structure of a notebook document
193 --------------------------------
193 --------------------------------
194
194
195 The notebook consists of a sequence of cells. A cell is a multi-line
195 The notebook consists of a sequence of cells. A cell is a multi-line
196 text input field, and its contents can be executed by using
196 text input field, and its contents can be executed by using
197 :kbd:`Shift-Enter`, or by clicking either the "Play" button the toolbar, or
197 :kbd:`Shift-Enter`, or by clicking either the "Play" button the toolbar, or
198 `Cell | Run` in the menu bar. The execution behavior of a cell is determined
198 `Cell | Run` in the menu bar. The execution behavior of a cell is determined
199 the cell's type. There are four types of cells: **code cells**, **markdown
199 the cell's type. There are four types of cells: **code cells**, **markdown
200 cells**, **raw cells** and **heading cells**. Every cell starts off
200 cells**, **raw cells** and **heading cells**. Every cell starts off
201 being a **code cell**, but its type can be changed by using a dropdown on the
201 being a **code cell**, but its type can be changed by using a dropdown on the
202 toolbar (which will be "Code", initially), or via :ref:`keyboard shortcuts
202 toolbar (which will be "Code", initially), or via :ref:`keyboard shortcuts
203 <keyboard-shortcuts>`.
203 <keyboard-shortcuts>`.
204
204
205 For more information on the different things you can do in a notebook,
205 For more information on the different things you can do in a notebook,
206 see the `collection of examples
206 see the `collection of examples
207 <http://nbviewer.ipython.org/github/ipython/ipython/blob/master/examples/Notebook/Index.ipynb>`_.
207 <http://nbviewer.ipython.org/github/ipython/ipython/blob/master/examples/Notebook/Index.ipynb>`_.
208
208
209 Code cells
209 Code cells
210 ~~~~~~~~~~
210 ~~~~~~~~~~
211 A *code cell* allows you to edit and write new code, with full syntax
211 A *code cell* allows you to edit and write new code, with full syntax
212 highlighting and tab completion. By default, the language associated to a code
212 highlighting and tab completion. By default, the language associated to a code
213 cell is Python, but other languages, such as ``Julia`` and ``R``, can be
213 cell is Python, but other languages, such as ``Julia`` and ``R``, can be
214 handled using :ref:`cell magic commands <magics_explained>`.
214 handled using :ref:`cell magic commands <magics_explained>`.
215
215
216 When a code cell is executed, code that it contains is sent to the kernel
216 When a code cell is executed, code that it contains is sent to the kernel
217 associated with the notebook. The results that are returned from this
217 associated with the notebook. The results that are returned from this
218 computation are then displayed in the notebook as the cell's *output*. The
218 computation are then displayed in the notebook as the cell's *output*. The
219 output is not limited to text, with many other possible forms of output are
219 output is not limited to text, with many other possible forms of output are
220 also possible, including ``matplotlib`` figures and HTML tables (as used, for
220 also possible, including ``matplotlib`` figures and HTML tables (as used, for
221 example, in the ``pandas`` data analysis package). This is known as IPython's
221 example, in the ``pandas`` data analysis package). This is known as IPython's
222 *rich display* capability.
222 *rich display* capability.
223
223
224 .. seealso::
224 .. seealso::
225
225
226 `Basic Output`_ example notebook
226 `Basic Output`_ example notebook
227
227
228 `Rich Display System`_ example notebook
228 `Rich Display System`_ example notebook
229
229
230 Markdown cells
230 Markdown cells
231 ~~~~~~~~~~~~~~
231 ~~~~~~~~~~~~~~
232 You can document the computational process in a literate way, alternating
232 You can document the computational process in a literate way, alternating
233 descriptive text with code, using *rich text*. In IPython this is accomplished
233 descriptive text with code, using *rich text*. In IPython this is accomplished
234 by marking up text with the Markdown language. The corresponding cells are
234 by marking up text with the Markdown language. The corresponding cells are
235 called *Markdown cells*. The Markdown language provides a simple way to
235 called *Markdown cells*. The Markdown language provides a simple way to
236 perform this text markup, that is, to specify which parts of the text should
236 perform this text markup, that is, to specify which parts of the text should
237 be emphasized (italics), bold, form lists, etc.
237 be emphasized (italics), bold, form lists, etc.
238
238
239
239
240 When a Markdown cell is executed, the Markdown code is converted into
240 When a Markdown cell is executed, the Markdown code is converted into
241 the corresponding formatted rich text. Markdown allows arbitrary HTML code for
241 the corresponding formatted rich text. Markdown allows arbitrary HTML code for
242 formatting.
242 formatting.
243
243
244 Within Markdown cells, you can also include *mathematics* in a straightforward
244 Within Markdown cells, you can also include *mathematics* in a straightforward
245 way, using standard LaTeX notation: ``$...$`` for inline mathematics and
245 way, using standard LaTeX notation: ``$...$`` for inline mathematics and
246 ``$$...$$`` for displayed mathematics. When the Markdown cell is executed,
246 ``$$...$$`` for displayed mathematics. When the Markdown cell is executed,
247 the LaTeX portions are automatically rendered in the HTML output as equations
247 the LaTeX portions are automatically rendered in the HTML output as equations
248 with high quality typography. This is made possible by MathJax_, which
248 with high quality typography. This is made possible by MathJax_, which
249 supports a `large subset <mathjax_tex>`_ of LaTeX functionality
249 supports a `large subset <mathjax_tex>`_ of LaTeX functionality
250
250
251 .. _mathjax_tex: http://docs.mathjax.org/en/latest/tex.html
251 .. _mathjax_tex: http://docs.mathjax.org/en/latest/tex.html
252
252
253 Standard mathematics environments defined by LaTeX and AMS-LaTeX (the
253 Standard mathematics environments defined by LaTeX and AMS-LaTeX (the
254 `amsmath` package) also work, such as
254 `amsmath` package) also work, such as
255 ``\begin{equation}...\end{equation}``, and ``\begin{align}...\end{align}``.
255 ``\begin{equation}...\end{equation}``, and ``\begin{align}...\end{align}``.
256 New LaTeX macros may be defined using standard methods,
256 New LaTeX macros may be defined using standard methods,
257 such as ``\newcommand``, by placing them anywhere *between math delimiters* in
257 such as ``\newcommand``, by placing them anywhere *between math delimiters* in
258 a Markdown cell. These definitions are then available throughout the rest of
258 a Markdown cell. These definitions are then available throughout the rest of
259 the IPython session.
259 the IPython session.
260
260
261 .. seealso::
261 .. seealso::
262
262
263 `Markdown Cells`_ example notebook
263 `Markdown Cells`_ example notebook
264
264
265 Raw cells
265 Raw cells
266 ~~~~~~~~~
266 ~~~~~~~~~
267
267
268 *Raw* cells provide a place in which you can write *output* directly.
268 *Raw* cells provide a place in which you can write *output* directly.
269 Raw cells are not evaluated by the notebook.
269 Raw cells are not evaluated by the notebook.
270 When passed through :ref:`nbconvert <nbconvert>`, raw cells arrive in the
270 When passed through :ref:`nbconvert <nbconvert>`, raw cells arrive in the
271 destination format unmodified. For example, this allows you to type full LaTeX
271 destination format unmodified. For example, this allows you to type full LaTeX
272 into a raw cell, which will only be rendered by LaTeX after conversion by
272 into a raw cell, which will only be rendered by LaTeX after conversion by
273 nbconvert.
273 nbconvert.
274
274
275 Heading cells
275 Heading cells
276 ~~~~~~~~~~~~~
276 ~~~~~~~~~~~~~
277
277
278 You can provide a conceptual structure for your computational document as a
278 You can provide a conceptual structure for your computational document as a
279 whole using different levels of headings; there are 6 levels available, from
279 whole using different levels of headings; there are 6 levels available, from
280 level 1 (top level) down to level 6 (paragraph). These can be used later for
280 level 1 (top level) down to level 6 (paragraph). These can be used later for
281 constructing tables of contents, etc. As with Markdown cells, a heading
281 constructing tables of contents, etc. As with Markdown cells, a heading
282 cell is replaced by a rich text rendering of the heading when the cell is
282 cell is replaced by a rich text rendering of the heading when the cell is
283 executed.
283 executed.
284
284
285
285
286 Basic workflow
286 Basic workflow
287 --------------
287 --------------
288
288
289 The normal workflow in a notebook is, then, quite similar to a standard
289 The normal workflow in a notebook is, then, quite similar to a standard
290 IPython session, with the difference that you can edit cells in-place multiple
290 IPython session, with the difference that you can edit cells in-place multiple
291 times until you obtain the desired results, rather than having to
291 times until you obtain the desired results, rather than having to
292 rerun separate scripts with the ``%run`` magic command.
292 rerun separate scripts with the ``%run`` magic command.
293
293
294
294
295 Typically, you will work on a computational problem in pieces, organizing
295 Typically, you will work on a computational problem in pieces, organizing
296 related ideas into cells and moving forward once previous parts work
296 related ideas into cells and moving forward once previous parts work
297 correctly. This is much more convenient for interactive exploration than
297 correctly. This is much more convenient for interactive exploration than
298 breaking up a computation into scripts that must be executed together, as was
298 breaking up a computation into scripts that must be executed together, as was
299 previously necessary, especially if parts of them take a long time to run.
299 previously necessary, especially if parts of them take a long time to run.
300
300
301 At certain moments, it may be necessary to interrupt a calculation which is
301 At certain moments, it may be necessary to interrupt a calculation which is
302 taking too long to complete. This may be done with the `Kernel | Interrupt`
302 taking too long to complete. This may be done with the `Kernel | Interrupt`
303 menu option, or the :kbd:`Ctrl-m i` keyboard shortcut.
303 menu option, or the :kbd:`Ctrl-m i` keyboard shortcut.
304 Similarly, it may be necessary or desirable to restart the whole computational
304 Similarly, it may be necessary or desirable to restart the whole computational
305 process, with the `Kernel | Restart` menu option or :kbd:`Ctrl-m .`
305 process, with the `Kernel | Restart` menu option or :kbd:`Ctrl-m .`
306 shortcut.
306 shortcut.
307
307
308 A notebook may be downloaded in either a ``.ipynb`` or ``.py`` file from the
308 A notebook may be downloaded in either a ``.ipynb`` or ``.py`` file from the
309 menu option `File | Download as`. Choosing the ``.py`` option downloads a
309 menu option `File | Download as`. Choosing the ``.py`` option downloads a
310 Python ``.py`` script, in which all rich output has been removed and the
310 Python ``.py`` script, in which all rich output has been removed and the
311 content of markdown cells have been inserted as comments.
311 content of markdown cells have been inserted as comments.
312
312
313 .. seealso::
313 .. seealso::
314
314
315 `Running Code in the IPython Notebook`_ example notebook
315 `Running Code in the IPython Notebook`_ example notebook
316
316
317 `Basic Output`_ example notebook
317 `Basic Output`_ example notebook
318
318
319 :ref:`a warning about doing "roundtrip" conversions <note_about_roundtrip>`.
319 :ref:`a warning about doing "roundtrip" conversions <note_about_roundtrip>`.
320
320
321 .. _keyboard-shortcuts:
321 .. _keyboard-shortcuts:
322
322
323 Keyboard shortcuts
323 Keyboard shortcuts
324 ~~~~~~~~~~~~~~~~~~
324 ~~~~~~~~~~~~~~~~~~
325 All actions in the notebook can be performed with the mouse, but keyboard
325 All actions in the notebook can be performed with the mouse, but keyboard
326 shortcuts are also available for the most common ones. The essential shortcuts
326 shortcuts are also available for the most common ones. The essential shortcuts
327 to remember are the following:
327 to remember are the following:
328
328
329 * :kbd:`Shift-Enter`: run cell
329 * :kbd:`Shift-Enter`: run cell
330 Execute the current cell, show output (if any), and jump to the next cell
330 Execute the current cell, show output (if any), and jump to the next cell
331 below. If :kbd:`Shift-Enter` is invoked on the last cell, a new code
331 below. If :kbd:`Shift-Enter` is invoked on the last cell, a new code
332 cell will also be created. Note that in the notebook, typing :kbd:`Enter`
332 cell will also be created. Note that in the notebook, typing :kbd:`Enter`
333 on its own *never* forces execution, but rather just inserts a new line in
333 on its own *never* forces execution, but rather just inserts a new line in
334 the current cell. :kbd:`Shift-Enter` is equivalent to clicking the
334 the current cell. :kbd:`Shift-Enter` is equivalent to clicking the
335 ``Cell | Run`` menu item.
335 ``Cell | Run`` menu item.
336
336
337 * :kbd:`Ctrl-Enter`: run cell in-place
337 * :kbd:`Ctrl-Enter`: run cell in-place
338 Execute the current cell as if it were in "terminal mode", where any
338 Execute the current cell as if it were in "terminal mode", where any
339 output is shown, but the cursor *remains* in the current cell. The cell's
339 output is shown, but the cursor *remains* in the current cell. The cell's
340 entire contents are selected after execution, so you can just start typing
340 entire contents are selected after execution, so you can just start typing
341 and only the new input will be in the cell. This is convenient for doing
341 and only the new input will be in the cell. This is convenient for doing
342 quick experiments in place, or for querying things like filesystem
342 quick experiments in place, or for querying things like filesystem
343 content, without needing to create additional cells that you may not want
343 content, without needing to create additional cells that you may not want
344 to be saved in the notebook.
344 to be saved in the notebook.
345
345
346 * :kbd:`Alt-Enter`: run cell, insert below
346 * :kbd:`Alt-Enter`: run cell, insert below
347 Executes the current cell, shows the output, and inserts a *new*
347 Executes the current cell, shows the output, and inserts a *new*
348 cell between the current cell and the cell below (if one exists). This
348 cell between the current cell and the cell below (if one exists). This
349 is thus a shortcut for the sequence :kbd:`Shift-Enter`, :kbd:`Ctrl-m a`.
349 is thus a shortcut for the sequence :kbd:`Shift-Enter`, :kbd:`Ctrl-m a`.
350 (:kbd:`Ctrl-m a` adds a new cell above the current one.)
350 (:kbd:`Ctrl-m a` adds a new cell above the current one.)
351
351
352 * :kbd:`Esc` and :kbd:`Enter`: Command mode and edit mode
352 * :kbd:`Esc` and :kbd:`Enter`: Command mode and edit mode
353 In command mode, you can easily navigate around the notebook using keyboard
353 In command mode, you can easily navigate around the notebook using keyboard
354 shortcuts. In edit mode, you can edit text in cells.
354 shortcuts. In edit mode, you can edit text in cells.
355
355
356 For the full list of available shortcuts, click :guilabel:`Help`,
356 For the full list of available shortcuts, click :guilabel:`Help`,
357 :guilabel:`Keyboard Shortcuts` in the notebook menus.
357 :guilabel:`Keyboard Shortcuts` in the notebook menus.
358
358
359 Plotting
359 Plotting
360 --------
360 --------
361 One major feature of the notebook is the ability to display plots that are the
361 One major feature of the notebook is the ability to display plots that are the
362 output of running code cells. IPython is designed to work seamlessly with the
362 output of running code cells. IPython is designed to work seamlessly with the
363 matplotlib_ plotting library to provide this functionality.
363 matplotlib_ plotting library to provide this functionality.
364
364
365 To set this up, before any plotting is performed you must execute the
365 To set this up, before any plotting is performed you must execute the
366 ``%matplotlib`` :ref:`magic command <magics_explained>`. This performs the
366 ``%matplotlib`` :ref:`magic command <magics_explained>`. This performs the
367 necessary behind-the-scenes setup for IPython to work correctly hand in hand
367 necessary behind-the-scenes setup for IPython to work correctly hand in hand
368 with ``matplotlib``; it does *not*, however, actually execute any Python
368 with ``matplotlib``; it does *not*, however, actually execute any Python
369 ``import`` commands, that is, no names are added to the namespace.
369 ``import`` commands, that is, no names are added to the namespace.
370
370
371 If the ``%matplotlib`` magic is called without an argument, the
371 If the ``%matplotlib`` magic is called without an argument, the
372 output of a plotting command is displayed using the default ``matplotlib``
372 output of a plotting command is displayed using the default ``matplotlib``
373 backend in a separate window. Alternatively, the backend can be explicitly
373 backend in a separate window. Alternatively, the backend can be explicitly
374 requested using, for example::
374 requested using, for example::
375
375
376 %matplotlib gtk
376 %matplotlib gtk
377
377
378 A particularly interesting backend, provided by IPython, is the ``inline``
378 A particularly interesting backend, provided by IPython, is the ``inline``
379 backend. This is available only for the IPython Notebook and the
379 backend. This is available only for the IPython Notebook and the
380 :ref:`IPython QtConsole <qtconsole>`. It can be invoked as follows::
380 :ref:`IPython QtConsole <qtconsole>`. It can be invoked as follows::
381
381
382 %matplotlib inline
382 %matplotlib inline
383
383
384 With this backend, the output of plotting commands is displayed *inline*
384 With this backend, the output of plotting commands is displayed *inline*
385 within the notebook, directly below the code cell that produced it. The
385 within the notebook, directly below the code cell that produced it. The
386 resulting plots will then also be stored in the notebook document.
386 resulting plots will then also be stored in the notebook document.
387
387
388 .. seealso::
388 .. seealso::
389
389
390 `Plotting with Matplotlib`_ example notebook
390 `Plotting with Matplotlib`_ example notebook
391
391
392
392
393 Configuring the IPython Notebook
393 Configuring the IPython Notebook
394 --------------------------------
394 --------------------------------
395 The notebook server can be run with a variety of command line arguments.
395 The notebook server can be run with a variety of command line arguments.
396 To see a list of available options enter::
396 To see a list of available options enter::
397
397
398 $ ipython notebook --help
398 $ ipython notebook --help
399
399
400 Defaults for these options can also be set by creating a file named
400 Defaults for these options can also be set by creating a file named
401 ``ipython_notebook_config.py`` in your IPython *profile folder*. The profile
401 ``ipython_notebook_config.py`` in your IPython *profile folder*. The profile
402 folder is a subfolder of your IPython directory; to find out where it is
402 folder is a subfolder of your IPython directory; to find out where it is
403 located, run::
403 located, run::
404
404
405 $ ipython locate
405 $ ipython locate
406
406
407 To create a new set of default configuration files, with lots of information
407 To create a new set of default configuration files, with lots of information
408 on available options, use::
408 on available options, use::
409
409
410 $ ipython profile create
410 $ ipython profile create
411
411
412 .. seealso::
412 .. seealso::
413
413
414 :ref:`config_overview`, in particular :ref:`Profiles`.
414 :ref:`config_overview`, in particular :ref:`Profiles`.
415
415
416 :ref:`notebook_server_security`
416 :ref:`notebook_server_security`
417
417
418 :ref:`notebook_public_server`
418 :ref:`notebook_public_server`
419
419
420 Installing new kernels
421 ----------------------
422
423 Running the notebook makes the current python installation available as a kernel. Other
424 python installations (different python versions, virtualenv or conda environments) can
425 be installed as kernels by following these steps:
426
427 * make sure that the desired python installation is active (e.g. activate the environment)
428 and ipython is installed
429 * run once ``ipython kernelspec install-self --user`` (or ``ipython2 ...`` or ``ipython3 ...``
430 if you want to install specific python versions)
431
432 The last command installs a kernel spec file for the current python installation in
433 ``~/.ipython/kernels/``. Kernel spec files are JSON files, which can be viewed and changed with a
434 normal text editor.
435
436 Kernels for other languages can be found in the `IPython wiki
437 <https://github.com/ipython/ipython/wiki/IPython%20kernels%20for%20other%20languages>`_.
438 They usually come with instruction what to run to make the kernel available in the notebook.
439
420
440
421 .. _signing_notebooks:
441 .. _signing_notebooks:
422
442
423 Signing Notebooks
443 Signing Notebooks
424 -----------------
444 -----------------
425
445
426 To prevent untrusted code from executing on users' behalf when notebooks open,
446 To prevent untrusted code from executing on users' behalf when notebooks open,
427 we have added a signature to the notebook, stored in metadata.
447 we have added a signature to the notebook, stored in metadata.
428 The notebook server verifies this signature when a notebook is opened.
448 The notebook server verifies this signature when a notebook is opened.
429 If the signature stored in the notebook metadata does not match,
449 If the signature stored in the notebook metadata does not match,
430 javascript and HTML output will not be displayed on load,
450 javascript and HTML output will not be displayed on load,
431 and must be regenerated by re-executing the cells.
451 and must be regenerated by re-executing the cells.
432
452
433 Any notebook that you have executed yourself *in its entirety* will be considered trusted,
453 Any notebook that you have executed yourself *in its entirety* will be considered trusted,
434 and its HTML and javascript output will be displayed on load.
454 and its HTML and javascript output will be displayed on load.
435
455
436 If you need to see HTML or Javascript output without re-executing,
456 If you need to see HTML or Javascript output without re-executing,
437 you can explicitly trust notebooks, such as those shared with you,
457 you can explicitly trust notebooks, such as those shared with you,
438 or those that you have written yourself prior to IPython 2.0,
458 or those that you have written yourself prior to IPython 2.0,
439 at the command-line with::
459 at the command-line with::
440
460
441 $ ipython trust mynotebook.ipynb [other notebooks.ipynb]
461 $ ipython trust mynotebook.ipynb [other notebooks.ipynb]
442
462
443 This just generates a new signature stored in each notebook.
463 This just generates a new signature stored in each notebook.
444
464
445 You can generate a new notebook signing key with::
465 You can generate a new notebook signing key with::
446
466
447 $ ipython trust --reset
467 $ ipython trust --reset
448
468
449
469
450 Importing ``.py`` files
470 Importing ``.py`` files
451 -----------------------
471 -----------------------
452
472
453 ``.py`` files will be imported as a notebook with
473 ``.py`` files will be imported as a notebook with
454 the same basename, but an ``.ipynb`` extension, located in the notebook
474 the same basename, but an ``.ipynb`` extension, located in the notebook
455 directory. The notebook created will have just one cell, which will contain
475 directory. The notebook created will have just one cell, which will contain
456 all the code in the ``.py`` file. You can later manually partition this into
476 all the code in the ``.py`` file. You can later manually partition this into
457 individual cells using the ``Edit | Split Cell`` menu option, or the
477 individual cells using the ``Edit | Split Cell`` menu option, or the
458 :kbd:`Ctrl-m -` keyboard shortcut.
478 :kbd:`Ctrl-m -` keyboard shortcut.
459
479
460 Note that ``.py`` scripts obtained from a notebook document using :doc:`nbconvert <nbconvert>`
480 Note that ``.py`` scripts obtained from a notebook document using :doc:`nbconvert <nbconvert>`
461 maintain the structure of the notebook in comments. Reimporting such a
481 maintain the structure of the notebook in comments. Reimporting such a
462 script back into a notebook will preserve this structure.
482 script back into a notebook will preserve this structure.
463
483
464 .. _note_about_roundtrip:
484 .. _note_about_roundtrip:
465
485
466 .. warning::
486 .. warning::
467
487
468 While in simple cases you can "roundtrip" a notebook to Python, edit the
488 While in simple cases you can "roundtrip" a notebook to Python, edit the
469 Python file, and then import it back without loss of main content, this is
489 Python file, and then import it back without loss of main content, this is
470 in general *not guaranteed to work*. First, there is extra metadata
490 in general *not guaranteed to work*. First, there is extra metadata
471 saved in the notebook that may not be saved to the ``.py`` format. And as
491 saved in the notebook that may not be saved to the ``.py`` format. And as
472 the notebook format evolves in complexity, there will be attributes of the
492 the notebook format evolves in complexity, there will be attributes of the
473 notebook that will not survive a roundtrip through the Python form. You
493 notebook that will not survive a roundtrip through the Python form. You
474 should think of the Python format as a way to output a script version of a
494 should think of the Python format as a way to output a script version of a
475 notebook and the import capabilities as a way to load existing code to get
495 notebook and the import capabilities as a way to load existing code to get
476 a notebook started. But the Python version is *not* an alternate notebook
496 a notebook started. But the Python version is *not* an alternate notebook
477 format.
497 format.
478
498
479 .. seealso::
499 .. seealso::
480 :ref:`nbformat`
500 :ref:`nbformat`
481
501
482 .. include:: ../links.txt
502 .. include:: ../links.txt
General Comments 0
You need to be logged in to leave comments. Login now