##// END OF EJS Templates
upstream » ipython
RSS

Clone from https://github.com/ipython/ipython.git

Clarified that 'notebook' also refers to the state of the computation inside the Notebook, but that this is the same as the content of the .ipynb file
David P. Sanders -
Show More
Show file before | Show file after | Hide comments
@@ -1,511 +1,548 b''
1 .. _htmlnotebook:
1 .. _htmlnotebook:
2
2
3 The IPython Notebook
3 The IPython Notebook
4 ====================
4 ====================
5
5
6 .. seealso::
6 .. seealso::
7
7
8 :ref:`Installation requirements <installnotebook>` for the Notebook.
8 :ref:`Installation requirements <installnotebook>` for the Notebook.
9
9
10 The IPython Notebook combines two components:
10 The IPython Notebook combines two components:
11
11
12 * A web application, called the *IPython Notebook web app*, for interactive authoring of literate computations, in which explanatory text, mathematics, computations and rich media output may be combined. Input and output are stored in persistent cells that may be edited in-place.
12 * A web application, called the *IPython Notebook web app*, for interactive authoring of literate computations, in which explanatory text, mathematics, computations and rich media output may be combined. Input and output are stored in persistent cells that may be edited in-place.
13
13
14 * Plain text documents, called *notebook documents*, or *notebooks*, for recording and distributing the results of the rich computations.
14 * Plain text documents, called *notebook documents*, or *notebooks*, for recording and distributing the results of the rich computations.
15
15
16 In the documentation, the distinction between the *N*otebook app and *n*otebook documents is made by capitalization.
16 In the documentation, the distinction between the *N*otebook app and *n*otebook documents is made by capitalization.
17
17
18 The Notebook app automatically saves the current state of the computation in the web browser to the corresponding notebook, which is just a standard text file with the extension ``.ipynb``, stored in a working directory on your computer. This file can be easily put under version control and shared with colleagues.
18 The Notebook app automatically saves the current state of the computation in the web browser to the corresponding notebook document.
19
20 It is also common to refer to the current state of the computation, as represented by the sequence of input cells in the Notebook app, as a
21 *notebook*. There is no problem with confounding these two concepts, since
22 there is actually a one-to-one correspondence between what you see on the
23 screen inside the app, and what is stored in the corresponding ``.ipynb`` notebook document.
19
24
20 Despite the fact that the notebook documents are plain text files, they use the JSON format in order to store a *complete*, *reproducible* copy of the state of the computation as it is inside the Notebook app.
21
25
22
26
23 Features of the IPython Notebook web app
27 Features of the IPython Notebook web app
24 ----------------------------------------
28 ----------------------------------------
25
29
26 Some of the main
30 Some of the main
27 features of the IPython Notebook app include:
31 features of the IPython Notebook app include:
28
32
29 * Display rich data representations (e.g. HTML / LaTeX / SVG) in the browser as a result of computations.
33 * Display rich data representations (e.g. HTML / LaTeX / SVG) in the browser as a result of computations.
30 * Compose text cells using Markdown and HTML.
34 * Compose text cells using Markdown and HTML.
31 * Include mathematical equations, rendered directly in the browser by MathJax.
35 * Include mathematical equations, rendered directly in the browser by MathJax.
32 * Import standard Python scripts
36 * Import standard Python scripts
33 * In-browser editing, syntax highlighting, tab completion and autoindentation.
37 * In-browser editing, syntax highlighting, tab completion and autoindentation.
34 * Inline figures rendered by the ``matplotlib`` library with publication quality, in a range of formats (SVG / PDF / PNG).
38 * Inline figures rendered by the ``matplotlib`` library with publication quality, in a range of formats (SVG / PDF / PNG).
35
39
36 If you have ever used the Mathematica or SAGE notebooks (the latter is also
40 If you have ever used the Mathematica or SAGE notebooks (the latter is also
37 web-based__) you should feel right at home. If you have not, you will be
41 web-based__) you should feel right at home. If you have not, you will be
38 able to learn how to use the IPython Notebook in just a few minutes.
42 able to learn how to use the IPython Notebook in just a few minutes.
39
43
40 .. __: http://sagenb.org
44 .. __: http://sagenb.org
41
45
42
46
43
47
44
48
45
49
46 Notebook documents
50 Notebook documents
47 ------------------
51 ------------------
48
52
49 Notebook documents, or *notebooks*, are files which record all computations carried out and the results obtained in a literate way, including inputs, outputs, toegether with descriptive text and mathematics.
53 Notebook document files are just standard text files with the extension
54 ``.ipynb``, stored in the working directory on your computer. This file can be easily put under version control and shared with colleagues.
50
55
51 They are plain text files, which are thus easy to share with colleagues and place under version control. But, by using the
56 Despite the fact that the notebook documents are plain text files, they use
52 JSON format, they can record all aspects of the computation, including embedding rich media output.
57 the JSON format in order to store a *complete*, *reproducible* copy of the
53 The standard file extension for notebook documents is ``.ipynb``.
58 state of the computation as it is inside the Notebook app.
59 That is, they record all computations carried out and the results obtained in a literate way; inputs and outputs of computations can be freely mixed with descriptive text, mathematics, and HTML 5 objects.
54
60
55 Notebooks may easily be exported to a range of static formats, including HTML (for example, for blog posts), PDF and slide shows.
61 Notebooks may easily be exported to a range of static formats, including HTML (for example, for blog posts), PDF and slide shows.
56 Furthermore, any publicly
62 Furthermore, any publicly
57 available notebook may be shared via the `IPython Notebook Viewer
63 available notebook may be shared via the `IPython Notebook Viewer
58 <http://nbviewer.ipython.org>`_ service, which will provide it as a static web
64 <http://nbviewer.ipython.org>`_ service, which will provide it as a static web
59 page. The results may thus be shared without having to install anything.
65 page. The results may thus be shared without having to install anything.
60
66
61
67
62 See :ref:`our installation documentation <install_index>` for directions on
68 See :ref:`our installation documentation <install_index>` for directions on
63 how to install the notebook and its dependencies.
69 how to install the notebook and its dependencies.
64
70
65 .. note::
71 .. note::
66
72
67 You can start more than one notebook server at the same time, if you want to
73 You can start more than one notebook server at the same time, if you want to
68 work on notebooks in different directories. By default the first notebook
74 work on notebooks in different directories. By default the first notebook
69 server starts on port 8888, and later notebook servers search for ports near
75 server starts on port 8888, and later notebook servers search for ports near
70 that one. You can also manually specify the port with the ``--port``
76 that one. You can also manually specify the port with the ``--port``
71 option.
77 option.
72
78
73
79
74 Starting the IPython Notebook web app
80 Starting the IPython Notebook web app
75 =====================================
81 =====================================
76
82
77 The Notebook web app is started with the command::
83 The Notebook web app is started with the command::
78
84
79 $ ipython notebook
85 $ ipython notebook
80
86
81 The landing page of the notebook server application, the *dashboard*, shows the notebooks currently available in the *working directory* (the directory from which the notebook was started).
87 The landing page of the notebook server application, the *dashboard*, shows the notebooks currently available in the *working directory* (the directory from which the notebook was started).
82 You can create new notebooks from the dashboard with the ``New Notebook``
88 You can create new notebooks from the dashboard with the ``New Notebook``
83 button, or open existing ones by clicking on their name.
89 button, or open existing ones by clicking on their name.
84 You can also drag and drop ``.ipynb`` notebooks and standard ``.py`` Python source code files into the notebook list area.
90 You can also drag and drop ``.ipynb`` notebooks and standard ``.py`` Python source code files into the notebook list area.
85
91
86 ``.py`` files will be imported into the IPython Notebook as a notebook with the same name, but an ``.ipynb`` extension, located in the working directory. The notebook will consist of a single cell containing all the
92 ``.py`` files will be imported into the IPython Notebook as a notebook with the same name, but an ``.ipynb`` extension, located in the working directory. The notebook will consist of a single cell containing all the
87 code in the ``.py`` file, which you can later manually partition into individual cells.
93 code in the ``.py`` file, which you can later manually partition into individual cells.
88
94
89 .. Alternatively, prior to importing the ``.py``, you can manually add ``# <nbformat>2</nbformat>`` at the start of the file, and then add separators for text and code cells, to get a cleaner import with the file already broken into individual cells.
95 .. Alternatively, prior to importing the ``.py``, you can manually add ``# <nbformat>2</nbformat>`` at the start of the file, and then add separators for text and code cells, to get a cleaner import with the file already broken into individual cells.
90
96
91
97
92 The IPython Notebook web app is based on a server-client structure.
98 The IPython Notebook web app is based on a server-client structure.
93 This server uses a two-process kernel architecture based on ZeroMQ, as well as Tornado for serving HTTP requests. Other clients may connect to the same underlying IPython kernel.
99 This server uses a two-process kernel architecture based on ZeroMQ, as well as Tornado for serving HTTP requests. Other clients may connect to the same underlying IPython kernel.
94
100
95
101
96
97 Basic workflow
98 --------------
99
100 When you open or create a new notebook, your browser tab will reflect the name of that notebook, prefixed with "IPy".
102 When you open or create a new notebook, your browser tab will reflect the name of that notebook, prefixed with "IPy".
101 The URL is currently not meant to be human-readable and is not persistent across invocations of the notebook server; however, this will change in a future version of IPython.
103 The URL is currently not meant to be human-readable and is not persistent across invocations of the notebook server; however, this will change in a future version of IPython.
102
104
105
106 Basic concepts in the Notebook app
107 ----------------------------------
108
109 When you finally start editing a notebook document in the Notebook, you will be presented with the title of the notebook, a *menu bar*, a *toolbar* and an empty *input cell*.
110
111 Notebook title
112 Λ†Λ†Λ†Λ†Λ†Λ†Λ†Λ†Λ†Λ†Λ†Λ†Λ†Λ†Λ†
113
114 The title of the notebook document that is currently being edited is displayed at the top of the page, next to the ``IP[y]: Notebook`` logo. This title may be edited directly by clicking on it. The title is reflected in the name of the ``.ipynb`` notebook document file that is saved.
115
116 Menu bar
117 Λ†Λ†Λ†Λ†Λ†Λ†Λ†Λ†Λ†
118
119 The menu bar presents different options that may be used to manipulate the way the Notebook functions.
120
121 Toolbar
122 Λ†Λ†Λ†Λ†Λ†Λ†Λ†Λ†
123
124 The tool bar gives handy icons for the most-used operations within the Notebook.
125
126 Input cell
127 Λ†Λ†Λ†Λ†Λ†Λ†Λ†Λ†Λ†Λ†Λ†
128
129 Input cells are the core of the funcionality of the IPython Notebook.
130 The notebook consists of
131 They provide the means by which you direct the computational process,
132 They allow you to enter information of different types as input to the computation.
133
134
135 The IPython Notebook consists of a sequence of *input cells*. There are several
136
103 The normal workflow in a notebook is quite similar to a standard IPython
137 The normal workflow in a notebook is quite similar to a standard IPython
104 session, with the difference that you can edit a cell in-place multiple
138 session, with the difference that you can edit a cell in-place multiple
105 times until you obtain the desired results, rather than having to
139 times until you obtain the desired results, rather than having to
106 rerun separate scripts with the ``%run`` magic. (Magics do, however, also work
140 rerun separate scripts with the ``%run`` magic. (Magics do, however, also work
107 in the notebook.) Typically, you'll work on a problem in pieces,
141 in the notebook.) Typically, you'll work on a problem in pieces,
108 organizing related pieces into cells and moving forward as previous
142 organizing related pieces into cells and moving forward as previous
109 parts work correctly. This is much more convenient for interactive exploration than breaking up a computation into scripts that must be
143 parts work correctly. This is much more convenient for interactive exploration than breaking up a computation into scripts that must be
110 executed together, especially if parts of them take a long time to run
144 executed together, especially if parts of them take a long time to run
111
145
112 The only significant limitation that the notebook currently has, compared to the Qt console, is that it cannot run any code that
146 The only significant limitation that the notebook currently has, compared to the Qt console, is that it cannot run any code that
113 expects input from the kernel (such as scripts that call
147 expects input from the kernel (such as scripts that call
114 :func:`raw_input`). Very importantly, this means that the ``%debug``
148 :func:`raw_input`). Very importantly, this means that the ``%debug``
115 magic does *not* currently work in the notebook! This limitation will
149 magic does *not* currently work in the notebook! This limitation will
116 be overcome in the future, but in the meantime, there is a way to debug problems in the notebook: you can attach a Qt console to your existing notebook kernel, and run ``%debug`` from the Qt console.
150 be overcome in the future, but in the meantime, there is a way to debug problems in the notebook: you can attach a Qt console to your existing notebook kernel, and run ``%debug`` from the Qt console.
117 If your notebook is running on a local
151 If your notebook is running on a local
118 computer (i.e. if you are accessing it via your localhost address at ``127.0.0.1``), you can just type ``%qtconsole`` in the notebook and a Qt console will open up, connected to that same kernel.
152 computer (i.e. if you are accessing it via your localhost address at ``127.0.0.1``), you can just type ``%qtconsole`` in the notebook and a Qt console will open up, connected to that same kernel.
119
153
120
154
121 Cell types
155 Cell types
122 ----------
156 ----------
123
157
124 Each IPython input cell has a cell type.
158 Each IPython input cell has a cell type.
125 There is a limited number of possible cell types, which may be set by using the cell type dropdown on the toolbar, or via the following keyboard shortcuts:
159 There is a limited number of possible cell types, which may be set by using the cell type dropdown on the toolbar, or via the following keyboard shortcuts:
126
160
127 * code :kbd:`Ctrl-m y`
161 * code :kbd:`Ctrl-m y`
128 * markdown :kbd:`Ctrl-m m`
162 * markdown :kbd:`Ctrl-m m`
129 * raw :kbd:`Ctrl-m t`
163 * raw :kbd:`Ctrl-m t`
130 * heading :kbd:`Ctrl-m 1` - :kbd:`Ctrl-m 6`
164 * heading :kbd:`Ctrl-m 1` - :kbd:`Ctrl-m 6`
131
165
132
166
133 Code cells
167 Code cells
134 ----------
168 Λ†Λ†Λ†Λ†Λ†Λ†Λ†Λ†Λ†Λ†Λ†
169
135 Code cells contain code, which is Python by default. This code is executed when :kbd:`Shift-Enter` is typed, and the result of running the code will then be displayed as its output just below the cell. For example, the output may be a figure, which can be displayed inline (see below).
170 Code cells contain code, which is Python by default. This code is executed when :kbd:`Shift-Enter` is typed, and the result of running the code will then be displayed as its output just below the cell. For example, the output may be a figure, which can be displayed inline (see below).
136
171
137 Code may be edited inline in the cell, with full syntax highlighting.
172 Code may be edited inline in the cell, with full syntax highlighting.
138
173
139
174
140 Rich text using markdown
175 Rich text using markdown
141 -------------------------
176 Λ†Λ†Λ†Λ†Λ†Λ†Λ†Λ†Λ†Λ†Λ†Λ†Λ†Λ†Λ†Λ†Λ†Λ†Λ†Λ†Λ†Λ†Λ†Λ†Λ†
142
177
143 The computational process may be documented using rich text by using a markdown cell. Rich text is entered using Markdown_ syntax, allowing for italics, bold, ordered and unordered lists, etc.
178 The computational process may be documented using rich text by using a markdown cell. Rich text is entered using Markdown_ syntax, allowing for italics, bold, ordered and unordered lists, etc.
144
179
145
180
146 Mathematics using LaTeX
181 Mathematics using LaTeX
147 -----------------------
182 Λ†Λ†Λ†Λ†Λ†Λ†Λ†Λ†Λ†Λ†Λ†Λ†Λ†Λ†Λ†Λ†Λ†Λ†Λ†Λ†Λ†Λ†Λ†
148
183
149 You can write mathematics by including LaTeX code in markdown cells.
184 You can write mathematics by including LaTeX code in markdown cells.
150 Use ``$...$`` for inline math and ``$$...$$`` for displayed math. Standard LaTeX environments, such as ``\begin{equation}...\end{equation}`` also work.
185 Use ``$...$`` for inline math and ``$$...$$`` for displayed math. Standard LaTeX environments, such as ``\begin{equation}...\end{equation}`` also work.
151 New commands may be defined using standard LaTeX commands, placed anywhere in a markdown cell.
186 New commands may be defined using standard LaTeX commands, placed anywhere in a markdown cell.
152
187
153 Raw cells
188 Raw cells
154 ---------
189 Λ†Λ†Λ†Λ†Λ†Λ†Λ†Λ†Λ†Λ†
190
191
155
192
156 Raw cells provide a place to put additional information which is not evaluated by the Notebook. This can be used, for example, for extra information to be used when the notebook is exported to a certain format.
193 Raw cells provide a place to put additional information which is not evaluated by the Notebook. This can be used, for example, for extra information to be used when the notebook is exported to a certain format.
157
194
158
195
159 Plotting
196 Plotting
160 --------
197 --------
161
198
162 The Notebook allows
199 The Notebook allows
163
200
164 `%matplotlib` and `%pylab` magics
201 `%matplotlib` and `%pylab` magics
165
202
166 Inline versus non inline
203 Inline versus non inline
167
204
168 %config
205 %config
169
206
170 Test!
207 Test!
171
208
172
209
173 Exporting a notebook and importing existing scripts
210 Exporting a notebook and importing existing scripts
174 ---------------------------------------------------
211 ---------------------------------------------------
175
212
176 If you want to provide others with a static HTML or PDF view of your notebook,
213 If you want to provide others with a static HTML or PDF view of your notebook,
177 use the ``Print`` button. This opens a static view of the document, which you
214 use the ``Print`` button. This opens a static view of the document, which you
178 can print to PDF using your operating system's facilities, or save to a file
215 can print to PDF using your operating system's facilities, or save to a file
179 with your web browser's 'Save' option (note that typically, this will create
216 with your web browser's 'Save' option (note that typically, this will create
180 both an html file *and* a directory called `notebook_name_files` next to it
217 both an html file *and* a directory called `notebook_name_files` next to it
181 that contains all the necessary style information, so if you intend to share
218 that contains all the necessary style information, so if you intend to share
182 this, you must send the directory along with the main html file).
219 this, you must send the directory along with the main html file).
183
220
184 The `Download` button lets you save a notebook file to the Download area
221 The `Download` button lets you save a notebook file to the Download area
185 configured by your web browser (particularly useful if you are running the
222 configured by your web browser (particularly useful if you are running the
186 notebook server on a remote host and need a file locally). The notebook is
223 notebook server on a remote host and need a file locally). The notebook is
187 saved by default with the ``.ipynb`` extension and the files contain JSON data
224 saved by default with the ``.ipynb`` extension and the files contain JSON data
188 that is not meant for human editing or consumption. But you can always export
225 that is not meant for human editing or consumption. But you can always export
189 the input part of a notebook to a plain python script by choosing Python format
226 the input part of a notebook to a plain python script by choosing Python format
190 in the `Download` drop list. This removes all output and saves the text cells
227 in the `Download` drop list. This removes all output and saves the text cells
191 in comment areas. See ref:`below <notebook_format>` for more details on the
228 in comment areas. See ref:`below <notebook_format>` for more details on the
192 notebook format.
229 notebook format.
193
230
194
231
195 .. warning::
232 .. warning::
196
233
197 While in simple cases you can roundtrip a notebook to Python, edit the
234 While in simple cases you can roundtrip a notebook to Python, edit the
198 python file and import it back without loss of main content, this is in
235 python file and import it back without loss of main content, this is in
199 general *not guaranteed to work at all*. First, there is extra metadata
236 general *not guaranteed to work at all*. First, there is extra metadata
200 saved in the notebook that may not be saved to the ``.py`` format. And as
237 saved in the notebook that may not be saved to the ``.py`` format. And as
201 the notebook format evolves in complexity, there will be attributes of the
238 the notebook format evolves in complexity, there will be attributes of the
202 notebook that will not survive a roundtrip through the Python form. You
239 notebook that will not survive a roundtrip through the Python form. You
203 should think of the Python format as a way to output a script version of a
240 should think of the Python format as a way to output a script version of a
204 notebook and the import capabilities as a way to load existing code to get a
241 notebook and the import capabilities as a way to load existing code to get a
205 notebook started. But the Python version is *not* an alternate notebook
242 notebook started. But the Python version is *not* an alternate notebook
206 format.
243 format.
207
244
208
245
209 Importing or executing a notebook as a normal Python file
246 Importing or executing a notebook as a normal Python file
210 ---------------------------------------------------------
247 ---------------------------------------------------------
211
248
212 The native format of the notebook, a file with a ``.ipynb`` `extension, is a
249 The native format of the notebook, a file with a ``.ipynb`` `extension, is a
213 JSON container of all the input and output of the notebook, and therefore not
250 JSON container of all the input and output of the notebook, and therefore not
214 valid Python by itself. This means that by default, you cannot directly
251 valid Python by itself. This means that by default, you cannot directly
215 import a notebook from Python, nor execute it as a normal python script.
252 import a notebook from Python, nor execute it as a normal python script.
216
253
217 But if you want to be able to use notebooks also as regular Python files, you can start the notebook server with::
254 But if you want to be able to use notebooks also as regular Python files, you can start the notebook server with::
218
255
219 ipython notebook --script
256 ipython notebook --script
220
257
221 or you can set this option permanently in your configuration file with::
258 or you can set this option permanently in your configuration file with::
222
259
223 c.NotebookManager.save_script=True
260 c.NotebookManager.save_script=True
224
261
225 This will instruct the notebook server to save the ``.py`` export of each
262 This will instruct the notebook server to save the ``.py`` export of each
226 notebook, in addition to the ``.ipynb``, at every save. These are standard ``.py`` files, and so they can be
263 notebook, in addition to the ``.ipynb``, at every save. These are standard ``.py`` files, and so they can be
227 ``%run``, imported from regular IPython sessions or other notebooks, or
264 ``%run``, imported from regular IPython sessions or other notebooks, or
228 executed at the command-line. Since we export the raw
265 executed at the command-line. Since we export the raw
229 code you have typed, for these files to be importable from other code you will
266 code you have typed, for these files to be importable from other code you will
230 have to avoid using syntax such as ``%magics`` and other IPython-specific
267 have to avoid using syntax such as ``%magics`` and other IPython-specific
231 extensions to the language.
268 extensions to the language.
232
269
233 In regular practice, the standard way to differentiate importable code from the
270 In regular practice, the standard way to differentiate importable code from the
234 'executable' part of a script is to put at the bottom::
271 'executable' part of a script is to put at the bottom::
235
272
236 if __name__ == '__main__':
273 if __name__ == '__main__':
237 # rest of the code...
274 # rest of the code...
238
275
239 Since all cells in the notebook are run as top-level code, you'll need to
276 Since all cells in the notebook are run as top-level code, you'll need to
240 similarly protect *all* cells that you do not want executed when other scripts
277 similarly protect *all* cells that you do not want executed when other scripts
241 try to import your notebook. A convenient shortand for this is to define early
278 try to import your notebook. A convenient shortand for this is to define early
242 on::
279 on::
243
280
244 script = __name__ == '__main__'
281 script = __name__ == '__main__'
245
282
246 and then on any cell that you need to protect, use::
283 and then on any cell that you need to protect, use::
247
284
248 if script:
285 if script:
249 # rest of the cell...
286 # rest of the cell...
250
287
251 Configuration
288 Configuration
252 -------------
289 -------------
253
290
254 The IPython notebook server can be run with a variety of command line arguments.
291 The IPython notebook server can be run with a variety of command line arguments.
255 To see a list of available options enter::
292 To see a list of available options enter::
256
293
257 $ ipython notebook --help
294 $ ipython notebook --help
258
295
259 Defaults for these options can also be set by creating a file named
296 Defaults for these options can also be set by creating a file named
260 ``ipython_notebook_config.py`` in your IPython profile folder. The profile folder is a subfolder of your IPython directory; ``ipython locate`` will show you where it is located.
297 ``ipython_notebook_config.py`` in your IPython profile folder. The profile folder is a subfolder of your IPython directory; ``ipython locate`` will show you where it is located.
261
298
262 To create a new set of default configuration files, with lots of information on available options, use::
299 To create a new set of default configuration files, with lots of information on available options, use::
263
300
264 $ ipython profile create
301 $ ipython profile create
265
302
266 .. seealso:
303 .. seealso:
267
304
268 :ref:`config_overview`, in particular :ref:`Profiles`.
305 :ref:`config_overview`, in particular :ref:`Profiles`.
269
306
270
307
271 Keyboard shortcuts
308 Keyboard shortcuts
272 ------------------
309 ------------------
273
310
274 All actions in the notebook can be achieved with the mouse, but we have also
311 All actions in the notebook can be achieved with the mouse, but we have also
275 added keyboard shortcuts for the most common ones, so that productive use of
312 added keyboard shortcuts for the most common ones, so that productive use of
276 the notebook can be achieved with minimal mouse intervention. The main
313 the notebook can be achieved with minimal mouse intervention. The main
277 key bindings you need to remember are:
314 key bindings you need to remember are:
278
315
279 * :kbd:`Shift-Enter`: execute the current cell (similar to the Qt console),
316 * :kbd:`Shift-Enter`: execute the current cell (similar to the Qt console),
280 show output (if any) and jump to the next cell below. If :kbd:`Shift-Enter`
317 show output (if any) and jump to the next cell below. If :kbd:`Shift-Enter`
281 was invoked on the last input line, a new code cell will also be created. Note
318 was invoked on the last input line, a new code cell will also be created. Note
282 that in the notebook, simply using :kbd:`Enter` *never* forces execution,
319 that in the notebook, simply using :kbd:`Enter` *never* forces execution,
283 it simply inserts a new line in the current cell. Therefore, in the notebook
320 it simply inserts a new line in the current cell. Therefore, in the notebook
284 you must always use :kbd:`Shift-Enter` to get execution (or use the mouse and
321 you must always use :kbd:`Shift-Enter` to get execution (or use the mouse and
285 click on the ``Run Selected`` button).
322 click on the ``Run Selected`` button).
286
323
287 * :kbd:`Alt-Enter`: this combination is similar to the previous one, with the
324 * :kbd:`Alt-Enter`: this combination is similar to the previous one, with the
288 exception that, if the next cell below is not empty, a new code cell will be
325 exception that, if the next cell below is not empty, a new code cell will be
289 added to the notebook, even if the cell execution happens not in the last cell.
326 added to the notebook, even if the cell execution happens not in the last cell.
290 In this regard, :kbd:`Alt-Enter`: is simply a shortcut for the :kbd:`Shift-Enter`,
327 In this regard, :kbd:`Alt-Enter`: is simply a shortcut for the :kbd:`Shift-Enter`,
291 :kbd:`Ctrl-m a` sequence.
328 :kbd:`Ctrl-m a` sequence.
292
329
293 * :kbd:`Ctrl-Enter`: execute the current cell in "terminal mode", where any
330 * :kbd:`Ctrl-Enter`: execute the current cell in "terminal mode", where any
294 output is shown but the cursor stays in the current cell, whose input
331 output is shown but the cursor stays in the current cell, whose input
295 area is flushed empty. This is convenient to do quick in-place experiments
332 area is flushed empty. This is convenient to do quick in-place experiments
296 or query things like filesystem content without creating additional cells you
333 or query things like filesystem content without creating additional cells you
297 may not want saved in your notebook.
334 may not want saved in your notebook.
298
335
299 * :kbd:`Ctrl-m`: this is the prefix for all other keybindings, which consist
336 * :kbd:`Ctrl-m`: this is the prefix for all other keybindings, which consist
300 of an additional single letter. Type :kbd:`Ctrl-m h` (that is, the sole
337 of an additional single letter. Type :kbd:`Ctrl-m h` (that is, the sole
301 letter :kbd:`h` after :kbd:`Ctrl-m`) and IPython will show you the remaining
338 letter :kbd:`h` after :kbd:`Ctrl-m`) and IPython will show you the remaining
302 available keybindings.
339 available keybindings.
303
340
304
341
305 .. _notebook_security:
342 .. _notebook_security:
306
343
307 Security
344 Security
308 ========
345 ========
309
346
310 You can protect your notebook server with a simple single-password by
347 You can protect your notebook server with a simple single-password by
311 setting the :attr:`NotebookApp.password` configurable. You can prepare a
348 setting the :attr:`NotebookApp.password` configurable. You can prepare a
312 hashed password using the function :func:`IPython.lib.security.passwd`:
349 hashed password using the function :func:`IPython.lib.security.passwd`:
313
350
314 .. sourcecode:: ipython
351 .. sourcecode:: ipython
315
352
316 In [1]: from IPython.lib import passwd
353 In [1]: from IPython.lib import passwd
317 In [2]: passwd()
354 In [2]: passwd()
318 Enter password:
355 Enter password:
319 Verify password:
356 Verify password:
320 Out[2]: 'sha1:67c9e60bb8b6:9ffede0825894254b2e042ea597d771089e11aed'
357 Out[2]: 'sha1:67c9e60bb8b6:9ffede0825894254b2e042ea597d771089e11aed'
321
358
322 .. note::
359 .. note::
323
360
324 :func:`~IPython.lib.security.passwd` can also take the password as a string
361 :func:`~IPython.lib.security.passwd` can also take the password as a string
325 argument. **Do not** pass it as an argument inside an IPython session, as it
362 argument. **Do not** pass it as an argument inside an IPython session, as it
326 will be saved in your input history.
363 will be saved in your input history.
327
364
328 You can then add this to your :file:`ipython_notebook_config.py`, e.g.::
365 You can then add this to your :file:`ipython_notebook_config.py`, e.g.::
329
366
330 # Password to use for web authentication
367 # Password to use for web authentication
331 c.NotebookApp.password = u'sha1:67c9e60bb8b6:9ffede0825894254b2e042ea597d771089e11aed'
368 c.NotebookApp.password = u'sha1:67c9e60bb8b6:9ffede0825894254b2e042ea597d771089e11aed'
332
369
333 When using a password, it is a good idea to also use SSL, so that your password
370 When using a password, it is a good idea to also use SSL, so that your password
334 is not sent unencrypted by your browser. You can start the notebook to
371 is not sent unencrypted by your browser. You can start the notebook to
335 communicate via a secure protocol mode using a self-signed certificate by
372 communicate via a secure protocol mode using a self-signed certificate by
336 typing::
373 typing::
337
374
338 $ ipython notebook --certfile=mycert.pem
375 $ ipython notebook --certfile=mycert.pem
339
376
340 .. note::
377 .. note::
341
378
342 A self-signed certificate can be generated with openssl. For example, the
379 A self-signed certificate can be generated with openssl. For example, the
343 following command will create a certificate valid for 365 days with both
380 following command will create a certificate valid for 365 days with both
344 the key and certificate data written to the same file::
381 the key and certificate data written to the same file::
345
382
346 $ openssl req -x509 -nodes -days 365 -newkey rsa:1024 -keyout mycert.pem -out mycert.pem
383 $ openssl req -x509 -nodes -days 365 -newkey rsa:1024 -keyout mycert.pem -out mycert.pem
347
384
348 Your browser will warn you of a dangerous certificate because it is
385 Your browser will warn you of a dangerous certificate because it is
349 self-signed. If you want to have a fully compliant certificate that will not
386 self-signed. If you want to have a fully compliant certificate that will not
350 raise warnings, it is possible (but rather involved) to obtain one for free,
387 raise warnings, it is possible (but rather involved) to obtain one for free,
351 `as explained in detailed in this tutorial`__.
388 `as explained in detailed in this tutorial`__.
352
389
353 .. __: http://arstechnica.com/security/news/2009/12/how-to-get-set-with-a-secure-sertificate-for-free.ars
390 .. __: http://arstechnica.com/security/news/2009/12/how-to-get-set-with-a-secure-sertificate-for-free.ars
354
391
355 Keep in mind that when you enable SSL support, you'll need to access the
392 Keep in mind that when you enable SSL support, you'll need to access the
356 notebook server over ``https://``, not over plain ``http://``. The startup
393 notebook server over ``https://``, not over plain ``http://``. The startup
357 message from the server prints this, but it's easy to overlook and think the
394 message from the server prints this, but it's easy to overlook and think the
358 server is for some reason non-responsive.
395 server is for some reason non-responsive.
359
396
360 Quick how to's
397 Quick how to's
361 ==============
398 ==============
362
399
363 Connecting to an existing kernel
400 Connecting to an existing kernel
364 ---------------------------------
401 ---------------------------------
365
402
366 The notebook server always prints to the terminal the full details of
403 The notebook server always prints to the terminal the full details of
367 how to connect to each kernel, with lines like::
404 how to connect to each kernel, with lines like::
368
405
369 [IPKernelApp] To connect another client to this kernel, use:
406 [IPKernelApp] To connect another client to this kernel, use:
370 [IPKernelApp] --existing kernel-3bb93edd-6b5a-455c-99c8-3b658f45dde5.json
407 [IPKernelApp] --existing kernel-3bb93edd-6b5a-455c-99c8-3b658f45dde5.json
371
408
372 This is the name of a JSON file that contains all the port and
409 This is the name of a JSON file that contains all the port and
373 validation information necessary to connect to the kernel. You can
410 validation information necessary to connect to the kernel. You can
374 manually start a Qt console with::
411 manually start a Qt console with::
375
412
376 ipython qtconsole --existing kernel-3bb93edd-6b5a-455c-99c8-3b658f45dde5.json
413 ipython qtconsole --existing kernel-3bb93edd-6b5a-455c-99c8-3b658f45dde5.json
377
414
378 and if you only have a single kernel running, simply typing::
415 and if you only have a single kernel running, simply typing::
379
416
380 ipython qtconsole --existing
417 ipython qtconsole --existing
381
418
382 will automatically find it (it will always find the most recently
419 will automatically find it (it will always find the most recently
383 started kernel if there is more than one). You can also request this
420 started kernel if there is more than one). You can also request this
384 connection data by typing ``%connect_info``; this will print the same
421 connection data by typing ``%connect_info``; this will print the same
385 file information as well as the content of the JSON data structure it contains.
422 file information as well as the content of the JSON data structure it contains.
386
423
387
424
388 Running a public notebook server
425 Running a public notebook server
389 --------------------------------
426 --------------------------------
390
427
391 If you want to access your notebook server remotely with just a web browser,
428 If you want to access your notebook server remotely with just a web browser,
392 here is a quick set of instructions. Start by creating a certificate file and
429 here is a quick set of instructions. Start by creating a certificate file and
393 a hashed password as explained above. Then, create a custom profile for the
430 a hashed password as explained above. Then, create a custom profile for the
394 notebook. At the command line, type::
431 notebook. At the command line, type::
395
432
396 ipython profile create nbserver
433 ipython profile create nbserver
397
434
398 In the profile directory, edit the file ``ipython_notebook_config.py``. By
435 In the profile directory, edit the file ``ipython_notebook_config.py``. By
399 default the file has all fields commented, the minimum set you need to
436 default the file has all fields commented, the minimum set you need to
400 uncomment and edit is here::
437 uncomment and edit is here::
401
438
402 c = get_config()
439 c = get_config()
403
440
404 # Kernel config
441 # Kernel config
405 c.IPKernelApp.pylab = 'inline' # if you want plotting support always
442 c.IPKernelApp.pylab = 'inline' # if you want plotting support always
406
443
407 # Notebook config
444 # Notebook config
408 c.NotebookApp.certfile = u'/absolute/path/to/your/certificate/mycert.pem'
445 c.NotebookApp.certfile = u'/absolute/path/to/your/certificate/mycert.pem'
409 c.NotebookApp.ip = '*'
446 c.NotebookApp.ip = '*'
410 c.NotebookApp.open_browser = False
447 c.NotebookApp.open_browser = False
411 c.NotebookApp.password = u'sha1:bcd259ccf...your hashed password here'
448 c.NotebookApp.password = u'sha1:bcd259ccf...your hashed password here'
412 # It's a good idea to put it on a known, fixed port
449 # It's a good idea to put it on a known, fixed port
413 c.NotebookApp.port = 9999
450 c.NotebookApp.port = 9999
414
451
415 You can then start the notebook and access it later by pointing your browser to
452 You can then start the notebook and access it later by pointing your browser to
416 ``https://your.host.com:9999`` with ``ipython notebook --profile=nbserver``.
453 ``https://your.host.com:9999`` with ``ipython notebook --profile=nbserver``.
417
454
418 Running with a different URL prefix
455 Running with a different URL prefix
419 -----------------------------------
456 -----------------------------------
420
457
421 The notebook dashboard (i.e. the default landing page with an overview
458 The notebook dashboard (i.e. the default landing page with an overview
422 of all your notebooks) typically lives at a URL path of
459 of all your notebooks) typically lives at a URL path of
423 "http://localhost:8888/". If you want to have it, and the rest of the
460 "http://localhost:8888/". If you want to have it, and the rest of the
424 notebook, live under a sub-directory,
461 notebook, live under a sub-directory,
425 e.g. "http://localhost:8888/ipython/", you can do so with
462 e.g. "http://localhost:8888/ipython/", you can do so with
426 configuration options like these (see above for instructions about
463 configuration options like these (see above for instructions about
427 modifying ``ipython_notebook_config.py``)::
464 modifying ``ipython_notebook_config.py``)::
428
465
429 c.NotebookApp.base_project_url = '/ipython/'
466 c.NotebookApp.base_project_url = '/ipython/'
430 c.NotebookApp.base_kernel_url = '/ipython/'
467 c.NotebookApp.base_kernel_url = '/ipython/'
431 c.NotebookApp.webapp_settings = {'static_url_prefix':'/ipython/static/'}
468 c.NotebookApp.webapp_settings = {'static_url_prefix':'/ipython/static/'}
432
469
433 Using a different notebook store
470 Using a different notebook store
434 --------------------------------
471 --------------------------------
435
472
436 By default the notebook server stores notebooks as files in the working
473 By default the notebook server stores notebooks as files in the working
437 directory of the notebook server, also known as the ``notebook_dir``. This
474 directory of the notebook server, also known as the ``notebook_dir``. This
438 logic is implemented in the :class:`FileNotebookManager` class. However, the
475 logic is implemented in the :class:`FileNotebookManager` class. However, the
439 server can be configured to use a different notebook manager class, which can
476 server can be configured to use a different notebook manager class, which can
440 store the notebooks in a different format. Currently, we ship a
477 store the notebooks in a different format. Currently, we ship a
441 :class:`AzureNotebookManager` class that stores notebooks in Azure blob
478 :class:`AzureNotebookManager` class that stores notebooks in Azure blob
442 storage. This can be used by adding the following lines to your
479 storage. This can be used by adding the following lines to your
443 ``ipython_notebook_config.py`` file::
480 ``ipython_notebook_config.py`` file::
444
481
445 c.NotebookApp.notebook_manager_class = 'IPython.html.services.notebooks.azurenbmanager.AzureNotebookManager'
482 c.NotebookApp.notebook_manager_class = 'IPython.html.services.notebooks.azurenbmanager.AzureNotebookManager'
446 c.AzureNotebookManager.account_name = u'paste_your_account_name_here'
483 c.AzureNotebookManager.account_name = u'paste_your_account_name_here'
447 c.AzureNotebookManager.account_key = u'paste_your_account_key_here'
484 c.AzureNotebookManager.account_key = u'paste_your_account_key_here'
448 c.AzureNotebookManager.container = u'notebooks'
485 c.AzureNotebookManager.container = u'notebooks'
449
486
450 In addition to providing your Azure Blob Storage account name and key, you will
487 In addition to providing your Azure Blob Storage account name and key, you will
451 have to provide a container name; you can use multiple containers to organize
488 have to provide a container name; you can use multiple containers to organize
452 your Notebooks.
489 your Notebooks.
453
490
454 .. _notebook_format:
491 .. _notebook_format:
455
492
456 The notebook format
493 The notebook format
457 ===================
494 ===================
458
495
459 The notebooks themselves are JSON files with an ``ipynb`` extension, formatted
496 The notebooks themselves are JSON files with an ``ipynb`` extension, formatted
460 as legibly as possible with minimal extra indentation and cell content broken
497 as legibly as possible with minimal extra indentation and cell content broken
461 across lines to make them reasonably friendly to use in version-control
498 across lines to make them reasonably friendly to use in version-control
462 workflows. You should be very careful if you ever edit manually this JSON
499 workflows. You should be very careful if you ever edit manually this JSON
463 data, as it is extremely easy to corrupt its internal structure and make the
500 data, as it is extremely easy to corrupt its internal structure and make the
464 file impossible to load. In general, you should consider the notebook as a
501 file impossible to load. In general, you should consider the notebook as a
465 file meant only to be edited by IPython itself, not for hand-editing.
502 file meant only to be edited by IPython itself, not for hand-editing.
466
503
467 .. note::
504 .. note::
468
505
469 Binary data such as figures are directly saved in the JSON file. This
506 Binary data such as figures are directly saved in the JSON file. This
470 provides convenient single-file portability but means the files can be
507 provides convenient single-file portability but means the files can be
471 large and diffs of binary data aren't very meaningful. Since the binary
508 large and diffs of binary data aren't very meaningful. Since the binary
472 blobs are encoded in a single line they only affect one line of the diff
509 blobs are encoded in a single line they only affect one line of the diff
473 output, but they are typically very long lines. You can use the
510 output, but they are typically very long lines. You can use the
474 'ClearAll' button to remove all output from a notebook prior to
511 'ClearAll' button to remove all output from a notebook prior to
475 committing it to version control, if this is a concern.
512 committing it to version control, if this is a concern.
476
513
477 The notebook server can also generate a pure-python version of your notebook,
514 The notebook server can also generate a pure-python version of your notebook,
478 by clicking on the 'Download' button and selecting ``py`` as the format. This
515 by clicking on the 'Download' button and selecting ``py`` as the format. This
479 file will contain all the code cells from your notebook verbatim, and all text
516 file will contain all the code cells from your notebook verbatim, and all text
480 cells prepended with a comment marker. The separation between code and text
517 cells prepended with a comment marker. The separation between code and text
481 cells is indicated with special comments and there is a header indicating the
518 cells is indicated with special comments and there is a header indicating the
482 format version. All output is stripped out when exporting to python.
519 format version. All output is stripped out when exporting to python.
483
520
484 Here is an example of a simple notebook with one text cell and one code input
521 Here is an example of a simple notebook with one text cell and one code input
485 cell, when exported to python format::
522 cell, when exported to python format::
486
523
487 # <nbformat>2</nbformat>
524 # <nbformat>2</nbformat>
488
525
489 # <markdowncell>
526 # <markdowncell>
490
527
491 # A text cell
528 # A text cell
492
529
493 # <codecell>
530 # <codecell>
494
531
495 print "hello IPython"
532 print "hello IPython"
496
533
497
534
498 Known issues
535 Known issues
499 ============
536 ============
500
537
501 When behind a proxy, especially if your system or browser is set to autodetect
538 When behind a proxy, especially if your system or browser is set to autodetect
502 the proxy, the html notebook might fail to connect to the server's websockets,
539 the proxy, the html notebook might fail to connect to the server's websockets,
503 and present you with a warning at startup. In this case, you need to configure
540 and present you with a warning at startup. In this case, you need to configure
504 your system not to use the proxy for the server's address.
541 your system not to use the proxy for the server's address.
505
542
506 In Firefox, for example, go to the Preferences panel, Advanced section,
543 In Firefox, for example, go to the Preferences panel, Advanced section,
507 Network tab, click 'Settings...', and add the address of the notebook server
544 Network tab, click 'Settings...', and add the address of the notebook server
508 to the 'No proxy for' field.
545 to the 'No proxy for' field.
509
546
510
547
511 .. _Markdown: http://daringfireball.net/projects/markdown/basics
548 .. _Markdown: http://daringfireball.net/projects/markdown/basics
General Comments 0
You need to be logged in to leave comments. Login now