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

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

major doc update for 1.0 release...
Paul Ivanov -
Show More
Show file before | Show file after | Hide comments
@@ -0,0 +1,9 b''
1 <html>
2 <head>
3 <meta http-equiv="Refresh" content="0; url=notebook.html" />
4 <title>Notebook page has move</title>
5 </head>
6 <body>
7 <p>The notebook page has moved to <a href="notebook.html">this link</a>.</p>
8 </body>
9 </html>
Show file before | Show file after | Hide comments
@@ -157,7 +157,9 b" html_last_updated_fmt = '%b %d, %Y'"
157 157
158 158 # Additional templates that should be rendered to pages, maps page names to
159 159 # template names.
160 #html_additional_pages = {}
160 html_additional_pages = {
161 'interactive/htmlnotebook': 'htmlnotebook.html',
162 }
161 163
162 164 # If false, no module index is generated.
163 165 #html_use_modindex = True
Show file before | Show file after | Hide comments
@@ -319,7 +319,7 b' Dependencies for the IPython HTML notebook'
319 319 ==========================================
320 320
321 321 The IPython notebook is a notebook-style web interface to IPython and can be
322 started withe command ``ipython notebook``.
322 started with the command ``ipython notebook``.
323 323
324 324 pyzmq
325 325 -----
Show file before | Show file after | Hide comments
@@ -12,6 +12,6 b' Using IPython for interactive work'
12 12 qtconsole
13 13 notebook
14 14 nbconvert
15 working_remotely
15 public_server
16 16
17 17
Show file before | Show file after | Hide comments
This diff has been collapsed as it changes many lines, (548 lines changed) Show them Hide them
@@ -3,116 +3,116 b''
3 3 The IPython Notebook
4 4 ====================
5 5
6 The IPython Notebook is part of the IPython package, which aims to provide a
7 powerful, interactive approach to scientific computation.
8 The IPython Notebook extends the previous text-console-based approach, and the
9 later Qt console, in a qualitatively new diretion, providing a web-based
10 application suitable for capturing the whole scientific computation process.
6 Introduction
7 ------------
11 8
12 .. seealso::
9 The notebook extends the console-based approach to interactive computing in
10 a qualitatively new direction, providing a web-based application suitable for
11 capturing the whole computation process: developing, documenting, and
12 executing code, as well as communicating the results. The IPython notebook
13 combines two components:
13 14
14 :ref:`Installation requirements <installnotebook>` for the Notebook.
15 **A web application**: a browser-based tool for interactive authoring of
16 documents which combine explanatory text, mathematics, computations and their
17 rich media output.
15 18
19 **Notebook documents**: a representation of all content visible in the web
20 application, including inputs and outputs of the computations, explanatory
21 text, mathematics, images, and rich media representations of objects.
16 22
17 .. Basic structure
18 .. ---------------
23 .. seealso::
19 24
20 Introduction
21 ------------
25 See the :ref:`installation documentation <installnotebook>` for directions
26 on how to install the notebook and its dependencies.
22 27
23 The IPython Notebook combines two components:
24 28
25 * **The IPython Notebook web application**:
29 Main features of the web application
30 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
26 31
27 The *IPython Notebook web app* is a browser-based tool for interactive
28 authoring of literate computations, in which explanatory text,
29 mathematics, computations and rich media output may be combined. Input
30 and output are stored in persistent cells that may be edited in-place.
32 * In-browser editing for code, with automatic syntax highlighting,
33 indentation, and tab completion/introspection.
31 34
32 * **Notebook documents**:
35 * The ability to execute code from the browser, with the results of
36 computations attached to the code which generated them.
33 37
34 *Notebook documents*, or *notebooks*, are plain text documents which
35 record all inputs and outputs of the computations, interspersed with
36 text, mathematics and HTML 5 representations of objects, in a literate
37 style.
38 * Displaying the result of computation using rich media representations, such
39 as HTML, LaTeX, PNG, SVG, etc. For example, publication-quality figures
40 rendered by the matplotlib_ library, can be included inline.
38 41
39 Since the similarity in names can lead to some confusion, in this
40 documentation we will use capitalization of the word "notebook" to
41 distinguish the Notebook app and notebook documents, thinking of the
42 Notebook app as being a proper noun. We will also always refer to the
43 "Notebook app" when we are referring to the browser-based interface,
44 and usually to "notebook documents", instead of "notebooks", for added
45 precision.
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.
46 44
47 We refer to the current state of the computational process taking place in the
48 Notebook app, i.e. the (numbered) sequence of input and output cells, as the
49 *notebook space*. Notebook documents provide an *exact*, *one-to-one* record
50 of all the content in the notebook space, as a plain text file in JSON format.
51 The Notebook app automatically saves, at certain intervals, the contents of
52 the notebook space to a notebook document stored on disk, with the same name
53 as the title of the notebook space, and the file extension ``.ipynb``. For
54 this reason, there is no confusion about using the same word "notebook" for
55 both the notebook space and the corresponding notebook document, since they are
56 really one and the same concept (we could say that they are "isomorphic").
45 * The ability to easily include mathematical notation within markdown cells
46 using LaTeX, and rendered natively by MathJax_.
57 47
58 48
59 Main features of the IPython Notebook web app
60 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
61 49
62 The main features of the IPython Notebook app include:
50 .. _MathJax: http://www.mathjax.org/
63 51
64 * In-browser editing for code, with automatic syntax highlighting and
65 indentation and tab completion/introspection.
66 52
67 * Literate combination of code with rich text using the Markdown_ markup
68 language.
53 Notebook documents
54 ~~~~~~~~~~~~~~~~~~
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
57 execution. In this way, notebook files can serve as a complete computational
58 record of a session, interleaving executable code with explanatory text,
59 mathematics, and rich representations of resulting objects. These documents
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
62 colleagues.
63
64 .. _JSON: http://en.wikipedia.org/wiki/JSON
69 65
70 * Mathematics is easily included within the Markdown using LaTeX notation, and
71 rendered natively by MathJax_.
66 Notebooks may be exported to a range of static formats, including HTML (for
67 example, for blog posts), reStructeredText, LaTeX, PDF, and slide shows, via
68 the new :ref:`nbconvert <nbconvert>` command.
72 69
73 * Displays rich data representations (e.g. HTML / LaTeX / SVG) as the result
74 of computations.
70 Furthermore, any ``.ipynb`` notebook document available from a public
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
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.
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
77 nbviewer.
75 78
76 * Publication-quality figures in a range of formats (SVG / PNG), rendered by
77 the matplotlib_ library, may be included inline and exported.
78 79
79 80
80 .. _MathJax: http://www.mathjax.org/
81 .. _matplotlib: http://matplotlib.org/
82 .. _Markdown: http://daringfireball.net/projects/markdown/syntax
81 .. seealso::
83 82
83 :ref:`Details on the notebook JSON file format <notebook_format>`
84
84 85
85 Notebook documents
86 ~~~~~~~~~~~~~~~~~~
86 Starting the notebook server
87 ----------------------------
87 88
88 Notebook document files are simple JSON_ files with the
89 extension ``.ipynb``.
90 Since JSON is just plain text, they can be easily version-controlled and shared with colleagues.
91 The notebook stores a *complete*, *reproducible*, *one-to-one* copy of the state of the
92 computational state as it is inside the Notebook app. All computations
93 carried out, and the corresponding results obtained, can be combined in
94 a literate way, interleaving executable code with rich text, mathematics,
95 and rich representations of objects.
89 You can start running a notebook server from the command line using the
90 following command::
96 91
97 .. _JSON: http://en.wikipedia.org/wiki/JSON
92 ipython notebook
98 93
99 Notebooks may easily be exported to a range of static formats, including
100 HTML (for example, for blog posts), PDF and slide shows,
101 via the new nbconvert_ command.
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,
96 ``http://127.0.0.1:8888``).
102 97
103 Furthermore, any ``.ipynb`` notebook document available from a public
104 URL can be shared via the `IPython Notebook Viewer <nbviewer>`_ service.
105 This service loads the notebook document from the URL and renders
106 it as a static web page. The results may thus be shared with a
107 colleague, or as a public blog post, without other users needing to install
108 IPython themselves. NbViewer is simply nbconvert_ as a simple webservice.
98 The landing page of the IPython notebook web application, the **dashboard**,
99 shows the notebooks currently available in the notebook directory (by default,
100 the directory from which the notebook server was started).
109 101
110 See the :ref:`installation documentation <install_index>` for directions on
111 how to install the notebook and its dependencies.
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
104 and drop ``.ipynb`` notebooks and standard ``.py`` Python source code files
105 into the notebook list area.
112 106
113 .. _nbconvert: ./nbconvert.html
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
109 my_notebook.ipynb``. The ``.ipynb`` extension is assumed if no extension is
110 given.
111
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
114 from the notebook directory or to create a new notebook.
114 115
115 .. _nbviewer: http://nbviewer.ipython.org
116 116
117 117 .. note::
118 118
@@ -121,145 +121,122 b' how to install the notebook and its dependencies.'
121 121 notebook server starts on port 8888, and later notebook servers search for
122 122 ports near that one. You can also manually specify the port with the
123 123 ``--port`` option.
124
125 124
126 Basic workflow in the IPython Notebook web app
127 ----------------------------------------------
125 Creating a new notebook document
126 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
128 127
129 Starting up
130 ~~~~~~~~~~~~
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
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 132
132 You can start running the Notebook web app using the following command::
133 133
134 $ ipython notebook
134 Opening notebooks
135 ~~~~~~~~~~~~~~~~~
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
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
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
142 notebooks without an active kernel have a ``Delete`` button in its place.
135 143
136 (Here, and in the sequel, the initial ``$`` represents the shell prompt,
137 indicating that the command is to be run from the command line in a shell.)
144 Other clients may connect to the same underlying IPython kernel.
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::
138 147
139 The landing page of the IPython Notebook application, the *dashboard*, shows
140 the notebooks currently available in the *notebook directory* (By default, the directory
141 from which the notebook was started).
142 You can create new notebooks from the dashboard with the ``New Notebook``
143 button, or open existing ones by clicking on their name.
144 You can also drag and drop ``.ipynb`` notebooks and standard ``.py`` Python
145 source code files into the notebook list area.
148 [NotebookApp] Kernel started: 87f7d2c0-13e3-43df-8bb8-1bd37aaf3373
146 149
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
152 connection data by running the ``%connect_info`` :ref:`magic
153 <magics_explained>`. This will print the same ID information as well as the
154 content of the JSON data structure it contains.
147 155
148 You can open an existing notebook directly, without having to go via the
149 dashboard, with::
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::
150 158
151 ipython notebook my_notebook
159 $ ipython qtconsole --existing 87f7d2c0
152 160
153 The ``.ipynb`` extension is assumed if no extension is given.
154
155 The `File | Open...` menu option will open the dashboard in a new browser tab,
156 to allow you to select a current notebook
157 from the notebook directory or to create a new notebook.
161 Without an ID, ``--existing`` will connect to the most recently
162 started kernel. This can also be done by running the ``%qtconsole``
163 :ref:`magic <magics_explained>` in the notebook.
158 164
165 .. seealso::
159 166
167 :ref:`ipythonzmq`
160 168
161 169 Notebook user interface
162 ~~~~~~~~~~~~~~~~~~~~~~~
163
164 When you open a new notebook document in the Notebook, you will be presented
165 with the title associated to the notebook space/document, a *menu bar*, a
166 *toolbar* and an empty *input cell*.
170 -----------------------
167 171
168 Notebook title
169 ^^^^^^^^^^^^^^
170 The title of the notebook document that is currently being edited is displayed
171 at the top of the page, next to the ``IP[y]: Notebook`` logo. This title may
172 be edited directly by clicking on it. The title is reflected in the name of
173 the ``.ipynb`` notebook document file that is saved.
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
174 cell**.
174 175
175 Menu bar
176 ^^^^^^^^
177 The menu bar presents different options that may be used to manipulate the way
178 the Notebook functions.
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
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
180 from "Untitled0" to "My first notebook" in the browser, renames the
181 ``Untitled0.ipynb`` file to ``My first notebook.ipynb``.
179 182
180 Toolbar
181 ^^^^^^^
182 The tool bar gives a quick way of accessing the most-used operations within
183 the Notebook, by clicking on an icon.
183 **menu bar**: The menu bar presents different options that may be used to
184 manipulate the way the notebook functions.
184 185
186 **toolbar**: The tool bar gives a quick way of performing the most-used
187 operations within the notebook, by clicking on an icon.
185 188
186 Creating a new notebook document
187 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
188
189 A new notebook space/document may be created at any time, either from the
190 dashboard, or using the `File | New` menu option from within an active
191 notebook. The new notebook is created within the same directory and
192 will open in a new browser tab. It will also be reflected as a new entry in
193 the notebook list on the dashboard.
189 **code cell**: the default type of cell, read on for an explanation of cells
194 190
195 191
196 192 Structure of a notebook document
197 193 --------------------------------
198 194
199 Input cells
200 ~~~~~~~~~~~
201 Input cells are at the core of the functionality of the IPython Notebook.
202 They are regions in the document in which you can enter different types of
203 text and commands. To *execute* or *run* the *current cell*, i.e. the cell
204 under the cursor, you can use the :kbd:`Shift-Enter` key combination.
205 This tells the Notebook app to perform the relevant operation for each type of
206 cell (see below), and then to display the resulting output.
207
208 The notebook consists of a sequence of input cells, labelled ``In[n]``, which
209 may be executed in a non-linear way, and outputs ``Out[n]``, where ``n`` is a
210 number which denotes the order in which the cells were executed over the
211 history of the computational process. The contents of all of these cells are
212 accessible as Python variables with the same names, forming a complete record
213 of the history of the computation.
214
215
216
217 Input cell types
218 ~~~~~~~~~~~~~~~~
219 Each IPython input cell has a *cell type*, of which there is a restricted
220 number. The type of a cell may be set by using the cell type dropdown on the
221 toolbar, or via the following keyboard shortcuts:
222
223 * **code**: :kbd:`Ctrl-m y`
224 * **markdown**: :kbd:`Ctrl-m m`
225 * **raw**: :kbd:`Ctrl-m t`
226 * **heading**: :kbd:`Ctrl-m 1` - :kbd:`Ctrl-m 6`
227
228 Upon initial creation, each input cell is by default a code cell.
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
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
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
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
203 <keyboard-shortcuts>`.
229 204
230 205
231 206 Code cells
232 ^^^^^^^^^^
233 A *code input cell* allows you to edit code inline within the cell, with full
234 syntax highlighting and autocompletion/introspection. By default, the language
235 associated to a code cell is Python, but other languages, such as ``julia``
236 and ``R``, can be handled using magic commands (see below).
237
238 When a code cell is executed with :kbd:`Shift-Enter`, the code that it
239 contains is transparently exported and run in that language (with automatic
240 compiling, etc., if necessary). The result that is returned from this
241 computation is then displayed in the notebook space as the cell's
242 *output*. If this output is of a textual nature, it is placed into a
243 numbered *output cell*. However, many other possible forms of output are also
244 possible, including ``matplotlib`` figures and HTML tables (as used, for
245 example, in the ``pandas`` data analyis package). This is known as IPython's
207 ~~~~~~~~~~
208 A *code cell* allows you to edit and write new code, with full syntax
209 highlighting and tab completion. By default, the language associated to a code
210 cell is Python, but other languages, such as ``Julia`` and ``R``, can be
211 handled using :ref:`cell magic commands <magics_explained>`.
212
213 When a code cell is executed, code that it contains is sent to the kernel
214 associated with the notebook. The results that are returned from this
215 computation are then displayed in the notebook as the cell's *output*. The
216 output is not limited to text, with many other possible forms of output are
217 also possible, including ``matplotlib`` figures and HTML tables (as used, for
218 example, in the ``pandas`` data analysis package). This is known as IPython's
246 219 *rich display* capability.
247 220
221 .. seealso::
222
223 `Basic Output`_ example notebook
224
225 `Rich Display System`_ example notebook
248 226
249 227 Markdown cells
250 ^^^^^^^^^^^^^^
228 ~~~~~~~~~~~~~~
251 229 You can document the computational process in a literate way, alternating
252 230 descriptive text with code, using *rich text*. In IPython this is accomplished
253 231 by marking up text with the Markdown language. The corresponding cells are
254 called *Markdown input cells*. The Markdown language provides a simple way to
232 called *Markdown cells*. The Markdown language provides a simple way to
255 233 perform this text markup, that is, to specify which parts of the text should
256 234 be emphasized (italics), bold, form lists, etc.
257 235
258 236
259 When a Markdown input cell is executed, the Markdown code is converted into
260 the corresponding formatted rich text. This output then *replaces* the
261 original Markdown input cell, leaving just the visually-significant marked up
262 rich text. Markdown allows arbitrary HTML code for formatting.
237 When a Markdown cell is executed, the Markdown code is converted into
238 the corresponding formatted rich text. Markdown allows arbitrary HTML code for
239 formatting.
263 240
264 241 Within Markdown cells, you can also include *mathematics* in a straightforward
265 242 way, using standard LaTeX notation: ``$...$`` for inline mathematics and
@@ -276,17 +253,21 b' Standard mathematics environments defined by LaTeX and AMS-LaTeX (the'
276 253 New LaTeX macros may be defined using standard methods,
277 254 such as ``\newcommand``, by placing them anywhere *between math delimiters* in
278 255 a Markdown cell. These definitions are then available throughout the rest of
279 the IPython session. (Note, however, that more care must be taken when using
280 nbconvert_ to output to LaTeX).
256 the IPython session.
257
258 .. seealso::
281 259
282 Raw input cells
283 ~~~~~~~~~~~~~~~
260 `Markdown Cells`_ example notebook
284 261
285 *Raw* input cells provide a place in which you can write *output* directly.
286 Raw cells are not evaluated by the Notebook, and have no output.
287 When passed through nbconvert, Raw cells arrive in the destination format unmodified,
288 allowing you to type full latex into a raw cell, which will only be rendered
289 by latex after conversion by nbconvert.
262 Raw cells
263 ~~~~~~~~~
264
265 *Raw* cells provide a place in which you can write *output* directly.
266 Raw cells are not evaluated by the notebook.
267 When passed through :ref:`nbconvert <nbconvert>`, raw cells arrive in the
268 destination format unmodified. For example, this allows you to type full LaTeX
269 into a raw cell, which will only be rendered by LaTeX after conversion by
270 nbconvert.
290 271
291 272 Heading cells
292 273 ~~~~~~~~~~~~~
@@ -294,10 +275,9 b' Heading cells'
294 275 You can provide a conceptual structure for your computational document as a
295 276 whole using different levels of headings; there are 6 levels available, from
296 277 level 1 (top level) down to level 6 (paragraph). These can be used later for
297 constructing tables of contents, etc.
298
299 As with Markdown cells, a heading input cell is replaced by a rich text
300 rendering of the heading when the cell is executed.
278 constructing tables of contents, etc. As with Markdown cells, a heading
279 cell is replaced by a rich text rendering of the heading when the cell is
280 executed.
301 281
302 282
303 283 Basic workflow
@@ -306,42 +286,36 b' Basic workflow'
306 286 The normal workflow in a notebook is, then, quite similar to a standard
307 287 IPython session, with the difference that you can edit cells in-place multiple
308 288 times until you obtain the desired results, rather than having to
309 rerun separate scripts with the ``%run`` magic command. (Magic commands do,
310 however, also work in the notebook; see below).
289 rerun separate scripts with the ``%run`` magic command.
290
311 291
312 292 Typically, you will work on a computational problem in pieces, organizing
313 293 related ideas into cells and moving forward once previous parts work
314 294 correctly. This is much more convenient for interactive exploration than
315 295 breaking up a computation into scripts that must be executed together, as was
316 previously necessary, especially if parts of them take a long time to run
296 previously necessary, especially if parts of them take a long time to run.
317 297
318 298 At certain moments, it may be necessary to interrupt a calculation which is
319 taking too long to complete. This may be done with the ``Kernel | Interrupt``
320 menu option, or the :kbd:``Ctrl-i`` keyboard shortcut.
299 taking too long to complete. This may be done with the `Kernel | Interrupt`
300 menu option, or the :kbd:`Ctrl-m i` keyboard shortcut.
321 301 Similarly, it may be necessary or desirable to restart the whole computational
322 process, with the ``Kernel | Restart`` menu option or :kbd:``Ctrl-.``
323 shortcut. This gives an equivalent state to loading the notebook document
324 afresh.
302 process, with the `Kernel | Restart` menu option or :kbd:`Ctrl-m .`
303 shortcut.
325 304
326 A notebook may be downloaded in either ``.ipynb`` or raw ``.py`` form from the
327 menu option ``File | Download as``. Choosing the ``.py`` option downloads a
328 Python ``.py`` script, in which all output has been removed and the content of
329 Markdown cells in comment areas. See ref:`below <notebook_format>` for more
330 details on the notebook format.
305 A notebook may be downloaded in either a ``.ipynb`` or ``.py`` file from the
306 menu option `File | Download as`. Choosing the ``.py`` option downloads a
307 Python ``.py`` script, in which all rich output has been removed and the
308 content of markdown cells have been inserted as comments.
331 309
332 .. warning::
310 .. seealso::
333 311
334 While in simple cases you can "roundtrip" a notebook to Python, edit the
335 Python file, and then import it back without loss of main content, this is
336 in general *not guaranteed to work*. First, there is extra metadata
337 saved in the notebook that may not be saved to the ``.py`` format. And as
338 the notebook format evolves in complexity, there will be attributes of the
339 notebook that will not survive a roundtrip through the Python form. You
340 should think of the Python format as a way to output a script version of a
341 notebook and the import capabilities as a way to load existing code to get
342 a notebook started. But the Python version is *not* an alternate notebook
343 format.
312 `Running Code in the IPython Notebook`_ example notebook
313
314 `Basic Output`_ example notebook
344 315
316 :ref:`a warning about doing "roundtrip" conversions <note_about_roundtrip>`.
317
318 .. _keyboard-shortcuts:
345 319
346 320 Keyboard shortcuts
347 321 ~~~~~~~~~~~~~~~~~~
@@ -351,10 +325,10 b' to remember are the following:'
351 325
352 326 * :kbd:`Shift-Enter`: run cell
353 327 Execute the current cell, show output (if any), and jump to the next cell
354 below. If :kbd:`Shift-Enter` is invoked on the last input cell, a new code
328 below. If :kbd:`Shift-Enter` is invoked on the last cell, a new code
355 329 cell will also be created. Note that in the notebook, typing :kbd:`Enter`
356 330 on its own *never* forces execution, but rather just inserts a new line in
357 the current input cell. :kbd:`Shift-Enter` is equivalent to clicking the
331 the current cell. :kbd:`Shift-Enter` is equivalent to clicking the
358 332 ``Cell | Run`` menu item.
359 333
360 334 * :kbd:`Ctrl-Enter`: run cell in-place
@@ -367,7 +341,7 b' to remember are the following:'
367 341 to be saved in the notebook.
368 342
369 343 * :kbd:`Alt-Enter`: run cell, insert below
370 Executes the current cell, shows the output, and inserts a *new* input
344 Executes the current cell, shows the output, and inserts a *new*
371 345 cell between the current cell and the cell below (if one exists). This
372 346 is thus a shortcut for the sequence :kbd:`Shift-Enter`, :kbd:`Ctrl-m a`.
373 347 (:kbd:`Ctrl-m a` adds a new cell above the current one.)
@@ -419,96 +393,19 b' Ctrl-m h show keyboard shortcuts'
419 393
420 394
421 395
422 Magic commands
423 --------------
424 Magic commands, or *magics*, are commands for controlling IPython itself.
425 They all begin with ``%`` and are entered into code input cells; the code
426 cells are executed as usual with :kbd:`Shift-Enter`.
427
428 The magic commands call special functions defined by IPython which manipulate
429 the computational state in certain ways.
430
431 There are two types of magics:
432
433 - **line magics**:
434
435 These begin with a single ``%`` and take as arguments the rest of the
436 *same line* of the code cell. Any other lines of the code cell are
437 treated as if they were part of a standard code cell.
438
439 - **cell magics**:
440
441 These begin with ``%%`` and operate on the *entire* remaining contents
442 of the code cell.
443
444 Line magics
445 ~~~~~~~~~~~
446 Some of the available line magics are the following:
447
448 * ``%load filename``:
449
450 Loads the contents of the file ``filename`` into a new code cell. This
451 can be a URL for a remote file.
452
453 * ``%timeit code``:
454
455 An easy way to time how long the single line of code ``code`` takes to
456 run
457
458 * ``%config``:
459
460 Configuration of the IPython Notebook
461
462 * ``%lsmagic``:
463
464 Provides a list of all available magic commands
465
466 Cell magics
467 ~~~~~~~~~~~
468
469 * ``%%latex``:
470
471 Renders the entire contents of the cell in LaTeX, without needing to use
472 explicit LaTeX delimiters.
473
474 * ``%%bash``:
475
476 The code cell is executed by sending it to be executed by ``bash``. The
477 output of the ``bash`` commands is captured and displayed in the
478 notebook.
479
480 * ``%%file filename``:
481
482 Writes the contents of the cell to the file ``filename``.
483 **Caution**: The file is over-written without warning!
484
485 * ``%%R``:
486
487 Execute the contents of the cell using the R language.
488
489 * ``%%timeit``:
490
491 Version of ``%timeit`` which times the entire block of code in the
492 current code cell.
493
494
495
496 Several of the cell magics provide functionality to manipulate the filesystem
497 of a remote server to which you otherwise do not have access.
498 396
499 397
500 398 Plotting
501 399 --------
502 One major feature of the Notebook is the ability to interact with
503 plots that are the output of running code cells. IPython is designed to work
504 seamlessly with the ``matplotlib`` plotting library to provide this
505 functionality.
400 One major feature of the notebook is the ability to display plots that are the
401 output of running code cells. IPython is designed to work seamlessly with the
402 matplotlib_ plotting library to provide this functionality.
506 403
507 404 To set this up, before any plotting is performed you must execute the
508 ``%matplotlib`` magic command. This performs the necessary behind-the-scenes
509 setup for IPython to work correctly hand in hand with ``matplotlib``; it does
510 *not*, however, actually execute any Python ``import`` commands, that is, no
511 names are added to the namespace.
405 ``%matplotlib`` :ref:`magic command <magics_explained>`. This performs the
406 necessary behind-the-scenes setup for IPython to work correctly hand in hand
407 with ``matplotlib``; it does *not*, however, actually execute any Python
408 ``import`` commands, that is, no names are added to the namespace.
512 409
513 410 If the ``%matplotlib`` magic is called without an argument, the
514 411 output of a plotting command is displayed using the default ``matplotlib``
@@ -517,25 +414,24 b' requested using, for example::'
517 414
518 415 %matplotlib gtk
519 416
520 A particularly interesting backend is the ``inline`` backend.
521 This is applicable only for the IPython Notebook and the IPython QtConsole.
522 It can be invoked as follows::
417 A particularly interesting backend, provided by IPython, is the ``inline``
418 backend. This is available only for the IPython Notebook and the
419 :ref:`IPython QtConsole <qtconsole>`. It can be invoked as follows::
523 420
524 421 %matplotlib inline
525 422
526 With this backend, output of plotting commands is displayed *inline* within
527 the notebook format, directly below the input cell that produced it. The
528 resulting plots will then also be stored in the notebook document. This
529 provides a key part of the functionality for reproducibility_ that the IPython
530 Notebook provides.
423 With this backend, the output of plotting commands is displayed *inline*
424 within the notebook, directly below the code cell that produced it. The
425 resulting plots will then also be stored in the notebook document.
531 426
532 .. _reproducibility: https://en.wikipedia.org/wiki/Reproducibility
427 .. seealso::
533 428
429 `Plotting with Matplotlib`_ example notebook
534 430
535 431
536 432 Configuring the IPython Notebook
537 433 --------------------------------
538 The IPython Notebook can be run with a variety of command line arguments.
434 The notebook server can be run with a variety of command line arguments.
539 435 To see a list of available options enter::
540 436
541 437 $ ipython notebook --help
@@ -555,12 +451,16 b' on available options, use::'
555 451 .. seealso::
556 452
557 453 :ref:`config_overview`, in particular :ref:`Profiles`.
454
455 :ref:`notebook_security`
456
457 :ref:`notebook_public_server`
558 458
559 459
560 460 Importing ``.py`` files
561 461 -----------------------
562 462
563 ``.py`` files will be imported into the IPython Notebook as a notebook with
463 ``.py`` files will be imported as a notebook with
564 464 the same basename, but an ``.ipynb`` extension, located in the notebook
565 465 directory. The notebook created will have just one cell, which will contain
566 466 all the code in the ``.py`` file. You can later manually partition this into
@@ -569,18 +469,18 b' individual cells using the ``Edit | Split Cell`` menu option, or the'
569 469
570 470 Note that ``.py`` scripts obtained from a notebook document using nbconvert_
571 471 maintain the structure of the notebook in comments. Reimporting such a
572 script back into the Notebook will preserve this structxure.
472 script back into a notebook will preserve this structure.
573 473
474 .. _note_about_roundtrip:
574 475
575 476 .. warning::
576 477
577 You can "roundtrip" a notebook to Python, by exporting the
578 notebook to a ``.py`` script, editing the script, and then importing it back
579 into the Notebook without loss of main content. However,
580 in general this is *not guaranteed* to work. First, there is extra metadata
581 saved in the notebook that may not be saved to the ``.py`` format. Second,
582 as the notebook format evolves in complexity, there will be attributes of
583 the notebook that will not survive a roundtrip through the Python form. You
478 While in simple cases you can "roundtrip" a notebook to Python, edit the
479 Python file, and then import it back without loss of main content, this is
480 in general *not guaranteed to work*. First, there is extra metadata
481 saved in the notebook that may not be saved to the ``.py`` format. And as
482 the notebook format evolves in complexity, there will be attributes of the
483 notebook that will not survive a roundtrip through the Python form. You
584 484 should think of the Python format as a way to output a script version of a
585 485 notebook and the import capabilities as a way to load existing code to get
586 486 a notebook started. But the Python version is *not* an alternate notebook
@@ -588,3 +488,5 b' script back into the Notebook will preserve this structxure.'
588 488
589 489 .. seealso::
590 490 :ref:`notebook_format`
491
492 .. include:: ../links.txt
Show file before | Show file after | Hide comments
@@ -1,13 +1,16 b''
1 1 .. _working_remotely.txt
2 2
3 Working remotely
4 ================
3 Running a notebook server
4 =========================
5 5
6 6
7 The IPython Notebook web app is based on a server-client structure.
8 This server uses a two-process kernel architecture based on ZeroMQ_, as well
9 as Tornado_ for serving HTTP requests. Other clients may connect to the same
10 underlying IPython kernel; see below.
7 The :ref:`IPython notebook <htmlnotebook>` web-application is based on a
8 server-client structure. This server uses a :ref:`two-process kernel
9 architecture <ipythonzmq>` based on ZeroMQ_, as well as Tornado_ for serving
10 HTTP requests. By default, a notebook server runs on http://127.0.0.1:8888/
11 and is accessible only from `localhost`. This document describes how you can
12 :ref:`secure a notebook server <notebook_security>` and how to :ref:`run it on
13 a public interface <notebook_public_server>`.
11 14
12 15 .. _ZeroMQ: http://zeromq.org
13 16
@@ -16,10 +19,10 b' underlying IPython kernel; see below.'
16 19
17 20 .. _notebook_security:
18 21
19 Security
20 --------
22 Notebook security
23 -----------------
21 24
22 You can protect your Notebook server with a simple single password by
25 You can protect your notebook server with a simple single password by
23 26 setting the :attr:`NotebookApp.password` configurable. You can prepare a
24 27 hashed password using the function :func:`IPython.lib.security.passwd`:
25 28
@@ -65,8 +68,7 b' self-signed. If you want to have a fully compliant certificate that will not'
65 68 raise warnings, it is possible (but rather involved) to obtain one,
66 69 as explained in detail in `this tutorial`__.
67 70
68 .. __: http://arstechnica.com/security/news/2009/12/how-to-get-set-with-a-
69 secure-sertificate-for-free.ars
71 .. __: http://arstechnica.com/security/news/2009/12/how-to-get-set-with-a-secure-sertificate-for-free.ars
70 72
71 73 Keep in mind that when you enable SSL support, you will need to access the
72 74 notebook server over ``https://``, not over plain ``http://``. The startup
@@ -74,32 +76,7 b' message from the server prints this, but it is easy to overlook and think the'
74 76 server is for some reason non-responsive.
75 77
76 78
77 Connecting to an existing kernel
78 ---------------------------------
79
80 The notebook server always prints to the terminal the full details of
81 how to connect to each kernel, with messages such as the following::
82
83 [IPKernelApp] To connect another client to this kernel, use:
84 [IPKernelApp] --existing kernel-3bb93edd-6b5a-455c-99c8-3b658f45dde5.json
85
86 This long string is the name of a JSON file that contains all the port and
87 validation information necessary to connect to the kernel. You can then, for
88 example, manually start a Qt console connected to the *same* kernel with::
89
90 $ ipython qtconsole --existing
91 kernel-3bb93edd-6b5a-455c-99c8-3b658f45dde5.json
92
93 If you have only a single kernel running, simply typing::
94
95 $ ipython qtconsole --existing
96
97 will automatically find it. (It will always find the most recently
98 started kernel if there is more than one.) You can also request this
99 connection data by typing ``%connect_info``; this will print the same
100 file information as well as the content of the JSON data structure it
101 contains.
102
79 .. _notebook_public_server:
103 80
104 81 Running a public notebook server
105 82 --------------------------------
@@ -152,8 +129,8 b' modifying ``ipython_notebook_config.py``)::'
152 129 Using a different notebook store
153 130 --------------------------------
154 131
155 By default, the Notebook app stores the notebook documents that it saves as
156 files in the working directory of the Notebook app, also known as the
132 By default, the notebook server stores the notebook documents that it saves as
133 files in the working directory of the notebook server, also known as the
157 134 ``notebook_dir``. This logic is implemented in the
158 135 :class:`FileNotebookManager` class. However, the server can be configured to
159 136 use a different notebook manager class, which can
@@ -178,9 +155,9 b' Known issues'
178 155 ------------
179 156
180 157 When behind a proxy, especially if your system or browser is set to autodetect
181 the proxy, the Notebook app might fail to connect to the server's websockets,
182 and present you with a warning at startup. In this case, you need to configure
183 your system not to use the proxy for the server's address.
158 the proxy, the notebook web application might fail to connect to the server's
159 websockets, and present you with a warning at startup. In this case, you need
160 to configure your system not to use the proxy for the server's address.
184 161
185 162 For example, in Firefox, go to the Preferences panel, Advanced section,
186 163 Network tab, click 'Settings...', and add the address of the notebook server
Show file before | Show file after | Hide comments
@@ -8,12 +8,27 b" You don't need to know anything beyond Python to start using IPython \xe2\x80\x93 just ty"
8 8 commands as you would at the standard Python prompt. But IPython can do much
9 9 more than the standard prompt. Some key features are described here. For more
10 10 information, check the :ref:`tips page <tips>`, or look at examples in the
11 `IPython cookbook <http://wiki.ipython.org/index.php?title=Cookbook>`_.
11 `IPython cookbook <https://github.com/ipython/ipython/wiki/Cookbook%3A-Index>`_.
12 12
13 13 If you've never used Python before, you might want to look at `the official
14 14 tutorial <http://docs.python.org/tutorial/>`_ or an alternative, `Dive into
15 15 Python <http://diveintopython.org/toc/index.html>`_.
16 16
17 The four most helpful commands
18 ===============================
19
20 The four most helpful commands, as well as their brief description, is shown
21 to you in a banner, every time you start IPython:
22
23 ========== =========================================================
24 command description
25 ========== =========================================================
26 ? Introduction and overview of IPython's features.
27 %quickref Quick reference.
28 help Python's own help system.
29 object? Details about 'object', use 'object??' for extra details.
30 ========== =========================================================
31
17 32 Tab completion
18 33 ==============
19 34
@@ -31,16 +46,19 b' including docstrings, function definition lines (for call arguments) and'
31 46 constructor details for classes. To get specific information on an object, you
32 47 can use the magic commands ``%pdoc``, ``%pdef``, ``%psource`` and ``%pfile``
33 48
49 .. _magics_explained:
50
34 51 Magic functions
35 52 ===============
36 53
37 54 IPython has a set of predefined 'magic functions' that you can call with a
38 55 command line style syntax. There are two kinds of magics, line-oriented and
39 cell-oriented. Line magics are prefixed with the ``%`` character and work much
56 cell-oriented. **Line magics** are prefixed with the ``%`` character and work much
40 57 like OS command-line calls: they get as an argument the rest of the line, where
41 arguments are passed without parentheses or quotes. Cell magics are prefixed
42 with a double ``%%``, and they are functions that get as an argument not only
43 the rest of the line, but also the lines below it in a separate argument.
58 arguments are passed without parentheses or quotes. **Cell magics** are
59 prefixed with a double ``%%``, and they are functions that get as an argument
60 not only the rest of the line, but also the lines below it in a separate
61 argument.
44 62
45 63 The following examples show how to call the builtin ``timeit`` magic, both in
46 64 line and cell mode::
@@ -58,34 +76,41 b' The builtin magics include:'
58 76 - Functions that work with code: ``%run``, ``%edit``, ``%save``, ``%macro``,
59 77 ``%recall``, etc.
60 78 - Functions which affect the shell: ``%colors``, ``%xmode``, ``%autoindent``,
61 etc.
62 - Other functions such as ``%reset``, ``%timeit`` or ``%paste``.
79 ``%automagic``, etc.
80 - Other functions such as ``%reset``, ``%timeit``, ``%%file``, ``%load``, or
81 ``%paste``.
63 82
64 You can always call them using the % prefix, and if you're calling a line magic
65 on a line by itself, you can omit even that (cell magics must always have the
66 ``%%`` prefix)::
83 You can always call them using the ``%`` prefix, and if you're calling a line
84 magic on a line by itself, you can omit even that::
67 85
68 86 run thescript.py
69 87
88 You can toggle this behavior by running the ``%automagic`` magic. Cell magics
89 must always have the ``%%`` prefix.
90
70 91 A more detailed explanation of the magic system can be obtained by calling
71 92 ``%magic``, and for more details on any magic function, call ``%somemagic?`` to
72 93 read its docstring. To see all the available magic functions, call
73 94 ``%lsmagic``.
74 95
96 .. seealso::
97
98 `Cell magics`_ example notebook
99
75 100 Running and Editing
76 101 -------------------
77 102
78 The %run magic command allows you to run any python script and load all of its
79 data directly into the interactive namespace. Since the file is re-read from
80 disk each time, changes you make to it are reflected immediately (unlike
81 imported modules, which have to be specifically reloaded). IPython also includes
82 :ref:`dreload <dreload>`, a recursive reload function.
103 The ``%run`` magic command allows you to run any python script and load all of
104 its data directly into the interactive namespace. Since the file is re-read
105 from disk each time, changes you make to it are reflected immediately (unlike
106 imported modules, which have to be specifically reloaded). IPython also
107 includes :ref:`dreload <dreload>`, a recursive reload function.
83 108
84 %run has special flags for timing the execution of your scripts (-t), or for
85 running them under the control of either Python's pdb debugger (-d) or
109 ``%run`` has special flags for timing the execution of your scripts (-t), or
110 for running them under the control of either Python's pdb debugger (-d) or
86 111 profiler (-p).
87 112
88 The %edit command gives a reasonable approximation of multiline editing,
113 The ``%edit`` command gives a reasonable approximation of multiline editing,
89 114 by invoking your favorite editor on the spot. IPython will execute the
90 115 code you type in there as if it were typed interactively.
91 116
@@ -153,11 +178,12 b' visited directories and allows you to go to any previously visited one.'
153 178 Configuration
154 179 =============
155 180
156 Much of IPython can be tweaked through configuration. To get started, use the
157 command ``ipython profile create`` to produce the default config files. These
158 will be placed in :file:`~/.ipython/profile_default` or
159 :file:`~/.config/ipython/profile_default`, and contain comments explaining what
160 the various options do.
181 Much of IPython can be tweaked through :ref:`configuration <config_overview>`.
182 To get started, use the command ``ipython profile create`` to produce the
183 default config files. These will be placed in
184 :file:`~/.ipython/profile_default` or
185 :file:`~/.config/ipython/profile_default`, and contain comments explaining
186 what the various options do.
161 187
162 188 Profiles allow you to use IPython for different tasks, keeping separate config
163 189 files and history for each one. More details in :ref:`the profiles section
@@ -173,7 +199,4 b' as the IPython shell is constructed, before any other code or scripts you have'
173 199 specified. The files will be run in order of their names, so you can control the
174 200 ordering with prefixes, like ``10-myimports.py``.
175 201
176 .. note::
177
178 Automatic startup files are new in IPython 0.12. Use InteractiveShellApp.exec_files
179 in :file:`ipython_config.py` for similar behavior in 0.11.
202 .. include:: ../links.txt
Show file before | Show file after | Hide comments
@@ -23,6 +23,7 b''
23 23 .. _ipython_github_repo: http://github.com/ipython/ipython/
24 24 .. _ipython_downloads: http://ipython.org/download.html
25 25 .. _ipython_pypi: http://pypi.python.org/pypi/ipython
26 .. _nbviewer: http://nbviewer.ipython.org
26 27
27 28 .. _ZeroMQ: http://zeromq.org
28 29
@@ -46,7 +47,7 b''
46 47 .. _numpy: http://numpy.scipy.org
47 48 .. _scipy: http://www.scipy.org
48 49 .. _scipy_conference: http://conference.scipy.org
49 .. _matplotlib: http://matplotlib.sourceforge.net
50 .. _matplotlib: http://matplotlib.org
50 51 .. _pythonxy: http://www.pythonxy.com
51 52 .. _ETS: http://code.enthought.com/projects/tool-suite.php
52 53 .. _EPD: http://www.enthought.com/products/epd.php
@@ -72,4 +73,29 b''
72 73 .. _indefero: http://www.indefero.net
73 74 .. _git: http://git-scm.com
74 75 .. _github: http://github.com
75 .. _MarkDown: http://daringfireball.net/projects/markdown/
76 .. _Markdown: http://daringfireball.net/projects/markdown/syntax
77
78 .. _Running Code in the IPython Notebook: notebook_p1_
79 .. _notebook_p1: http://nbviewer.ipython.org/urls/raw.github.com/ipython/ipython/1.x/examples/notebooks/Part%25201%2520-%2520Running%2520Code.ipynb
80
81 .. _Basic Output: notebook_p2_
82 .. _notebook_p2: http://nbviewer.ipython.org/urls/raw.github.com/ipython/ipython/1.x/examples/notebooks/Part%202%20-%20Basic%20Output.ipynb
83
84 .. _Plotting with Matplotlib: notebook_p3_
85 .. _notebook_p3: http://nbviewer.ipython.org/urls/raw.github.com/ipython/ipython/1.x/examples/notebooks/Part%203%20-%20Plotting%20with%20Matplotlib.ipynb
86
87 .. _Markdown Cells: notebook_p4
88 .. _notebook_p4: http://nbviewer.ipython.org/urls/raw.github.com/ipython/ipython/1.x/examples/notebooks/Part%204%20-%20Markdown%20Cells.ipynb
89
90 .. _Rich Display System: notebook_p5_
91 .. _notebook_p5: http://nbviewer.ipython.org/urls/raw.github.com/ipython/ipython/1.x/examples/notebooks/Part%205%20-%20Rich%20Display%20System.ipynb
92
93 .. _notebook_custom_display: http://nbviewer.ipython.org/urls/raw.github.com/ipython/ipython/1.x/examples/notebooks/Custom%20Display%20Logic.ipynb
94
95 .. _Frontend/Kernel Model: notebook_two_proc_
96 .. _notebook_two_proc: http://nbviewer.ipython.org/urls/raw.github.com/ipython/ipython/1.x/examples/notebooks/Frontend-Kernel%20Model.ipynb
97
98 .. _Cell magics: notebook_cell_magics_
99 .. _notebook_cell_magics: http://nbviewer.ipython.org/urls/raw.github.com/ipython/ipython/1.x/examples/notebooks/Cell%20Magics.ipynb
100
101
Show file before | Show file after | Hide comments
@@ -18,9 +18,9 b' interactive and exploratory computing. To support this goal, IPython'
18 18 has three main components:
19 19
20 20 * An enhanced interactive Python shell.
21 * A decoupled two-process communication model, which allows for multiple
22 clients to connect to a computation kernel, most notably the web-based
23 :ref:`notebook <htmlnotebook>`
21 * A decoupled :ref:`two-process communication model <ipythonzmq>`, which
22 allows for multiple clients to connect to a computation kernel, most notably
23 the web-based :ref:`notebook <htmlnotebook>`
24 24 * An architecture for interactive parallel computing.
25 25
26 26 All of IPython is open source (released under the revised BSD license).
@@ -197,7 +197,7 b' Decoupled two-process model'
197 197
198 198 IPython has abstracted and extended the notion of a traditional
199 199 *Read-Evaluate-Print Loop* (REPL) environment by decoupling the *evaluation*
200 into its own process. We call this process a kernel: it receives execution
200 into its own process. We call this process a **kernel**: it receives execution
201 201 instructions from clients and communicates the results back to them.
202 202
203 203 This decoupling allows us to have several clients connected to the same
@@ -222,6 +222,10 b' You can read more about using :ref:`ipython qtconsole <qtconsole>`, and'
222 222 <messaging>` which documents the protocol for communication between kernels
223 223 and clients.
224 224
225 .. seealso::
226
227 `Frontend/Kernel Model`_ example notebook
228
225 229
226 230 Interactive parallel computing
227 231 ==============================
@@ -283,3 +287,4 b' IPython is known to work on the following operating systems:'
283 287
284 288 See :ref:`here <install_index>` for instructions on how to install IPython.
285 289
290 .. include:: links.txt
General Comments 0
You need to be logged in to leave comments. Login now