##// END OF EJS Templates
Update the main documentation with new magics API....
Fernando Perez -
Show More
@@ -1,1005 +1,1150 b''
1 =================
1 =================
2 IPython reference
2 IPython reference
3 =================
3 =================
4
4
5 .. _command_line_options:
5 .. _command_line_options:
6
6
7 Command-line usage
7 Command-line usage
8 ==================
8 ==================
9
9
10 You start IPython with the command::
10 You start IPython with the command::
11
11
12 $ ipython [options] files
12 $ ipython [options] files
13
13
14 .. note::
14 .. note::
15
15
16 For IPython on Python 3, use ``ipython3`` in place of ``ipython``.
16 For IPython on Python 3, use ``ipython3`` in place of ``ipython``.
17
17
18 If invoked with no options, it executes all the files listed in sequence
18 If invoked with no options, it executes all the files listed in sequence
19 and drops you into the interpreter while still acknowledging any options
19 and drops you into the interpreter while still acknowledging any options
20 you may have set in your ipython_config.py. This behavior is different from
20 you may have set in your ipython_config.py. This behavior is different from
21 standard Python, which when called as python -i will only execute one
21 standard Python, which when called as python -i will only execute one
22 file and ignore your configuration setup.
22 file and ignore your configuration setup.
23
23
24 Please note that some of the configuration options are not available at
24 Please note that some of the configuration options are not available at
25 the command line, simply because they are not practical here. Look into
25 the command line, simply because they are not practical here. Look into
26 your configuration files for details on those. There are separate configuration
26 your configuration files for details on those. There are separate configuration
27 files for each profile, and the files look like "ipython_config.py" or
27 files for each profile, and the files look like "ipython_config.py" or
28 "ipython_config_<frontendname>.py". Profile directories look like
28 "ipython_config_<frontendname>.py". Profile directories look like
29 "profile_profilename" and are typically installed in the IPYTHONDIR directory.
29 "profile_profilename" and are typically installed in the IPYTHONDIR directory.
30 For Linux users, this will be $HOME/.config/ipython, and for other users it
30 For Linux users, this will be $HOME/.config/ipython, and for other users it
31 will be $HOME/.ipython. For Windows users, $HOME resolves to C:\\Documents and
31 will be $HOME/.ipython. For Windows users, $HOME resolves to C:\\Documents and
32 Settings\\YourUserName in most instances.
32 Settings\\YourUserName in most instances.
33
33
34
34
35 Eventloop integration
35 Eventloop integration
36 ---------------------
36 ---------------------
37
37
38 Previously IPython had command line options for controlling GUI event loop
38 Previously IPython had command line options for controlling GUI event loop
39 integration (-gthread, -qthread, -q4thread, -wthread, -pylab). As of IPython
39 integration (-gthread, -qthread, -q4thread, -wthread, -pylab). As of IPython
40 version 0.11, these have been removed. Please see the new ``%gui``
40 version 0.11, these have been removed. Please see the new ``%gui``
41 magic command or :ref:`this section <gui_support>` for details on the new
41 magic command or :ref:`this section <gui_support>` for details on the new
42 interface, or specify the gui at the commandline::
42 interface, or specify the gui at the commandline::
43
43
44 $ ipython --gui=qt
44 $ ipython --gui=qt
45
45
46
46
47 Command-line Options
47 Command-line Options
48 --------------------
48 --------------------
49
49
50 To see the options IPython accepts, use ``ipython --help`` (and you probably
50 To see the options IPython accepts, use ``ipython --help`` (and you probably
51 should run the output through a pager such as ``ipython --help | less`` for
51 should run the output through a pager such as ``ipython --help | less`` for
52 more convenient reading). This shows all the options that have a single-word
52 more convenient reading). This shows all the options that have a single-word
53 alias to control them, but IPython lets you configure all of its objects from
53 alias to control them, but IPython lets you configure all of its objects from
54 the command-line by passing the full class name and a corresponding value; type
54 the command-line by passing the full class name and a corresponding value; type
55 ``ipython --help-all`` to see this full list. For example::
55 ``ipython --help-all`` to see this full list. For example::
56
56
57 ipython --pylab qt
57 ipython --pylab qt
58
58
59 is equivalent to::
59 is equivalent to::
60
60
61 ipython --TerminalIPythonApp.pylab='qt'
61 ipython --TerminalIPythonApp.pylab='qt'
62
62
63 Note that in the second form, you *must* use the equal sign, as the expression
63 Note that in the second form, you *must* use the equal sign, as the expression
64 is evaluated as an actual Python assignment. While in the above example the
64 is evaluated as an actual Python assignment. While in the above example the
65 short form is more convenient, only the most common options have a short form,
65 short form is more convenient, only the most common options have a short form,
66 while any configurable variable in IPython can be set at the command-line by
66 while any configurable variable in IPython can be set at the command-line by
67 using the long form. This long form is the same syntax used in the
67 using the long form. This long form is the same syntax used in the
68 configuration files, if you want to set these options permanently.
68 configuration files, if you want to set these options permanently.
69
69
70
70
71 Interactive use
71 Interactive use
72 ===============
72 ===============
73
73
74 IPython is meant to work as a drop-in replacement for the standard interactive
74 IPython is meant to work as a drop-in replacement for the standard interactive
75 interpreter. As such, any code which is valid python should execute normally
75 interpreter. As such, any code which is valid python should execute normally
76 under IPython (cases where this is not true should be reported as bugs). It
76 under IPython (cases where this is not true should be reported as bugs). It
77 does, however, offer many features which are not available at a standard python
77 does, however, offer many features which are not available at a standard python
78 prompt. What follows is a list of these.
78 prompt. What follows is a list of these.
79
79
80
80
81 Caution for Windows users
81 Caution for Windows users
82 -------------------------
82 -------------------------
83
83
84 Windows, unfortunately, uses the '\\' character as a path separator. This is a
84 Windows, unfortunately, uses the '\\' character as a path separator. This is a
85 terrible choice, because '\\' also represents the escape character in most
85 terrible choice, because '\\' also represents the escape character in most
86 modern programming languages, including Python. For this reason, using '/'
86 modern programming languages, including Python. For this reason, using '/'
87 character is recommended if you have problems with ``\``. However, in Windows
87 character is recommended if you have problems with ``\``. However, in Windows
88 commands '/' flags options, so you can not use it for the root directory. This
88 commands '/' flags options, so you can not use it for the root directory. This
89 means that paths beginning at the root must be typed in a contrived manner
89 means that paths beginning at the root must be typed in a contrived manner
90 like: ``%copy \opt/foo/bar.txt \tmp``
90 like: ``%copy \opt/foo/bar.txt \tmp``
91
91
92 .. _magic:
92 .. _magic:
93
93
94 Magic command system
94 Magic command system
95 --------------------
95 --------------------
96
96
97 IPython will treat any line whose first character is a % as a special
97 IPython will treat any line whose first character is a % as a special
98 call to a 'magic' function. These allow you to control the behavior of
98 call to a 'magic' function. These allow you to control the behavior of
99 IPython itself, plus a lot of system-type features. They are all
99 IPython itself, plus a lot of system-type features. They are all
100 prefixed with a % character, but parameters are given without
100 prefixed with a % character, but parameters are given without
101 parentheses or quotes.
101 parentheses or quotes.
102
102
103 Example: typing ``%cd mydir`` changes your working directory to 'mydir', if it
103 Lines that begin with ``%%`` signal a *cell magic*: they take as arguments not
104 exists.
104 only the rest of the current line, but all lines below them as well, in the
105
105 current execution block. Cell magics can in fact make arbitrary modifications
106 If you have 'automagic' enabled (as it by default), you don't need
106 to the input they receive, which need not even be valid Python code at all.
107 to type in the % explicitly. IPython will scan its internal list of
107 They receive the whole block as a single string.
108 magic functions and call one if it exists. With automagic on you can
108
109 then just type ``cd mydir`` to go to directory 'mydir'. The automagic
109 As a line magic example, the ``%cd`` magic works just like the OS command of
110 system has the lowest possible precedence in name searches, so defining
110 the same name::
111 an identifier with the same name as an existing magic function will
111
112 shadow it for automagic use. You can still access the shadowed magic
112 In [8]: %cd
113 function by explicitly using the % character at the beginning of the line.
113 /home/fperez
114
115 The following uses the builtin ``timeit`` in cell mode::
116
117 In [10]: %%timeit x = range(10000)
118 ...: min(x)
119 ...: max(x)
120 ...:
121 1000 loops, best of 3: 438 us per loop
122
123 In this case, ``x = range(10000)`` is called as the line argument, and the
124 block with ``min(x)`` and ``max(x)`` is called as the cell body. The
125 ``timeit`` magic receives both.
126
127 If you have 'automagic' enabled (as it by default), you don't need to type in
128 the single ``%`` explicitly for line magics; IPython will scan its internal
129 list of magic functions and call one if it exists. With automagic on you can
130 then just type ``cd mydir`` to go to directory 'mydir'::
131
132 In [9]: cd mydir
133 /home/fperez/mydir
134
135 Note that cell magics *always* require an explicit ``%%`` prefix, automagic
136 calling only works for line magics.
137
138 The automagic system has the lowest possible precedence in name searches, so
139 defining an identifier with the same name as an existing magic function will
140 shadow it for automagic use. You can still access the shadowed magic function
141 by explicitly using the ``%`` character at the beginning of the line.
114
142
115 An example (with automagic on) should clarify all this:
143 An example (with automagic on) should clarify all this:
116
144
117 .. sourcecode:: ipython
145 .. sourcecode:: ipython
118
146
119 In [1]: cd ipython # %cd is called by automagic
147 In [1]: cd ipython # %cd is called by automagic
120 /home/fperez/ipython
148 /home/fperez/ipython
121
149
122 In [2]: cd=1 # now cd is just a variable
150 In [2]: cd=1 # now cd is just a variable
123
151
124 In [3]: cd .. # and doesn't work as a function anymore
152 In [3]: cd .. # and doesn't work as a function anymore
125 File "<ipython-input-3-9fedb3aff56c>", line 1
153 File "<ipython-input-3-9fedb3aff56c>", line 1
126 cd ..
154 cd ..
127 ^
155 ^
128 SyntaxError: invalid syntax
156 SyntaxError: invalid syntax
129
157
130
158
131 In [4]: %cd .. # but %cd always works
159 In [4]: %cd .. # but %cd always works
132 /home/fperez
160 /home/fperez
133
161
134 In [5]: del cd # if you remove the cd variable, automagic works again
162 In [5]: del cd # if you remove the cd variable, automagic works again
135
163
136 In [6]: cd ipython
164 In [6]: cd ipython
137
165
138 /home/fperez/ipython
166 /home/fperez/ipython
139
167
140 You can define your own magic functions to extend the system. The
168 Defining your own magics
141 following example defines a new magic command, %impall:
169 ~~~~~~~~~~~~~~~~~~~~~~~~
170
171 There are two main ways to define your own magic functions: from standalone
172 functions and by inheriting from a base class provided by IPython:
173 :class:`IPython.core.magic.Magics`. Below we show code you can place in a file
174 that you load from your configuration, such as any file in the ``startup``
175 subdirectory of your default IPython profile.
176
177 First, let us see the simplest case. The following shows how to create a line
178 magic, a cell one and one that works in both modes, using just plain functions:
142
179
143 .. sourcecode:: python
180 .. sourcecode:: python
144
181
182 from IPython.core.magic import (register_line_magic, register_cell_magic,
183 register_line_cell_magic)
184
185 @register_line_magic
186 def lmagic(line):
187 "my line magic"
188 return line
189
190 @register_cell_magic
191 def cmagic(line, cell):
192 "my cell magic"
193 return line, cell
194
195 @register_line_cell_magic
196 def lcmagic(line, cell=None):
197 "Magic that works both as %lcmagic and as %%lcmagic"
198 if cell is None:
199 print "Called as line magic"
200 return line
201 else:
202 print "Called as cell magic"
203 return line, cell
204
205 # We delete these to avoid name conflicts for automagic to work
206 del lmagic, lcmagic
207
208
209 You can also create magics of all three kinds by inheriting from the
210 :class:`IPython.core.magic.Magics` class. This lets you create magics that can
211 potentially hold state in between calls, and that have full access to the main
212 IPython object:
213
214 .. sourcecode:: python
215
216 # This code can be put in any Python module, it does not require IPython
217 # itself to be running already. It only creates the magics subclass but
218 # doesn't instantiate it yet.
219 from IPython.core.magic import (Magics, magics_class, line_magic,
220 cell_magic, line_cell_magic)
221
222 # The class MUST call this class decorator at creation time
223 @magics_class
224 class MyMagics(Magics):
225
226 @line_magic
227 def lmagic(self, line):
228 "my line magic"
229 print "Full access to the main IPython object:", self.shell
230 print "Variables in the user namespace:", self.user_ns.keys()
231 return line
232
233 @cell_magic
234 def cmagic(self, line, cell):
235 "my cell magic"
236 return line, cell
237
238 @line_cell_magic
239 def lcmagic(self, line, cell=None):
240 "Magic that works both as %lcmagic and as %%lcmagic"
241 if cell is None:
242 print "Called as line magic"
243 return line
244 else:
245 print "Called as cell magic"
246 return line, cell
247
248
249 # In order to actually use these magics, you must register them with a
250 # running IPython. This code must be placed in a file that is loaded once
251 # IPython is up and running:
145 ip = get_ipython()
252 ip = get_ipython()
253 # You can register the class itself without instantiating it. IPython will
254 # call the default constructor on it.
255 ip.register_magics(MyMagics)
256
257 If you want to create a class with a different constructor that holds
258 additional state, then you should always call the parent constructor and
259 instantiate the class yourself before registration:
260
261 .. sourcecode:: python
262
263 @magics_class
264 class StatefulMagics(Magics):
265 "Magics that hold additional state"
266
267 def __init__(self, shell, data):
268 # You must call the parent constructor
269 super(StatefulMagics, self).__init__(shell)
270 self.data = data
146
271
147 def doimp(self, arg):
272 # etc...
148 ip = self.api
149 ip.ex("import %s; reload(%s); from %s import *" % (arg,arg,arg) )
150
273
151 ip.define_magic('impall', doimp)
274 # This class must then be registered with a manually created instance,
275 # since its constructor has different arguments from the default:
276 ip = get_ipython()
277 magics = StatefulMagics(ip, some_data)
278 ip.register_magics(magics)
279
280
281 In earlier versions, IPython had an API for the creation of line magics (cell
282 magics did not exist at the time) that required you to create functions with a
283 method-looking signature and to manually pass both the function and the name.
284 While this API is no longer recommended, it remains indefinitely supported for
285 backwards compatibility purposes. With the old API, you'd create a magic as
286 follows:
287
288 .. sourcecode:: python
289
290 def func(self, line):
291 print "Line magic called with line:", line
292 print "IPython object:", self.shell
293
294 ip = get_ipython()
295 # Declare this function as the magic %mycommand
296 ip.define_magic('mycommand', func)
152
297
153 Type ``%magic`` for more information, including a list of all available magic
298 Type ``%magic`` for more information, including a list of all available magic
154 functions at any time and their docstrings. You can also type
299 functions at any time and their docstrings. You can also type
155 ``%magic_function_name?`` (see :ref:`below <dynamic_object_info>` for information on
300 ``%magic_function_name?`` (see :ref:`below <dynamic_object_info>` for
156 the '?' system) to get information about any particular magic function you are
301 information on the '?' system) to get information about any particular magic
157 interested in.
302 function you are interested in.
158
303
159 The API documentation for the :mod:`IPython.core.magic` module contains the full
304 The API documentation for the :mod:`IPython.core.magic` module contains the full
160 docstrings of all currently available magic commands.
305 docstrings of all currently available magic commands.
161
306
162
307
163 Access to the standard Python help
308 Access to the standard Python help
164 ----------------------------------
309 ----------------------------------
165
310
166 Simply type ``help()`` to access Python's standard help system. You can
311 Simply type ``help()`` to access Python's standard help system. You can
167 also type ``help(object)`` for information about a given object, or
312 also type ``help(object)`` for information about a given object, or
168 ``help('keyword')`` for information on a keyword. You may need to configure your
313 ``help('keyword')`` for information on a keyword. You may need to configure your
169 PYTHONDOCS environment variable for this feature to work correctly.
314 PYTHONDOCS environment variable for this feature to work correctly.
170
315
171 .. _dynamic_object_info:
316 .. _dynamic_object_info:
172
317
173 Dynamic object information
318 Dynamic object information
174 --------------------------
319 --------------------------
175
320
176 Typing ``?word`` or ``word?`` prints detailed information about an object. If
321 Typing ``?word`` or ``word?`` prints detailed information about an object. If
177 certain strings in the object are too long (e.g. function signatures) they get
322 certain strings in the object are too long (e.g. function signatures) they get
178 snipped in the center for brevity. This system gives access variable types and
323 snipped in the center for brevity. This system gives access variable types and
179 values, docstrings, function prototypes and other useful information.
324 values, docstrings, function prototypes and other useful information.
180
325
181 If the information will not fit in the terminal, it is displayed in a pager
326 If the information will not fit in the terminal, it is displayed in a pager
182 (``less`` if available, otherwise a basic internal pager).
327 (``less`` if available, otherwise a basic internal pager).
183
328
184 Typing ``??word`` or ``word??`` gives access to the full information, including
329 Typing ``??word`` or ``word??`` gives access to the full information, including
185 the source code where possible. Long strings are not snipped.
330 the source code where possible. Long strings are not snipped.
186
331
187 The following magic functions are particularly useful for gathering
332 The following magic functions are particularly useful for gathering
188 information about your working environment. You can get more details by
333 information about your working environment. You can get more details by
189 typing ``%magic`` or querying them individually (``%function_name?``);
334 typing ``%magic`` or querying them individually (``%function_name?``);
190 this is just a summary:
335 this is just a summary:
191
336
192 * **%pdoc <object>**: Print (or run through a pager if too long) the
337 * **%pdoc <object>**: Print (or run through a pager if too long) the
193 docstring for an object. If the given object is a class, it will
338 docstring for an object. If the given object is a class, it will
194 print both the class and the constructor docstrings.
339 print both the class and the constructor docstrings.
195 * **%pdef <object>**: Print the definition header for any callable
340 * **%pdef <object>**: Print the definition header for any callable
196 object. If the object is a class, print the constructor information.
341 object. If the object is a class, print the constructor information.
197 * **%psource <object>**: Print (or run through a pager if too long)
342 * **%psource <object>**: Print (or run through a pager if too long)
198 the source code for an object.
343 the source code for an object.
199 * **%pfile <object>**: Show the entire source file where an object was
344 * **%pfile <object>**: Show the entire source file where an object was
200 defined via a pager, opening it at the line where the object
345 defined via a pager, opening it at the line where the object
201 definition begins.
346 definition begins.
202 * **%who/%whos**: These functions give information about identifiers
347 * **%who/%whos**: These functions give information about identifiers
203 you have defined interactively (not things you loaded or defined
348 you have defined interactively (not things you loaded or defined
204 in your configuration files). %who just prints a list of
349 in your configuration files). %who just prints a list of
205 identifiers and %whos prints a table with some basic details about
350 identifiers and %whos prints a table with some basic details about
206 each identifier.
351 each identifier.
207
352
208 Note that the dynamic object information functions (?/??, ``%pdoc``,
353 Note that the dynamic object information functions (?/??, ``%pdoc``,
209 ``%pfile``, ``%pdef``, ``%psource``) work on object attributes, as well as
354 ``%pfile``, ``%pdef``, ``%psource``) work on object attributes, as well as
210 directly on variables. For example, after doing ``import os``, you can use
355 directly on variables. For example, after doing ``import os``, you can use
211 ``os.path.abspath??``.
356 ``os.path.abspath??``.
212
357
213 .. _readline:
358 .. _readline:
214
359
215 Readline-based features
360 Readline-based features
216 -----------------------
361 -----------------------
217
362
218 These features require the GNU readline library, so they won't work if your
363 These features require the GNU readline library, so they won't work if your
219 Python installation lacks readline support. We will first describe the default
364 Python installation lacks readline support. We will first describe the default
220 behavior IPython uses, and then how to change it to suit your preferences.
365 behavior IPython uses, and then how to change it to suit your preferences.
221
366
222
367
223 Command line completion
368 Command line completion
224 +++++++++++++++++++++++
369 +++++++++++++++++++++++
225
370
226 At any time, hitting TAB will complete any available python commands or
371 At any time, hitting TAB will complete any available python commands or
227 variable names, and show you a list of the possible completions if
372 variable names, and show you a list of the possible completions if
228 there's no unambiguous one. It will also complete filenames in the
373 there's no unambiguous one. It will also complete filenames in the
229 current directory if no python names match what you've typed so far.
374 current directory if no python names match what you've typed so far.
230
375
231
376
232 Search command history
377 Search command history
233 ++++++++++++++++++++++
378 ++++++++++++++++++++++
234
379
235 IPython provides two ways for searching through previous input and thus
380 IPython provides two ways for searching through previous input and thus
236 reduce the need for repetitive typing:
381 reduce the need for repetitive typing:
237
382
238 1. Start typing, and then use Ctrl-p (previous,up) and Ctrl-n
383 1. Start typing, and then use Ctrl-p (previous,up) and Ctrl-n
239 (next,down) to search through only the history items that match
384 (next,down) to search through only the history items that match
240 what you've typed so far. If you use Ctrl-p/Ctrl-n at a blank
385 what you've typed so far. If you use Ctrl-p/Ctrl-n at a blank
241 prompt, they just behave like normal arrow keys.
386 prompt, they just behave like normal arrow keys.
242 2. Hit Ctrl-r: opens a search prompt. Begin typing and the system
387 2. Hit Ctrl-r: opens a search prompt. Begin typing and the system
243 searches your history for lines that contain what you've typed so
388 searches your history for lines that contain what you've typed so
244 far, completing as much as it can.
389 far, completing as much as it can.
245
390
246
391
247 Persistent command history across sessions
392 Persistent command history across sessions
248 ++++++++++++++++++++++++++++++++++++++++++
393 ++++++++++++++++++++++++++++++++++++++++++
249
394
250 IPython will save your input history when it leaves and reload it next
395 IPython will save your input history when it leaves and reload it next
251 time you restart it. By default, the history file is named
396 time you restart it. By default, the history file is named
252 $IPYTHONDIR/profile_<name>/history.sqlite. This allows you to keep
397 $IPYTHONDIR/profile_<name>/history.sqlite. This allows you to keep
253 separate histories related to various tasks: commands related to
398 separate histories related to various tasks: commands related to
254 numerical work will not be clobbered by a system shell history, for
399 numerical work will not be clobbered by a system shell history, for
255 example.
400 example.
256
401
257
402
258 Autoindent
403 Autoindent
259 ++++++++++
404 ++++++++++
260
405
261 IPython can recognize lines ending in ':' and indent the next line,
406 IPython can recognize lines ending in ':' and indent the next line,
262 while also un-indenting automatically after 'raise' or 'return'.
407 while also un-indenting automatically after 'raise' or 'return'.
263
408
264 This feature uses the readline library, so it will honor your
409 This feature uses the readline library, so it will honor your
265 :file:`~/.inputrc` configuration (or whatever file your INPUTRC variable points
410 :file:`~/.inputrc` configuration (or whatever file your INPUTRC variable points
266 to). Adding the following lines to your :file:`.inputrc` file can make
411 to). Adding the following lines to your :file:`.inputrc` file can make
267 indenting/unindenting more convenient (M-i indents, M-u unindents)::
412 indenting/unindenting more convenient (M-i indents, M-u unindents)::
268
413
269 $if Python
414 $if Python
270 "\M-i": " "
415 "\M-i": " "
271 "\M-u": "\d\d\d\d"
416 "\M-u": "\d\d\d\d"
272 $endif
417 $endif
273
418
274 Note that there are 4 spaces between the quote marks after "M-i" above.
419 Note that there are 4 spaces between the quote marks after "M-i" above.
275
420
276 .. warning::
421 .. warning::
277
422
278 Setting the above indents will cause problems with unicode text entry in
423 Setting the above indents will cause problems with unicode text entry in
279 the terminal.
424 the terminal.
280
425
281 .. warning::
426 .. warning::
282
427
283 Autoindent is ON by default, but it can cause problems with the pasting of
428 Autoindent is ON by default, but it can cause problems with the pasting of
284 multi-line indented code (the pasted code gets re-indented on each line). A
429 multi-line indented code (the pasted code gets re-indented on each line). A
285 magic function %autoindent allows you to toggle it on/off at runtime. You
430 magic function %autoindent allows you to toggle it on/off at runtime. You
286 can also disable it permanently on in your :file:`ipython_config.py` file
431 can also disable it permanently on in your :file:`ipython_config.py` file
287 (set TerminalInteractiveShell.autoindent=False).
432 (set TerminalInteractiveShell.autoindent=False).
288
433
289 If you want to paste multiple lines in the terminal, it is recommended that
434 If you want to paste multiple lines in the terminal, it is recommended that
290 you use ``%paste``.
435 you use ``%paste``.
291
436
292
437
293 Customizing readline behavior
438 Customizing readline behavior
294 +++++++++++++++++++++++++++++
439 +++++++++++++++++++++++++++++
295
440
296 All these features are based on the GNU readline library, which has an
441 All these features are based on the GNU readline library, which has an
297 extremely customizable interface. Normally, readline is configured via a
442 extremely customizable interface. Normally, readline is configured via a
298 file which defines the behavior of the library; the details of the
443 file which defines the behavior of the library; the details of the
299 syntax for this can be found in the readline documentation available
444 syntax for this can be found in the readline documentation available
300 with your system or on the Internet. IPython doesn't read this file (if
445 with your system or on the Internet. IPython doesn't read this file (if
301 it exists) directly, but it does support passing to readline valid
446 it exists) directly, but it does support passing to readline valid
302 options via a simple interface. In brief, you can customize readline by
447 options via a simple interface. In brief, you can customize readline by
303 setting the following options in your configuration file (note
448 setting the following options in your configuration file (note
304 that these options can not be specified at the command line):
449 that these options can not be specified at the command line):
305
450
306 * **readline_parse_and_bind**: this holds a list of strings to be executed
451 * **readline_parse_and_bind**: this holds a list of strings to be executed
307 via a readline.parse_and_bind() command. The syntax for valid commands
452 via a readline.parse_and_bind() command. The syntax for valid commands
308 of this kind can be found by reading the documentation for the GNU
453 of this kind can be found by reading the documentation for the GNU
309 readline library, as these commands are of the kind which readline
454 readline library, as these commands are of the kind which readline
310 accepts in its configuration file.
455 accepts in its configuration file.
311 * **readline_remove_delims**: a string of characters to be removed
456 * **readline_remove_delims**: a string of characters to be removed
312 from the default word-delimiters list used by readline, so that
457 from the default word-delimiters list used by readline, so that
313 completions may be performed on strings which contain them. Do not
458 completions may be performed on strings which contain them. Do not
314 change the default value unless you know what you're doing.
459 change the default value unless you know what you're doing.
315
460
316 You will find the default values in your configuration file.
461 You will find the default values in your configuration file.
317
462
318
463
319 Session logging and restoring
464 Session logging and restoring
320 -----------------------------
465 -----------------------------
321
466
322 You can log all input from a session either by starting IPython with the
467 You can log all input from a session either by starting IPython with the
323 command line switch ``--logfile=foo.py`` (see :ref:`here <command_line_options>`)
468 command line switch ``--logfile=foo.py`` (see :ref:`here <command_line_options>`)
324 or by activating the logging at any moment with the magic function %logstart.
469 or by activating the logging at any moment with the magic function %logstart.
325
470
326 Log files can later be reloaded by running them as scripts and IPython
471 Log files can later be reloaded by running them as scripts and IPython
327 will attempt to 'replay' the log by executing all the lines in it, thus
472 will attempt to 'replay' the log by executing all the lines in it, thus
328 restoring the state of a previous session. This feature is not quite
473 restoring the state of a previous session. This feature is not quite
329 perfect, but can still be useful in many cases.
474 perfect, but can still be useful in many cases.
330
475
331 The log files can also be used as a way to have a permanent record of
476 The log files can also be used as a way to have a permanent record of
332 any code you wrote while experimenting. Log files are regular text files
477 any code you wrote while experimenting. Log files are regular text files
333 which you can later open in your favorite text editor to extract code or
478 which you can later open in your favorite text editor to extract code or
334 to 'clean them up' before using them to replay a session.
479 to 'clean them up' before using them to replay a session.
335
480
336 The `%logstart` function for activating logging in mid-session is used as
481 The `%logstart` function for activating logging in mid-session is used as
337 follows::
482 follows::
338
483
339 %logstart [log_name [log_mode]]
484 %logstart [log_name [log_mode]]
340
485
341 If no name is given, it defaults to a file named 'ipython_log.py' in your
486 If no name is given, it defaults to a file named 'ipython_log.py' in your
342 current working directory, in 'rotate' mode (see below).
487 current working directory, in 'rotate' mode (see below).
343
488
344 '%logstart name' saves to file 'name' in 'backup' mode. It saves your
489 '%logstart name' saves to file 'name' in 'backup' mode. It saves your
345 history up to that point and then continues logging.
490 history up to that point and then continues logging.
346
491
347 %logstart takes a second optional parameter: logging mode. This can be
492 %logstart takes a second optional parameter: logging mode. This can be
348 one of (note that the modes are given unquoted):
493 one of (note that the modes are given unquoted):
349
494
350 * [over:] overwrite existing log_name.
495 * [over:] overwrite existing log_name.
351 * [backup:] rename (if exists) to log_name~ and start log_name.
496 * [backup:] rename (if exists) to log_name~ and start log_name.
352 * [append:] well, that says it.
497 * [append:] well, that says it.
353 * [rotate:] create rotating logs log_name.1~, log_name.2~, etc.
498 * [rotate:] create rotating logs log_name.1~, log_name.2~, etc.
354
499
355 The %logoff and %logon functions allow you to temporarily stop and
500 The %logoff and %logon functions allow you to temporarily stop and
356 resume logging to a file which had previously been started with
501 resume logging to a file which had previously been started with
357 %logstart. They will fail (with an explanation) if you try to use them
502 %logstart. They will fail (with an explanation) if you try to use them
358 before logging has been started.
503 before logging has been started.
359
504
360 .. _system_shell_access:
505 .. _system_shell_access:
361
506
362 System shell access
507 System shell access
363 -------------------
508 -------------------
364
509
365 Any input line beginning with a ! character is passed verbatim (minus
510 Any input line beginning with a ! character is passed verbatim (minus
366 the !, of course) to the underlying operating system. For example,
511 the !, of course) to the underlying operating system. For example,
367 typing ``!ls`` will run 'ls' in the current directory.
512 typing ``!ls`` will run 'ls' in the current directory.
368
513
369 Manual capture of command output
514 Manual capture of command output
370 --------------------------------
515 --------------------------------
371
516
372 You can assign the result of a system command to a Python variable with the
517 You can assign the result of a system command to a Python variable with the
373 syntax ``myfiles = !ls``. This gets machine readable output from stdout
518 syntax ``myfiles = !ls``. This gets machine readable output from stdout
374 (e.g. without colours), and splits on newlines. To explicitly get this sort of
519 (e.g. without colours), and splits on newlines. To explicitly get this sort of
375 output without assigning to a variable, use two exclamation marks (``!!ls``) or
520 output without assigning to a variable, use two exclamation marks (``!!ls``) or
376 the ``%sx`` magic command.
521 the ``%sx`` magic command.
377
522
378 The captured list has some convenience features. ``myfiles.n`` or ``myfiles.s``
523 The captured list has some convenience features. ``myfiles.n`` or ``myfiles.s``
379 returns a string delimited by newlines or spaces, respectively. ``myfiles.p``
524 returns a string delimited by newlines or spaces, respectively. ``myfiles.p``
380 produces `path objects <http://pypi.python.org/pypi/path.py>`_ from the list items.
525 produces `path objects <http://pypi.python.org/pypi/path.py>`_ from the list items.
381 See :ref:`string_lists` for details.
526 See :ref:`string_lists` for details.
382
527
383 IPython also allows you to expand the value of python variables when
528 IPython also allows you to expand the value of python variables when
384 making system calls. Wrap variables or expressions in {braces}::
529 making system calls. Wrap variables or expressions in {braces}::
385
530
386 In [1]: pyvar = 'Hello world'
531 In [1]: pyvar = 'Hello world'
387 In [2]: !echo "A python variable: {pyvar}"
532 In [2]: !echo "A python variable: {pyvar}"
388 A python variable: Hello world
533 A python variable: Hello world
389 In [3]: import math
534 In [3]: import math
390 In [4]: x = 8
535 In [4]: x = 8
391 In [5]: !echo {math.factorial(x)}
536 In [5]: !echo {math.factorial(x)}
392 40320
537 40320
393
538
394 For simple cases, you can alternatively prepend $ to a variable name::
539 For simple cases, you can alternatively prepend $ to a variable name::
395
540
396 In [6]: !echo $sys.argv
541 In [6]: !echo $sys.argv
397 [/home/fperez/usr/bin/ipython]
542 [/home/fperez/usr/bin/ipython]
398 In [7]: !echo "A system variable: $$HOME" # Use $$ for literal $
543 In [7]: !echo "A system variable: $$HOME" # Use $$ for literal $
399 A system variable: /home/fperez
544 A system variable: /home/fperez
400
545
401 System command aliases
546 System command aliases
402 ----------------------
547 ----------------------
403
548
404 The %alias magic function allows you to define magic functions which are in fact
549 The %alias magic function allows you to define magic functions which are in fact
405 system shell commands. These aliases can have parameters.
550 system shell commands. These aliases can have parameters.
406
551
407 ``%alias alias_name cmd`` defines 'alias_name' as an alias for 'cmd'
552 ``%alias alias_name cmd`` defines 'alias_name' as an alias for 'cmd'
408
553
409 Then, typing ``alias_name params`` will execute the system command 'cmd
554 Then, typing ``alias_name params`` will execute the system command 'cmd
410 params' (from your underlying operating system).
555 params' (from your underlying operating system).
411
556
412 You can also define aliases with parameters using %s specifiers (one per
557 You can also define aliases with parameters using %s specifiers (one per
413 parameter). The following example defines the parts function as an
558 parameter). The following example defines the parts function as an
414 alias to the command 'echo first %s second %s' where each %s will be
559 alias to the command 'echo first %s second %s' where each %s will be
415 replaced by a positional parameter to the call to %parts::
560 replaced by a positional parameter to the call to %parts::
416
561
417 In [1]: %alias parts echo first %s second %s
562 In [1]: %alias parts echo first %s second %s
418 In [2]: parts A B
563 In [2]: parts A B
419 first A second B
564 first A second B
420 In [3]: parts A
565 In [3]: parts A
421 ERROR: Alias <parts> requires 2 arguments, 1 given.
566 ERROR: Alias <parts> requires 2 arguments, 1 given.
422
567
423 If called with no parameters, %alias prints the table of currently
568 If called with no parameters, %alias prints the table of currently
424 defined aliases.
569 defined aliases.
425
570
426 The %rehashx magic allows you to load your entire $PATH as
571 The %rehashx magic allows you to load your entire $PATH as
427 ipython aliases. See its docstring for further details.
572 ipython aliases. See its docstring for further details.
428
573
429
574
430 .. _dreload:
575 .. _dreload:
431
576
432 Recursive reload
577 Recursive reload
433 ----------------
578 ----------------
434
579
435 The :mod:`IPython.lib.deepreload` module allows you to recursively reload a
580 The :mod:`IPython.lib.deepreload` module allows you to recursively reload a
436 module: changes made to any of its dependencies will be reloaded without
581 module: changes made to any of its dependencies will be reloaded without
437 having to exit. To start using it, do::
582 having to exit. To start using it, do::
438
583
439 from IPython.lib.deepreload import reload as dreload
584 from IPython.lib.deepreload import reload as dreload
440
585
441
586
442 Verbose and colored exception traceback printouts
587 Verbose and colored exception traceback printouts
443 -------------------------------------------------
588 -------------------------------------------------
444
589
445 IPython provides the option to see very detailed exception tracebacks,
590 IPython provides the option to see very detailed exception tracebacks,
446 which can be especially useful when debugging large programs. You can
591 which can be especially useful when debugging large programs. You can
447 run any Python file with the %run function to benefit from these
592 run any Python file with the %run function to benefit from these
448 detailed tracebacks. Furthermore, both normal and verbose tracebacks can
593 detailed tracebacks. Furthermore, both normal and verbose tracebacks can
449 be colored (if your terminal supports it) which makes them much easier
594 be colored (if your terminal supports it) which makes them much easier
450 to parse visually.
595 to parse visually.
451
596
452 See the magic xmode and colors functions for details (just type %magic).
597 See the magic xmode and colors functions for details (just type %magic).
453
598
454 These features are basically a terminal version of Ka-Ping Yee's cgitb
599 These features are basically a terminal version of Ka-Ping Yee's cgitb
455 module, now part of the standard Python library.
600 module, now part of the standard Python library.
456
601
457
602
458 .. _input_caching:
603 .. _input_caching:
459
604
460 Input caching system
605 Input caching system
461 --------------------
606 --------------------
462
607
463 IPython offers numbered prompts (In/Out) with input and output caching
608 IPython offers numbered prompts (In/Out) with input and output caching
464 (also referred to as 'input history'). All input is saved and can be
609 (also referred to as 'input history'). All input is saved and can be
465 retrieved as variables (besides the usual arrow key recall), in
610 retrieved as variables (besides the usual arrow key recall), in
466 addition to the %rep magic command that brings a history entry
611 addition to the %rep magic command that brings a history entry
467 up for editing on the next command line.
612 up for editing on the next command line.
468
613
469 The following GLOBAL variables always exist (so don't overwrite them!):
614 The following GLOBAL variables always exist (so don't overwrite them!):
470
615
471 * _i, _ii, _iii: store previous, next previous and next-next previous inputs.
616 * _i, _ii, _iii: store previous, next previous and next-next previous inputs.
472 * In, _ih : a list of all inputs; _ih[n] is the input from line n. If you
617 * In, _ih : a list of all inputs; _ih[n] is the input from line n. If you
473 overwrite In with a variable of your own, you can remake the assignment to the
618 overwrite In with a variable of your own, you can remake the assignment to the
474 internal list with a simple ``In=_ih``.
619 internal list with a simple ``In=_ih``.
475
620
476 Additionally, global variables named _i<n> are dynamically created (<n>
621 Additionally, global variables named _i<n> are dynamically created (<n>
477 being the prompt counter), so ``_i<n> == _ih[<n>] == In[<n>]``.
622 being the prompt counter), so ``_i<n> == _ih[<n>] == In[<n>]``.
478
623
479 For example, what you typed at prompt 14 is available as _i14, _ih[14]
624 For example, what you typed at prompt 14 is available as _i14, _ih[14]
480 and In[14].
625 and In[14].
481
626
482 This allows you to easily cut and paste multi line interactive prompts
627 This allows you to easily cut and paste multi line interactive prompts
483 by printing them out: they print like a clean string, without prompt
628 by printing them out: they print like a clean string, without prompt
484 characters. You can also manipulate them like regular variables (they
629 characters. You can also manipulate them like regular variables (they
485 are strings), modify or exec them (typing ``exec _i9`` will re-execute the
630 are strings), modify or exec them (typing ``exec _i9`` will re-execute the
486 contents of input prompt 9.
631 contents of input prompt 9.
487
632
488 You can also re-execute multiple lines of input easily by using the
633 You can also re-execute multiple lines of input easily by using the
489 magic %rerun or %macro functions. The macro system also allows you to re-execute
634 magic %rerun or %macro functions. The macro system also allows you to re-execute
490 previous lines which include magic function calls (which require special
635 previous lines which include magic function calls (which require special
491 processing). Type %macro? for more details on the macro system.
636 processing). Type %macro? for more details on the macro system.
492
637
493 A history function %hist allows you to see any part of your input
638 A history function %hist allows you to see any part of your input
494 history by printing a range of the _i variables.
639 history by printing a range of the _i variables.
495
640
496 You can also search ('grep') through your history by typing
641 You can also search ('grep') through your history by typing
497 ``%hist -g somestring``. This is handy for searching for URLs, IP addresses,
642 ``%hist -g somestring``. This is handy for searching for URLs, IP addresses,
498 etc. You can bring history entries listed by '%hist -g' up for editing
643 etc. You can bring history entries listed by '%hist -g' up for editing
499 with the %recall command, or run them immediately with %rerun.
644 with the %recall command, or run them immediately with %rerun.
500
645
501 .. _output_caching:
646 .. _output_caching:
502
647
503 Output caching system
648 Output caching system
504 ---------------------
649 ---------------------
505
650
506 For output that is returned from actions, a system similar to the input
651 For output that is returned from actions, a system similar to the input
507 cache exists but using _ instead of _i. Only actions that produce a
652 cache exists but using _ instead of _i. Only actions that produce a
508 result (NOT assignments, for example) are cached. If you are familiar
653 result (NOT assignments, for example) are cached. If you are familiar
509 with Mathematica, IPython's _ variables behave exactly like
654 with Mathematica, IPython's _ variables behave exactly like
510 Mathematica's % variables.
655 Mathematica's % variables.
511
656
512 The following GLOBAL variables always exist (so don't overwrite them!):
657 The following GLOBAL variables always exist (so don't overwrite them!):
513
658
514 * [_] (a single underscore) : stores previous output, like Python's
659 * [_] (a single underscore) : stores previous output, like Python's
515 default interpreter.
660 default interpreter.
516 * [__] (two underscores): next previous.
661 * [__] (two underscores): next previous.
517 * [___] (three underscores): next-next previous.
662 * [___] (three underscores): next-next previous.
518
663
519 Additionally, global variables named _<n> are dynamically created (<n>
664 Additionally, global variables named _<n> are dynamically created (<n>
520 being the prompt counter), such that the result of output <n> is always
665 being the prompt counter), such that the result of output <n> is always
521 available as _<n> (don't use the angle brackets, just the number, e.g.
666 available as _<n> (don't use the angle brackets, just the number, e.g.
522 _21).
667 _21).
523
668
524 These variables are also stored in a global dictionary (not a
669 These variables are also stored in a global dictionary (not a
525 list, since it only has entries for lines which returned a result)
670 list, since it only has entries for lines which returned a result)
526 available under the names _oh and Out (similar to _ih and In). So the
671 available under the names _oh and Out (similar to _ih and In). So the
527 output from line 12 can be obtained as _12, Out[12] or _oh[12]. If you
672 output from line 12 can be obtained as _12, Out[12] or _oh[12]. If you
528 accidentally overwrite the Out variable you can recover it by typing
673 accidentally overwrite the Out variable you can recover it by typing
529 'Out=_oh' at the prompt.
674 'Out=_oh' at the prompt.
530
675
531 This system obviously can potentially put heavy memory demands on your
676 This system obviously can potentially put heavy memory demands on your
532 system, since it prevents Python's garbage collector from removing any
677 system, since it prevents Python's garbage collector from removing any
533 previously computed results. You can control how many results are kept
678 previously computed results. You can control how many results are kept
534 in memory with the option (at the command line or in your configuration
679 in memory with the option (at the command line or in your configuration
535 file) cache_size. If you set it to 0, the whole system is completely
680 file) cache_size. If you set it to 0, the whole system is completely
536 disabled and the prompts revert to the classic '>>>' of normal Python.
681 disabled and the prompts revert to the classic '>>>' of normal Python.
537
682
538
683
539 Directory history
684 Directory history
540 -----------------
685 -----------------
541
686
542 Your history of visited directories is kept in the global list _dh, and
687 Your history of visited directories is kept in the global list _dh, and
543 the magic %cd command can be used to go to any entry in that list. The
688 the magic %cd command can be used to go to any entry in that list. The
544 %dhist command allows you to view this history. Do ``cd -<TAB>`` to
689 %dhist command allows you to view this history. Do ``cd -<TAB>`` to
545 conveniently view the directory history.
690 conveniently view the directory history.
546
691
547
692
548 Automatic parentheses and quotes
693 Automatic parentheses and quotes
549 --------------------------------
694 --------------------------------
550
695
551 These features were adapted from Nathan Gray's LazyPython. They are
696 These features were adapted from Nathan Gray's LazyPython. They are
552 meant to allow less typing for common situations.
697 meant to allow less typing for common situations.
553
698
554
699
555 Automatic parentheses
700 Automatic parentheses
556 +++++++++++++++++++++
701 +++++++++++++++++++++
557
702
558 Callable objects (i.e. functions, methods, etc) can be invoked like this
703 Callable objects (i.e. functions, methods, etc) can be invoked like this
559 (notice the commas between the arguments)::
704 (notice the commas between the arguments)::
560
705
561 In [1]: callable_ob arg1, arg2, arg3
706 In [1]: callable_ob arg1, arg2, arg3
562 ------> callable_ob(arg1, arg2, arg3)
707 ------> callable_ob(arg1, arg2, arg3)
563
708
564 You can force automatic parentheses by using '/' as the first character
709 You can force automatic parentheses by using '/' as the first character
565 of a line. For example::
710 of a line. For example::
566
711
567 In [2]: /globals # becomes 'globals()'
712 In [2]: /globals # becomes 'globals()'
568
713
569 Note that the '/' MUST be the first character on the line! This won't work::
714 Note that the '/' MUST be the first character on the line! This won't work::
570
715
571 In [3]: print /globals # syntax error
716 In [3]: print /globals # syntax error
572
717
573 In most cases the automatic algorithm should work, so you should rarely
718 In most cases the automatic algorithm should work, so you should rarely
574 need to explicitly invoke /. One notable exception is if you are trying
719 need to explicitly invoke /. One notable exception is if you are trying
575 to call a function with a list of tuples as arguments (the parenthesis
720 to call a function with a list of tuples as arguments (the parenthesis
576 will confuse IPython)::
721 will confuse IPython)::
577
722
578 In [4]: zip (1,2,3),(4,5,6) # won't work
723 In [4]: zip (1,2,3),(4,5,6) # won't work
579
724
580 but this will work::
725 but this will work::
581
726
582 In [5]: /zip (1,2,3),(4,5,6)
727 In [5]: /zip (1,2,3),(4,5,6)
583 ------> zip ((1,2,3),(4,5,6))
728 ------> zip ((1,2,3),(4,5,6))
584 Out[5]: [(1, 4), (2, 5), (3, 6)]
729 Out[5]: [(1, 4), (2, 5), (3, 6)]
585
730
586 IPython tells you that it has altered your command line by displaying
731 IPython tells you that it has altered your command line by displaying
587 the new command line preceded by ->. e.g.::
732 the new command line preceded by ->. e.g.::
588
733
589 In [6]: callable list
734 In [6]: callable list
590 ------> callable(list)
735 ------> callable(list)
591
736
592
737
593 Automatic quoting
738 Automatic quoting
594 +++++++++++++++++
739 +++++++++++++++++
595
740
596 You can force automatic quoting of a function's arguments by using ','
741 You can force automatic quoting of a function's arguments by using ','
597 or ';' as the first character of a line. For example::
742 or ';' as the first character of a line. For example::
598
743
599 In [1]: ,my_function /home/me # becomes my_function("/home/me")
744 In [1]: ,my_function /home/me # becomes my_function("/home/me")
600
745
601 If you use ';' the whole argument is quoted as a single string, while ',' splits
746 If you use ';' the whole argument is quoted as a single string, while ',' splits
602 on whitespace::
747 on whitespace::
603
748
604 In [2]: ,my_function a b c # becomes my_function("a","b","c")
749 In [2]: ,my_function a b c # becomes my_function("a","b","c")
605
750
606 In [3]: ;my_function a b c # becomes my_function("a b c")
751 In [3]: ;my_function a b c # becomes my_function("a b c")
607
752
608 Note that the ',' or ';' MUST be the first character on the line! This
753 Note that the ',' or ';' MUST be the first character on the line! This
609 won't work::
754 won't work::
610
755
611 In [4]: x = ,my_function /home/me # syntax error
756 In [4]: x = ,my_function /home/me # syntax error
612
757
613 IPython as your default Python environment
758 IPython as your default Python environment
614 ==========================================
759 ==========================================
615
760
616 Python honors the environment variable PYTHONSTARTUP and will execute at
761 Python honors the environment variable PYTHONSTARTUP and will execute at
617 startup the file referenced by this variable. If you put the following code at
762 startup the file referenced by this variable. If you put the following code at
618 the end of that file, then IPython will be your working environment anytime you
763 the end of that file, then IPython will be your working environment anytime you
619 start Python::
764 start Python::
620
765
621 from IPython.frontend.terminal.ipapp import launch_new_instance
766 from IPython.frontend.terminal.ipapp import launch_new_instance
622 launch_new_instance()
767 launch_new_instance()
623 raise SystemExit
768 raise SystemExit
624
769
625 The ``raise SystemExit`` is needed to exit Python when
770 The ``raise SystemExit`` is needed to exit Python when
626 it finishes, otherwise you'll be back at the normal Python '>>>'
771 it finishes, otherwise you'll be back at the normal Python '>>>'
627 prompt.
772 prompt.
628
773
629 This is probably useful to developers who manage multiple Python
774 This is probably useful to developers who manage multiple Python
630 versions and don't want to have correspondingly multiple IPython
775 versions and don't want to have correspondingly multiple IPython
631 versions. Note that in this mode, there is no way to pass IPython any
776 versions. Note that in this mode, there is no way to pass IPython any
632 command-line options, as those are trapped first by Python itself.
777 command-line options, as those are trapped first by Python itself.
633
778
634 .. _Embedding:
779 .. _Embedding:
635
780
636 Embedding IPython
781 Embedding IPython
637 =================
782 =================
638
783
639 It is possible to start an IPython instance inside your own Python
784 It is possible to start an IPython instance inside your own Python
640 programs. This allows you to evaluate dynamically the state of your
785 programs. This allows you to evaluate dynamically the state of your
641 code, operate with your variables, analyze them, etc. Note however that
786 code, operate with your variables, analyze them, etc. Note however that
642 any changes you make to values while in the shell do not propagate back
787 any changes you make to values while in the shell do not propagate back
643 to the running code, so it is safe to modify your values because you
788 to the running code, so it is safe to modify your values because you
644 won't break your code in bizarre ways by doing so.
789 won't break your code in bizarre ways by doing so.
645
790
646 .. note::
791 .. note::
647
792
648 At present, trying to embed IPython from inside IPython causes problems. Run
793 At present, trying to embed IPython from inside IPython causes problems. Run
649 the code samples below outside IPython.
794 the code samples below outside IPython.
650
795
651 This feature allows you to easily have a fully functional python
796 This feature allows you to easily have a fully functional python
652 environment for doing object introspection anywhere in your code with a
797 environment for doing object introspection anywhere in your code with a
653 simple function call. In some cases a simple print statement is enough,
798 simple function call. In some cases a simple print statement is enough,
654 but if you need to do more detailed analysis of a code fragment this
799 but if you need to do more detailed analysis of a code fragment this
655 feature can be very valuable.
800 feature can be very valuable.
656
801
657 It can also be useful in scientific computing situations where it is
802 It can also be useful in scientific computing situations where it is
658 common to need to do some automatic, computationally intensive part and
803 common to need to do some automatic, computationally intensive part and
659 then stop to look at data, plots, etc.
804 then stop to look at data, plots, etc.
660 Opening an IPython instance will give you full access to your data and
805 Opening an IPython instance will give you full access to your data and
661 functions, and you can resume program execution once you are done with
806 functions, and you can resume program execution once you are done with
662 the interactive part (perhaps to stop again later, as many times as
807 the interactive part (perhaps to stop again later, as many times as
663 needed).
808 needed).
664
809
665 The following code snippet is the bare minimum you need to include in
810 The following code snippet is the bare minimum you need to include in
666 your Python programs for this to work (detailed examples follow later)::
811 your Python programs for this to work (detailed examples follow later)::
667
812
668 from IPython import embed
813 from IPython import embed
669
814
670 embed() # this call anywhere in your program will start IPython
815 embed() # this call anywhere in your program will start IPython
671
816
672 .. note::
817 .. note::
673
818
674 As of 0.13, you can embed an IPython *kernel*, for use with qtconsole,
819 As of 0.13, you can embed an IPython *kernel*, for use with qtconsole,
675 etc. via ``IPython.embed_kernel()`` instead of ``IPython.embed()``.
820 etc. via ``IPython.embed_kernel()`` instead of ``IPython.embed()``.
676 It should function just the same as regular embed, but you connect
821 It should function just the same as regular embed, but you connect
677 an external frontend rather than IPython starting up in the local
822 an external frontend rather than IPython starting up in the local
678 terminal.
823 terminal.
679
824
680 You can run embedded instances even in code which is itself being run at
825 You can run embedded instances even in code which is itself being run at
681 the IPython interactive prompt with '%run <filename>'. Since it's easy
826 the IPython interactive prompt with '%run <filename>'. Since it's easy
682 to get lost as to where you are (in your top-level IPython or in your
827 to get lost as to where you are (in your top-level IPython or in your
683 embedded one), it's a good idea in such cases to set the in/out prompts
828 embedded one), it's a good idea in such cases to set the in/out prompts
684 to something different for the embedded instances. The code examples
829 to something different for the embedded instances. The code examples
685 below illustrate this.
830 below illustrate this.
686
831
687 You can also have multiple IPython instances in your program and open
832 You can also have multiple IPython instances in your program and open
688 them separately, for example with different options for data
833 them separately, for example with different options for data
689 presentation. If you close and open the same instance multiple times,
834 presentation. If you close and open the same instance multiple times,
690 its prompt counters simply continue from each execution to the next.
835 its prompt counters simply continue from each execution to the next.
691
836
692 Please look at the docstrings in the :mod:`~IPython.frontend.terminal.embed`
837 Please look at the docstrings in the :mod:`~IPython.frontend.terminal.embed`
693 module for more details on the use of this system.
838 module for more details on the use of this system.
694
839
695 The following sample file illustrating how to use the embedding
840 The following sample file illustrating how to use the embedding
696 functionality is provided in the examples directory as example-embed.py.
841 functionality is provided in the examples directory as example-embed.py.
697 It should be fairly self-explanatory:
842 It should be fairly self-explanatory:
698
843
699 .. literalinclude:: ../../examples/core/example-embed.py
844 .. literalinclude:: ../../examples/core/example-embed.py
700 :language: python
845 :language: python
701
846
702 Once you understand how the system functions, you can use the following
847 Once you understand how the system functions, you can use the following
703 code fragments in your programs which are ready for cut and paste:
848 code fragments in your programs which are ready for cut and paste:
704
849
705 .. literalinclude:: ../../examples/core/example-embed-short.py
850 .. literalinclude:: ../../examples/core/example-embed-short.py
706 :language: python
851 :language: python
707
852
708 Using the Python debugger (pdb)
853 Using the Python debugger (pdb)
709 ===============================
854 ===============================
710
855
711 Running entire programs via pdb
856 Running entire programs via pdb
712 -------------------------------
857 -------------------------------
713
858
714 pdb, the Python debugger, is a powerful interactive debugger which
859 pdb, the Python debugger, is a powerful interactive debugger which
715 allows you to step through code, set breakpoints, watch variables,
860 allows you to step through code, set breakpoints, watch variables,
716 etc. IPython makes it very easy to start any script under the control
861 etc. IPython makes it very easy to start any script under the control
717 of pdb, regardless of whether you have wrapped it into a 'main()'
862 of pdb, regardless of whether you have wrapped it into a 'main()'
718 function or not. For this, simply type '%run -d myscript' at an
863 function or not. For this, simply type '%run -d myscript' at an
719 IPython prompt. See the %run command's documentation (via '%run?' or
864 IPython prompt. See the %run command's documentation (via '%run?' or
720 in Sec. magic_ for more details, including how to control where pdb
865 in Sec. magic_ for more details, including how to control where pdb
721 will stop execution first.
866 will stop execution first.
722
867
723 For more information on the use of the pdb debugger, read the included
868 For more information on the use of the pdb debugger, read the included
724 pdb.doc file (part of the standard Python distribution). On a stock
869 pdb.doc file (part of the standard Python distribution). On a stock
725 Linux system it is located at /usr/lib/python2.3/pdb.doc, but the
870 Linux system it is located at /usr/lib/python2.3/pdb.doc, but the
726 easiest way to read it is by using the help() function of the pdb module
871 easiest way to read it is by using the help() function of the pdb module
727 as follows (in an IPython prompt)::
872 as follows (in an IPython prompt)::
728
873
729 In [1]: import pdb
874 In [1]: import pdb
730 In [2]: pdb.help()
875 In [2]: pdb.help()
731
876
732 This will load the pdb.doc document in a file viewer for you automatically.
877 This will load the pdb.doc document in a file viewer for you automatically.
733
878
734
879
735 Automatic invocation of pdb on exceptions
880 Automatic invocation of pdb on exceptions
736 -----------------------------------------
881 -----------------------------------------
737
882
738 IPython, if started with the ``--pdb`` option (or if the option is set in
883 IPython, if started with the ``--pdb`` option (or if the option is set in
739 your config file) can call the Python pdb debugger every time your code
884 your config file) can call the Python pdb debugger every time your code
740 triggers an uncaught exception. This feature
885 triggers an uncaught exception. This feature
741 can also be toggled at any time with the %pdb magic command. This can be
886 can also be toggled at any time with the %pdb magic command. This can be
742 extremely useful in order to find the origin of subtle bugs, because pdb
887 extremely useful in order to find the origin of subtle bugs, because pdb
743 opens up at the point in your code which triggered the exception, and
888 opens up at the point in your code which triggered the exception, and
744 while your program is at this point 'dead', all the data is still
889 while your program is at this point 'dead', all the data is still
745 available and you can walk up and down the stack frame and understand
890 available and you can walk up and down the stack frame and understand
746 the origin of the problem.
891 the origin of the problem.
747
892
748 Furthermore, you can use these debugging facilities both with the
893 Furthermore, you can use these debugging facilities both with the
749 embedded IPython mode and without IPython at all. For an embedded shell
894 embedded IPython mode and without IPython at all. For an embedded shell
750 (see sec. Embedding_), simply call the constructor with
895 (see sec. Embedding_), simply call the constructor with
751 ``--pdb`` in the argument string and pdb will automatically be called if an
896 ``--pdb`` in the argument string and pdb will automatically be called if an
752 uncaught exception is triggered by your code.
897 uncaught exception is triggered by your code.
753
898
754 For stand-alone use of the feature in your programs which do not use
899 For stand-alone use of the feature in your programs which do not use
755 IPython at all, put the following lines toward the top of your 'main'
900 IPython at all, put the following lines toward the top of your 'main'
756 routine::
901 routine::
757
902
758 import sys
903 import sys
759 from IPython.core import ultratb
904 from IPython.core import ultratb
760 sys.excepthook = ultratb.FormattedTB(mode='Verbose',
905 sys.excepthook = ultratb.FormattedTB(mode='Verbose',
761 color_scheme='Linux', call_pdb=1)
906 color_scheme='Linux', call_pdb=1)
762
907
763 The mode keyword can be either 'Verbose' or 'Plain', giving either very
908 The mode keyword can be either 'Verbose' or 'Plain', giving either very
764 detailed or normal tracebacks respectively. The color_scheme keyword can
909 detailed or normal tracebacks respectively. The color_scheme keyword can
765 be one of 'NoColor', 'Linux' (default) or 'LightBG'. These are the same
910 be one of 'NoColor', 'Linux' (default) or 'LightBG'. These are the same
766 options which can be set in IPython with ``--colors`` and ``--xmode``.
911 options which can be set in IPython with ``--colors`` and ``--xmode``.
767
912
768 This will give any of your programs detailed, colored tracebacks with
913 This will give any of your programs detailed, colored tracebacks with
769 automatic invocation of pdb.
914 automatic invocation of pdb.
770
915
771
916
772 Extensions for syntax processing
917 Extensions for syntax processing
773 ================================
918 ================================
774
919
775 This isn't for the faint of heart, because the potential for breaking
920 This isn't for the faint of heart, because the potential for breaking
776 things is quite high. But it can be a very powerful and useful feature.
921 things is quite high. But it can be a very powerful and useful feature.
777 In a nutshell, you can redefine the way IPython processes the user input
922 In a nutshell, you can redefine the way IPython processes the user input
778 line to accept new, special extensions to the syntax without needing to
923 line to accept new, special extensions to the syntax without needing to
779 change any of IPython's own code.
924 change any of IPython's own code.
780
925
781 In the IPython/extensions directory you will find some examples
926 In the IPython/extensions directory you will find some examples
782 supplied, which we will briefly describe now. These can be used 'as is'
927 supplied, which we will briefly describe now. These can be used 'as is'
783 (and both provide very useful functionality), or you can use them as a
928 (and both provide very useful functionality), or you can use them as a
784 starting point for writing your own extensions.
929 starting point for writing your own extensions.
785
930
786 .. _pasting_with_prompts:
931 .. _pasting_with_prompts:
787
932
788 Pasting of code starting with Python or IPython prompts
933 Pasting of code starting with Python or IPython prompts
789 -------------------------------------------------------
934 -------------------------------------------------------
790
935
791 IPython is smart enough to filter out input prompts, be they plain Python ones
936 IPython is smart enough to filter out input prompts, be they plain Python ones
792 (``>>>`` and ``...``) or IPython ones (``In [N]:`` and `` ...:``). You can
937 (``>>>`` and ``...``) or IPython ones (``In [N]:`` and `` ...:``). You can
793 therefore copy and paste from existing interactive sessions without worry.
938 therefore copy and paste from existing interactive sessions without worry.
794
939
795 The following is a 'screenshot' of how things work, copying an example from the
940 The following is a 'screenshot' of how things work, copying an example from the
796 standard Python tutorial::
941 standard Python tutorial::
797
942
798 In [1]: >>> # Fibonacci series:
943 In [1]: >>> # Fibonacci series:
799
944
800 In [2]: ... # the sum of two elements defines the next
945 In [2]: ... # the sum of two elements defines the next
801
946
802 In [3]: ... a, b = 0, 1
947 In [3]: ... a, b = 0, 1
803
948
804 In [4]: >>> while b < 10:
949 In [4]: >>> while b < 10:
805 ...: ... print b
950 ...: ... print b
806 ...: ... a, b = b, a+b
951 ...: ... a, b = b, a+b
807 ...:
952 ...:
808 1
953 1
809 1
954 1
810 2
955 2
811 3
956 3
812 5
957 5
813 8
958 8
814
959
815 And pasting from IPython sessions works equally well::
960 And pasting from IPython sessions works equally well::
816
961
817 In [1]: In [5]: def f(x):
962 In [1]: In [5]: def f(x):
818 ...: ...: "A simple function"
963 ...: ...: "A simple function"
819 ...: ...: return x**2
964 ...: ...: return x**2
820 ...: ...:
965 ...: ...:
821
966
822 In [2]: f(3)
967 In [2]: f(3)
823 Out[2]: 9
968 Out[2]: 9
824
969
825 .. _gui_support:
970 .. _gui_support:
826
971
827 GUI event loop support
972 GUI event loop support
828 ======================
973 ======================
829
974
830 .. versionadded:: 0.11
975 .. versionadded:: 0.11
831 The ``%gui`` magic and :mod:`IPython.lib.inputhook`.
976 The ``%gui`` magic and :mod:`IPython.lib.inputhook`.
832
977
833 IPython has excellent support for working interactively with Graphical User
978 IPython has excellent support for working interactively with Graphical User
834 Interface (GUI) toolkits, such as wxPython, PyQt4/PySide, PyGTK and Tk. This is
979 Interface (GUI) toolkits, such as wxPython, PyQt4/PySide, PyGTK and Tk. This is
835 implemented using Python's builtin ``PyOSInputHook`` hook. This implementation
980 implemented using Python's builtin ``PyOSInputHook`` hook. This implementation
836 is extremely robust compared to our previous thread-based version. The
981 is extremely robust compared to our previous thread-based version. The
837 advantages of this are:
982 advantages of this are:
838
983
839 * GUIs can be enabled and disabled dynamically at runtime.
984 * GUIs can be enabled and disabled dynamically at runtime.
840 * The active GUI can be switched dynamically at runtime.
985 * The active GUI can be switched dynamically at runtime.
841 * In some cases, multiple GUIs can run simultaneously with no problems.
986 * In some cases, multiple GUIs can run simultaneously with no problems.
842 * There is a developer API in :mod:`IPython.lib.inputhook` for customizing
987 * There is a developer API in :mod:`IPython.lib.inputhook` for customizing
843 all of these things.
988 all of these things.
844
989
845 For users, enabling GUI event loop integration is simple. You simple use the
990 For users, enabling GUI event loop integration is simple. You simple use the
846 ``%gui`` magic as follows::
991 ``%gui`` magic as follows::
847
992
848 %gui [GUINAME]
993 %gui [GUINAME]
849
994
850 With no arguments, ``%gui`` removes all GUI support. Valid ``GUINAME``
995 With no arguments, ``%gui`` removes all GUI support. Valid ``GUINAME``
851 arguments are ``wx``, ``qt``, ``gtk`` and ``tk``.
996 arguments are ``wx``, ``qt``, ``gtk`` and ``tk``.
852
997
853 Thus, to use wxPython interactively and create a running :class:`wx.App`
998 Thus, to use wxPython interactively and create a running :class:`wx.App`
854 object, do::
999 object, do::
855
1000
856 %gui wx
1001 %gui wx
857
1002
858 For information on IPython's Matplotlib integration (and the ``pylab`` mode)
1003 For information on IPython's Matplotlib integration (and the ``pylab`` mode)
859 see :ref:`this section <matplotlib_support>`.
1004 see :ref:`this section <matplotlib_support>`.
860
1005
861 For developers that want to use IPython's GUI event loop integration in the
1006 For developers that want to use IPython's GUI event loop integration in the
862 form of a library, these capabilities are exposed in library form in the
1007 form of a library, these capabilities are exposed in library form in the
863 :mod:`IPython.lib.inputhook` and :mod:`IPython.lib.guisupport` modules.
1008 :mod:`IPython.lib.inputhook` and :mod:`IPython.lib.guisupport` modules.
864 Interested developers should see the module docstrings for more information,
1009 Interested developers should see the module docstrings for more information,
865 but there are a few points that should be mentioned here.
1010 but there are a few points that should be mentioned here.
866
1011
867 First, the ``PyOSInputHook`` approach only works in command line settings
1012 First, the ``PyOSInputHook`` approach only works in command line settings
868 where readline is activated. The integration with various eventloops
1013 where readline is activated. The integration with various eventloops
869 is handled somewhat differently (and more simply) when using the standalone
1014 is handled somewhat differently (and more simply) when using the standalone
870 kernel, as in the qtconsole and notebook.
1015 kernel, as in the qtconsole and notebook.
871
1016
872 Second, when using the ``PyOSInputHook`` approach, a GUI application should
1017 Second, when using the ``PyOSInputHook`` approach, a GUI application should
873 *not* start its event loop. Instead all of this is handled by the
1018 *not* start its event loop. Instead all of this is handled by the
874 ``PyOSInputHook``. This means that applications that are meant to be used both
1019 ``PyOSInputHook``. This means that applications that are meant to be used both
875 in IPython and as standalone apps need to have special code to detects how the
1020 in IPython and as standalone apps need to have special code to detects how the
876 application is being run. We highly recommend using IPython's support for this.
1021 application is being run. We highly recommend using IPython's support for this.
877 Since the details vary slightly between toolkits, we point you to the various
1022 Since the details vary slightly between toolkits, we point you to the various
878 examples in our source directory :file:`docs/examples/lib` that demonstrate
1023 examples in our source directory :file:`docs/examples/lib` that demonstrate
879 these capabilities.
1024 these capabilities.
880
1025
881 Third, unlike previous versions of IPython, we no longer "hijack" (replace
1026 Third, unlike previous versions of IPython, we no longer "hijack" (replace
882 them with no-ops) the event loops. This is done to allow applications that
1027 them with no-ops) the event loops. This is done to allow applications that
883 actually need to run the real event loops to do so. This is often needed to
1028 actually need to run the real event loops to do so. This is often needed to
884 process pending events at critical points.
1029 process pending events at critical points.
885
1030
886 Finally, we also have a number of examples in our source directory
1031 Finally, we also have a number of examples in our source directory
887 :file:`docs/examples/lib` that demonstrate these capabilities.
1032 :file:`docs/examples/lib` that demonstrate these capabilities.
888
1033
889 PyQt and PySide
1034 PyQt and PySide
890 ---------------
1035 ---------------
891
1036
892 .. attempt at explanation of the complete mess that is Qt support
1037 .. attempt at explanation of the complete mess that is Qt support
893
1038
894 When you use ``--gui=qt`` or ``--pylab=qt``, IPython can work with either
1039 When you use ``--gui=qt`` or ``--pylab=qt``, IPython can work with either
895 PyQt4 or PySide. There are three options for configuration here, because
1040 PyQt4 or PySide. There are three options for configuration here, because
896 PyQt4 has two APIs for QString and QVariant - v1, which is the default on
1041 PyQt4 has two APIs for QString and QVariant - v1, which is the default on
897 Python 2, and the more natural v2, which is the only API supported by PySide.
1042 Python 2, and the more natural v2, which is the only API supported by PySide.
898 v2 is also the default for PyQt4 on Python 3. IPython's code for the QtConsole
1043 v2 is also the default for PyQt4 on Python 3. IPython's code for the QtConsole
899 uses v2, but you can still use any interface in your code, since the
1044 uses v2, but you can still use any interface in your code, since the
900 Qt frontend is in a different process.
1045 Qt frontend is in a different process.
901
1046
902 The default will be to import PyQt4 without configuration of the APIs, thus
1047 The default will be to import PyQt4 without configuration of the APIs, thus
903 matching what most applications would expect. It will fall back of PySide if
1048 matching what most applications would expect. It will fall back of PySide if
904 PyQt4 is unavailable.
1049 PyQt4 is unavailable.
905
1050
906 If specified, IPython will respect the environment variable ``QT_API`` used
1051 If specified, IPython will respect the environment variable ``QT_API`` used
907 by ETS. ETS 4.0 also works with both PyQt4 and PySide, but it requires
1052 by ETS. ETS 4.0 also works with both PyQt4 and PySide, but it requires
908 PyQt4 to use its v2 API. So if ``QT_API=pyside`` PySide will be used,
1053 PyQt4 to use its v2 API. So if ``QT_API=pyside`` PySide will be used,
909 and if ``QT_API=pyqt`` then PyQt4 will be used *with the v2 API* for
1054 and if ``QT_API=pyqt`` then PyQt4 will be used *with the v2 API* for
910 QString and QVariant, so ETS codes like MayaVi will also work with IPython.
1055 QString and QVariant, so ETS codes like MayaVi will also work with IPython.
911
1056
912 If you launch IPython in pylab mode with ``ipython --pylab=qt``, then IPython
1057 If you launch IPython in pylab mode with ``ipython --pylab=qt``, then IPython
913 will ask matplotlib which Qt library to use (only if QT_API is *not set*), via
1058 will ask matplotlib which Qt library to use (only if QT_API is *not set*), via
914 the 'backend.qt4' rcParam. If matplotlib is version 1.0.1 or older, then
1059 the 'backend.qt4' rcParam. If matplotlib is version 1.0.1 or older, then
915 IPython will always use PyQt4 without setting the v2 APIs, since neither v2
1060 IPython will always use PyQt4 without setting the v2 APIs, since neither v2
916 PyQt nor PySide work.
1061 PyQt nor PySide work.
917
1062
918 .. warning::
1063 .. warning::
919
1064
920 Note that this means for ETS 4 to work with PyQt4, ``QT_API`` *must* be set
1065 Note that this means for ETS 4 to work with PyQt4, ``QT_API`` *must* be set
921 to work with IPython's qt integration, because otherwise PyQt4 will be
1066 to work with IPython's qt integration, because otherwise PyQt4 will be
922 loaded in an incompatible mode.
1067 loaded in an incompatible mode.
923
1068
924 It also means that you must *not* have ``QT_API`` set if you want to
1069 It also means that you must *not* have ``QT_API`` set if you want to
925 use ``--gui=qt`` with code that requires PyQt4 API v1.
1070 use ``--gui=qt`` with code that requires PyQt4 API v1.
926
1071
927
1072
928 .. _matplotlib_support:
1073 .. _matplotlib_support:
929
1074
930 Plotting with matplotlib
1075 Plotting with matplotlib
931 ========================
1076 ========================
932
1077
933 `Matplotlib`_ provides high quality 2D and 3D plotting for Python. Matplotlib
1078 `Matplotlib`_ provides high quality 2D and 3D plotting for Python. Matplotlib
934 can produce plots on screen using a variety of GUI toolkits, including Tk,
1079 can produce plots on screen using a variety of GUI toolkits, including Tk,
935 PyGTK, PyQt4 and wxPython. It also provides a number of commands useful for
1080 PyGTK, PyQt4 and wxPython. It also provides a number of commands useful for
936 scientific computing, all with a syntax compatible with that of the popular
1081 scientific computing, all with a syntax compatible with that of the popular
937 Matlab program.
1082 Matlab program.
938
1083
939 To start IPython with matplotlib support, use the ``--pylab`` switch. If no
1084 To start IPython with matplotlib support, use the ``--pylab`` switch. If no
940 arguments are given, IPython will automatically detect your choice of
1085 arguments are given, IPython will automatically detect your choice of
941 matplotlib backend. You can also request a specific backend with ``--pylab
1086 matplotlib backend. You can also request a specific backend with ``--pylab
942 backend``, where ``backend`` must be one of: 'tk', 'qt', 'wx', 'gtk', 'osx'.
1087 backend``, where ``backend`` must be one of: 'tk', 'qt', 'wx', 'gtk', 'osx'.
943 In the web notebook and Qt console, 'inline' is also a valid backend value,
1088 In the web notebook and Qt console, 'inline' is also a valid backend value,
944 which produces static figures inlined inside the application window instead of
1089 which produces static figures inlined inside the application window instead of
945 matplotlib's interactive figures that live in separate windows.
1090 matplotlib's interactive figures that live in separate windows.
946
1091
947 .. _Matplotlib: http://matplotlib.sourceforge.net
1092 .. _Matplotlib: http://matplotlib.sourceforge.net
948
1093
949 .. _interactive_demos:
1094 .. _interactive_demos:
950
1095
951 Interactive demos with IPython
1096 Interactive demos with IPython
952 ==============================
1097 ==============================
953
1098
954 IPython ships with a basic system for running scripts interactively in
1099 IPython ships with a basic system for running scripts interactively in
955 sections, useful when presenting code to audiences. A few tags embedded
1100 sections, useful when presenting code to audiences. A few tags embedded
956 in comments (so that the script remains valid Python code) divide a file
1101 in comments (so that the script remains valid Python code) divide a file
957 into separate blocks, and the demo can be run one block at a time, with
1102 into separate blocks, and the demo can be run one block at a time, with
958 IPython printing (with syntax highlighting) the block before executing
1103 IPython printing (with syntax highlighting) the block before executing
959 it, and returning to the interactive prompt after each block. The
1104 it, and returning to the interactive prompt after each block. The
960 interactive namespace is updated after each block is run with the
1105 interactive namespace is updated after each block is run with the
961 contents of the demo's namespace.
1106 contents of the demo's namespace.
962
1107
963 This allows you to show a piece of code, run it and then execute
1108 This allows you to show a piece of code, run it and then execute
964 interactively commands based on the variables just created. Once you
1109 interactively commands based on the variables just created. Once you
965 want to continue, you simply execute the next block of the demo. The
1110 want to continue, you simply execute the next block of the demo. The
966 following listing shows the markup necessary for dividing a script into
1111 following listing shows the markup necessary for dividing a script into
967 sections for execution as a demo:
1112 sections for execution as a demo:
968
1113
969 .. literalinclude:: ../../examples/lib/example-demo.py
1114 .. literalinclude:: ../../examples/lib/example-demo.py
970 :language: python
1115 :language: python
971
1116
972 In order to run a file as a demo, you must first make a Demo object out
1117 In order to run a file as a demo, you must first make a Demo object out
973 of it. If the file is named myscript.py, the following code will make a
1118 of it. If the file is named myscript.py, the following code will make a
974 demo::
1119 demo::
975
1120
976 from IPython.lib.demo import Demo
1121 from IPython.lib.demo import Demo
977
1122
978 mydemo = Demo('myscript.py')
1123 mydemo = Demo('myscript.py')
979
1124
980 This creates the mydemo object, whose blocks you run one at a time by
1125 This creates the mydemo object, whose blocks you run one at a time by
981 simply calling the object with no arguments. If you have autocall active
1126 simply calling the object with no arguments. If you have autocall active
982 in IPython (the default), all you need to do is type::
1127 in IPython (the default), all you need to do is type::
983
1128
984 mydemo
1129 mydemo
985
1130
986 and IPython will call it, executing each block. Demo objects can be
1131 and IPython will call it, executing each block. Demo objects can be
987 restarted, you can move forward or back skipping blocks, re-execute the
1132 restarted, you can move forward or back skipping blocks, re-execute the
988 last block, etc. Simply use the Tab key on a demo object to see its
1133 last block, etc. Simply use the Tab key on a demo object to see its
989 methods, and call '?' on them to see their docstrings for more usage
1134 methods, and call '?' on them to see their docstrings for more usage
990 details. In addition, the demo module itself contains a comprehensive
1135 details. In addition, the demo module itself contains a comprehensive
991 docstring, which you can access via::
1136 docstring, which you can access via::
992
1137
993 from IPython.lib import demo
1138 from IPython.lib import demo
994
1139
995 demo?
1140 demo?
996
1141
997 Limitations: It is important to note that these demos are limited to
1142 Limitations: It is important to note that these demos are limited to
998 fairly simple uses. In particular, you cannot break up sections within
1143 fairly simple uses. In particular, you cannot break up sections within
999 indented code (loops, if statements, function definitions, etc.)
1144 indented code (loops, if statements, function definitions, etc.)
1000 Supporting something like this would basically require tracking the
1145 Supporting something like this would basically require tracking the
1001 internal execution state of the Python interpreter, so only top-level
1146 internal execution state of the Python interpreter, so only top-level
1002 divisions are allowed. If you want to be able to open an IPython
1147 divisions are allowed. If you want to be able to open an IPython
1003 instance at an arbitrary point in a program, you can use IPython's
1148 instance at an arbitrary point in a program, you can use IPython's
1004 embedding facilities, see :func:`IPython.embed` for details.
1149 embedding facilities, see :func:`IPython.embed` for details.
1005
1150
@@ -1,157 +1,179 b''
1 .. _tutorial:
1 .. _tutorial:
2
2
3 ======================
3 ======================
4 Introducing IPython
4 Introducing IPython
5 ======================
5 ======================
6
6
7 You don't need to know anything beyond Python to start using IPython – just type
7 You don't need to know anything beyond Python to start using IPython – just type
8 commands as you would at the standard Python prompt. But IPython can do much
8 commands as you would at the standard Python prompt. But IPython can do much
9 more than the standard prompt. Some key features are described here. For more
9 more than the standard prompt. Some key features are described here. For more
10 information, check the :ref:`tips page <tips>`, or look at examples in the
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 <http://wiki.ipython.org/index.php?title=Cookbook>`_.
12
12
13 If you've never used Python before, you might want to look at `the official
13 If you've never used Python before, you might want to look at `the official
14 tutorial <http://docs.python.org/tutorial/>`_ or an alternative, `Dive into
14 tutorial <http://docs.python.org/tutorial/>`_ or an alternative, `Dive into
15 Python <http://diveintopython.org/toc/index.html>`_.
15 Python <http://diveintopython.org/toc/index.html>`_.
16
16
17 Tab completion
17 Tab completion
18 ==============
18 ==============
19
19
20 Tab completion, especially for attributes, is a convenient way to explore the
20 Tab completion, especially for attributes, is a convenient way to explore the
21 structure of any object you're dealing with. Simply type ``object_name.<TAB>``
21 structure of any object you're dealing with. Simply type ``object_name.<TAB>``
22 to view the object's attributes (see :ref:`the readline section <readline>` for
22 to view the object's attributes (see :ref:`the readline section <readline>` for
23 more). Besides Python objects and keywords, tab completion also works on file
23 more). Besides Python objects and keywords, tab completion also works on file
24 and directory names.
24 and directory names.
25
25
26 Exploring your objects
26 Exploring your objects
27 ======================
27 ======================
28
28
29 Typing ``object_name?`` will print all sorts of details about any object,
29 Typing ``object_name?`` will print all sorts of details about any object,
30 including docstrings, function definition lines (for call arguments) and
30 including docstrings, function definition lines (for call arguments) and
31 constructor details for classes. To get specific information on an object, you
31 constructor details for classes. To get specific information on an object, you
32 can use the magic commands ``%pdoc``, ``%pdef``, ``%psource`` and ``%pfile``
32 can use the magic commands ``%pdoc``, ``%pdef``, ``%psource`` and ``%pfile``
33
33
34 Magic functions
34 Magic functions
35 ===============
35 ===============
36
36
37 IPython has a set of predefined 'magic functions' that you can call with a
37 IPython has a set of predefined 'magic functions' that you can call with a
38 command line style syntax. These include:
38 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
40 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.
44
45 The following examples show how to call the builtin ``timeit`` magic, both in
46 line and cell mode::
47
48 In [1]: %timeit range(1000)
49 100000 loops, best of 3: 7.76 us per loop
50
51 In [2]: %%timeit x = range(10000)
52 ...: max(x)
53 ...:
54 1000 loops, best of 3: 223 us per loop
55
56 The builtin magics include:
39
57
40 - Functions that work with code: ``%run``, ``%edit``, ``%save``, ``%macro``,
58 - Functions that work with code: ``%run``, ``%edit``, ``%save``, ``%macro``,
41 ``%recall``, etc.
59 ``%recall``, etc.
42 - Functions which affect the shell: ``%colors``, ``%xmode``, ``%autoindent``, etc.
60 - Functions which affect the shell: ``%colors``, ``%xmode``, ``%autoindent``,
61 etc.
43 - Other functions such as ``%reset``, ``%timeit`` or ``%paste``.
62 - Other functions such as ``%reset``, ``%timeit`` or ``%paste``.
44
63
45 You can always call these using the % prefix, and if you're typing one on a line
64 You can always call them using the % prefix, and if you're calling a line magic
46 by itself, you can omit even that::
65 on a line by itself, you can omit even that (cell magics must always have the
66 ``%%`` prefix)::
47
67
48 run thescript.py
68 run thescript.py
49
69
50 For more details on any magic function, call ``%somemagic?`` to read its
70 A more detailed explanation of the magic system can be obtained by calling
51 docstring. To see all the available magic functions, call ``%lsmagic``.
71 ``%magic``, and for more details on any magic function, call ``%somemagic?`` to
72 read its docstring. To see all the available magic functions, call
73 ``%lsmagic``.
52
74
53 Running and Editing
75 Running and Editing
54 -------------------
76 -------------------
55
77
56 The %run magic command allows you to run any python script and load all of its
78 The %run magic command allows you to run any python script and load all of its
57 data directly into the interactive namespace. Since the file is re-read from
79 data directly into the interactive namespace. Since the file is re-read from
58 disk each time, changes you make to it are reflected immediately (unlike
80 disk each time, changes you make to it are reflected immediately (unlike
59 imported modules, which have to be specifically reloaded). IPython also includes
81 imported modules, which have to be specifically reloaded). IPython also includes
60 :ref:`dreload <dreload>`, a recursive reload function.
82 :ref:`dreload <dreload>`, a recursive reload function.
61
83
62 %run has special flags for timing the execution of your scripts (-t), or for
84 %run has special flags for timing the execution of your scripts (-t), or for
63 running them under the control of either Python's pdb debugger (-d) or
85 running them under the control of either Python's pdb debugger (-d) or
64 profiler (-p).
86 profiler (-p).
65
87
66 The %edit command gives a reasonable approximation of multiline editing,
88 The %edit command gives a reasonable approximation of multiline editing,
67 by invoking your favorite editor on the spot. IPython will execute the
89 by invoking your favorite editor on the spot. IPython will execute the
68 code you type in there as if it were typed interactively.
90 code you type in there as if it were typed interactively.
69
91
70 Debugging
92 Debugging
71 ---------
93 ---------
72
94
73 After an exception occurs, you can call ``%debug`` to jump into the Python
95 After an exception occurs, you can call ``%debug`` to jump into the Python
74 debugger (pdb) and examine the problem. Alternatively, if you call ``%pdb``,
96 debugger (pdb) and examine the problem. Alternatively, if you call ``%pdb``,
75 IPython will automatically start the debugger on any uncaught exception. You can
97 IPython will automatically start the debugger on any uncaught exception. You can
76 print variables, see code, execute statements and even walk up and down the
98 print variables, see code, execute statements and even walk up and down the
77 call stack to track down the true source of the problem. This can be an efficient
99 call stack to track down the true source of the problem. This can be an efficient
78 way to develop and debug code, in many cases eliminating the need for print
100 way to develop and debug code, in many cases eliminating the need for print
79 statements or external debugging tools.
101 statements or external debugging tools.
80
102
81 You can also step through a program from the beginning by calling
103 You can also step through a program from the beginning by calling
82 ``%run -d theprogram.py``.
104 ``%run -d theprogram.py``.
83
105
84 History
106 History
85 =======
107 =======
86
108
87 IPython stores both the commands you enter, and the results it produces. You
109 IPython stores both the commands you enter, and the results it produces. You
88 can easily go through previous commands with the up- and down-arrow keys, or
110 can easily go through previous commands with the up- and down-arrow keys, or
89 access your history in more sophisticated ways.
111 access your history in more sophisticated ways.
90
112
91 Input and output history are kept in variables called ``In`` and ``Out``, keyed
113 Input and output history are kept in variables called ``In`` and ``Out``, keyed
92 by the prompt numbers, e.g. ``In[4]``. The last three objects in output history
114 by the prompt numbers, e.g. ``In[4]``. The last three objects in output history
93 are also kept in variables named ``_``, ``__`` and ``___``.
115 are also kept in variables named ``_``, ``__`` and ``___``.
94
116
95 You can use the ``%history`` magic function to examine past input and output.
117 You can use the ``%history`` magic function to examine past input and output.
96 Input history from previous sessions is saved in a database, and IPython can be
118 Input history from previous sessions is saved in a database, and IPython can be
97 configured to save output history.
119 configured to save output history.
98
120
99 Several other magic functions can use your input history, including ``%edit``,
121 Several other magic functions can use your input history, including ``%edit``,
100 ``%rerun``, ``%recall``, ``%macro``, ``%save`` and ``%pastebin``. You can use a
122 ``%rerun``, ``%recall``, ``%macro``, ``%save`` and ``%pastebin``. You can use a
101 standard format to refer to lines::
123 standard format to refer to lines::
102
124
103 %pastebin 3 18-20 ~1/1-5
125 %pastebin 3 18-20 ~1/1-5
104
126
105 This will take line 3 and lines 18 to 20 from the current session, and lines
127 This will take line 3 and lines 18 to 20 from the current session, and lines
106 1-5 from the previous session.
128 1-5 from the previous session.
107
129
108 System shell commands
130 System shell commands
109 =====================
131 =====================
110
132
111 To run any command at the system shell, simply prefix it with !, e.g.::
133 To run any command at the system shell, simply prefix it with !, e.g.::
112
134
113 !ping www.bbc.co.uk
135 !ping www.bbc.co.uk
114
136
115 You can capture the output into a Python list, e.g.: ``files = !ls``. To pass
137 You can capture the output into a Python list, e.g.: ``files = !ls``. To pass
116 the values of Python variables or expressions to system commands, prefix them
138 the values of Python variables or expressions to system commands, prefix them
117 with $: ``!grep -rF $pattern ipython/*``. See :ref:`our shell section
139 with $: ``!grep -rF $pattern ipython/*``. See :ref:`our shell section
118 <system_shell_access>` for more details.
140 <system_shell_access>` for more details.
119
141
120 Define your own system aliases
142 Define your own system aliases
121 ------------------------------
143 ------------------------------
122
144
123 It's convenient to have aliases to the system commands you use most often.
145 It's convenient to have aliases to the system commands you use most often.
124 This allows you to work seamlessly from inside IPython with the same commands
146 This allows you to work seamlessly from inside IPython with the same commands
125 you are used to in your system shell. IPython comes with some pre-defined
147 you are used to in your system shell. IPython comes with some pre-defined
126 aliases and a complete system for changing directories, both via a stack (see
148 aliases and a complete system for changing directories, both via a stack (see
127 %pushd, %popd and %dhist) and via direct %cd. The latter keeps a history of
149 %pushd, %popd and %dhist) and via direct %cd. The latter keeps a history of
128 visited directories and allows you to go to any previously visited one.
150 visited directories and allows you to go to any previously visited one.
129
151
130
152
131 Configuration
153 Configuration
132 =============
154 =============
133
155
134 Much of IPython can be tweaked through configuration. To get started, use the
156 Much of IPython can be tweaked through configuration. To get started, use the
135 command ``ipython profile create`` to produce the default config files. These
157 command ``ipython profile create`` to produce the default config files. These
136 will be placed in :file:`~/.ipython/profile_default` or
158 will be placed in :file:`~/.ipython/profile_default` or
137 :file:`~/.config/ipython/profile_default`, and contain comments explaining what
159 :file:`~/.config/ipython/profile_default`, and contain comments explaining what
138 the various options do.
160 the various options do.
139
161
140 Profiles allow you to use IPython for different tasks, keeping separate config
162 Profiles allow you to use IPython for different tasks, keeping separate config
141 files and history for each one. More details in :ref:`the profiles section
163 files and history for each one. More details in :ref:`the profiles section
142 <profiles>`.
164 <profiles>`.
143
165
144 Startup Files
166 Startup Files
145 -------------
167 -------------
146
168
147 If you want some code to be run at the beginning of every IPython session, the
169 If you want some code to be run at the beginning of every IPython session, the
148 easiest way is to add Python (.py) or IPython (.ipy) scripts to your
170 easiest way is to add Python (.py) or IPython (.ipy) scripts to your
149 :file:`profile_default/startup/` directory. Files here will be executed as soon
171 :file:`profile_default/startup/` directory. Files here will be executed as soon
150 as the IPython shell is constructed, before any other code or scripts you have
172 as the IPython shell is constructed, before any other code or scripts you have
151 specified. The files will be run in order of their names, so you can control the
173 specified. The files will be run in order of their names, so you can control the
152 ordering with prefixes, like ``10-myimports.py``.
174 ordering with prefixes, like ``10-myimports.py``.
153
175
154 .. note::
176 .. note::
155
177
156 Automatic startup files are new in IPython 0.12. Use InteractiveShellApp.exec_files
178 Automatic startup files are new in IPython 0.12. Use InteractiveShellApp.exec_files
157 in :file:`ipython_config.py` for similar behavior in 0.11.
179 in :file:`ipython_config.py` for similar behavior in 0.11.
General Comments 0
You need to be logged in to leave comments. Login now