##// END OF EJS Templates
docs: add shadow history
Ville M. Vainio -
Show More
@@ -1,3162 +1,3174 b''
1 .. IPython documentation master file, created by sphinx-quickstart.py on Mon Mar 24 17:01:34 2008.
1 .. IPython documentation master file, created by sphinx-quickstart.py on Mon Mar 24 17:01:34 2008.
2 You can adapt this file completely to your liking, but it should at least
2 You can adapt this file completely to your liking, but it should at least
3 contain the root 'toctree' directive.
3 contain the root 'toctree' directive.
4
4
5 =================
5 =================
6 IPython reference
6 IPython reference
7 =================
7 =================
8
8
9 .. contents::
9 .. contents::
10
10
11 .. _command_line_options:
11 .. _command_line_options:
12
12
13 Command-line usage
13 Command-line usage
14 ==================
14 ==================
15
15
16 You start IPython with the command::
16 You start IPython with the command::
17
17
18 $ ipython [options] files
18 $ ipython [options] files
19
19
20 If invoked with no options, it executes all the files listed in sequence
20 If invoked with no options, it executes all the files listed in sequence
21 and drops you into the interpreter while still acknowledging any options
21 and drops you into the interpreter while still acknowledging any options
22 you may have set in your ipythonrc file. This behavior is different from
22 you may have set in your ipythonrc file. This behavior is different from
23 standard Python, which when called as python -i will only execute one
23 standard Python, which when called as python -i will only execute one
24 file and ignore your configuration setup.
24 file and ignore your configuration setup.
25
25
26 Please note that some of the configuration options are not available at
26 Please note that some of the configuration options are not available at
27 the command line, simply because they are not practical here. Look into
27 the command line, simply because they are not practical here. Look into
28 your ipythonrc configuration file for details on those. This file
28 your ipythonrc configuration file for details on those. This file
29 typically installed in the $HOME/.ipython directory. For Windows users,
29 typically installed in the $HOME/.ipython directory. For Windows users,
30 $HOME resolves to C:\\Documents and Settings\\YourUserName in most
30 $HOME resolves to C:\\Documents and Settings\\YourUserName in most
31 instances. In the rest of this text, we will refer to this directory as
31 instances. In the rest of this text, we will refer to this directory as
32 IPYTHONDIR.
32 IPYTHONDIR.
33
33
34 .. _Threading options:
34 .. _Threading options:
35
35
36
36
37 Special Threading Options
37 Special Threading Options
38 -------------------------
38 -------------------------
39
39
40 The following special options are ONLY valid at the beginning of the
40 The following special options are ONLY valid at the beginning of the
41 command line, and not later. This is because they control the initial-
41 command line, and not later. This is because they control the initial-
42 ization of ipython itself, before the normal option-handling mechanism
42 ization of ipython itself, before the normal option-handling mechanism
43 is active.
43 is active.
44
44
45 -gthread, -qthread, -q4thread, -wthread, -pylab:
45 -gthread, -qthread, -q4thread, -wthread, -pylab:
46 Only one of these can be given, and it can only be given as
46 Only one of these can be given, and it can only be given as
47 the first option passed to IPython (it will have no effect in
47 the first option passed to IPython (it will have no effect in
48 any other position). They provide threading support for the
48 any other position). They provide threading support for the
49 GTK, Qt (versions 3 and 4) and WXPython toolkits, and for the
49 GTK, Qt (versions 3 and 4) and WXPython toolkits, and for the
50 matplotlib library.
50 matplotlib library.
51
51
52 With any of the first four options, IPython starts running a
52 With any of the first four options, IPython starts running a
53 separate thread for the graphical toolkit's operation, so that
53 separate thread for the graphical toolkit's operation, so that
54 you can open and control graphical elements from within an
54 you can open and control graphical elements from within an
55 IPython command line, without blocking. All four provide
55 IPython command line, without blocking. All four provide
56 essentially the same functionality, respectively for GTK, Qt3,
56 essentially the same functionality, respectively for GTK, Qt3,
57 Qt4 and WXWidgets (via their Python interfaces).
57 Qt4 and WXWidgets (via their Python interfaces).
58
58
59 Note that with -wthread, you can additionally use the
59 Note that with -wthread, you can additionally use the
60 -wxversion option to request a specific version of wx to be
60 -wxversion option to request a specific version of wx to be
61 used. This requires that you have the wxversion Python module
61 used. This requires that you have the wxversion Python module
62 installed, which is part of recent wxPython distributions.
62 installed, which is part of recent wxPython distributions.
63
63
64 If -pylab is given, IPython loads special support for the mat
64 If -pylab is given, IPython loads special support for the mat
65 plotlib library (http://matplotlib.sourceforge.net), allowing
65 plotlib library (http://matplotlib.sourceforge.net), allowing
66 interactive usage of any of its backends as defined in the
66 interactive usage of any of its backends as defined in the
67 user's ~/.matplotlib/matplotlibrc file. It automatically
67 user's ~/.matplotlib/matplotlibrc file. It automatically
68 activates GTK, Qt or WX threading for IPyhton if the choice of
68 activates GTK, Qt or WX threading for IPyhton if the choice of
69 matplotlib backend requires it. It also modifies the %run
69 matplotlib backend requires it. It also modifies the %run
70 command to correctly execute (without blocking) any
70 command to correctly execute (without blocking) any
71 matplotlib-based script which calls show() at the end.
71 matplotlib-based script which calls show() at the end.
72
72
73 -tk
73 -tk
74 The -g/q/q4/wthread options, and -pylab (if matplotlib is
74 The -g/q/q4/wthread options, and -pylab (if matplotlib is
75 configured to use GTK, Qt3, Qt4 or WX), will normally block Tk
75 configured to use GTK, Qt3, Qt4 or WX), will normally block Tk
76 graphical interfaces. This means that when either GTK, Qt or WX
76 graphical interfaces. This means that when either GTK, Qt or WX
77 threading is active, any attempt to open a Tk GUI will result in a
77 threading is active, any attempt to open a Tk GUI will result in a
78 dead window, and possibly cause the Python interpreter to crash.
78 dead window, and possibly cause the Python interpreter to crash.
79 An extra option, -tk, is available to address this issue. It can
79 An extra option, -tk, is available to address this issue. It can
80 only be given as a second option after any of the above (-gthread,
80 only be given as a second option after any of the above (-gthread,
81 -wthread or -pylab).
81 -wthread or -pylab).
82
82
83 If -tk is given, IPython will try to coordinate Tk threading
83 If -tk is given, IPython will try to coordinate Tk threading
84 with GTK, Qt or WX. This is however potentially unreliable, and
84 with GTK, Qt or WX. This is however potentially unreliable, and
85 you will have to test on your platform and Python configuration to
85 you will have to test on your platform and Python configuration to
86 determine whether it works for you. Debian users have reported
86 determine whether it works for you. Debian users have reported
87 success, apparently due to the fact that Debian builds all of Tcl,
87 success, apparently due to the fact that Debian builds all of Tcl,
88 Tk, Tkinter and Python with pthreads support. Under other Linux
88 Tk, Tkinter and Python with pthreads support. Under other Linux
89 environments (such as Fedora Core 2/3), this option has caused
89 environments (such as Fedora Core 2/3), this option has caused
90 random crashes and lockups of the Python interpreter. Under other
90 random crashes and lockups of the Python interpreter. Under other
91 operating systems (Mac OSX and Windows), you'll need to try it to
91 operating systems (Mac OSX and Windows), you'll need to try it to
92 find out, since currently no user reports are available.
92 find out, since currently no user reports are available.
93
93
94 There is unfortunately no way for IPython to determine at run time
94 There is unfortunately no way for IPython to determine at run time
95 whether -tk will work reliably or not, so you will need to do some
95 whether -tk will work reliably or not, so you will need to do some
96 experiments before relying on it for regular work.
96 experiments before relying on it for regular work.
97
97
98
98
99
99
100 Regular Options
100 Regular Options
101 ---------------
101 ---------------
102
102
103 After the above threading options have been given, regular options can
103 After the above threading options have been given, regular options can
104 follow in any order. All options can be abbreviated to their shortest
104 follow in any order. All options can be abbreviated to their shortest
105 non-ambiguous form and are case-sensitive. One or two dashes can be
105 non-ambiguous form and are case-sensitive. One or two dashes can be
106 used. Some options have an alternate short form, indicated after a ``|``.
106 used. Some options have an alternate short form, indicated after a ``|``.
107
107
108 Most options can also be set from your ipythonrc configuration file. See
108 Most options can also be set from your ipythonrc configuration file. See
109 the provided example for more details on what the options do. Options
109 the provided example for more details on what the options do. Options
110 given at the command line override the values set in the ipythonrc file.
110 given at the command line override the values set in the ipythonrc file.
111
111
112 All options with a [no] prepended can be specified in negated form
112 All options with a [no] prepended can be specified in negated form
113 (-nooption instead of -option) to turn the feature off.
113 (-nooption instead of -option) to turn the feature off.
114
114
115 -help print a help message and exit.
115 -help print a help message and exit.
116
116
117 -pylab
117 -pylab
118 this can only be given as the first option passed to IPython
118 this can only be given as the first option passed to IPython
119 (it will have no effect in any other position). It adds
119 (it will have no effect in any other position). It adds
120 special support for the matplotlib library
120 special support for the matplotlib library
121 (http://matplotlib.sourceforge.ne), allowing interactive usage
121 (http://matplotlib.sourceforge.ne), allowing interactive usage
122 of any of its backends as defined in the user's .matplotlibrc
122 of any of its backends as defined in the user's .matplotlibrc
123 file. It automatically activates GTK or WX threading for
123 file. It automatically activates GTK or WX threading for
124 IPyhton if the choice of matplotlib backend requires it. It
124 IPyhton if the choice of matplotlib backend requires it. It
125 also modifies the %run command to correctly execute (without
125 also modifies the %run command to correctly execute (without
126 blocking) any matplotlib-based script which calls show() at
126 blocking) any matplotlib-based script which calls show() at
127 the end. See `Matplotlib support`_ for more details.
127 the end. See `Matplotlib support`_ for more details.
128
128
129 -autocall <val>
129 -autocall <val>
130 Make IPython automatically call any callable object even if you
130 Make IPython automatically call any callable object even if you
131 didn't type explicit parentheses. For example, 'str 43' becomes
131 didn't type explicit parentheses. For example, 'str 43' becomes
132 'str(43)' automatically. The value can be '0' to disable the feature,
132 'str(43)' automatically. The value can be '0' to disable the feature,
133 '1' for smart autocall, where it is not applied if there are no more
133 '1' for smart autocall, where it is not applied if there are no more
134 arguments on the line, and '2' for full autocall, where all callable
134 arguments on the line, and '2' for full autocall, where all callable
135 objects are automatically called (even if no arguments are
135 objects are automatically called (even if no arguments are
136 present). The default is '1'.
136 present). The default is '1'.
137
137
138 -[no]autoindent
138 -[no]autoindent
139 Turn automatic indentation on/off.
139 Turn automatic indentation on/off.
140
140
141 -[no]automagic
141 -[no]automagic
142 make magic commands automatic (without needing their first character
142 make magic commands automatic (without needing their first character
143 to be %). Type %magic at the IPython prompt for more information.
143 to be %). Type %magic at the IPython prompt for more information.
144
144
145 -[no]autoedit_syntax
145 -[no]autoedit_syntax
146 When a syntax error occurs after editing a file, automatically
146 When a syntax error occurs after editing a file, automatically
147 open the file to the trouble causing line for convenient
147 open the file to the trouble causing line for convenient
148 fixing.
148 fixing.
149
149
150 -[no]banner Print the initial information banner (default on).
150 -[no]banner Print the initial information banner (default on).
151
151
152 -c <command>
152 -c <command>
153 execute the given command string. This is similar to the -c
153 execute the given command string. This is similar to the -c
154 option in the normal Python interpreter.
154 option in the normal Python interpreter.
155
155
156 -cache_size, cs <n>
156 -cache_size, cs <n>
157 size of the output cache (maximum number of entries to hold in
157 size of the output cache (maximum number of entries to hold in
158 memory). The default is 1000, you can change it permanently in your
158 memory). The default is 1000, you can change it permanently in your
159 config file. Setting it to 0 completely disables the caching system,
159 config file. Setting it to 0 completely disables the caching system,
160 and the minimum value accepted is 20 (if you provide a value less than
160 and the minimum value accepted is 20 (if you provide a value less than
161 20, it is reset to 0 and a warning is issued) This limit is defined
161 20, it is reset to 0 and a warning is issued) This limit is defined
162 because otherwise you'll spend more time re-flushing a too small cache
162 because otherwise you'll spend more time re-flushing a too small cache
163 than working.
163 than working.
164
164
165 -classic, cl
165 -classic, cl
166 Gives IPython a similar feel to the classic Python
166 Gives IPython a similar feel to the classic Python
167 prompt.
167 prompt.
168
168
169 -colors <scheme>
169 -colors <scheme>
170 Color scheme for prompts and exception reporting. Currently
170 Color scheme for prompts and exception reporting. Currently
171 implemented: NoColor, Linux and LightBG.
171 implemented: NoColor, Linux and LightBG.
172
172
173 -[no]color_info
173 -[no]color_info
174 IPython can display information about objects via a set of functions,
174 IPython can display information about objects via a set of functions,
175 and optionally can use colors for this, syntax highlighting source
175 and optionally can use colors for this, syntax highlighting source
176 code and various other elements. However, because this information is
176 code and various other elements. However, because this information is
177 passed through a pager (like 'less') and many pagers get confused with
177 passed through a pager (like 'less') and many pagers get confused with
178 color codes, this option is off by default. You can test it and turn
178 color codes, this option is off by default. You can test it and turn
179 it on permanently in your ipythonrc file if it works for you. As a
179 it on permanently in your ipythonrc file if it works for you. As a
180 reference, the 'less' pager supplied with Mandrake 8.2 works ok, but
180 reference, the 'less' pager supplied with Mandrake 8.2 works ok, but
181 that in RedHat 7.2 doesn't.
181 that in RedHat 7.2 doesn't.
182
182
183 Test it and turn it on permanently if it works with your
183 Test it and turn it on permanently if it works with your
184 system. The magic function %color_info allows you to toggle this
184 system. The magic function %color_info allows you to toggle this
185 interactively for testing.
185 interactively for testing.
186
186
187 -[no]debug
187 -[no]debug
188 Show information about the loading process. Very useful to pin down
188 Show information about the loading process. Very useful to pin down
189 problems with your configuration files or to get details about
189 problems with your configuration files or to get details about
190 session restores.
190 session restores.
191
191
192 -[no]deep_reload:
192 -[no]deep_reload:
193 IPython can use the deep_reload module which reloads changes in
193 IPython can use the deep_reload module which reloads changes in
194 modules recursively (it replaces the reload() function, so you don't
194 modules recursively (it replaces the reload() function, so you don't
195 need to change anything to use it). deep_reload() forces a full
195 need to change anything to use it). deep_reload() forces a full
196 reload of modules whose code may have changed, which the default
196 reload of modules whose code may have changed, which the default
197 reload() function does not.
197 reload() function does not.
198
198
199 When deep_reload is off, IPython will use the normal reload(),
199 When deep_reload is off, IPython will use the normal reload(),
200 but deep_reload will still be available as dreload(). This
200 but deep_reload will still be available as dreload(). This
201 feature is off by default [which means that you have both
201 feature is off by default [which means that you have both
202 normal reload() and dreload()].
202 normal reload() and dreload()].
203
203
204 -editor <name>
204 -editor <name>
205 Which editor to use with the %edit command. By default,
205 Which editor to use with the %edit command. By default,
206 IPython will honor your EDITOR environment variable (if not
206 IPython will honor your EDITOR environment variable (if not
207 set, vi is the Unix default and notepad the Windows one).
207 set, vi is the Unix default and notepad the Windows one).
208 Since this editor is invoked on the fly by IPython and is
208 Since this editor is invoked on the fly by IPython and is
209 meant for editing small code snippets, you may want to use a
209 meant for editing small code snippets, you may want to use a
210 small, lightweight editor here (in case your default EDITOR is
210 small, lightweight editor here (in case your default EDITOR is
211 something like Emacs).
211 something like Emacs).
212
212
213 -ipythondir <name>
213 -ipythondir <name>
214 name of your IPython configuration directory IPYTHONDIR. This
214 name of your IPython configuration directory IPYTHONDIR. This
215 can also be specified through the environment variable
215 can also be specified through the environment variable
216 IPYTHONDIR.
216 IPYTHONDIR.
217
217
218 -log, l
218 -log, l
219 generate a log file of all input. The file is named
219 generate a log file of all input. The file is named
220 ipython_log.py in your current directory (which prevents logs
220 ipython_log.py in your current directory (which prevents logs
221 from multiple IPython sessions from trampling each other). You
221 from multiple IPython sessions from trampling each other). You
222 can use this to later restore a session by loading your
222 can use this to later restore a session by loading your
223 logfile as a file to be executed with option -logplay (see
223 logfile as a file to be executed with option -logplay (see
224 below).
224 below).
225
225
226 -logfile, lf <name> specify the name of your logfile.
226 -logfile, lf <name> specify the name of your logfile.
227
227
228 -logplay, lp <name>
228 -logplay, lp <name>
229
229
230 you can replay a previous log. For restoring a session as close as
230 you can replay a previous log. For restoring a session as close as
231 possible to the state you left it in, use this option (don't just run
231 possible to the state you left it in, use this option (don't just run
232 the logfile). With -logplay, IPython will try to reconstruct the
232 the logfile). With -logplay, IPython will try to reconstruct the
233 previous working environment in full, not just execute the commands in
233 previous working environment in full, not just execute the commands in
234 the logfile.
234 the logfile.
235
235
236 When a session is restored, logging is automatically turned on
236 When a session is restored, logging is automatically turned on
237 again with the name of the logfile it was invoked with (it is
237 again with the name of the logfile it was invoked with (it is
238 read from the log header). So once you've turned logging on for
238 read from the log header). So once you've turned logging on for
239 a session, you can quit IPython and reload it as many times as
239 a session, you can quit IPython and reload it as many times as
240 you want and it will continue to log its history and restore
240 you want and it will continue to log its history and restore
241 from the beginning every time.
241 from the beginning every time.
242
242
243 Caveats: there are limitations in this option. The history
243 Caveats: there are limitations in this option. The history
244 variables _i*,_* and _dh don't get restored properly. In the
244 variables _i*,_* and _dh don't get restored properly. In the
245 future we will try to implement full session saving by writing
245 future we will try to implement full session saving by writing
246 and retrieving a 'snapshot' of the memory state of IPython. But
246 and retrieving a 'snapshot' of the memory state of IPython. But
247 our first attempts failed because of inherent limitations of
247 our first attempts failed because of inherent limitations of
248 Python's Pickle module, so this may have to wait.
248 Python's Pickle module, so this may have to wait.
249
249
250 -[no]messages
250 -[no]messages
251 Print messages which IPython collects about its startup
251 Print messages which IPython collects about its startup
252 process (default on).
252 process (default on).
253
253
254 -[no]pdb
254 -[no]pdb
255 Automatically call the pdb debugger after every uncaught
255 Automatically call the pdb debugger after every uncaught
256 exception. If you are used to debugging using pdb, this puts
256 exception. If you are used to debugging using pdb, this puts
257 you automatically inside of it after any call (either in
257 you automatically inside of it after any call (either in
258 IPython or in code called by it) which triggers an exception
258 IPython or in code called by it) which triggers an exception
259 which goes uncaught.
259 which goes uncaught.
260
260
261 -pydb
261 -pydb
262 Makes IPython use the third party "pydb" package as debugger,
262 Makes IPython use the third party "pydb" package as debugger,
263 instead of pdb. Requires that pydb is installed.
263 instead of pdb. Requires that pydb is installed.
264
264
265 -[no]pprint
265 -[no]pprint
266 ipython can optionally use the pprint (pretty printer) module
266 ipython can optionally use the pprint (pretty printer) module
267 for displaying results. pprint tends to give a nicer display
267 for displaying results. pprint tends to give a nicer display
268 of nested data structures. If you like it, you can turn it on
268 of nested data structures. If you like it, you can turn it on
269 permanently in your config file (default off).
269 permanently in your config file (default off).
270
270
271 -profile, p <name>
271 -profile, p <name>
272
272
273 assume that your config file is ipythonrc-<name> or
273 assume that your config file is ipythonrc-<name> or
274 ipy_profile_<name>.py (looks in current dir first, then in
274 ipy_profile_<name>.py (looks in current dir first, then in
275 IPYTHONDIR). This is a quick way to keep and load multiple
275 IPYTHONDIR). This is a quick way to keep and load multiple
276 config files for different tasks, especially if you use the
276 config files for different tasks, especially if you use the
277 include option of config files. You can keep a basic
277 include option of config files. You can keep a basic
278 IPYTHONDIR/ipythonrc file and then have other 'profiles' which
278 IPYTHONDIR/ipythonrc file and then have other 'profiles' which
279 include this one and load extra things for particular
279 include this one and load extra things for particular
280 tasks. For example:
280 tasks. For example:
281
281
282 1. $HOME/.ipython/ipythonrc : load basic things you always want.
282 1. $HOME/.ipython/ipythonrc : load basic things you always want.
283 2. $HOME/.ipython/ipythonrc-math : load (1) and basic math-related modules.
283 2. $HOME/.ipython/ipythonrc-math : load (1) and basic math-related modules.
284 3. $HOME/.ipython/ipythonrc-numeric : load (1) and Numeric and plotting modules.
284 3. $HOME/.ipython/ipythonrc-numeric : load (1) and Numeric and plotting modules.
285
285
286 Since it is possible to create an endless loop by having
286 Since it is possible to create an endless loop by having
287 circular file inclusions, IPython will stop if it reaches 15
287 circular file inclusions, IPython will stop if it reaches 15
288 recursive inclusions.
288 recursive inclusions.
289
289
290 -prompt_in1, pi1 <string>
290 -prompt_in1, pi1 <string>
291
291
292 Specify the string used for input prompts. Note that if you are using
292 Specify the string used for input prompts. Note that if you are using
293 numbered prompts, the number is represented with a '\#' in the
293 numbered prompts, the number is represented with a '\#' in the
294 string. Don't forget to quote strings with spaces embedded in
294 string. Don't forget to quote strings with spaces embedded in
295 them. Default: 'In [\#]:'. The :ref:`prompts section <prompts>`
295 them. Default: 'In [\#]:'. The :ref:`prompts section <prompts>`
296 discusses in detail all the available escapes to customize your
296 discusses in detail all the available escapes to customize your
297 prompts.
297 prompts.
298
298
299 -prompt_in2, pi2 <string>
299 -prompt_in2, pi2 <string>
300 Similar to the previous option, but used for the continuation
300 Similar to the previous option, but used for the continuation
301 prompts. The special sequence '\D' is similar to '\#', but
301 prompts. The special sequence '\D' is similar to '\#', but
302 with all digits replaced dots (so you can have your
302 with all digits replaced dots (so you can have your
303 continuation prompt aligned with your input prompt). Default:
303 continuation prompt aligned with your input prompt). Default:
304 ' .\D.:' (note three spaces at the start for alignment with
304 ' .\D.:' (note three spaces at the start for alignment with
305 'In [\#]').
305 'In [\#]').
306
306
307 -prompt_out,po <string>
307 -prompt_out,po <string>
308 String used for output prompts, also uses numbers like
308 String used for output prompts, also uses numbers like
309 prompt_in1. Default: 'Out[\#]:'
309 prompt_in1. Default: 'Out[\#]:'
310
310
311 -quick start in bare bones mode (no config file loaded).
311 -quick start in bare bones mode (no config file loaded).
312
312
313 -rcfile <name>
313 -rcfile <name>
314 name of your IPython resource configuration file. Normally
314 name of your IPython resource configuration file. Normally
315 IPython loads ipythonrc (from current directory) or
315 IPython loads ipythonrc (from current directory) or
316 IPYTHONDIR/ipythonrc.
316 IPYTHONDIR/ipythonrc.
317
317
318 If the loading of your config file fails, IPython starts with
318 If the loading of your config file fails, IPython starts with
319 a bare bones configuration (no modules loaded at all).
319 a bare bones configuration (no modules loaded at all).
320
320
321 -[no]readline
321 -[no]readline
322 use the readline library, which is needed to support name
322 use the readline library, which is needed to support name
323 completion and command history, among other things. It is
323 completion and command history, among other things. It is
324 enabled by default, but may cause problems for users of
324 enabled by default, but may cause problems for users of
325 X/Emacs in Python comint or shell buffers.
325 X/Emacs in Python comint or shell buffers.
326
326
327 Note that X/Emacs 'eterm' buffers (opened with M-x term) support
327 Note that X/Emacs 'eterm' buffers (opened with M-x term) support
328 IPython's readline and syntax coloring fine, only 'emacs' (M-x
328 IPython's readline and syntax coloring fine, only 'emacs' (M-x
329 shell and C-c !) buffers do not.
329 shell and C-c !) buffers do not.
330
330
331 -screen_length, sl <n>
331 -screen_length, sl <n>
332 number of lines of your screen. This is used to control
332 number of lines of your screen. This is used to control
333 printing of very long strings. Strings longer than this number
333 printing of very long strings. Strings longer than this number
334 of lines will be sent through a pager instead of directly
334 of lines will be sent through a pager instead of directly
335 printed.
335 printed.
336
336
337 The default value for this is 0, which means IPython will
337 The default value for this is 0, which means IPython will
338 auto-detect your screen size every time it needs to print certain
338 auto-detect your screen size every time it needs to print certain
339 potentially long strings (this doesn't change the behavior of the
339 potentially long strings (this doesn't change the behavior of the
340 'print' keyword, it's only triggered internally). If for some
340 'print' keyword, it's only triggered internally). If for some
341 reason this isn't working well (it needs curses support), specify
341 reason this isn't working well (it needs curses support), specify
342 it yourself. Otherwise don't change the default.
342 it yourself. Otherwise don't change the default.
343
343
344 -separate_in, si <string>
344 -separate_in, si <string>
345
345
346 separator before input prompts.
346 separator before input prompts.
347 Default: '\n'
347 Default: '\n'
348
348
349 -separate_out, so <string>
349 -separate_out, so <string>
350 separator before output prompts.
350 separator before output prompts.
351 Default: nothing.
351 Default: nothing.
352
352
353 -separate_out2, so2
353 -separate_out2, so2
354 separator after output prompts.
354 separator after output prompts.
355 Default: nothing.
355 Default: nothing.
356 For these three options, use the value 0 to specify no separator.
356 For these three options, use the value 0 to specify no separator.
357
357
358 -nosep
358 -nosep
359 shorthand for '-SeparateIn 0 -SeparateOut 0 -SeparateOut2
359 shorthand for '-SeparateIn 0 -SeparateOut 0 -SeparateOut2
360 0'. Simply removes all input/output separators.
360 0'. Simply removes all input/output separators.
361
361
362 -upgrade
362 -upgrade
363 allows you to upgrade your IPYTHONDIR configuration when you
363 allows you to upgrade your IPYTHONDIR configuration when you
364 install a new version of IPython. Since new versions may
364 install a new version of IPython. Since new versions may
365 include new command line options or example files, this copies
365 include new command line options or example files, this copies
366 updated ipythonrc-type files. However, it backs up (with a
366 updated ipythonrc-type files. However, it backs up (with a
367 .old extension) all files which it overwrites so that you can
367 .old extension) all files which it overwrites so that you can
368 merge back any customizations you might have in your personal
368 merge back any customizations you might have in your personal
369 files. Note that you should probably use %upgrade instead,
369 files. Note that you should probably use %upgrade instead,
370 it's a safer alternative.
370 it's a safer alternative.
371
371
372
372
373 -Version print version information and exit.
373 -Version print version information and exit.
374
374
375 -wxversion <string>
375 -wxversion <string>
376 Select a specific version of wxPython (used in conjunction
376 Select a specific version of wxPython (used in conjunction
377 with -wthread). Requires the wxversion module, part of recent
377 with -wthread). Requires the wxversion module, part of recent
378 wxPython distributions
378 wxPython distributions
379
379
380 -xmode <modename>
380 -xmode <modename>
381
381
382 Mode for exception reporting.
382 Mode for exception reporting.
383
383
384 Valid modes: Plain, Context and Verbose.
384 Valid modes: Plain, Context and Verbose.
385
385
386 * Plain: similar to python's normal traceback printing.
386 * Plain: similar to python's normal traceback printing.
387 * Context: prints 5 lines of context source code around each
387 * Context: prints 5 lines of context source code around each
388 line in the traceback.
388 line in the traceback.
389 * Verbose: similar to Context, but additionally prints the
389 * Verbose: similar to Context, but additionally prints the
390 variables currently visible where the exception happened
390 variables currently visible where the exception happened
391 (shortening their strings if too long). This can potentially be
391 (shortening their strings if too long). This can potentially be
392 very slow, if you happen to have a huge data structure whose
392 very slow, if you happen to have a huge data structure whose
393 string representation is complex to compute. Your computer may
393 string representation is complex to compute. Your computer may
394 appear to freeze for a while with cpu usage at 100%. If this
394 appear to freeze for a while with cpu usage at 100%. If this
395 occurs, you can cancel the traceback with Ctrl-C (maybe hitting it
395 occurs, you can cancel the traceback with Ctrl-C (maybe hitting it
396 more than once).
396 more than once).
397
397
398 Interactive use
398 Interactive use
399 ===============
399 ===============
400
400
401 Warning: IPython relies on the existence of a global variable called
401 Warning: IPython relies on the existence of a global variable called
402 _ip which controls the shell itself. If you redefine _ip to anything,
402 _ip which controls the shell itself. If you redefine _ip to anything,
403 bizarre behavior will quickly occur.
403 bizarre behavior will quickly occur.
404
404
405 Other than the above warning, IPython is meant to work as a drop-in
405 Other than the above warning, IPython is meant to work as a drop-in
406 replacement for the standard interactive interpreter. As such, any code
406 replacement for the standard interactive interpreter. As such, any code
407 which is valid python should execute normally under IPython (cases where
407 which is valid python should execute normally under IPython (cases where
408 this is not true should be reported as bugs). It does, however, offer
408 this is not true should be reported as bugs). It does, however, offer
409 many features which are not available at a standard python prompt. What
409 many features which are not available at a standard python prompt. What
410 follows is a list of these.
410 follows is a list of these.
411
411
412
412
413 Caution for Windows users
413 Caution for Windows users
414 -------------------------
414 -------------------------
415
415
416 Windows, unfortunately, uses the '\' character as a path
416 Windows, unfortunately, uses the '\' character as a path
417 separator. This is a terrible choice, because '\' also represents the
417 separator. This is a terrible choice, because '\' also represents the
418 escape character in most modern programming languages, including
418 escape character in most modern programming languages, including
419 Python. For this reason, using '/' character is recommended if you
419 Python. For this reason, using '/' character is recommended if you
420 have problems with ``\``. However, in Windows commands '/' flags
420 have problems with ``\``. However, in Windows commands '/' flags
421 options, so you can not use it for the root directory. This means that
421 options, so you can not use it for the root directory. This means that
422 paths beginning at the root must be typed in a contrived manner like:
422 paths beginning at the root must be typed in a contrived manner like:
423 ``%copy \opt/foo/bar.txt \tmp``
423 ``%copy \opt/foo/bar.txt \tmp``
424
424
425 .. _magic:
425 .. _magic:
426
426
427 Magic command system
427 Magic command system
428 --------------------
428 --------------------
429
429
430 IPython will treat any line whose first character is a % as a special
430 IPython will treat any line whose first character is a % as a special
431 call to a 'magic' function. These allow you to control the behavior of
431 call to a 'magic' function. These allow you to control the behavior of
432 IPython itself, plus a lot of system-type features. They are all
432 IPython itself, plus a lot of system-type features. They are all
433 prefixed with a % character, but parameters are given without
433 prefixed with a % character, but parameters are given without
434 parentheses or quotes.
434 parentheses or quotes.
435
435
436 Example: typing '%cd mydir' (without the quotes) changes you working
436 Example: typing '%cd mydir' (without the quotes) changes you working
437 directory to 'mydir', if it exists.
437 directory to 'mydir', if it exists.
438
438
439 If you have 'automagic' enabled (in your ipythonrc file, via the command
439 If you have 'automagic' enabled (in your ipythonrc file, via the command
440 line option -automagic or with the %automagic function), you don't need
440 line option -automagic or with the %automagic function), you don't need
441 to type in the % explicitly. IPython will scan its internal list of
441 to type in the % explicitly. IPython will scan its internal list of
442 magic functions and call one if it exists. With automagic on you can
442 magic functions and call one if it exists. With automagic on you can
443 then just type 'cd mydir' to go to directory 'mydir'. The automagic
443 then just type 'cd mydir' to go to directory 'mydir'. The automagic
444 system has the lowest possible precedence in name searches, so defining
444 system has the lowest possible precedence in name searches, so defining
445 an identifier with the same name as an existing magic function will
445 an identifier with the same name as an existing magic function will
446 shadow it for automagic use. You can still access the shadowed magic
446 shadow it for automagic use. You can still access the shadowed magic
447 function by explicitly using the % character at the beginning of the line.
447 function by explicitly using the % character at the beginning of the line.
448
448
449 An example (with automagic on) should clarify all this::
449 An example (with automagic on) should clarify all this::
450
450
451 In [1]: cd ipython # %cd is called by automagic
451 In [1]: cd ipython # %cd is called by automagic
452
452
453 /home/fperez/ipython
453 /home/fperez/ipython
454
454
455 In [2]: cd=1 # now cd is just a variable
455 In [2]: cd=1 # now cd is just a variable
456
456
457 In [3]: cd .. # and doesn't work as a function anymore
457 In [3]: cd .. # and doesn't work as a function anymore
458
458
459 ------------------------------
459 ------------------------------
460
460
461 File "<console>", line 1
461 File "<console>", line 1
462
462
463 cd ..
463 cd ..
464
464
465 ^
465 ^
466
466
467 SyntaxError: invalid syntax
467 SyntaxError: invalid syntax
468
468
469 In [4]: %cd .. # but %cd always works
469 In [4]: %cd .. # but %cd always works
470
470
471 /home/fperez
471 /home/fperez
472
472
473 In [5]: del cd # if you remove the cd variable
473 In [5]: del cd # if you remove the cd variable
474
474
475 In [6]: cd ipython # automagic can work again
475 In [6]: cd ipython # automagic can work again
476
476
477 /home/fperez/ipython
477 /home/fperez/ipython
478
478
479 You can define your own magic functions to extend the system. The
479 You can define your own magic functions to extend the system. The
480 following example defines a new magic command, %impall::
480 following example defines a new magic command, %impall::
481
481
482 import IPython.ipapi
482 import IPython.ipapi
483
483
484 ip = IPython.ipapi.get()
484 ip = IPython.ipapi.get()
485
485
486 def doimp(self, arg):
486 def doimp(self, arg):
487
487
488 ip = self.api
488 ip = self.api
489
489
490 ip.ex("import %s; reload(%s); from %s import *" % (
490 ip.ex("import %s; reload(%s); from %s import *" % (
491
491
492 arg,arg,arg)
492 arg,arg,arg)
493
493
494 )
494 )
495
495
496 ip.expose_magic('impall', doimp)
496 ip.expose_magic('impall', doimp)
497
497
498 You can also define your own aliased names for magic functions. In your
498 You can also define your own aliased names for magic functions. In your
499 ipythonrc file, placing a line like:
499 ipythonrc file, placing a line like:
500
500
501 execute __IP.magic_cl = __IP.magic_clear
501 execute __IP.magic_cl = __IP.magic_clear
502
502
503 will define %cl as a new name for %clear.
503 will define %cl as a new name for %clear.
504
504
505 Type %magic for more information, including a list of all available
505 Type %magic for more information, including a list of all available
506 magic functions at any time and their docstrings. You can also type
506 magic functions at any time and their docstrings. You can also type
507 %magic_function_name? (see sec. 6.4 <#sec:dyn-object-info> for
507 %magic_function_name? (see sec. 6.4 <#sec:dyn-object-info> for
508 information on the '?' system) to get information about any particular
508 information on the '?' system) to get information about any particular
509 magic function you are interested in.
509 magic function you are interested in.
510
510
511
511
512 Magic commands
512 Magic commands
513 --------------
513 --------------
514
514
515 The rest of this section is automatically generated for each release
515 The rest of this section is automatically generated for each release
516 from the docstrings in the IPython code. Therefore the formatting is
516 from the docstrings in the IPython code. Therefore the formatting is
517 somewhat minimal, but this method has the advantage of having
517 somewhat minimal, but this method has the advantage of having
518 information always in sync with the code.
518 information always in sync with the code.
519
519
520 A list of all the magic commands available in IPython's default
520 A list of all the magic commands available in IPython's default
521 installation follows. This is similar to what you'll see by simply
521 installation follows. This is similar to what you'll see by simply
522 typing %magic at the prompt, but that will also give you information
522 typing %magic at the prompt, but that will also give you information
523 about magic commands you may have added as part of your personal
523 about magic commands you may have added as part of your personal
524 customizations.
524 customizations.
525
525
526 .. magic_start
526 .. magic_start
527
527
528 **%Exit**::
528 **%Exit**::
529
529
530 Exit IPython without confirmation.
530 Exit IPython without confirmation.
531
531
532 **%Pprint**::
532 **%Pprint**::
533
533
534 Toggle pretty printing on/off.
534 Toggle pretty printing on/off.
535
535
536 **%alias**::
536 **%alias**::
537
537
538 Define an alias for a system command.
538 Define an alias for a system command.
539
539
540 '%alias alias_name cmd' defines 'alias_name' as an alias for 'cmd'
540 '%alias alias_name cmd' defines 'alias_name' as an alias for 'cmd'
541
541
542 Then, typing 'alias_name params' will execute the system command 'cmd
542 Then, typing 'alias_name params' will execute the system command 'cmd
543 params' (from your underlying operating system).
543 params' (from your underlying operating system).
544
544
545 Aliases have lower precedence than magic functions and Python normal
545 Aliases have lower precedence than magic functions and Python normal
546 variables, so if 'foo' is both a Python variable and an alias, the
546 variables, so if 'foo' is both a Python variable and an alias, the
547 alias can not be executed until 'del foo' removes the Python variable.
547 alias can not be executed until 'del foo' removes the Python variable.
548
548
549 You can use the %l specifier in an alias definition to represent the
549 You can use the %l specifier in an alias definition to represent the
550 whole line when the alias is called. For example:
550 whole line when the alias is called. For example:
551
551
552 In [2]: alias all echo "Input in brackets: <%l>"\
552 In [2]: alias all echo "Input in brackets: <%l>"\
553 In [3]: all hello world\
553 In [3]: all hello world\
554 Input in brackets: <hello world>
554 Input in brackets: <hello world>
555
555
556 You can also define aliases with parameters using %s specifiers (one
556 You can also define aliases with parameters using %s specifiers (one
557 per parameter):
557 per parameter):
558
558
559 In [1]: alias parts echo first %s second %s\
559 In [1]: alias parts echo first %s second %s\
560 In [2]: %parts A B\
560 In [2]: %parts A B\
561 first A second B\
561 first A second B\
562 In [3]: %parts A\
562 In [3]: %parts A\
563 Incorrect number of arguments: 2 expected.\
563 Incorrect number of arguments: 2 expected.\
564 parts is an alias to: 'echo first %s second %s'
564 parts is an alias to: 'echo first %s second %s'
565
565
566 Note that %l and %s are mutually exclusive. You can only use one or
566 Note that %l and %s are mutually exclusive. You can only use one or
567 the other in your aliases.
567 the other in your aliases.
568
568
569 Aliases expand Python variables just like system calls using ! or !!
569 Aliases expand Python variables just like system calls using ! or !!
570 do: all expressions prefixed with '$' get expanded. For details of
570 do: all expressions prefixed with '$' get expanded. For details of
571 the semantic rules, see PEP-215:
571 the semantic rules, see PEP-215:
572 http://www.python.org/peps/pep-0215.html. This is the library used by
572 http://www.python.org/peps/pep-0215.html. This is the library used by
573 IPython for variable expansion. If you want to access a true shell
573 IPython for variable expansion. If you want to access a true shell
574 variable, an extra $ is necessary to prevent its expansion by IPython:
574 variable, an extra $ is necessary to prevent its expansion by IPython:
575
575
576 In [6]: alias show echo\
576 In [6]: alias show echo\
577 In [7]: PATH='A Python string'\
577 In [7]: PATH='A Python string'\
578 In [8]: show $PATH\
578 In [8]: show $PATH\
579 A Python string\
579 A Python string\
580 In [9]: show $$PATH\
580 In [9]: show $$PATH\
581 /usr/local/lf9560/bin:/usr/local/intel/compiler70/ia32/bin:...
581 /usr/local/lf9560/bin:/usr/local/intel/compiler70/ia32/bin:...
582
582
583 You can use the alias facility to acess all of $PATH. See the %rehash
583 You can use the alias facility to acess all of $PATH. See the %rehash
584 and %rehashx functions, which automatically create aliases for the
584 and %rehashx functions, which automatically create aliases for the
585 contents of your $PATH.
585 contents of your $PATH.
586
586
587 If called with no parameters, %alias prints the current alias table.
587 If called with no parameters, %alias prints the current alias table.
588
588
589 **%autocall**::
589 **%autocall**::
590
590
591 Make functions callable without having to type parentheses.
591 Make functions callable without having to type parentheses.
592
592
593 Usage:
593 Usage:
594
594
595 %autocall [mode]
595 %autocall [mode]
596
596
597 The mode can be one of: 0->Off, 1->Smart, 2->Full. If not given, the
597 The mode can be one of: 0->Off, 1->Smart, 2->Full. If not given, the
598 value is toggled on and off (remembering the previous state).
598 value is toggled on and off (remembering the previous state).
599
599
600 In more detail, these values mean:
600 In more detail, these values mean:
601
601
602 0 -> fully disabled
602 0 -> fully disabled
603
603
604 1 -> active, but do not apply if there are no arguments on the line.
604 1 -> active, but do not apply if there are no arguments on the line.
605
605
606 In this mode, you get:
606 In this mode, you get:
607
607
608 In [1]: callable
608 In [1]: callable
609 Out[1]: <built-in function callable>
609 Out[1]: <built-in function callable>
610
610
611 In [2]: callable 'hello'
611 In [2]: callable 'hello'
612 ------> callable('hello')
612 ------> callable('hello')
613 Out[2]: False
613 Out[2]: False
614
614
615 2 -> Active always. Even if no arguments are present, the callable
615 2 -> Active always. Even if no arguments are present, the callable
616 object is called:
616 object is called:
617
617
618 In [4]: callable
618 In [4]: callable
619 ------> callable()
619 ------> callable()
620
620
621 Note that even with autocall off, you can still use '/' at the start of
621 Note that even with autocall off, you can still use '/' at the start of
622 a line to treat the first argument on the command line as a function
622 a line to treat the first argument on the command line as a function
623 and add parentheses to it:
623 and add parentheses to it:
624
624
625 In [8]: /str 43
625 In [8]: /str 43
626 ------> str(43)
626 ------> str(43)
627 Out[8]: '43'
627 Out[8]: '43'
628
628
629 **%autoindent**::
629 **%autoindent**::
630
630
631 Toggle autoindent on/off (if available).
631 Toggle autoindent on/off (if available).
632
632
633 **%automagic**::
633 **%automagic**::
634
634
635 Make magic functions callable without having to type the initial %.
635 Make magic functions callable without having to type the initial %.
636
636
637 Without argumentsl toggles on/off (when off, you must call it as
637 Without argumentsl toggles on/off (when off, you must call it as
638 %automagic, of course). With arguments it sets the value, and you can
638 %automagic, of course). With arguments it sets the value, and you can
639 use any of (case insensitive):
639 use any of (case insensitive):
640
640
641 - on,1,True: to activate
641 - on,1,True: to activate
642
642
643 - off,0,False: to deactivate.
643 - off,0,False: to deactivate.
644
644
645 Note that magic functions have lowest priority, so if there's a
645 Note that magic functions have lowest priority, so if there's a
646 variable whose name collides with that of a magic fn, automagic won't
646 variable whose name collides with that of a magic fn, automagic won't
647 work for that function (you get the variable instead). However, if you
647 work for that function (you get the variable instead). However, if you
648 delete the variable (del var), the previously shadowed magic function
648 delete the variable (del var), the previously shadowed magic function
649 becomes visible to automagic again.
649 becomes visible to automagic again.
650
650
651 **%bg**::
651 **%bg**::
652
652
653 Run a job in the background, in a separate thread.
653 Run a job in the background, in a separate thread.
654
654
655 For example,
655 For example,
656
656
657 %bg myfunc(x,y,z=1)
657 %bg myfunc(x,y,z=1)
658
658
659 will execute 'myfunc(x,y,z=1)' in a background thread. As soon as the
659 will execute 'myfunc(x,y,z=1)' in a background thread. As soon as the
660 execution starts, a message will be printed indicating the job
660 execution starts, a message will be printed indicating the job
661 number. If your job number is 5, you can use
661 number. If your job number is 5, you can use
662
662
663 myvar = jobs.result(5) or myvar = jobs[5].result
663 myvar = jobs.result(5) or myvar = jobs[5].result
664
664
665 to assign this result to variable 'myvar'.
665 to assign this result to variable 'myvar'.
666
666
667 IPython has a job manager, accessible via the 'jobs' object. You can
667 IPython has a job manager, accessible via the 'jobs' object. You can
668 type jobs? to get more information about it, and use jobs.<TAB> to see
668 type jobs? to get more information about it, and use jobs.<TAB> to see
669 its attributes. All attributes not starting with an underscore are
669 its attributes. All attributes not starting with an underscore are
670 meant for public use.
670 meant for public use.
671
671
672 In particular, look at the jobs.new() method, which is used to create
672 In particular, look at the jobs.new() method, which is used to create
673 new jobs. This magic %bg function is just a convenience wrapper
673 new jobs. This magic %bg function is just a convenience wrapper
674 around jobs.new(), for expression-based jobs. If you want to create a
674 around jobs.new(), for expression-based jobs. If you want to create a
675 new job with an explicit function object and arguments, you must call
675 new job with an explicit function object and arguments, you must call
676 jobs.new() directly.
676 jobs.new() directly.
677
677
678 The jobs.new docstring also describes in detail several important
678 The jobs.new docstring also describes in detail several important
679 caveats associated with a thread-based model for background job
679 caveats associated with a thread-based model for background job
680 execution. Type jobs.new? for details.
680 execution. Type jobs.new? for details.
681
681
682 You can check the status of all jobs with jobs.status().
682 You can check the status of all jobs with jobs.status().
683
683
684 The jobs variable is set by IPython into the Python builtin namespace.
684 The jobs variable is set by IPython into the Python builtin namespace.
685 If you ever declare a variable named 'jobs', you will shadow this
685 If you ever declare a variable named 'jobs', you will shadow this
686 name. You can either delete your global jobs variable to regain
686 name. You can either delete your global jobs variable to regain
687 access to the job manager, or make a new name and assign it manually
687 access to the job manager, or make a new name and assign it manually
688 to the manager (stored in IPython's namespace). For example, to
688 to the manager (stored in IPython's namespace). For example, to
689 assign the job manager to the Jobs name, use:
689 assign the job manager to the Jobs name, use:
690
690
691 Jobs = __builtins__.jobs
691 Jobs = __builtins__.jobs
692
692
693 **%bookmark**::
693 **%bookmark**::
694
694
695 Manage IPython's bookmark system.
695 Manage IPython's bookmark system.
696
696
697 %bookmark <name> - set bookmark to current dir
697 %bookmark <name> - set bookmark to current dir
698 %bookmark <name> <dir> - set bookmark to <dir>
698 %bookmark <name> <dir> - set bookmark to <dir>
699 %bookmark -l - list all bookmarks
699 %bookmark -l - list all bookmarks
700 %bookmark -d <name> - remove bookmark
700 %bookmark -d <name> - remove bookmark
701 %bookmark -r - remove all bookmarks
701 %bookmark -r - remove all bookmarks
702
702
703 You can later on access a bookmarked folder with:
703 You can later on access a bookmarked folder with:
704 %cd -b <name>
704 %cd -b <name>
705 or simply '%cd <name>' if there is no directory called <name> AND
705 or simply '%cd <name>' if there is no directory called <name> AND
706 there is such a bookmark defined.
706 there is such a bookmark defined.
707
707
708 Your bookmarks persist through IPython sessions, but they are
708 Your bookmarks persist through IPython sessions, but they are
709 associated with each profile.
709 associated with each profile.
710
710
711 **%cd**::
711 **%cd**::
712
712
713 Change the current working directory.
713 Change the current working directory.
714
714
715 This command automatically maintains an internal list of directories
715 This command automatically maintains an internal list of directories
716 you visit during your IPython session, in the variable _dh. The
716 you visit during your IPython session, in the variable _dh. The
717 command %dhist shows this history nicely formatted. You can also
717 command %dhist shows this history nicely formatted. You can also
718 do 'cd -<tab>' to see directory history conveniently.
718 do 'cd -<tab>' to see directory history conveniently.
719
719
720 Usage:
720 Usage:
721
721
722 cd 'dir': changes to directory 'dir'.
722 cd 'dir': changes to directory 'dir'.
723
723
724 cd -: changes to the last visited directory.
724 cd -: changes to the last visited directory.
725
725
726 cd -<n>: changes to the n-th directory in the directory history.
726 cd -<n>: changes to the n-th directory in the directory history.
727
727
728 cd -b <bookmark_name>: jump to a bookmark set by %bookmark
728 cd -b <bookmark_name>: jump to a bookmark set by %bookmark
729 (note: cd <bookmark_name> is enough if there is no
729 (note: cd <bookmark_name> is enough if there is no
730 directory <bookmark_name>, but a bookmark with the name exists.)
730 directory <bookmark_name>, but a bookmark with the name exists.)
731 'cd -b <tab>' allows you to tab-complete bookmark names.
731 'cd -b <tab>' allows you to tab-complete bookmark names.
732
732
733 Options:
733 Options:
734
734
735 -q: quiet. Do not print the working directory after the cd command is
735 -q: quiet. Do not print the working directory after the cd command is
736 executed. By default IPython's cd command does print this directory,
736 executed. By default IPython's cd command does print this directory,
737 since the default prompts do not display path information.
737 since the default prompts do not display path information.
738
738
739 Note that !cd doesn't work for this purpose because the shell where
739 Note that !cd doesn't work for this purpose because the shell where
740 !command runs is immediately discarded after executing 'command'.
740 !command runs is immediately discarded after executing 'command'.
741
741
742 **%clear**::
742 **%clear**::
743
743
744 Clear various data (e.g. stored history data)
744 Clear various data (e.g. stored history data)
745
745
746 %clear out - clear output history
746 %clear out - clear output history
747 %clear in - clear input history
747 %clear in - clear input history
748 %clear shadow_compress - Compresses shadow history (to speed up ipython)
748 %clear shadow_compress - Compresses shadow history (to speed up ipython)
749 %clear shadow_nuke - permanently erase all entries in shadow history
749 %clear shadow_nuke - permanently erase all entries in shadow history
750 %clear dhist - clear dir history
750 %clear dhist - clear dir history
751
751
752 **%color_info**::
752 **%color_info**::
753
753
754 Toggle color_info.
754 Toggle color_info.
755
755
756 The color_info configuration parameter controls whether colors are
756 The color_info configuration parameter controls whether colors are
757 used for displaying object details (by things like %psource, %pfile or
757 used for displaying object details (by things like %psource, %pfile or
758 the '?' system). This function toggles this value with each call.
758 the '?' system). This function toggles this value with each call.
759
759
760 Note that unless you have a fairly recent pager (less works better
760 Note that unless you have a fairly recent pager (less works better
761 than more) in your system, using colored object information displays
761 than more) in your system, using colored object information displays
762 will not work properly. Test it and see.
762 will not work properly. Test it and see.
763
763
764 **%colors**::
764 **%colors**::
765
765
766 Switch color scheme for prompts, info system and exception handlers.
766 Switch color scheme for prompts, info system and exception handlers.
767
767
768 Currently implemented schemes: NoColor, Linux, LightBG.
768 Currently implemented schemes: NoColor, Linux, LightBG.
769
769
770 Color scheme names are not case-sensitive.
770 Color scheme names are not case-sensitive.
771
771
772 **%cpaste**::
772 **%cpaste**::
773
773
774 Allows you to paste & execute a pre-formatted code block from clipboard
774 Allows you to paste & execute a pre-formatted code block from clipboard
775
775
776 You must terminate the block with '--' (two minus-signs) alone on the
776 You must terminate the block with '--' (two minus-signs) alone on the
777 line. You can also provide your own sentinel with '%paste -s %%' ('%%'
777 line. You can also provide your own sentinel with '%paste -s %%' ('%%'
778 is the new sentinel for this operation)
778 is the new sentinel for this operation)
779
779
780 The block is dedented prior to execution to enable execution of method
780 The block is dedented prior to execution to enable execution of method
781 definitions. '>' and '+' characters at the beginning of a line are
781 definitions. '>' and '+' characters at the beginning of a line are
782 ignored, to allow pasting directly from e-mails or diff files. The
782 ignored, to allow pasting directly from e-mails or diff files. The
783 executed block is also assigned to variable named 'pasted_block' for
783 executed block is also assigned to variable named 'pasted_block' for
784 later editing with '%edit pasted_block'.
784 later editing with '%edit pasted_block'.
785
785
786 You can also pass a variable name as an argument, e.g. '%cpaste foo'.
786 You can also pass a variable name as an argument, e.g. '%cpaste foo'.
787 This assigns the pasted block to variable 'foo' as string, without
787 This assigns the pasted block to variable 'foo' as string, without
788 dedenting or executing it.
788 dedenting or executing it.
789
789
790 Do not be alarmed by garbled output on Windows (it's a readline bug).
790 Do not be alarmed by garbled output on Windows (it's a readline bug).
791 Just press enter and type -- (and press enter again) and the block
791 Just press enter and type -- (and press enter again) and the block
792 will be what was just pasted.
792 will be what was just pasted.
793
793
794 IPython statements (magics, shell escapes) are not supported (yet).
794 IPython statements (magics, shell escapes) are not supported (yet).
795
795
796 **%debug**::
796 **%debug**::
797
797
798 Activate the interactive debugger in post-mortem mode.
798 Activate the interactive debugger in post-mortem mode.
799
799
800 If an exception has just occurred, this lets you inspect its stack
800 If an exception has just occurred, this lets you inspect its stack
801 frames interactively. Note that this will always work only on the last
801 frames interactively. Note that this will always work only on the last
802 traceback that occurred, so you must call this quickly after an
802 traceback that occurred, so you must call this quickly after an
803 exception that you wish to inspect has fired, because if another one
803 exception that you wish to inspect has fired, because if another one
804 occurs, it clobbers the previous one.
804 occurs, it clobbers the previous one.
805
805
806 If you want IPython to automatically do this on every exception, see
806 If you want IPython to automatically do this on every exception, see
807 the %pdb magic for more details.
807 the %pdb magic for more details.
808
808
809 **%dhist**::
809 **%dhist**::
810
810
811 Print your history of visited directories.
811 Print your history of visited directories.
812
812
813 %dhist -> print full history\
813 %dhist -> print full history\
814 %dhist n -> print last n entries only\
814 %dhist n -> print last n entries only\
815 %dhist n1 n2 -> print entries between n1 and n2 (n1 not included)\
815 %dhist n1 n2 -> print entries between n1 and n2 (n1 not included)\
816
816
817 This history is automatically maintained by the %cd command, and
817 This history is automatically maintained by the %cd command, and
818 always available as the global list variable _dh. You can use %cd -<n>
818 always available as the global list variable _dh. You can use %cd -<n>
819 to go to directory number <n>.
819 to go to directory number <n>.
820
820
821 Note that most of time, you should view directory history by entering
821 Note that most of time, you should view directory history by entering
822 cd -<TAB>.
822 cd -<TAB>.
823
823
824 **%dirs**::
824 **%dirs**::
825
825
826 Return the current directory stack.
826 Return the current directory stack.
827
827
828 **%doctest_mode**::
828 **%doctest_mode**::
829
829
830 Toggle doctest mode on and off.
830 Toggle doctest mode on and off.
831
831
832 This mode allows you to toggle the prompt behavior between normal
832 This mode allows you to toggle the prompt behavior between normal
833 IPython prompts and ones that are as similar to the default IPython
833 IPython prompts and ones that are as similar to the default IPython
834 interpreter as possible.
834 interpreter as possible.
835
835
836 It also supports the pasting of code snippets that have leading '>>>'
836 It also supports the pasting of code snippets that have leading '>>>'
837 and '...' prompts in them. This means that you can paste doctests from
837 and '...' prompts in them. This means that you can paste doctests from
838 files or docstrings (even if they have leading whitespace), and the
838 files or docstrings (even if they have leading whitespace), and the
839 code will execute correctly. You can then use '%history -tn' to see
839 code will execute correctly. You can then use '%history -tn' to see
840 the translated history without line numbers; this will give you the
840 the translated history without line numbers; this will give you the
841 input after removal of all the leading prompts and whitespace, which
841 input after removal of all the leading prompts and whitespace, which
842 can be pasted back into an editor.
842 can be pasted back into an editor.
843
843
844 With these features, you can switch into this mode easily whenever you
844 With these features, you can switch into this mode easily whenever you
845 need to do testing and changes to doctests, without having to leave
845 need to do testing and changes to doctests, without having to leave
846 your existing IPython session.
846 your existing IPython session.
847
847
848 **%ed**::
848 **%ed**::
849
849
850 Alias to %edit.
850 Alias to %edit.
851
851
852 **%edit**::
852 **%edit**::
853
853
854 Bring up an editor and execute the resulting code.
854 Bring up an editor and execute the resulting code.
855
855
856 Usage:
856 Usage:
857 %edit [options] [args]
857 %edit [options] [args]
858
858
859 %edit runs IPython's editor hook. The default version of this hook is
859 %edit runs IPython's editor hook. The default version of this hook is
860 set to call the __IPYTHON__.rc.editor command. This is read from your
860 set to call the __IPYTHON__.rc.editor command. This is read from your
861 environment variable $EDITOR. If this isn't found, it will default to
861 environment variable $EDITOR. If this isn't found, it will default to
862 vi under Linux/Unix and to notepad under Windows. See the end of this
862 vi under Linux/Unix and to notepad under Windows. See the end of this
863 docstring for how to change the editor hook.
863 docstring for how to change the editor hook.
864
864
865 You can also set the value of this editor via the command line option
865 You can also set the value of this editor via the command line option
866 '-editor' or in your ipythonrc file. This is useful if you wish to use
866 '-editor' or in your ipythonrc file. This is useful if you wish to use
867 specifically for IPython an editor different from your typical default
867 specifically for IPython an editor different from your typical default
868 (and for Windows users who typically don't set environment variables).
868 (and for Windows users who typically don't set environment variables).
869
869
870 This command allows you to conveniently edit multi-line code right in
870 This command allows you to conveniently edit multi-line code right in
871 your IPython session.
871 your IPython session.
872
872
873 If called without arguments, %edit opens up an empty editor with a
873 If called without arguments, %edit opens up an empty editor with a
874 temporary file and will execute the contents of this file when you
874 temporary file and will execute the contents of this file when you
875 close it (don't forget to save it!).
875 close it (don't forget to save it!).
876
876
877
877
878 Options:
878 Options:
879
879
880 -n <number>: open the editor at a specified line number. By default,
880 -n <number>: open the editor at a specified line number. By default,
881 the IPython editor hook uses the unix syntax 'editor +N filename', but
881 the IPython editor hook uses the unix syntax 'editor +N filename', but
882 you can configure this by providing your own modified hook if your
882 you can configure this by providing your own modified hook if your
883 favorite editor supports line-number specifications with a different
883 favorite editor supports line-number specifications with a different
884 syntax.
884 syntax.
885
885
886 -p: this will call the editor with the same data as the previous time
886 -p: this will call the editor with the same data as the previous time
887 it was used, regardless of how long ago (in your current session) it
887 it was used, regardless of how long ago (in your current session) it
888 was.
888 was.
889
889
890 -r: use 'raw' input. This option only applies to input taken from the
890 -r: use 'raw' input. This option only applies to input taken from the
891 user's history. By default, the 'processed' history is used, so that
891 user's history. By default, the 'processed' history is used, so that
892 magics are loaded in their transformed version to valid Python. If
892 magics are loaded in their transformed version to valid Python. If
893 this option is given, the raw input as typed as the command line is
893 this option is given, the raw input as typed as the command line is
894 used instead. When you exit the editor, it will be executed by
894 used instead. When you exit the editor, it will be executed by
895 IPython's own processor.
895 IPython's own processor.
896
896
897 -x: do not execute the edited code immediately upon exit. This is
897 -x: do not execute the edited code immediately upon exit. This is
898 mainly useful if you are editing programs which need to be called with
898 mainly useful if you are editing programs which need to be called with
899 command line arguments, which you can then do using %run.
899 command line arguments, which you can then do using %run.
900
900
901
901
902 Arguments:
902 Arguments:
903
903
904 If arguments are given, the following possibilites exist:
904 If arguments are given, the following possibilites exist:
905
905
906 - The arguments are numbers or pairs of colon-separated numbers (like
906 - The arguments are numbers or pairs of colon-separated numbers (like
907 1 4:8 9). These are interpreted as lines of previous input to be
907 1 4:8 9). These are interpreted as lines of previous input to be
908 loaded into the editor. The syntax is the same of the %macro command.
908 loaded into the editor. The syntax is the same of the %macro command.
909
909
910 - If the argument doesn't start with a number, it is evaluated as a
910 - If the argument doesn't start with a number, it is evaluated as a
911 variable and its contents loaded into the editor. You can thus edit
911 variable and its contents loaded into the editor. You can thus edit
912 any string which contains python code (including the result of
912 any string which contains python code (including the result of
913 previous edits).
913 previous edits).
914
914
915 - If the argument is the name of an object (other than a string),
915 - If the argument is the name of an object (other than a string),
916 IPython will try to locate the file where it was defined and open the
916 IPython will try to locate the file where it was defined and open the
917 editor at the point where it is defined. You can use `%edit function`
917 editor at the point where it is defined. You can use `%edit function`
918 to load an editor exactly at the point where 'function' is defined,
918 to load an editor exactly at the point where 'function' is defined,
919 edit it and have the file be executed automatically.
919 edit it and have the file be executed automatically.
920
920
921 If the object is a macro (see %macro for details), this opens up your
921 If the object is a macro (see %macro for details), this opens up your
922 specified editor with a temporary file containing the macro's data.
922 specified editor with a temporary file containing the macro's data.
923 Upon exit, the macro is reloaded with the contents of the file.
923 Upon exit, the macro is reloaded with the contents of the file.
924
924
925 Note: opening at an exact line is only supported under Unix, and some
925 Note: opening at an exact line is only supported under Unix, and some
926 editors (like kedit and gedit up to Gnome 2.8) do not understand the
926 editors (like kedit and gedit up to Gnome 2.8) do not understand the
927 '+NUMBER' parameter necessary for this feature. Good editors like
927 '+NUMBER' parameter necessary for this feature. Good editors like
928 (X)Emacs, vi, jed, pico and joe all do.
928 (X)Emacs, vi, jed, pico and joe all do.
929
929
930 - If the argument is not found as a variable, IPython will look for a
930 - If the argument is not found as a variable, IPython will look for a
931 file with that name (adding .py if necessary) and load it into the
931 file with that name (adding .py if necessary) and load it into the
932 editor. It will execute its contents with execfile() when you exit,
932 editor. It will execute its contents with execfile() when you exit,
933 loading any code in the file into your interactive namespace.
933 loading any code in the file into your interactive namespace.
934
934
935 After executing your code, %edit will return as output the code you
935 After executing your code, %edit will return as output the code you
936 typed in the editor (except when it was an existing file). This way
936 typed in the editor (except when it was an existing file). This way
937 you can reload the code in further invocations of %edit as a variable,
937 you can reload the code in further invocations of %edit as a variable,
938 via _<NUMBER> or Out[<NUMBER>], where <NUMBER> is the prompt number of
938 via _<NUMBER> or Out[<NUMBER>], where <NUMBER> is the prompt number of
939 the output.
939 the output.
940
940
941 Note that %edit is also available through the alias %ed.
941 Note that %edit is also available through the alias %ed.
942
942
943 This is an example of creating a simple function inside the editor and
943 This is an example of creating a simple function inside the editor and
944 then modifying it. First, start up the editor:
944 then modifying it. First, start up the editor:
945
945
946 In [1]: ed\
946 In [1]: ed\
947 Editing... done. Executing edited code...\
947 Editing... done. Executing edited code...\
948 Out[1]: 'def foo():\n print "foo() was defined in an editing session"\n'
948 Out[1]: 'def foo():\n print "foo() was defined in an editing session"\n'
949
949
950 We can then call the function foo():
950 We can then call the function foo():
951
951
952 In [2]: foo()\
952 In [2]: foo()\
953 foo() was defined in an editing session
953 foo() was defined in an editing session
954
954
955 Now we edit foo. IPython automatically loads the editor with the
955 Now we edit foo. IPython automatically loads the editor with the
956 (temporary) file where foo() was previously defined:
956 (temporary) file where foo() was previously defined:
957
957
958 In [3]: ed foo\
958 In [3]: ed foo\
959 Editing... done. Executing edited code...
959 Editing... done. Executing edited code...
960
960
961 And if we call foo() again we get the modified version:
961 And if we call foo() again we get the modified version:
962
962
963 In [4]: foo()\
963 In [4]: foo()\
964 foo() has now been changed!
964 foo() has now been changed!
965
965
966 Here is an example of how to edit a code snippet successive
966 Here is an example of how to edit a code snippet successive
967 times. First we call the editor:
967 times. First we call the editor:
968
968
969 In [8]: ed\
969 In [8]: ed\
970 Editing... done. Executing edited code...\
970 Editing... done. Executing edited code...\
971 hello\
971 hello\
972 Out[8]: "print 'hello'\n"
972 Out[8]: "print 'hello'\n"
973
973
974 Now we call it again with the previous output (stored in _):
974 Now we call it again with the previous output (stored in _):
975
975
976 In [9]: ed _\
976 In [9]: ed _\
977 Editing... done. Executing edited code...\
977 Editing... done. Executing edited code...\
978 hello world\
978 hello world\
979 Out[9]: "print 'hello world'\n"
979 Out[9]: "print 'hello world'\n"
980
980
981 Now we call it with the output #8 (stored in _8, also as Out[8]):
981 Now we call it with the output #8 (stored in _8, also as Out[8]):
982
982
983 In [10]: ed _8\
983 In [10]: ed _8\
984 Editing... done. Executing edited code...\
984 Editing... done. Executing edited code...\
985 hello again\
985 hello again\
986 Out[10]: "print 'hello again'\n"
986 Out[10]: "print 'hello again'\n"
987
987
988
988
989 Changing the default editor hook:
989 Changing the default editor hook:
990
990
991 If you wish to write your own editor hook, you can put it in a
991 If you wish to write your own editor hook, you can put it in a
992 configuration file which you load at startup time. The default hook
992 configuration file which you load at startup time. The default hook
993 is defined in the IPython.hooks module, and you can use that as a
993 is defined in the IPython.hooks module, and you can use that as a
994 starting example for further modifications. That file also has
994 starting example for further modifications. That file also has
995 general instructions on how to set a new hook for use once you've
995 general instructions on how to set a new hook for use once you've
996 defined it.
996 defined it.
997
997
998 **%env**::
998 **%env**::
999
999
1000 List environment variables.
1000 List environment variables.
1001
1001
1002 **%exit**::
1002 **%exit**::
1003
1003
1004 Exit IPython, confirming if configured to do so.
1004 Exit IPython, confirming if configured to do so.
1005
1005
1006 You can configure whether IPython asks for confirmation upon exit by
1006 You can configure whether IPython asks for confirmation upon exit by
1007 setting the confirm_exit flag in the ipythonrc file.
1007 setting the confirm_exit flag in the ipythonrc file.
1008
1008
1009 **%hist**::
1009 **%hist**::
1010
1010
1011 Alternate name for %history.
1011 Alternate name for %history.
1012
1012
1013 **%history**::
1013 **%history**::
1014
1014
1015 Print input history (_i<n> variables), with most recent last.
1015 Print input history (_i<n> variables), with most recent last.
1016
1016
1017 %history -> print at most 40 inputs (some may be multi-line)\
1017 %history -> print at most 40 inputs (some may be multi-line)\
1018 %history n -> print at most n inputs\
1018 %history n -> print at most n inputs\
1019 %history n1 n2 -> print inputs between n1 and n2 (n2 not included)\
1019 %history n1 n2 -> print inputs between n1 and n2 (n2 not included)\
1020
1020
1021 Each input's number <n> is shown, and is accessible as the
1021 Each input's number <n> is shown, and is accessible as the
1022 automatically generated variable _i<n>. Multi-line statements are
1022 automatically generated variable _i<n>. Multi-line statements are
1023 printed starting at a new line for easy copy/paste.
1023 printed starting at a new line for easy copy/paste.
1024
1024
1025
1025
1026 Options:
1026 Options:
1027
1027
1028 -n: do NOT print line numbers. This is useful if you want to get a
1028 -n: do NOT print line numbers. This is useful if you want to get a
1029 printout of many lines which can be directly pasted into a text
1029 printout of many lines which can be directly pasted into a text
1030 editor.
1030 editor.
1031
1031
1032 This feature is only available if numbered prompts are in use.
1032 This feature is only available if numbered prompts are in use.
1033
1033
1034 -t: (default) print the 'translated' history, as IPython understands it.
1034 -t: (default) print the 'translated' history, as IPython understands it.
1035 IPython filters your input and converts it all into valid Python source
1035 IPython filters your input and converts it all into valid Python source
1036 before executing it (things like magics or aliases are turned into
1036 before executing it (things like magics or aliases are turned into
1037 function calls, for example). With this option, you'll see the native
1037 function calls, for example). With this option, you'll see the native
1038 history instead of the user-entered version: '%cd /' will be seen as
1038 history instead of the user-entered version: '%cd /' will be seen as
1039 '_ip.magic("%cd /")' instead of '%cd /'.
1039 '_ip.magic("%cd /")' instead of '%cd /'.
1040
1040
1041 -r: print the 'raw' history, i.e. the actual commands you typed.
1041 -r: print the 'raw' history, i.e. the actual commands you typed.
1042
1042
1043 -g: treat the arg as a pattern to grep for in (full) history.
1043 -g: treat the arg as a pattern to grep for in (full) history.
1044 This includes the "shadow history" (almost all commands ever written).
1044 This includes the "shadow history" (almost all commands ever written).
1045 Use '%hist -g' to show full shadow history (may be very long).
1045 Use '%hist -g' to show full shadow history (may be very long).
1046 In shadow history, every index nuwber starts with 0.
1046 In shadow history, every index nuwber starts with 0.
1047
1047
1048 -f FILENAME: instead of printing the output to the screen, redirect it to
1048 -f FILENAME: instead of printing the output to the screen, redirect it to
1049 the given file. The file is always overwritten, though IPython asks for
1049 the given file. The file is always overwritten, though IPython asks for
1050 confirmation first if it already exists.
1050 confirmation first if it already exists.
1051
1051
1052 **%logoff**::
1052 **%logoff**::
1053
1053
1054 Temporarily stop logging.
1054 Temporarily stop logging.
1055
1055
1056 You must have previously started logging.
1056 You must have previously started logging.
1057
1057
1058 **%logon**::
1058 **%logon**::
1059
1059
1060 Restart logging.
1060 Restart logging.
1061
1061
1062 This function is for restarting logging which you've temporarily
1062 This function is for restarting logging which you've temporarily
1063 stopped with %logoff. For starting logging for the first time, you
1063 stopped with %logoff. For starting logging for the first time, you
1064 must use the %logstart function, which allows you to specify an
1064 must use the %logstart function, which allows you to specify an
1065 optional log filename.
1065 optional log filename.
1066
1066
1067 **%logstart**::
1067 **%logstart**::
1068
1068
1069 Start logging anywhere in a session.
1069 Start logging anywhere in a session.
1070
1070
1071 %logstart [-o|-r|-t] [log_name [log_mode]]
1071 %logstart [-o|-r|-t] [log_name [log_mode]]
1072
1072
1073 If no name is given, it defaults to a file named 'ipython_log.py' in your
1073 If no name is given, it defaults to a file named 'ipython_log.py' in your
1074 current directory, in 'rotate' mode (see below).
1074 current directory, in 'rotate' mode (see below).
1075
1075
1076 '%logstart name' saves to file 'name' in 'backup' mode. It saves your
1076 '%logstart name' saves to file 'name' in 'backup' mode. It saves your
1077 history up to that point and then continues logging.
1077 history up to that point and then continues logging.
1078
1078
1079 %logstart takes a second optional parameter: logging mode. This can be one
1079 %logstart takes a second optional parameter: logging mode. This can be one
1080 of (note that the modes are given unquoted):\
1080 of (note that the modes are given unquoted):\
1081 append: well, that says it.\
1081 append: well, that says it.\
1082 backup: rename (if exists) to name~ and start name.\
1082 backup: rename (if exists) to name~ and start name.\
1083 global: single logfile in your home dir, appended to.\
1083 global: single logfile in your home dir, appended to.\
1084 over : overwrite existing log.\
1084 over : overwrite existing log.\
1085 rotate: create rotating logs name.1~, name.2~, etc.
1085 rotate: create rotating logs name.1~, name.2~, etc.
1086
1086
1087 Options:
1087 Options:
1088
1088
1089 -o: log also IPython's output. In this mode, all commands which
1089 -o: log also IPython's output. In this mode, all commands which
1090 generate an Out[NN] prompt are recorded to the logfile, right after
1090 generate an Out[NN] prompt are recorded to the logfile, right after
1091 their corresponding input line. The output lines are always
1091 their corresponding input line. The output lines are always
1092 prepended with a '#[Out]# ' marker, so that the log remains valid
1092 prepended with a '#[Out]# ' marker, so that the log remains valid
1093 Python code.
1093 Python code.
1094
1094
1095 Since this marker is always the same, filtering only the output from
1095 Since this marker is always the same, filtering only the output from
1096 a log is very easy, using for example a simple awk call:
1096 a log is very easy, using for example a simple awk call:
1097
1097
1098 awk -F'#\[Out\]# ' '{if($2) {print $2}}' ipython_log.py
1098 awk -F'#\[Out\]# ' '{if($2) {print $2}}' ipython_log.py
1099
1099
1100 -r: log 'raw' input. Normally, IPython's logs contain the processed
1100 -r: log 'raw' input. Normally, IPython's logs contain the processed
1101 input, so that user lines are logged in their final form, converted
1101 input, so that user lines are logged in their final form, converted
1102 into valid Python. For example, %Exit is logged as
1102 into valid Python. For example, %Exit is logged as
1103 '_ip.magic("Exit"). If the -r flag is given, all input is logged
1103 '_ip.magic("Exit"). If the -r flag is given, all input is logged
1104 exactly as typed, with no transformations applied.
1104 exactly as typed, with no transformations applied.
1105
1105
1106 -t: put timestamps before each input line logged (these are put in
1106 -t: put timestamps before each input line logged (these are put in
1107 comments).
1107 comments).
1108
1108
1109 **%logstate**::
1109 **%logstate**::
1110
1110
1111 Print the status of the logging system.
1111 Print the status of the logging system.
1112
1112
1113 **%logstop**::
1113 **%logstop**::
1114
1114
1115 Fully stop logging and close log file.
1115 Fully stop logging and close log file.
1116
1116
1117 In order to start logging again, a new %logstart call needs to be made,
1117 In order to start logging again, a new %logstart call needs to be made,
1118 possibly (though not necessarily) with a new filename, mode and other
1118 possibly (though not necessarily) with a new filename, mode and other
1119 options.
1119 options.
1120
1120
1121 **%lsmagic**::
1121 **%lsmagic**::
1122
1122
1123 List currently available magic functions.
1123 List currently available magic functions.
1124
1124
1125 **%macro**::
1125 **%macro**::
1126
1126
1127 Define a set of input lines as a macro for future re-execution.
1127 Define a set of input lines as a macro for future re-execution.
1128
1128
1129 Usage:\
1129 Usage:\
1130 %macro [options] name n1-n2 n3-n4 ... n5 .. n6 ...
1130 %macro [options] name n1-n2 n3-n4 ... n5 .. n6 ...
1131
1131
1132 Options:
1132 Options:
1133
1133
1134 -r: use 'raw' input. By default, the 'processed' history is used,
1134 -r: use 'raw' input. By default, the 'processed' history is used,
1135 so that magics are loaded in their transformed version to valid
1135 so that magics are loaded in their transformed version to valid
1136 Python. If this option is given, the raw input as typed as the
1136 Python. If this option is given, the raw input as typed as the
1137 command line is used instead.
1137 command line is used instead.
1138
1138
1139 This will define a global variable called `name` which is a string
1139 This will define a global variable called `name` which is a string
1140 made of joining the slices and lines you specify (n1,n2,... numbers
1140 made of joining the slices and lines you specify (n1,n2,... numbers
1141 above) from your input history into a single string. This variable
1141 above) from your input history into a single string. This variable
1142 acts like an automatic function which re-executes those lines as if
1142 acts like an automatic function which re-executes those lines as if
1143 you had typed them. You just type 'name' at the prompt and the code
1143 you had typed them. You just type 'name' at the prompt and the code
1144 executes.
1144 executes.
1145
1145
1146 The notation for indicating number ranges is: n1-n2 means 'use line
1146 The notation for indicating number ranges is: n1-n2 means 'use line
1147 numbers n1,...n2' (the endpoint is included). That is, '5-7' means
1147 numbers n1,...n2' (the endpoint is included). That is, '5-7' means
1148 using the lines numbered 5,6 and 7.
1148 using the lines numbered 5,6 and 7.
1149
1149
1150 Note: as a 'hidden' feature, you can also use traditional python slice
1150 Note: as a 'hidden' feature, you can also use traditional python slice
1151 notation, where N:M means numbers N through M-1.
1151 notation, where N:M means numbers N through M-1.
1152
1152
1153 For example, if your history contains (%hist prints it):
1153 For example, if your history contains (%hist prints it):
1154
1154
1155 44: x=1\
1155 44: x=1\
1156 45: y=3\
1156 45: y=3\
1157 46: z=x+y\
1157 46: z=x+y\
1158 47: print x\
1158 47: print x\
1159 48: a=5\
1159 48: a=5\
1160 49: print 'x',x,'y',y\
1160 49: print 'x',x,'y',y\
1161
1161
1162 you can create a macro with lines 44 through 47 (included) and line 49
1162 you can create a macro with lines 44 through 47 (included) and line 49
1163 called my_macro with:
1163 called my_macro with:
1164
1164
1165 In [51]: %macro my_macro 44-47 49
1165 In [51]: %macro my_macro 44-47 49
1166
1166
1167 Now, typing `my_macro` (without quotes) will re-execute all this code
1167 Now, typing `my_macro` (without quotes) will re-execute all this code
1168 in one pass.
1168 in one pass.
1169
1169
1170 You don't need to give the line-numbers in order, and any given line
1170 You don't need to give the line-numbers in order, and any given line
1171 number can appear multiple times. You can assemble macros with any
1171 number can appear multiple times. You can assemble macros with any
1172 lines from your input history in any order.
1172 lines from your input history in any order.
1173
1173
1174 The macro is a simple object which holds its value in an attribute,
1174 The macro is a simple object which holds its value in an attribute,
1175 but IPython's display system checks for macros and executes them as
1175 but IPython's display system checks for macros and executes them as
1176 code instead of printing them when you type their name.
1176 code instead of printing them when you type their name.
1177
1177
1178 You can view a macro's contents by explicitly printing it with:
1178 You can view a macro's contents by explicitly printing it with:
1179
1179
1180 'print macro_name'.
1180 'print macro_name'.
1181
1181
1182 For one-off cases which DON'T contain magic function calls in them you
1182 For one-off cases which DON'T contain magic function calls in them you
1183 can obtain similar results by explicitly executing slices from your
1183 can obtain similar results by explicitly executing slices from your
1184 input history with:
1184 input history with:
1185
1185
1186 In [60]: exec In[44:48]+In[49]
1186 In [60]: exec In[44:48]+In[49]
1187
1187
1188 **%magic**::
1188 **%magic**::
1189
1189
1190 Print information about the magic function system.
1190 Print information about the magic function system.
1191
1191
1192 **%mglob**::
1192 **%mglob**::
1193
1193
1194 This program allows specifying filenames with "mglob" mechanism.
1194 This program allows specifying filenames with "mglob" mechanism.
1195 Supported syntax in globs (wilcard matching patterns)::
1195 Supported syntax in globs (wilcard matching patterns)::
1196
1196
1197 *.cpp ?ellowo*
1197 *.cpp ?ellowo*
1198 - obvious. Differs from normal glob in that dirs are not included.
1198 - obvious. Differs from normal glob in that dirs are not included.
1199 Unix users might want to write this as: "*.cpp" "?ellowo*"
1199 Unix users might want to write this as: "*.cpp" "?ellowo*"
1200 rec:/usr/share=*.txt,*.doc
1200 rec:/usr/share=*.txt,*.doc
1201 - get all *.txt and *.doc under /usr/share,
1201 - get all *.txt and *.doc under /usr/share,
1202 recursively
1202 recursively
1203 rec:/usr/share
1203 rec:/usr/share
1204 - All files under /usr/share, recursively
1204 - All files under /usr/share, recursively
1205 rec:*.py
1205 rec:*.py
1206 - All .py files under current working dir, recursively
1206 - All .py files under current working dir, recursively
1207 foo
1207 foo
1208 - File or dir foo
1208 - File or dir foo
1209 !*.bak readme*
1209 !*.bak readme*
1210 - readme*, exclude files ending with .bak
1210 - readme*, exclude files ending with .bak
1211 !.svn/ !.hg/ !*_Data/ rec:.
1211 !.svn/ !.hg/ !*_Data/ rec:.
1212 - Skip .svn, .hg, foo_Data dirs (and their subdirs) in recurse.
1212 - Skip .svn, .hg, foo_Data dirs (and their subdirs) in recurse.
1213 Trailing / is the key, \ does not work!
1213 Trailing / is the key, \ does not work!
1214 dir:foo
1214 dir:foo
1215 - the directory foo if it exists (not files in foo)
1215 - the directory foo if it exists (not files in foo)
1216 dir:*
1216 dir:*
1217 - all directories in current folder
1217 - all directories in current folder
1218 foo.py bar.* !h* rec:*.py
1218 foo.py bar.* !h* rec:*.py
1219 - Obvious. !h* exclusion only applies for rec:*.py.
1219 - Obvious. !h* exclusion only applies for rec:*.py.
1220 foo.py is *not* included twice.
1220 foo.py is *not* included twice.
1221 @filelist.txt
1221 @filelist.txt
1222 - All files listed in 'filelist.txt' file, on separate lines.
1222 - All files listed in 'filelist.txt' file, on separate lines.
1223
1223
1224 **%page**::
1224 **%page**::
1225
1225
1226 Pretty print the object and display it through a pager.
1226 Pretty print the object and display it through a pager.
1227
1227
1228 %page [options] OBJECT
1228 %page [options] OBJECT
1229
1229
1230 If no object is given, use _ (last output).
1230 If no object is given, use _ (last output).
1231
1231
1232 Options:
1232 Options:
1233
1233
1234 -r: page str(object), don't pretty-print it.
1234 -r: page str(object), don't pretty-print it.
1235
1235
1236 **%pdb**::
1236 **%pdb**::
1237
1237
1238 Control the automatic calling of the pdb interactive debugger.
1238 Control the automatic calling of the pdb interactive debugger.
1239
1239
1240 Call as '%pdb on', '%pdb 1', '%pdb off' or '%pdb 0'. If called without
1240 Call as '%pdb on', '%pdb 1', '%pdb off' or '%pdb 0'. If called without
1241 argument it works as a toggle.
1241 argument it works as a toggle.
1242
1242
1243 When an exception is triggered, IPython can optionally call the
1243 When an exception is triggered, IPython can optionally call the
1244 interactive pdb debugger after the traceback printout. %pdb toggles
1244 interactive pdb debugger after the traceback printout. %pdb toggles
1245 this feature on and off.
1245 this feature on and off.
1246
1246
1247 The initial state of this feature is set in your ipythonrc
1247 The initial state of this feature is set in your ipythonrc
1248 configuration file (the variable is called 'pdb').
1248 configuration file (the variable is called 'pdb').
1249
1249
1250 If you want to just activate the debugger AFTER an exception has fired,
1250 If you want to just activate the debugger AFTER an exception has fired,
1251 without having to type '%pdb on' and rerunning your code, you can use
1251 without having to type '%pdb on' and rerunning your code, you can use
1252 the %debug magic.
1252 the %debug magic.
1253
1253
1254 **%pdef**::
1254 **%pdef**::
1255
1255
1256 Print the definition header for any callable object.
1256 Print the definition header for any callable object.
1257
1257
1258 If the object is a class, print the constructor information.
1258 If the object is a class, print the constructor information.
1259
1259
1260 **%pdoc**::
1260 **%pdoc**::
1261
1261
1262 Print the docstring for an object.
1262 Print the docstring for an object.
1263
1263
1264 If the given object is a class, it will print both the class and the
1264 If the given object is a class, it will print both the class and the
1265 constructor docstrings.
1265 constructor docstrings.
1266
1266
1267 **%pfile**::
1267 **%pfile**::
1268
1268
1269 Print (or run through pager) the file where an object is defined.
1269 Print (or run through pager) the file where an object is defined.
1270
1270
1271 The file opens at the line where the object definition begins. IPython
1271 The file opens at the line where the object definition begins. IPython
1272 will honor the environment variable PAGER if set, and otherwise will
1272 will honor the environment variable PAGER if set, and otherwise will
1273 do its best to print the file in a convenient form.
1273 do its best to print the file in a convenient form.
1274
1274
1275 If the given argument is not an object currently defined, IPython will
1275 If the given argument is not an object currently defined, IPython will
1276 try to interpret it as a filename (automatically adding a .py extension
1276 try to interpret it as a filename (automatically adding a .py extension
1277 if needed). You can thus use %pfile as a syntax highlighting code
1277 if needed). You can thus use %pfile as a syntax highlighting code
1278 viewer.
1278 viewer.
1279
1279
1280 **%pinfo**::
1280 **%pinfo**::
1281
1281
1282 Provide detailed information about an object.
1282 Provide detailed information about an object.
1283
1283
1284 '%pinfo object' is just a synonym for object? or ?object.
1284 '%pinfo object' is just a synonym for object? or ?object.
1285
1285
1286 **%popd**::
1286 **%popd**::
1287
1287
1288 Change to directory popped off the top of the stack.
1288 Change to directory popped off the top of the stack.
1289
1289
1290 **%profile**::
1290 **%profile**::
1291
1291
1292 Print your currently active IPyhton profile.
1292 Print your currently active IPyhton profile.
1293
1293
1294 **%prun**::
1294 **%prun**::
1295
1295
1296 Run a statement through the python code profiler.
1296 Run a statement through the python code profiler.
1297
1297
1298 Usage:\
1298 Usage:\
1299 %prun [options] statement
1299 %prun [options] statement
1300
1300
1301 The given statement (which doesn't require quote marks) is run via the
1301 The given statement (which doesn't require quote marks) is run via the
1302 python profiler in a manner similar to the profile.run() function.
1302 python profiler in a manner similar to the profile.run() function.
1303 Namespaces are internally managed to work correctly; profile.run
1303 Namespaces are internally managed to work correctly; profile.run
1304 cannot be used in IPython because it makes certain assumptions about
1304 cannot be used in IPython because it makes certain assumptions about
1305 namespaces which do not hold under IPython.
1305 namespaces which do not hold under IPython.
1306
1306
1307 Options:
1307 Options:
1308
1308
1309 -l <limit>: you can place restrictions on what or how much of the
1309 -l <limit>: you can place restrictions on what or how much of the
1310 profile gets printed. The limit value can be:
1310 profile gets printed. The limit value can be:
1311
1311
1312 * A string: only information for function names containing this string
1312 * A string: only information for function names containing this string
1313 is printed.
1313 is printed.
1314
1314
1315 * An integer: only these many lines are printed.
1315 * An integer: only these many lines are printed.
1316
1316
1317 * A float (between 0 and 1): this fraction of the report is printed
1317 * A float (between 0 and 1): this fraction of the report is printed
1318 (for example, use a limit of 0.4 to see the topmost 40% only).
1318 (for example, use a limit of 0.4 to see the topmost 40% only).
1319
1319
1320 You can combine several limits with repeated use of the option. For
1320 You can combine several limits with repeated use of the option. For
1321 example, '-l __init__ -l 5' will print only the topmost 5 lines of
1321 example, '-l __init__ -l 5' will print only the topmost 5 lines of
1322 information about class constructors.
1322 information about class constructors.
1323
1323
1324 -r: return the pstats.Stats object generated by the profiling. This
1324 -r: return the pstats.Stats object generated by the profiling. This
1325 object has all the information about the profile in it, and you can
1325 object has all the information about the profile in it, and you can
1326 later use it for further analysis or in other functions.
1326 later use it for further analysis or in other functions.
1327
1327
1328 -s <key>: sort profile by given key. You can provide more than one key
1328 -s <key>: sort profile by given key. You can provide more than one key
1329 by using the option several times: '-s key1 -s key2 -s key3...'. The
1329 by using the option several times: '-s key1 -s key2 -s key3...'. The
1330 default sorting key is 'time'.
1330 default sorting key is 'time'.
1331
1331
1332 The following is copied verbatim from the profile documentation
1332 The following is copied verbatim from the profile documentation
1333 referenced below:
1333 referenced below:
1334
1334
1335 When more than one key is provided, additional keys are used as
1335 When more than one key is provided, additional keys are used as
1336 secondary criteria when the there is equality in all keys selected
1336 secondary criteria when the there is equality in all keys selected
1337 before them.
1337 before them.
1338
1338
1339 Abbreviations can be used for any key names, as long as the
1339 Abbreviations can be used for any key names, as long as the
1340 abbreviation is unambiguous. The following are the keys currently
1340 abbreviation is unambiguous. The following are the keys currently
1341 defined:
1341 defined:
1342
1342
1343 Valid Arg Meaning\
1343 Valid Arg Meaning\
1344 "calls" call count\
1344 "calls" call count\
1345 "cumulative" cumulative time\
1345 "cumulative" cumulative time\
1346 "file" file name\
1346 "file" file name\
1347 "module" file name\
1347 "module" file name\
1348 "pcalls" primitive call count\
1348 "pcalls" primitive call count\
1349 "line" line number\
1349 "line" line number\
1350 "name" function name\
1350 "name" function name\
1351 "nfl" name/file/line\
1351 "nfl" name/file/line\
1352 "stdname" standard name\
1352 "stdname" standard name\
1353 "time" internal time
1353 "time" internal time
1354
1354
1355 Note that all sorts on statistics are in descending order (placing
1355 Note that all sorts on statistics are in descending order (placing
1356 most time consuming items first), where as name, file, and line number
1356 most time consuming items first), where as name, file, and line number
1357 searches are in ascending order (i.e., alphabetical). The subtle
1357 searches are in ascending order (i.e., alphabetical). The subtle
1358 distinction between "nfl" and "stdname" is that the standard name is a
1358 distinction between "nfl" and "stdname" is that the standard name is a
1359 sort of the name as printed, which means that the embedded line
1359 sort of the name as printed, which means that the embedded line
1360 numbers get compared in an odd way. For example, lines 3, 20, and 40
1360 numbers get compared in an odd way. For example, lines 3, 20, and 40
1361 would (if the file names were the same) appear in the string order
1361 would (if the file names were the same) appear in the string order
1362 "20" "3" and "40". In contrast, "nfl" does a numeric compare of the
1362 "20" "3" and "40". In contrast, "nfl" does a numeric compare of the
1363 line numbers. In fact, sort_stats("nfl") is the same as
1363 line numbers. In fact, sort_stats("nfl") is the same as
1364 sort_stats("name", "file", "line").
1364 sort_stats("name", "file", "line").
1365
1365
1366 -T <filename>: save profile results as shown on screen to a text
1366 -T <filename>: save profile results as shown on screen to a text
1367 file. The profile is still shown on screen.
1367 file. The profile is still shown on screen.
1368
1368
1369 -D <filename>: save (via dump_stats) profile statistics to given
1369 -D <filename>: save (via dump_stats) profile statistics to given
1370 filename. This data is in a format understod by the pstats module, and
1370 filename. This data is in a format understod by the pstats module, and
1371 is generated by a call to the dump_stats() method of profile
1371 is generated by a call to the dump_stats() method of profile
1372 objects. The profile is still shown on screen.
1372 objects. The profile is still shown on screen.
1373
1373
1374 If you want to run complete programs under the profiler's control, use
1374 If you want to run complete programs under the profiler's control, use
1375 '%run -p [prof_opts] filename.py [args to program]' where prof_opts
1375 '%run -p [prof_opts] filename.py [args to program]' where prof_opts
1376 contains profiler specific options as described here.
1376 contains profiler specific options as described here.
1377
1377
1378 You can read the complete documentation for the profile module with:\
1378 You can read the complete documentation for the profile module with:\
1379 In [1]: import profile; profile.help()
1379 In [1]: import profile; profile.help()
1380
1380
1381 **%psearch**::
1381 **%psearch**::
1382
1382
1383 Search for object in namespaces by wildcard.
1383 Search for object in namespaces by wildcard.
1384
1384
1385 %psearch [options] PATTERN [OBJECT TYPE]
1385 %psearch [options] PATTERN [OBJECT TYPE]
1386
1386
1387 Note: ? can be used as a synonym for %psearch, at the beginning or at
1387 Note: ? can be used as a synonym for %psearch, at the beginning or at
1388 the end: both a*? and ?a* are equivalent to '%psearch a*'. Still, the
1388 the end: both a*? and ?a* are equivalent to '%psearch a*'. Still, the
1389 rest of the command line must be unchanged (options come first), so
1389 rest of the command line must be unchanged (options come first), so
1390 for example the following forms are equivalent
1390 for example the following forms are equivalent
1391
1391
1392 %psearch -i a* function
1392 %psearch -i a* function
1393 -i a* function?
1393 -i a* function?
1394 ?-i a* function
1394 ?-i a* function
1395
1395
1396 Arguments:
1396 Arguments:
1397
1397
1398 PATTERN
1398 PATTERN
1399
1399
1400 where PATTERN is a string containing * as a wildcard similar to its
1400 where PATTERN is a string containing * as a wildcard similar to its
1401 use in a shell. The pattern is matched in all namespaces on the
1401 use in a shell. The pattern is matched in all namespaces on the
1402 search path. By default objects starting with a single _ are not
1402 search path. By default objects starting with a single _ are not
1403 matched, many IPython generated objects have a single
1403 matched, many IPython generated objects have a single
1404 underscore. The default is case insensitive matching. Matching is
1404 underscore. The default is case insensitive matching. Matching is
1405 also done on the attributes of objects and not only on the objects
1405 also done on the attributes of objects and not only on the objects
1406 in a module.
1406 in a module.
1407
1407
1408 [OBJECT TYPE]
1408 [OBJECT TYPE]
1409
1409
1410 Is the name of a python type from the types module. The name is
1410 Is the name of a python type from the types module. The name is
1411 given in lowercase without the ending type, ex. StringType is
1411 given in lowercase without the ending type, ex. StringType is
1412 written string. By adding a type here only objects matching the
1412 written string. By adding a type here only objects matching the
1413 given type are matched. Using all here makes the pattern match all
1413 given type are matched. Using all here makes the pattern match all
1414 types (this is the default).
1414 types (this is the default).
1415
1415
1416 Options:
1416 Options:
1417
1417
1418 -a: makes the pattern match even objects whose names start with a
1418 -a: makes the pattern match even objects whose names start with a
1419 single underscore. These names are normally ommitted from the
1419 single underscore. These names are normally ommitted from the
1420 search.
1420 search.
1421
1421
1422 -i/-c: make the pattern case insensitive/sensitive. If neither of
1422 -i/-c: make the pattern case insensitive/sensitive. If neither of
1423 these options is given, the default is read from your ipythonrc
1423 these options is given, the default is read from your ipythonrc
1424 file. The option name which sets this value is
1424 file. The option name which sets this value is
1425 'wildcards_case_sensitive'. If this option is not specified in your
1425 'wildcards_case_sensitive'. If this option is not specified in your
1426 ipythonrc file, IPython's internal default is to do a case sensitive
1426 ipythonrc file, IPython's internal default is to do a case sensitive
1427 search.
1427 search.
1428
1428
1429 -e/-s NAMESPACE: exclude/search a given namespace. The pattern you
1429 -e/-s NAMESPACE: exclude/search a given namespace. The pattern you
1430 specifiy can be searched in any of the following namespaces:
1430 specifiy can be searched in any of the following namespaces:
1431 'builtin', 'user', 'user_global','internal', 'alias', where
1431 'builtin', 'user', 'user_global','internal', 'alias', where
1432 'builtin' and 'user' are the search defaults. Note that you should
1432 'builtin' and 'user' are the search defaults. Note that you should
1433 not use quotes when specifying namespaces.
1433 not use quotes when specifying namespaces.
1434
1434
1435 'Builtin' contains the python module builtin, 'user' contains all
1435 'Builtin' contains the python module builtin, 'user' contains all
1436 user data, 'alias' only contain the shell aliases and no python
1436 user data, 'alias' only contain the shell aliases and no python
1437 objects, 'internal' contains objects used by IPython. The
1437 objects, 'internal' contains objects used by IPython. The
1438 'user_global' namespace is only used by embedded IPython instances,
1438 'user_global' namespace is only used by embedded IPython instances,
1439 and it contains module-level globals. You can add namespaces to the
1439 and it contains module-level globals. You can add namespaces to the
1440 search with -s or exclude them with -e (these options can be given
1440 search with -s or exclude them with -e (these options can be given
1441 more than once).
1441 more than once).
1442
1442
1443 Examples:
1443 Examples:
1444
1444
1445 %psearch a* -> objects beginning with an a
1445 %psearch a* -> objects beginning with an a
1446 %psearch -e builtin a* -> objects NOT in the builtin space starting in a
1446 %psearch -e builtin a* -> objects NOT in the builtin space starting in a
1447 %psearch a* function -> all functions beginning with an a
1447 %psearch a* function -> all functions beginning with an a
1448 %psearch re.e* -> objects beginning with an e in module re
1448 %psearch re.e* -> objects beginning with an e in module re
1449 %psearch r*.e* -> objects that start with e in modules starting in r
1449 %psearch r*.e* -> objects that start with e in modules starting in r
1450 %psearch r*.* string -> all strings in modules beginning with r
1450 %psearch r*.* string -> all strings in modules beginning with r
1451
1451
1452 Case sensitve search:
1452 Case sensitve search:
1453
1453
1454 %psearch -c a* list all object beginning with lower case a
1454 %psearch -c a* list all object beginning with lower case a
1455
1455
1456 Show objects beginning with a single _:
1456 Show objects beginning with a single _:
1457
1457
1458 %psearch -a _* list objects beginning with a single underscore
1458 %psearch -a _* list objects beginning with a single underscore
1459
1459
1460 **%psource**::
1460 **%psource**::
1461
1461
1462 Print (or run through pager) the source code for an object.
1462 Print (or run through pager) the source code for an object.
1463
1463
1464 **%pushd**::
1464 **%pushd**::
1465
1465
1466 Place the current dir on stack and change directory.
1466 Place the current dir on stack and change directory.
1467
1467
1468 Usage:\
1468 Usage:\
1469 %pushd ['dirname']
1469 %pushd ['dirname']
1470
1470
1471 **%pwd**::
1471 **%pwd**::
1472
1472
1473 Return the current working directory path.
1473 Return the current working directory path.
1474
1474
1475 **%pycat**::
1475 **%pycat**::
1476
1476
1477 Show a syntax-highlighted file through a pager.
1477 Show a syntax-highlighted file through a pager.
1478
1478
1479 This magic is similar to the cat utility, but it will assume the file
1479 This magic is similar to the cat utility, but it will assume the file
1480 to be Python source and will show it with syntax highlighting.
1480 to be Python source and will show it with syntax highlighting.
1481
1481
1482 **%quickref**::
1482 **%quickref**::
1483
1483
1484 Show a quick reference sheet
1484 Show a quick reference sheet
1485
1485
1486 **%quit**::
1486 **%quit**::
1487
1487
1488 Exit IPython, confirming if configured to do so (like %exit)
1488 Exit IPython, confirming if configured to do so (like %exit)
1489
1489
1490 **%r**::
1490 **%r**::
1491
1491
1492 Repeat previous input.
1492 Repeat previous input.
1493
1493
1494 Note: Consider using the more powerfull %rep instead!
1494 Note: Consider using the more powerfull %rep instead!
1495
1495
1496 If given an argument, repeats the previous command which starts with
1496 If given an argument, repeats the previous command which starts with
1497 the same string, otherwise it just repeats the previous input.
1497 the same string, otherwise it just repeats the previous input.
1498
1498
1499 Shell escaped commands (with ! as first character) are not recognized
1499 Shell escaped commands (with ! as first character) are not recognized
1500 by this system, only pure python code and magic commands.
1500 by this system, only pure python code and magic commands.
1501
1501
1502 **%rehashdir**::
1502 **%rehashdir**::
1503
1503
1504 Add executables in all specified dirs to alias table
1504 Add executables in all specified dirs to alias table
1505
1505
1506 Usage:
1506 Usage:
1507
1507
1508 %rehashdir c:/bin;c:/tools
1508 %rehashdir c:/bin;c:/tools
1509 - Add all executables under c:/bin and c:/tools to alias table, in
1509 - Add all executables under c:/bin and c:/tools to alias table, in
1510 order to make them directly executable from any directory.
1510 order to make them directly executable from any directory.
1511
1511
1512 Without arguments, add all executables in current directory.
1512 Without arguments, add all executables in current directory.
1513
1513
1514 **%rehashx**::
1514 **%rehashx**::
1515
1515
1516 Update the alias table with all executable files in $PATH.
1516 Update the alias table with all executable files in $PATH.
1517
1517
1518 This version explicitly checks that every entry in $PATH is a file
1518 This version explicitly checks that every entry in $PATH is a file
1519 with execute access (os.X_OK), so it is much slower than %rehash.
1519 with execute access (os.X_OK), so it is much slower than %rehash.
1520
1520
1521 Under Windows, it checks executability as a match agains a
1521 Under Windows, it checks executability as a match agains a
1522 '|'-separated string of extensions, stored in the IPython config
1522 '|'-separated string of extensions, stored in the IPython config
1523 variable win_exec_ext. This defaults to 'exe|com|bat'.
1523 variable win_exec_ext. This defaults to 'exe|com|bat'.
1524
1524
1525 This function also resets the root module cache of module completer,
1525 This function also resets the root module cache of module completer,
1526 used on slow filesystems.
1526 used on slow filesystems.
1527
1527
1528 **%rep**::
1528 **%rep**::
1529
1529
1530 Repeat a command, or get command to input line for editing
1530 Repeat a command, or get command to input line for editing
1531
1531
1532 - %rep (no arguments):
1532 - %rep (no arguments):
1533
1533
1534 Place a string version of last computation result (stored in the special '_'
1534 Place a string version of last computation result (stored in the special '_'
1535 variable) to the next input prompt. Allows you to create elaborate command
1535 variable) to the next input prompt. Allows you to create elaborate command
1536 lines without using copy-paste::
1536 lines without using copy-paste::
1537
1537
1538 $ l = ["hei", "vaan"]
1538 $ l = ["hei", "vaan"]
1539 $ "".join(l)
1539 $ "".join(l)
1540 ==> heivaan
1540 ==> heivaan
1541 $ %rep
1541 $ %rep
1542 $ heivaan_ <== cursor blinking
1542 $ heivaan_ <== cursor blinking
1543
1543
1544 %rep 45
1544 %rep 45
1545
1545
1546 Place history line 45 to next input prompt. Use %hist to find out the
1546 Place history line 45 to next input prompt. Use %hist to find out the
1547 number.
1547 number.
1548
1548
1549 %rep 1-4 6-7 3
1549 %rep 1-4 6-7 3
1550
1550
1551 Repeat the specified lines immediately. Input slice syntax is the same as
1551 Repeat the specified lines immediately. Input slice syntax is the same as
1552 in %macro and %save.
1552 in %macro and %save.
1553
1553
1554 %rep foo
1554 %rep foo
1555
1555
1556 Place the most recent line that has the substring "foo" to next input.
1556 Place the most recent line that has the substring "foo" to next input.
1557 (e.g. 'svn ci -m foobar').
1557 (e.g. 'svn ci -m foobar').
1558
1558
1559 **%reset**::
1559 **%reset**::
1560
1560
1561 Resets the namespace by removing all names defined by the user.
1561 Resets the namespace by removing all names defined by the user.
1562
1562
1563 Input/Output history are left around in case you need them.
1563 Input/Output history are left around in case you need them.
1564
1564
1565 **%run**::
1565 **%run**::
1566
1566
1567 Run the named file inside IPython as a program.
1567 Run the named file inside IPython as a program.
1568
1568
1569 Usage:\
1569 Usage:\
1570 %run [-n -i -t [-N<N>] -d [-b<N>] -p [profile options]] file [args]
1570 %run [-n -i -t [-N<N>] -d [-b<N>] -p [profile options]] file [args]
1571
1571
1572 Parameters after the filename are passed as command-line arguments to
1572 Parameters after the filename are passed as command-line arguments to
1573 the program (put in sys.argv). Then, control returns to IPython's
1573 the program (put in sys.argv). Then, control returns to IPython's
1574 prompt.
1574 prompt.
1575
1575
1576 This is similar to running at a system prompt:\
1576 This is similar to running at a system prompt:\
1577 $ python file args\
1577 $ python file args\
1578 but with the advantage of giving you IPython's tracebacks, and of
1578 but with the advantage of giving you IPython's tracebacks, and of
1579 loading all variables into your interactive namespace for further use
1579 loading all variables into your interactive namespace for further use
1580 (unless -p is used, see below).
1580 (unless -p is used, see below).
1581
1581
1582 The file is executed in a namespace initially consisting only of
1582 The file is executed in a namespace initially consisting only of
1583 __name__=='__main__' and sys.argv constructed as indicated. It thus
1583 __name__=='__main__' and sys.argv constructed as indicated. It thus
1584 sees its environment as if it were being run as a stand-alone program
1584 sees its environment as if it were being run as a stand-alone program
1585 (except for sharing global objects such as previously imported
1585 (except for sharing global objects such as previously imported
1586 modules). But after execution, the IPython interactive namespace gets
1586 modules). But after execution, the IPython interactive namespace gets
1587 updated with all variables defined in the program (except for __name__
1587 updated with all variables defined in the program (except for __name__
1588 and sys.argv). This allows for very convenient loading of code for
1588 and sys.argv). This allows for very convenient loading of code for
1589 interactive work, while giving each program a 'clean sheet' to run in.
1589 interactive work, while giving each program a 'clean sheet' to run in.
1590
1590
1591 Options:
1591 Options:
1592
1592
1593 -n: __name__ is NOT set to '__main__', but to the running file's name
1593 -n: __name__ is NOT set to '__main__', but to the running file's name
1594 without extension (as python does under import). This allows running
1594 without extension (as python does under import). This allows running
1595 scripts and reloading the definitions in them without calling code
1595 scripts and reloading the definitions in them without calling code
1596 protected by an ' if __name__ == "__main__" ' clause.
1596 protected by an ' if __name__ == "__main__" ' clause.
1597
1597
1598 -i: run the file in IPython's namespace instead of an empty one. This
1598 -i: run the file in IPython's namespace instead of an empty one. This
1599 is useful if you are experimenting with code written in a text editor
1599 is useful if you are experimenting with code written in a text editor
1600 which depends on variables defined interactively.
1600 which depends on variables defined interactively.
1601
1601
1602 -e: ignore sys.exit() calls or SystemExit exceptions in the script
1602 -e: ignore sys.exit() calls or SystemExit exceptions in the script
1603 being run. This is particularly useful if IPython is being used to
1603 being run. This is particularly useful if IPython is being used to
1604 run unittests, which always exit with a sys.exit() call. In such
1604 run unittests, which always exit with a sys.exit() call. In such
1605 cases you are interested in the output of the test results, not in
1605 cases you are interested in the output of the test results, not in
1606 seeing a traceback of the unittest module.
1606 seeing a traceback of the unittest module.
1607
1607
1608 -t: print timing information at the end of the run. IPython will give
1608 -t: print timing information at the end of the run. IPython will give
1609 you an estimated CPU time consumption for your script, which under
1609 you an estimated CPU time consumption for your script, which under
1610 Unix uses the resource module to avoid the wraparound problems of
1610 Unix uses the resource module to avoid the wraparound problems of
1611 time.clock(). Under Unix, an estimate of time spent on system tasks
1611 time.clock(). Under Unix, an estimate of time spent on system tasks
1612 is also given (for Windows platforms this is reported as 0.0).
1612 is also given (for Windows platforms this is reported as 0.0).
1613
1613
1614 If -t is given, an additional -N<N> option can be given, where <N>
1614 If -t is given, an additional -N<N> option can be given, where <N>
1615 must be an integer indicating how many times you want the script to
1615 must be an integer indicating how many times you want the script to
1616 run. The final timing report will include total and per run results.
1616 run. The final timing report will include total and per run results.
1617
1617
1618 For example (testing the script uniq_stable.py):
1618 For example (testing the script uniq_stable.py):
1619
1619
1620 In [1]: run -t uniq_stable
1620 In [1]: run -t uniq_stable
1621
1621
1622 IPython CPU timings (estimated):\
1622 IPython CPU timings (estimated):\
1623 User : 0.19597 s.\
1623 User : 0.19597 s.\
1624 System: 0.0 s.\
1624 System: 0.0 s.\
1625
1625
1626 In [2]: run -t -N5 uniq_stable
1626 In [2]: run -t -N5 uniq_stable
1627
1627
1628 IPython CPU timings (estimated):\
1628 IPython CPU timings (estimated):\
1629 Total runs performed: 5\
1629 Total runs performed: 5\
1630 Times : Total Per run\
1630 Times : Total Per run\
1631 User : 0.910862 s, 0.1821724 s.\
1631 User : 0.910862 s, 0.1821724 s.\
1632 System: 0.0 s, 0.0 s.
1632 System: 0.0 s, 0.0 s.
1633
1633
1634 -d: run your program under the control of pdb, the Python debugger.
1634 -d: run your program under the control of pdb, the Python debugger.
1635 This allows you to execute your program step by step, watch variables,
1635 This allows you to execute your program step by step, watch variables,
1636 etc. Internally, what IPython does is similar to calling:
1636 etc. Internally, what IPython does is similar to calling:
1637
1637
1638 pdb.run('execfile("YOURFILENAME")')
1638 pdb.run('execfile("YOURFILENAME")')
1639
1639
1640 with a breakpoint set on line 1 of your file. You can change the line
1640 with a breakpoint set on line 1 of your file. You can change the line
1641 number for this automatic breakpoint to be <N> by using the -bN option
1641 number for this automatic breakpoint to be <N> by using the -bN option
1642 (where N must be an integer). For example:
1642 (where N must be an integer). For example:
1643
1643
1644 %run -d -b40 myscript
1644 %run -d -b40 myscript
1645
1645
1646 will set the first breakpoint at line 40 in myscript.py. Note that
1646 will set the first breakpoint at line 40 in myscript.py. Note that
1647 the first breakpoint must be set on a line which actually does
1647 the first breakpoint must be set on a line which actually does
1648 something (not a comment or docstring) for it to stop execution.
1648 something (not a comment or docstring) for it to stop execution.
1649
1649
1650 When the pdb debugger starts, you will see a (Pdb) prompt. You must
1650 When the pdb debugger starts, you will see a (Pdb) prompt. You must
1651 first enter 'c' (without qoutes) to start execution up to the first
1651 first enter 'c' (without qoutes) to start execution up to the first
1652 breakpoint.
1652 breakpoint.
1653
1653
1654 Entering 'help' gives information about the use of the debugger. You
1654 Entering 'help' gives information about the use of the debugger. You
1655 can easily see pdb's full documentation with "import pdb;pdb.help()"
1655 can easily see pdb's full documentation with "import pdb;pdb.help()"
1656 at a prompt.
1656 at a prompt.
1657
1657
1658 -p: run program under the control of the Python profiler module (which
1658 -p: run program under the control of the Python profiler module (which
1659 prints a detailed report of execution times, function calls, etc).
1659 prints a detailed report of execution times, function calls, etc).
1660
1660
1661 You can pass other options after -p which affect the behavior of the
1661 You can pass other options after -p which affect the behavior of the
1662 profiler itself. See the docs for %prun for details.
1662 profiler itself. See the docs for %prun for details.
1663
1663
1664 In this mode, the program's variables do NOT propagate back to the
1664 In this mode, the program's variables do NOT propagate back to the
1665 IPython interactive namespace (because they remain in the namespace
1665 IPython interactive namespace (because they remain in the namespace
1666 where the profiler executes them).
1666 where the profiler executes them).
1667
1667
1668 Internally this triggers a call to %prun, see its documentation for
1668 Internally this triggers a call to %prun, see its documentation for
1669 details on the options available specifically for profiling.
1669 details on the options available specifically for profiling.
1670
1670
1671 There is one special usage for which the text above doesn't apply:
1671 There is one special usage for which the text above doesn't apply:
1672 if the filename ends with .ipy, the file is run as ipython script,
1672 if the filename ends with .ipy, the file is run as ipython script,
1673 just as if the commands were written on IPython prompt.
1673 just as if the commands were written on IPython prompt.
1674
1674
1675 **%runlog**::
1675 **%runlog**::
1676
1676
1677 Run files as logs.
1677 Run files as logs.
1678
1678
1679 Usage:\
1679 Usage:\
1680 %runlog file1 file2 ...
1680 %runlog file1 file2 ...
1681
1681
1682 Run the named files (treating them as log files) in sequence inside
1682 Run the named files (treating them as log files) in sequence inside
1683 the interpreter, and return to the prompt. This is much slower than
1683 the interpreter, and return to the prompt. This is much slower than
1684 %run because each line is executed in a try/except block, but it
1684 %run because each line is executed in a try/except block, but it
1685 allows running files with syntax errors in them.
1685 allows running files with syntax errors in them.
1686
1686
1687 Normally IPython will guess when a file is one of its own logfiles, so
1687 Normally IPython will guess when a file is one of its own logfiles, so
1688 you can typically use %run even for logs. This shorthand allows you to
1688 you can typically use %run even for logs. This shorthand allows you to
1689 force any file to be treated as a log file.
1689 force any file to be treated as a log file.
1690
1690
1691 **%save**::
1691 **%save**::
1692
1692
1693 Save a set of lines to a given filename.
1693 Save a set of lines to a given filename.
1694
1694
1695 Usage:\
1695 Usage:\
1696 %save [options] filename n1-n2 n3-n4 ... n5 .. n6 ...
1696 %save [options] filename n1-n2 n3-n4 ... n5 .. n6 ...
1697
1697
1698 Options:
1698 Options:
1699
1699
1700 -r: use 'raw' input. By default, the 'processed' history is used,
1700 -r: use 'raw' input. By default, the 'processed' history is used,
1701 so that magics are loaded in their transformed version to valid
1701 so that magics are loaded in their transformed version to valid
1702 Python. If this option is given, the raw input as typed as the
1702 Python. If this option is given, the raw input as typed as the
1703 command line is used instead.
1703 command line is used instead.
1704
1704
1705 This function uses the same syntax as %macro for line extraction, but
1705 This function uses the same syntax as %macro for line extraction, but
1706 instead of creating a macro it saves the resulting string to the
1706 instead of creating a macro it saves the resulting string to the
1707 filename you specify.
1707 filename you specify.
1708
1708
1709 It adds a '.py' extension to the file if you don't do so yourself, and
1709 It adds a '.py' extension to the file if you don't do so yourself, and
1710 it asks for confirmation before overwriting existing files.
1710 it asks for confirmation before overwriting existing files.
1711
1711
1712 **%sc**::
1712 **%sc**::
1713
1713
1714 Shell capture - execute a shell command and capture its output.
1714 Shell capture - execute a shell command and capture its output.
1715
1715
1716 DEPRECATED. Suboptimal, retained for backwards compatibility.
1716 DEPRECATED. Suboptimal, retained for backwards compatibility.
1717
1717
1718 You should use the form 'var = !command' instead. Example:
1718 You should use the form 'var = !command' instead. Example:
1719
1719
1720 "%sc -l myfiles = ls ~" should now be written as
1720 "%sc -l myfiles = ls ~" should now be written as
1721
1721
1722 "myfiles = !ls ~"
1722 "myfiles = !ls ~"
1723
1723
1724 myfiles.s, myfiles.l and myfiles.n still apply as documented
1724 myfiles.s, myfiles.l and myfiles.n still apply as documented
1725 below.
1725 below.
1726
1726
1727 --
1727 --
1728 %sc [options] varname=command
1728 %sc [options] varname=command
1729
1729
1730 IPython will run the given command using commands.getoutput(), and
1730 IPython will run the given command using commands.getoutput(), and
1731 will then update the user's interactive namespace with a variable
1731 will then update the user's interactive namespace with a variable
1732 called varname, containing the value of the call. Your command can
1732 called varname, containing the value of the call. Your command can
1733 contain shell wildcards, pipes, etc.
1733 contain shell wildcards, pipes, etc.
1734
1734
1735 The '=' sign in the syntax is mandatory, and the variable name you
1735 The '=' sign in the syntax is mandatory, and the variable name you
1736 supply must follow Python's standard conventions for valid names.
1736 supply must follow Python's standard conventions for valid names.
1737
1737
1738 (A special format without variable name exists for internal use)
1738 (A special format without variable name exists for internal use)
1739
1739
1740 Options:
1740 Options:
1741
1741
1742 -l: list output. Split the output on newlines into a list before
1742 -l: list output. Split the output on newlines into a list before
1743 assigning it to the given variable. By default the output is stored
1743 assigning it to the given variable. By default the output is stored
1744 as a single string.
1744 as a single string.
1745
1745
1746 -v: verbose. Print the contents of the variable.
1746 -v: verbose. Print the contents of the variable.
1747
1747
1748 In most cases you should not need to split as a list, because the
1748 In most cases you should not need to split as a list, because the
1749 returned value is a special type of string which can automatically
1749 returned value is a special type of string which can automatically
1750 provide its contents either as a list (split on newlines) or as a
1750 provide its contents either as a list (split on newlines) or as a
1751 space-separated string. These are convenient, respectively, either
1751 space-separated string. These are convenient, respectively, either
1752 for sequential processing or to be passed to a shell command.
1752 for sequential processing or to be passed to a shell command.
1753
1753
1754 For example:
1754 For example:
1755
1755
1756 # Capture into variable a
1756 # Capture into variable a
1757 In [9]: sc a=ls *py
1757 In [9]: sc a=ls *py
1758
1758
1759 # a is a string with embedded newlines
1759 # a is a string with embedded newlines
1760 In [10]: a
1760 In [10]: a
1761 Out[10]: 'setup.py win32_manual_post_install.py'
1761 Out[10]: 'setup.py win32_manual_post_install.py'
1762
1762
1763 # which can be seen as a list:
1763 # which can be seen as a list:
1764 In [11]: a.l
1764 In [11]: a.l
1765 Out[11]: ['setup.py', 'win32_manual_post_install.py']
1765 Out[11]: ['setup.py', 'win32_manual_post_install.py']
1766
1766
1767 # or as a whitespace-separated string:
1767 # or as a whitespace-separated string:
1768 In [12]: a.s
1768 In [12]: a.s
1769 Out[12]: 'setup.py win32_manual_post_install.py'
1769 Out[12]: 'setup.py win32_manual_post_install.py'
1770
1770
1771 # a.s is useful to pass as a single command line:
1771 # a.s is useful to pass as a single command line:
1772 In [13]: !wc -l $a.s
1772 In [13]: !wc -l $a.s
1773 146 setup.py
1773 146 setup.py
1774 130 win32_manual_post_install.py
1774 130 win32_manual_post_install.py
1775 276 total
1775 276 total
1776
1776
1777 # while the list form is useful to loop over:
1777 # while the list form is useful to loop over:
1778 In [14]: for f in a.l:
1778 In [14]: for f in a.l:
1779 ....: !wc -l $f
1779 ....: !wc -l $f
1780 ....:
1780 ....:
1781 146 setup.py
1781 146 setup.py
1782 130 win32_manual_post_install.py
1782 130 win32_manual_post_install.py
1783
1783
1784 Similiarly, the lists returned by the -l option are also special, in
1784 Similiarly, the lists returned by the -l option are also special, in
1785 the sense that you can equally invoke the .s attribute on them to
1785 the sense that you can equally invoke the .s attribute on them to
1786 automatically get a whitespace-separated string from their contents:
1786 automatically get a whitespace-separated string from their contents:
1787
1787
1788 In [1]: sc -l b=ls *py
1788 In [1]: sc -l b=ls *py
1789
1789
1790 In [2]: b
1790 In [2]: b
1791 Out[2]: ['setup.py', 'win32_manual_post_install.py']
1791 Out[2]: ['setup.py', 'win32_manual_post_install.py']
1792
1792
1793 In [3]: b.s
1793 In [3]: b.s
1794 Out[3]: 'setup.py win32_manual_post_install.py'
1794 Out[3]: 'setup.py win32_manual_post_install.py'
1795
1795
1796 In summary, both the lists and strings used for ouptut capture have
1796 In summary, both the lists and strings used for ouptut capture have
1797 the following special attributes:
1797 the following special attributes:
1798
1798
1799 .l (or .list) : value as list.
1799 .l (or .list) : value as list.
1800 .n (or .nlstr): value as newline-separated string.
1800 .n (or .nlstr): value as newline-separated string.
1801 .s (or .spstr): value as space-separated string.
1801 .s (or .spstr): value as space-separated string.
1802
1802
1803 **%store**::
1803 **%store**::
1804
1804
1805 Lightweight persistence for python variables.
1805 Lightweight persistence for python variables.
1806
1806
1807 Example:
1807 Example:
1808
1808
1809 ville@badger[~]|1> A = ['hello',10,'world']\
1809 ville@badger[~]|1> A = ['hello',10,'world']\
1810 ville@badger[~]|2> %store A\
1810 ville@badger[~]|2> %store A\
1811 ville@badger[~]|3> Exit
1811 ville@badger[~]|3> Exit
1812
1812
1813 (IPython session is closed and started again...)
1813 (IPython session is closed and started again...)
1814
1814
1815 ville@badger:~$ ipython -p pysh\
1815 ville@badger:~$ ipython -p pysh\
1816 ville@badger[~]|1> print A
1816 ville@badger[~]|1> print A
1817
1817
1818 ['hello', 10, 'world']
1818 ['hello', 10, 'world']
1819
1819
1820 Usage:
1820 Usage:
1821
1821
1822 %store - Show list of all variables and their current values\
1822 %store - Show list of all variables and their current values\
1823 %store <var> - Store the *current* value of the variable to disk\
1823 %store <var> - Store the *current* value of the variable to disk\
1824 %store -d <var> - Remove the variable and its value from storage\
1824 %store -d <var> - Remove the variable and its value from storage\
1825 %store -z - Remove all variables from storage\
1825 %store -z - Remove all variables from storage\
1826 %store -r - Refresh all variables from store (delete current vals)\
1826 %store -r - Refresh all variables from store (delete current vals)\
1827 %store foo >a.txt - Store value of foo to new file a.txt\
1827 %store foo >a.txt - Store value of foo to new file a.txt\
1828 %store foo >>a.txt - Append value of foo to file a.txt\
1828 %store foo >>a.txt - Append value of foo to file a.txt\
1829
1829
1830 It should be noted that if you change the value of a variable, you
1830 It should be noted that if you change the value of a variable, you
1831 need to %store it again if you want to persist the new value.
1831 need to %store it again if you want to persist the new value.
1832
1832
1833 Note also that the variables will need to be pickleable; most basic
1833 Note also that the variables will need to be pickleable; most basic
1834 python types can be safely %stored.
1834 python types can be safely %stored.
1835
1835
1836 Also aliases can be %store'd across sessions.
1836 Also aliases can be %store'd across sessions.
1837
1837
1838 **%sx**::
1838 **%sx**::
1839
1839
1840 Shell execute - run a shell command and capture its output.
1840 Shell execute - run a shell command and capture its output.
1841
1841
1842 %sx command
1842 %sx command
1843
1843
1844 IPython will run the given command using commands.getoutput(), and
1844 IPython will run the given command using commands.getoutput(), and
1845 return the result formatted as a list (split on '\n'). Since the
1845 return the result formatted as a list (split on '\n'). Since the
1846 output is _returned_, it will be stored in ipython's regular output
1846 output is _returned_, it will be stored in ipython's regular output
1847 cache Out[N] and in the '_N' automatic variables.
1847 cache Out[N] and in the '_N' automatic variables.
1848
1848
1849 Notes:
1849 Notes:
1850
1850
1851 1) If an input line begins with '!!', then %sx is automatically
1851 1) If an input line begins with '!!', then %sx is automatically
1852 invoked. That is, while:
1852 invoked. That is, while:
1853 !ls
1853 !ls
1854 causes ipython to simply issue system('ls'), typing
1854 causes ipython to simply issue system('ls'), typing
1855 !!ls
1855 !!ls
1856 is a shorthand equivalent to:
1856 is a shorthand equivalent to:
1857 %sx ls
1857 %sx ls
1858
1858
1859 2) %sx differs from %sc in that %sx automatically splits into a list,
1859 2) %sx differs from %sc in that %sx automatically splits into a list,
1860 like '%sc -l'. The reason for this is to make it as easy as possible
1860 like '%sc -l'. The reason for this is to make it as easy as possible
1861 to process line-oriented shell output via further python commands.
1861 to process line-oriented shell output via further python commands.
1862 %sc is meant to provide much finer control, but requires more
1862 %sc is meant to provide much finer control, but requires more
1863 typing.
1863 typing.
1864
1864
1865 3) Just like %sc -l, this is a list with special attributes:
1865 3) Just like %sc -l, this is a list with special attributes:
1866
1866
1867 .l (or .list) : value as list.
1867 .l (or .list) : value as list.
1868 .n (or .nlstr): value as newline-separated string.
1868 .n (or .nlstr): value as newline-separated string.
1869 .s (or .spstr): value as whitespace-separated string.
1869 .s (or .spstr): value as whitespace-separated string.
1870
1870
1871 This is very useful when trying to use such lists as arguments to
1871 This is very useful when trying to use such lists as arguments to
1872 system commands.
1872 system commands.
1873
1873
1874 **%system_verbose**::
1874 **%system_verbose**::
1875
1875
1876 Set verbose printing of system calls.
1876 Set verbose printing of system calls.
1877
1877
1878 If called without an argument, act as a toggle
1878 If called without an argument, act as a toggle
1879
1879
1880 **%time**::
1880 **%time**::
1881
1881
1882 Time execution of a Python statement or expression.
1882 Time execution of a Python statement or expression.
1883
1883
1884 The CPU and wall clock times are printed, and the value of the
1884 The CPU and wall clock times are printed, and the value of the
1885 expression (if any) is returned. Note that under Win32, system time
1885 expression (if any) is returned. Note that under Win32, system time
1886 is always reported as 0, since it can not be measured.
1886 is always reported as 0, since it can not be measured.
1887
1887
1888 This function provides very basic timing functionality. In Python
1888 This function provides very basic timing functionality. In Python
1889 2.3, the timeit module offers more control and sophistication, so this
1889 2.3, the timeit module offers more control and sophistication, so this
1890 could be rewritten to use it (patches welcome).
1890 could be rewritten to use it (patches welcome).
1891
1891
1892 Some examples:
1892 Some examples:
1893
1893
1894 In [1]: time 2**128
1894 In [1]: time 2**128
1895 CPU times: user 0.00 s, sys: 0.00 s, total: 0.00 s
1895 CPU times: user 0.00 s, sys: 0.00 s, total: 0.00 s
1896 Wall time: 0.00
1896 Wall time: 0.00
1897 Out[1]: 340282366920938463463374607431768211456L
1897 Out[1]: 340282366920938463463374607431768211456L
1898
1898
1899 In [2]: n = 1000000
1899 In [2]: n = 1000000
1900
1900
1901 In [3]: time sum(range(n))
1901 In [3]: time sum(range(n))
1902 CPU times: user 1.20 s, sys: 0.05 s, total: 1.25 s
1902 CPU times: user 1.20 s, sys: 0.05 s, total: 1.25 s
1903 Wall time: 1.37
1903 Wall time: 1.37
1904 Out[3]: 499999500000L
1904 Out[3]: 499999500000L
1905
1905
1906 In [4]: time print 'hello world'
1906 In [4]: time print 'hello world'
1907 hello world
1907 hello world
1908 CPU times: user 0.00 s, sys: 0.00 s, total: 0.00 s
1908 CPU times: user 0.00 s, sys: 0.00 s, total: 0.00 s
1909 Wall time: 0.00
1909 Wall time: 0.00
1910
1910
1911 Note that the time needed by Python to compile the given expression
1911 Note that the time needed by Python to compile the given expression
1912 will be reported if it is more than 0.1s. In this example, the
1912 will be reported if it is more than 0.1s. In this example, the
1913 actual exponentiation is done by Python at compilation time, so while
1913 actual exponentiation is done by Python at compilation time, so while
1914 the expression can take a noticeable amount of time to compute, that
1914 the expression can take a noticeable amount of time to compute, that
1915 time is purely due to the compilation:
1915 time is purely due to the compilation:
1916
1916
1917 In [5]: time 3**9999;
1917 In [5]: time 3**9999;
1918 CPU times: user 0.00 s, sys: 0.00 s, total: 0.00 s
1918 CPU times: user 0.00 s, sys: 0.00 s, total: 0.00 s
1919 Wall time: 0.00 s
1919 Wall time: 0.00 s
1920
1920
1921 In [6]: time 3**999999;
1921 In [6]: time 3**999999;
1922 CPU times: user 0.00 s, sys: 0.00 s, total: 0.00 s
1922 CPU times: user 0.00 s, sys: 0.00 s, total: 0.00 s
1923 Wall time: 0.00 s
1923 Wall time: 0.00 s
1924 Compiler : 0.78 s
1924 Compiler : 0.78 s
1925
1925
1926 **%timeit**::
1926 **%timeit**::
1927
1927
1928 Time execution of a Python statement or expression
1928 Time execution of a Python statement or expression
1929
1929
1930 Usage:\
1930 Usage:\
1931 %timeit [-n<N> -r<R> [-t|-c]] statement
1931 %timeit [-n<N> -r<R> [-t|-c]] statement
1932
1932
1933 Time execution of a Python statement or expression using the timeit
1933 Time execution of a Python statement or expression using the timeit
1934 module.
1934 module.
1935
1935
1936 Options:
1936 Options:
1937 -n<N>: execute the given statement <N> times in a loop. If this value
1937 -n<N>: execute the given statement <N> times in a loop. If this value
1938 is not given, a fitting value is chosen.
1938 is not given, a fitting value is chosen.
1939
1939
1940 -r<R>: repeat the loop iteration <R> times and take the best result.
1940 -r<R>: repeat the loop iteration <R> times and take the best result.
1941 Default: 3
1941 Default: 3
1942
1942
1943 -t: use time.time to measure the time, which is the default on Unix.
1943 -t: use time.time to measure the time, which is the default on Unix.
1944 This function measures wall time.
1944 This function measures wall time.
1945
1945
1946 -c: use time.clock to measure the time, which is the default on
1946 -c: use time.clock to measure the time, which is the default on
1947 Windows and measures wall time. On Unix, resource.getrusage is used
1947 Windows and measures wall time. On Unix, resource.getrusage is used
1948 instead and returns the CPU user time.
1948 instead and returns the CPU user time.
1949
1949
1950 -p<P>: use a precision of <P> digits to display the timing result.
1950 -p<P>: use a precision of <P> digits to display the timing result.
1951 Default: 3
1951 Default: 3
1952
1952
1953
1953
1954 Examples:\
1954 Examples:\
1955 In [1]: %timeit pass
1955 In [1]: %timeit pass
1956 10000000 loops, best of 3: 53.3 ns per loop
1956 10000000 loops, best of 3: 53.3 ns per loop
1957
1957
1958 In [2]: u = None
1958 In [2]: u = None
1959
1959
1960 In [3]: %timeit u is None
1960 In [3]: %timeit u is None
1961 10000000 loops, best of 3: 184 ns per loop
1961 10000000 loops, best of 3: 184 ns per loop
1962
1962
1963 In [4]: %timeit -r 4 u == None
1963 In [4]: %timeit -r 4 u == None
1964 1000000 loops, best of 4: 242 ns per loop
1964 1000000 loops, best of 4: 242 ns per loop
1965
1965
1966 In [5]: import time
1966 In [5]: import time
1967
1967
1968 In [6]: %timeit -n1 time.sleep(2)
1968 In [6]: %timeit -n1 time.sleep(2)
1969 1 loops, best of 3: 2 s per loop
1969 1 loops, best of 3: 2 s per loop
1970
1970
1971
1971
1972 The times reported by %timeit will be slightly higher than those
1972 The times reported by %timeit will be slightly higher than those
1973 reported by the timeit.py script when variables are accessed. This is
1973 reported by the timeit.py script when variables are accessed. This is
1974 due to the fact that %timeit executes the statement in the namespace
1974 due to the fact that %timeit executes the statement in the namespace
1975 of the shell, compared with timeit.py, which uses a single setup
1975 of the shell, compared with timeit.py, which uses a single setup
1976 statement to import function or create variables. Generally, the bias
1976 statement to import function or create variables. Generally, the bias
1977 does not matter as long as results from timeit.py are not mixed with
1977 does not matter as long as results from timeit.py are not mixed with
1978 those from %timeit.
1978 those from %timeit.
1979
1979
1980 **%unalias**::
1980 **%unalias**::
1981
1981
1982 Remove an alias
1982 Remove an alias
1983
1983
1984 **%upgrade**::
1984 **%upgrade**::
1985
1985
1986 Upgrade your IPython installation
1986 Upgrade your IPython installation
1987
1987
1988 This will copy the config files that don't yet exist in your
1988 This will copy the config files that don't yet exist in your
1989 ipython dir from the system config dir. Use this after upgrading
1989 ipython dir from the system config dir. Use this after upgrading
1990 IPython if you don't wish to delete your .ipython dir.
1990 IPython if you don't wish to delete your .ipython dir.
1991
1991
1992 Call with -nolegacy to get rid of ipythonrc* files (recommended for
1992 Call with -nolegacy to get rid of ipythonrc* files (recommended for
1993 new users)
1993 new users)
1994
1994
1995 **%which**::
1995 **%which**::
1996
1996
1997 %which <cmd> => search PATH for files matching cmd. Also scans aliases.
1997 %which <cmd> => search PATH for files matching cmd. Also scans aliases.
1998
1998
1999 Traverses PATH and prints all files (not just executables!) that match the
1999 Traverses PATH and prints all files (not just executables!) that match the
2000 pattern on command line. Probably more useful in finding stuff
2000 pattern on command line. Probably more useful in finding stuff
2001 interactively than 'which', which only prints the first matching item.
2001 interactively than 'which', which only prints the first matching item.
2002
2002
2003 Also discovers and expands aliases, so you'll see what will be executed
2003 Also discovers and expands aliases, so you'll see what will be executed
2004 when you call an alias.
2004 when you call an alias.
2005
2005
2006 Example:
2006 Example:
2007
2007
2008 [~]|62> %which d
2008 [~]|62> %which d
2009 d -> ls -F --color=auto
2009 d -> ls -F --color=auto
2010 == c:\cygwin\bin\ls.exe
2010 == c:\cygwin\bin\ls.exe
2011 c:\cygwin\bin\d.exe
2011 c:\cygwin\bin\d.exe
2012
2012
2013 [~]|64> %which diff*
2013 [~]|64> %which diff*
2014 diff3 -> diff3
2014 diff3 -> diff3
2015 == c:\cygwin\bin\diff3.exe
2015 == c:\cygwin\bin\diff3.exe
2016 diff -> diff
2016 diff -> diff
2017 == c:\cygwin\bin\diff.exe
2017 == c:\cygwin\bin\diff.exe
2018 c:\cygwin\bin\diff.exe
2018 c:\cygwin\bin\diff.exe
2019 c:\cygwin\bin\diff3.exe
2019 c:\cygwin\bin\diff3.exe
2020
2020
2021 **%who**::
2021 **%who**::
2022
2022
2023 Print all interactive variables, with some minimal formatting.
2023 Print all interactive variables, with some minimal formatting.
2024
2024
2025 If any arguments are given, only variables whose type matches one of
2025 If any arguments are given, only variables whose type matches one of
2026 these are printed. For example:
2026 these are printed. For example:
2027
2027
2028 %who function str
2028 %who function str
2029
2029
2030 will only list functions and strings, excluding all other types of
2030 will only list functions and strings, excluding all other types of
2031 variables. To find the proper type names, simply use type(var) at a
2031 variables. To find the proper type names, simply use type(var) at a
2032 command line to see how python prints type names. For example:
2032 command line to see how python prints type names. For example:
2033
2033
2034 In [1]: type('hello')\
2034 In [1]: type('hello')\
2035 Out[1]: <type 'str'>
2035 Out[1]: <type 'str'>
2036
2036
2037 indicates that the type name for strings is 'str'.
2037 indicates that the type name for strings is 'str'.
2038
2038
2039 %who always excludes executed names loaded through your configuration
2039 %who always excludes executed names loaded through your configuration
2040 file and things which are internal to IPython.
2040 file and things which are internal to IPython.
2041
2041
2042 This is deliberate, as typically you may load many modules and the
2042 This is deliberate, as typically you may load many modules and the
2043 purpose of %who is to show you only what you've manually defined.
2043 purpose of %who is to show you only what you've manually defined.
2044
2044
2045 **%who_ls**::
2045 **%who_ls**::
2046
2046
2047 Return a sorted list of all interactive variables.
2047 Return a sorted list of all interactive variables.
2048
2048
2049 If arguments are given, only variables of types matching these
2049 If arguments are given, only variables of types matching these
2050 arguments are returned.
2050 arguments are returned.
2051
2051
2052 **%whos**::
2052 **%whos**::
2053
2053
2054 Like %who, but gives some extra information about each variable.
2054 Like %who, but gives some extra information about each variable.
2055
2055
2056 The same type filtering of %who can be applied here.
2056 The same type filtering of %who can be applied here.
2057
2057
2058 For all variables, the type is printed. Additionally it prints:
2058 For all variables, the type is printed. Additionally it prints:
2059
2059
2060 - For {},[],(): their length.
2060 - For {},[],(): their length.
2061
2061
2062 - For numpy and Numeric arrays, a summary with shape, number of
2062 - For numpy and Numeric arrays, a summary with shape, number of
2063 elements, typecode and size in memory.
2063 elements, typecode and size in memory.
2064
2064
2065 - Everything else: a string representation, snipping their middle if
2065 - Everything else: a string representation, snipping their middle if
2066 too long.
2066 too long.
2067
2067
2068 **%xmode**::
2068 **%xmode**::
2069
2069
2070 Switch modes for the exception handlers.
2070 Switch modes for the exception handlers.
2071
2071
2072 Valid modes: Plain, Context and Verbose.
2072 Valid modes: Plain, Context and Verbose.
2073
2073
2074 If called without arguments, acts as a toggle.
2074 If called without arguments, acts as a toggle.
2075
2075
2076 .. magic_end
2076 .. magic_end
2077
2077
2078 Access to the standard Python help
2078 Access to the standard Python help
2079 ----------------------------------
2079 ----------------------------------
2080
2080
2081 As of Python 2.1, a help system is available with access to object docstrings
2081 As of Python 2.1, a help system is available with access to object docstrings
2082 and the Python manuals. Simply type 'help' (no quotes) to access it. You can
2082 and the Python manuals. Simply type 'help' (no quotes) to access it. You can
2083 also type help(object) to obtain information about a given object, and
2083 also type help(object) to obtain information about a given object, and
2084 help('keyword') for information on a keyword. As noted :ref:`here
2084 help('keyword') for information on a keyword. As noted :ref:`here
2085 <accessing_help>`, you need to properly configure your environment variable
2085 <accessing_help>`, you need to properly configure your environment variable
2086 PYTHONDOCS for this feature to work correctly.
2086 PYTHONDOCS for this feature to work correctly.
2087
2087
2088 .. _dynamic_object_info:
2088 .. _dynamic_object_info:
2089
2089
2090 Dynamic object information
2090 Dynamic object information
2091 --------------------------
2091 --------------------------
2092
2092
2093 Typing ?word or word? prints detailed information about an object. If
2093 Typing ?word or word? prints detailed information about an object. If
2094 certain strings in the object are too long (docstrings, code, etc.) they
2094 certain strings in the object are too long (docstrings, code, etc.) they
2095 get snipped in the center for brevity. This system gives access variable
2095 get snipped in the center for brevity. This system gives access variable
2096 types and values, full source code for any object (if available),
2096 types and values, full source code for any object (if available),
2097 function prototypes and other useful information.
2097 function prototypes and other useful information.
2098
2098
2099 Typing ??word or word?? gives access to the full information without
2099 Typing ??word or word?? gives access to the full information without
2100 snipping long strings. Long strings are sent to the screen through the
2100 snipping long strings. Long strings are sent to the screen through the
2101 less pager if longer than the screen and printed otherwise. On systems
2101 less pager if longer than the screen and printed otherwise. On systems
2102 lacking the less command, IPython uses a very basic internal pager.
2102 lacking the less command, IPython uses a very basic internal pager.
2103
2103
2104 The following magic functions are particularly useful for gathering
2104 The following magic functions are particularly useful for gathering
2105 information about your working environment. You can get more details by
2105 information about your working environment. You can get more details by
2106 typing %magic or querying them individually (use %function_name? with or
2106 typing %magic or querying them individually (use %function_name? with or
2107 without the %), this is just a summary:
2107 without the %), this is just a summary:
2108
2108
2109 * **%pdoc <object>**: Print (or run through a pager if too long) the
2109 * **%pdoc <object>**: Print (or run through a pager if too long) the
2110 docstring for an object. If the given object is a class, it will
2110 docstring for an object. If the given object is a class, it will
2111 print both the class and the constructor docstrings.
2111 print both the class and the constructor docstrings.
2112 * **%pdef <object>**: Print the definition header for any callable
2112 * **%pdef <object>**: Print the definition header for any callable
2113 object. If the object is a class, print the constructor information.
2113 object. If the object is a class, print the constructor information.
2114 * **%psource <object>**: Print (or run through a pager if too long)
2114 * **%psource <object>**: Print (or run through a pager if too long)
2115 the source code for an object.
2115 the source code for an object.
2116 * **%pfile <object>**: Show the entire source file where an object was
2116 * **%pfile <object>**: Show the entire source file where an object was
2117 defined via a pager, opening it at the line where the object
2117 defined via a pager, opening it at the line where the object
2118 definition begins.
2118 definition begins.
2119 * **%who/%whos**: These functions give information about identifiers
2119 * **%who/%whos**: These functions give information about identifiers
2120 you have defined interactively (not things you loaded or defined
2120 you have defined interactively (not things you loaded or defined
2121 in your configuration files). %who just prints a list of
2121 in your configuration files). %who just prints a list of
2122 identifiers and %whos prints a table with some basic details about
2122 identifiers and %whos prints a table with some basic details about
2123 each identifier.
2123 each identifier.
2124
2124
2125 Note that the dynamic object information functions (?/??, %pdoc, %pfile,
2125 Note that the dynamic object information functions (?/??, %pdoc, %pfile,
2126 %pdef, %psource) give you access to documentation even on things which
2126 %pdef, %psource) give you access to documentation even on things which
2127 are not really defined as separate identifiers. Try for example typing
2127 are not really defined as separate identifiers. Try for example typing
2128 {}.get? or after doing import os, type os.path.abspath??.
2128 {}.get? or after doing import os, type os.path.abspath??.
2129
2129
2130
2130
2131 .. _readline:
2131 .. _readline:
2132
2132
2133 Readline-based features
2133 Readline-based features
2134 -----------------------
2134 -----------------------
2135
2135
2136 These features require the GNU readline library, so they won't work if
2136 These features require the GNU readline library, so they won't work if
2137 your Python installation lacks readline support. We will first describe
2137 your Python installation lacks readline support. We will first describe
2138 the default behavior IPython uses, and then how to change it to suit
2138 the default behavior IPython uses, and then how to change it to suit
2139 your preferences.
2139 your preferences.
2140
2140
2141
2141
2142 Command line completion
2142 Command line completion
2143 +++++++++++++++++++++++
2143 +++++++++++++++++++++++
2144
2144
2145 At any time, hitting TAB will complete any available python commands or
2145 At any time, hitting TAB will complete any available python commands or
2146 variable names, and show you a list of the possible completions if
2146 variable names, and show you a list of the possible completions if
2147 there's no unambiguous one. It will also complete filenames in the
2147 there's no unambiguous one. It will also complete filenames in the
2148 current directory if no python names match what you've typed so far.
2148 current directory if no python names match what you've typed so far.
2149
2149
2150
2150
2151 Search command history
2151 Search command history
2152 ++++++++++++++++++++++
2152 ++++++++++++++++++++++
2153
2153
2154 IPython provides two ways for searching through previous input and thus
2154 IPython provides two ways for searching through previous input and thus
2155 reduce the need for repetitive typing:
2155 reduce the need for repetitive typing:
2156
2156
2157 1. Start typing, and then use Ctrl-p (previous,up) and Ctrl-n
2157 1. Start typing, and then use Ctrl-p (previous,up) and Ctrl-n
2158 (next,down) to search through only the history items that match
2158 (next,down) to search through only the history items that match
2159 what you've typed so far. If you use Ctrl-p/Ctrl-n at a blank
2159 what you've typed so far. If you use Ctrl-p/Ctrl-n at a blank
2160 prompt, they just behave like normal arrow keys.
2160 prompt, they just behave like normal arrow keys.
2161 2. Hit Ctrl-r: opens a search prompt. Begin typing and the system
2161 2. Hit Ctrl-r: opens a search prompt. Begin typing and the system
2162 searches your history for lines that contain what you've typed so
2162 searches your history for lines that contain what you've typed so
2163 far, completing as much as it can.
2163 far, completing as much as it can.
2164
2164
2165
2165
2166 Persistent command history across sessions
2166 Persistent command history across sessions
2167 ++++++++++++++++++++++++++++++++++++++++++
2167 ++++++++++++++++++++++++++++++++++++++++++
2168
2168
2169 IPython will save your input history when it leaves and reload it next
2169 IPython will save your input history when it leaves and reload it next
2170 time you restart it. By default, the history file is named
2170 time you restart it. By default, the history file is named
2171 $IPYTHONDIR/history, but if you've loaded a named profile,
2171 $IPYTHONDIR/history, but if you've loaded a named profile,
2172 '-PROFILE_NAME' is appended to the name. This allows you to keep
2172 '-PROFILE_NAME' is appended to the name. This allows you to keep
2173 separate histories related to various tasks: commands related to
2173 separate histories related to various tasks: commands related to
2174 numerical work will not be clobbered by a system shell history, for
2174 numerical work will not be clobbered by a system shell history, for
2175 example.
2175 example.
2176
2176
2177
2177
2178 Autoindent
2178 Autoindent
2179 ++++++++++
2179 ++++++++++
2180
2180
2181 IPython can recognize lines ending in ':' and indent the next line,
2181 IPython can recognize lines ending in ':' and indent the next line,
2182 while also un-indenting automatically after 'raise' or 'return'.
2182 while also un-indenting automatically after 'raise' or 'return'.
2183
2183
2184 This feature uses the readline library, so it will honor your ~/.inputrc
2184 This feature uses the readline library, so it will honor your ~/.inputrc
2185 configuration (or whatever file your INPUTRC variable points to). Adding
2185 configuration (or whatever file your INPUTRC variable points to). Adding
2186 the following lines to your .inputrc file can make indenting/unindenting
2186 the following lines to your .inputrc file can make indenting/unindenting
2187 more convenient (M-i indents, M-u unindents)::
2187 more convenient (M-i indents, M-u unindents)::
2188
2188
2189 $if Python
2189 $if Python
2190 "\M-i": " "
2190 "\M-i": " "
2191 "\M-u": "\d\d\d\d"
2191 "\M-u": "\d\d\d\d"
2192 $endif
2192 $endif
2193
2193
2194 Note that there are 4 spaces between the quote marks after "M-i" above.
2194 Note that there are 4 spaces between the quote marks after "M-i" above.
2195
2195
2196 Warning: this feature is ON by default, but it can cause problems with
2196 Warning: this feature is ON by default, but it can cause problems with
2197 the pasting of multi-line indented code (the pasted code gets
2197 the pasting of multi-line indented code (the pasted code gets
2198 re-indented on each line). A magic function %autoindent allows you to
2198 re-indented on each line). A magic function %autoindent allows you to
2199 toggle it on/off at runtime. You can also disable it permanently on in
2199 toggle it on/off at runtime. You can also disable it permanently on in
2200 your ipythonrc file (set autoindent 0).
2200 your ipythonrc file (set autoindent 0).
2201
2201
2202
2202
2203 Customizing readline behavior
2203 Customizing readline behavior
2204 +++++++++++++++++++++++++++++
2204 +++++++++++++++++++++++++++++
2205
2205
2206 All these features are based on the GNU readline library, which has an
2206 All these features are based on the GNU readline library, which has an
2207 extremely customizable interface. Normally, readline is configured via a
2207 extremely customizable interface. Normally, readline is configured via a
2208 file which defines the behavior of the library; the details of the
2208 file which defines the behavior of the library; the details of the
2209 syntax for this can be found in the readline documentation available
2209 syntax for this can be found in the readline documentation available
2210 with your system or on the Internet. IPython doesn't read this file (if
2210 with your system or on the Internet. IPython doesn't read this file (if
2211 it exists) directly, but it does support passing to readline valid
2211 it exists) directly, but it does support passing to readline valid
2212 options via a simple interface. In brief, you can customize readline by
2212 options via a simple interface. In brief, you can customize readline by
2213 setting the following options in your ipythonrc configuration file (note
2213 setting the following options in your ipythonrc configuration file (note
2214 that these options can not be specified at the command line):
2214 that these options can not be specified at the command line):
2215
2215
2216 * **readline_parse_and_bind**: this option can appear as many times as
2216 * **readline_parse_and_bind**: this option can appear as many times as
2217 you want, each time defining a string to be executed via a
2217 you want, each time defining a string to be executed via a
2218 readline.parse_and_bind() command. The syntax for valid commands
2218 readline.parse_and_bind() command. The syntax for valid commands
2219 of this kind can be found by reading the documentation for the GNU
2219 of this kind can be found by reading the documentation for the GNU
2220 readline library, as these commands are of the kind which readline
2220 readline library, as these commands are of the kind which readline
2221 accepts in its configuration file.
2221 accepts in its configuration file.
2222 * **readline_remove_delims**: a string of characters to be removed
2222 * **readline_remove_delims**: a string of characters to be removed
2223 from the default word-delimiters list used by readline, so that
2223 from the default word-delimiters list used by readline, so that
2224 completions may be performed on strings which contain them. Do not
2224 completions may be performed on strings which contain them. Do not
2225 change the default value unless you know what you're doing.
2225 change the default value unless you know what you're doing.
2226 * **readline_omit__names**: when tab-completion is enabled, hitting
2226 * **readline_omit__names**: when tab-completion is enabled, hitting
2227 <tab> after a '.' in a name will complete all attributes of an
2227 <tab> after a '.' in a name will complete all attributes of an
2228 object, including all the special methods whose names include
2228 object, including all the special methods whose names include
2229 double underscores (like __getitem__ or __class__). If you'd
2229 double underscores (like __getitem__ or __class__). If you'd
2230 rather not see these names by default, you can set this option to
2230 rather not see these names by default, you can set this option to
2231 1. Note that even when this option is set, you can still see those
2231 1. Note that even when this option is set, you can still see those
2232 names by explicitly typing a _ after the period and hitting <tab>:
2232 names by explicitly typing a _ after the period and hitting <tab>:
2233 'name._<tab>' will always complete attribute names starting with '_'.
2233 'name._<tab>' will always complete attribute names starting with '_'.
2234
2234
2235 This option is off by default so that new users see all
2235 This option is off by default so that new users see all
2236 attributes of any objects they are dealing with.
2236 attributes of any objects they are dealing with.
2237
2237
2238 You will find the default values along with a corresponding detailed
2238 You will find the default values along with a corresponding detailed
2239 explanation in your ipythonrc file.
2239 explanation in your ipythonrc file.
2240
2240
2241
2241
2242 Session logging and restoring
2242 Session logging and restoring
2243 -----------------------------
2243 -----------------------------
2244
2244
2245 You can log all input from a session either by starting IPython with the
2245 You can log all input from a session either by starting IPython with the
2246 command line switches -log or -logfile (see :ref:`here <command_line_options>`)
2246 command line switches -log or -logfile (see :ref:`here <command_line_options>`)
2247 or by activating the logging at any moment with the magic function %logstart.
2247 or by activating the logging at any moment with the magic function %logstart.
2248
2248
2249 Log files can later be reloaded with the -logplay option and IPython
2249 Log files can later be reloaded with the -logplay option and IPython
2250 will attempt to 'replay' the log by executing all the lines in it, thus
2250 will attempt to 'replay' the log by executing all the lines in it, thus
2251 restoring the state of a previous session. This feature is not quite
2251 restoring the state of a previous session. This feature is not quite
2252 perfect, but can still be useful in many cases.
2252 perfect, but can still be useful in many cases.
2253
2253
2254 The log files can also be used as a way to have a permanent record of
2254 The log files can also be used as a way to have a permanent record of
2255 any code you wrote while experimenting. Log files are regular text files
2255 any code you wrote while experimenting. Log files are regular text files
2256 which you can later open in your favorite text editor to extract code or
2256 which you can later open in your favorite text editor to extract code or
2257 to 'clean them up' before using them to replay a session.
2257 to 'clean them up' before using them to replay a session.
2258
2258
2259 The %logstart function for activating logging in mid-session is used as
2259 The %logstart function for activating logging in mid-session is used as
2260 follows:
2260 follows:
2261
2261
2262 %logstart [log_name [log_mode]]
2262 %logstart [log_name [log_mode]]
2263
2263
2264 If no name is given, it defaults to a file named 'log' in your
2264 If no name is given, it defaults to a file named 'log' in your
2265 IPYTHONDIR directory, in 'rotate' mode (see below).
2265 IPYTHONDIR directory, in 'rotate' mode (see below).
2266
2266
2267 '%logstart name' saves to file 'name' in 'backup' mode. It saves your
2267 '%logstart name' saves to file 'name' in 'backup' mode. It saves your
2268 history up to that point and then continues logging.
2268 history up to that point and then continues logging.
2269
2269
2270 %logstart takes a second optional parameter: logging mode. This can be
2270 %logstart takes a second optional parameter: logging mode. This can be
2271 one of (note that the modes are given unquoted):
2271 one of (note that the modes are given unquoted):
2272
2272
2273 * [over:] overwrite existing log_name.
2273 * [over:] overwrite existing log_name.
2274 * [backup:] rename (if exists) to log_name~ and start log_name.
2274 * [backup:] rename (if exists) to log_name~ and start log_name.
2275 * [append:] well, that says it.
2275 * [append:] well, that says it.
2276 * [rotate:] create rotating logs log_name.1~, log_name.2~, etc.
2276 * [rotate:] create rotating logs log_name.1~, log_name.2~, etc.
2277
2277
2278 The %logoff and %logon functions allow you to temporarily stop and
2278 The %logoff and %logon functions allow you to temporarily stop and
2279 resume logging to a file which had previously been started with
2279 resume logging to a file which had previously been started with
2280 %logstart. They will fail (with an explanation) if you try to use them
2280 %logstart. They will fail (with an explanation) if you try to use them
2281 before logging has been started.
2281 before logging has been started.
2282
2282
2283 .. _system_shell_access:
2283 .. _system_shell_access:
2284
2284
2285 System shell access
2285 System shell access
2286 -------------------
2286 -------------------
2287
2287
2288 Any input line beginning with a ! character is passed verbatim (minus
2288 Any input line beginning with a ! character is passed verbatim (minus
2289 the !, of course) to the underlying operating system. For example,
2289 the !, of course) to the underlying operating system. For example,
2290 typing !ls will run 'ls' in the current directory.
2290 typing !ls will run 'ls' in the current directory.
2291
2291
2292 Manual capture of command output
2292 Manual capture of command output
2293 --------------------------------
2293 --------------------------------
2294
2294
2295 If the input line begins with two exclamation marks, !!, the command is
2295 If the input line begins with two exclamation marks, !!, the command is
2296 executed but its output is captured and returned as a python list, split
2296 executed but its output is captured and returned as a python list, split
2297 on newlines. Any output sent by the subprocess to standard error is
2297 on newlines. Any output sent by the subprocess to standard error is
2298 printed separately, so that the resulting list only captures standard
2298 printed separately, so that the resulting list only captures standard
2299 output. The !! syntax is a shorthand for the %sx magic command.
2299 output. The !! syntax is a shorthand for the %sx magic command.
2300
2300
2301 Finally, the %sc magic (short for 'shell capture') is similar to %sx,
2301 Finally, the %sc magic (short for 'shell capture') is similar to %sx,
2302 but allowing more fine-grained control of the capture details, and
2302 but allowing more fine-grained control of the capture details, and
2303 storing the result directly into a named variable. The direct use of
2303 storing the result directly into a named variable. The direct use of
2304 %sc is now deprecated, and you should ise the ``var = !cmd`` syntax
2304 %sc is now deprecated, and you should ise the ``var = !cmd`` syntax
2305 instead.
2305 instead.
2306
2306
2307 IPython also allows you to expand the value of python variables when
2307 IPython also allows you to expand the value of python variables when
2308 making system calls. Any python variable or expression which you prepend
2308 making system calls. Any python variable or expression which you prepend
2309 with $ will get expanded before the system call is made::
2309 with $ will get expanded before the system call is made::
2310
2310
2311 In [1]: pyvar='Hello world'
2311 In [1]: pyvar='Hello world'
2312 In [2]: !echo "A python variable: $pyvar"
2312 In [2]: !echo "A python variable: $pyvar"
2313 A python variable: Hello world
2313 A python variable: Hello world
2314
2314
2315 If you want the shell to actually see a literal $, you need to type it
2315 If you want the shell to actually see a literal $, you need to type it
2316 twice::
2316 twice::
2317
2317
2318 In [3]: !echo "A system variable: $$HOME"
2318 In [3]: !echo "A system variable: $$HOME"
2319 A system variable: /home/fperez
2319 A system variable: /home/fperez
2320
2320
2321 You can pass arbitrary expressions, though you'll need to delimit them
2321 You can pass arbitrary expressions, though you'll need to delimit them
2322 with {} if there is ambiguity as to the extent of the expression::
2322 with {} if there is ambiguity as to the extent of the expression::
2323
2323
2324 In [5]: x=10
2324 In [5]: x=10
2325 In [6]: y=20
2325 In [6]: y=20
2326 In [13]: !echo $x+y
2326 In [13]: !echo $x+y
2327 10+y
2327 10+y
2328 In [7]: !echo ${x+y}
2328 In [7]: !echo ${x+y}
2329 30
2329 30
2330
2330
2331 Even object attributes can be expanded::
2331 Even object attributes can be expanded::
2332
2332
2333 In [12]: !echo $sys.argv
2333 In [12]: !echo $sys.argv
2334 [/home/fperez/usr/bin/ipython]
2334 [/home/fperez/usr/bin/ipython]
2335
2335
2336
2336
2337 System command aliases
2337 System command aliases
2338 ----------------------
2338 ----------------------
2339
2339
2340 The %alias magic function and the alias option in the ipythonrc
2340 The %alias magic function and the alias option in the ipythonrc
2341 configuration file allow you to define magic functions which are in fact
2341 configuration file allow you to define magic functions which are in fact
2342 system shell commands. These aliases can have parameters.
2342 system shell commands. These aliases can have parameters.
2343
2343
2344 '%alias alias_name cmd' defines 'alias_name' as an alias for 'cmd'
2344 '%alias alias_name cmd' defines 'alias_name' as an alias for 'cmd'
2345
2345
2346 Then, typing '%alias_name params' will execute the system command 'cmd
2346 Then, typing '%alias_name params' will execute the system command 'cmd
2347 params' (from your underlying operating system).
2347 params' (from your underlying operating system).
2348
2348
2349 You can also define aliases with parameters using %s specifiers (one per
2349 You can also define aliases with parameters using %s specifiers (one per
2350 parameter). The following example defines the %parts function as an
2350 parameter). The following example defines the %parts function as an
2351 alias to the command 'echo first %s second %s' where each %s will be
2351 alias to the command 'echo first %s second %s' where each %s will be
2352 replaced by a positional parameter to the call to %parts::
2352 replaced by a positional parameter to the call to %parts::
2353
2353
2354 In [1]: alias parts echo first %s second %s
2354 In [1]: alias parts echo first %s second %s
2355 In [2]: %parts A B
2355 In [2]: %parts A B
2356 first A second B
2356 first A second B
2357 In [3]: %parts A
2357 In [3]: %parts A
2358 Incorrect number of arguments: 2 expected.
2358 Incorrect number of arguments: 2 expected.
2359 parts is an alias to: 'echo first %s second %s'
2359 parts is an alias to: 'echo first %s second %s'
2360
2360
2361 If called with no parameters, %alias prints the table of currently
2361 If called with no parameters, %alias prints the table of currently
2362 defined aliases.
2362 defined aliases.
2363
2363
2364 The %rehash/rehashx magics allow you to load your entire $PATH as
2364 The %rehash/rehashx magics allow you to load your entire $PATH as
2365 ipython aliases. See their respective docstrings (or sec. 6.2
2365 ipython aliases. See their respective docstrings (or sec. 6.2
2366 <#sec:magic> for further details).
2366 <#sec:magic> for further details).
2367
2367
2368
2368
2369 .. _dreload:
2369 .. _dreload:
2370
2370
2371 Recursive reload
2371 Recursive reload
2372 ----------------
2372 ----------------
2373
2373
2374 The dreload function does a recursive reload of a module: changes made
2374 The dreload function does a recursive reload of a module: changes made
2375 to the module since you imported will actually be available without
2375 to the module since you imported will actually be available without
2376 having to exit.
2376 having to exit.
2377
2377
2378
2378
2379 Verbose and colored exception traceback printouts
2379 Verbose and colored exception traceback printouts
2380 -------------------------------------------------
2380 -------------------------------------------------
2381
2381
2382 IPython provides the option to see very detailed exception tracebacks,
2382 IPython provides the option to see very detailed exception tracebacks,
2383 which can be especially useful when debugging large programs. You can
2383 which can be especially useful when debugging large programs. You can
2384 run any Python file with the %run function to benefit from these
2384 run any Python file with the %run function to benefit from these
2385 detailed tracebacks. Furthermore, both normal and verbose tracebacks can
2385 detailed tracebacks. Furthermore, both normal and verbose tracebacks can
2386 be colored (if your terminal supports it) which makes them much easier
2386 be colored (if your terminal supports it) which makes them much easier
2387 to parse visually.
2387 to parse visually.
2388
2388
2389 See the magic xmode and colors functions for details (just type %magic).
2389 See the magic xmode and colors functions for details (just type %magic).
2390
2390
2391 These features are basically a terminal version of Ka-Ping Yee's cgitb
2391 These features are basically a terminal version of Ka-Ping Yee's cgitb
2392 module, now part of the standard Python library.
2392 module, now part of the standard Python library.
2393
2393
2394
2394
2395 .. _input_caching:
2395 .. _input_caching:
2396
2396
2397 Input caching system
2397 Input caching system
2398 --------------------
2398 --------------------
2399
2399
2400 IPython offers numbered prompts (In/Out) with input and output caching.
2400 IPython offers numbered prompts (In/Out) with input and output caching
2401 All input is saved and can be retrieved as variables (besides the usual
2401 (also referred to as 'input history'). All input is saved and can be
2402 arrow key recall).
2402 retrieved as variables (besides the usual arrow key recall), in
2403 addition to the %rep magic command that brings a history entry
2404 up for editing on the next command line.
2403
2405
2404 The following GLOBAL variables always exist (so don't overwrite them!):
2406 The following GLOBAL variables always exist (so don't overwrite them!):
2405 _i: stores previous input. _ii: next previous. _iii: next-next previous.
2407 _i: stores previous input. _ii: next previous. _iii: next-next previous.
2406 _ih : a list of all input _ih[n] is the input from line n and this list
2408 _ih : a list of all input _ih[n] is the input from line n and this list
2407 is aliased to the global variable In. If you overwrite In with a
2409 is aliased to the global variable In. If you overwrite In with a
2408 variable of your own, you can remake the assignment to the internal list
2410 variable of your own, you can remake the assignment to the internal list
2409 with a simple 'In=_ih'.
2411 with a simple 'In=_ih'.
2410
2412
2411 Additionally, global variables named _i<n> are dynamically created (<n>
2413 Additionally, global variables named _i<n> are dynamically created (<n>
2412 being the prompt counter), such that
2414 being the prompt counter), such that
2413 _i<n> == _ih[<n>] == In[<n>].
2415 _i<n> == _ih[<n>] == In[<n>].
2414
2416
2415 For example, what you typed at prompt 14 is available as _i14, _ih[14]
2417 For example, what you typed at prompt 14 is available as _i14, _ih[14]
2416 and In[14].
2418 and In[14].
2417
2419
2418 This allows you to easily cut and paste multi line interactive prompts
2420 This allows you to easily cut and paste multi line interactive prompts
2419 by printing them out: they print like a clean string, without prompt
2421 by printing them out: they print like a clean string, without prompt
2420 characters. You can also manipulate them like regular variables (they
2422 characters. You can also manipulate them like regular variables (they
2421 are strings), modify or exec them (typing 'exec _i9' will re-execute the
2423 are strings), modify or exec them (typing 'exec _i9' will re-execute the
2422 contents of input prompt 9, 'exec In[9:14]+In[18]' will re-execute lines
2424 contents of input prompt 9, 'exec In[9:14]+In[18]' will re-execute lines
2423 9 through 13 and line 18).
2425 9 through 13 and line 18).
2424
2426
2425 You can also re-execute multiple lines of input easily by using the
2427 You can also re-execute multiple lines of input easily by using the
2426 magic %macro function (which automates the process and allows
2428 magic %macro function (which automates the process and allows
2427 re-execution without having to type 'exec' every time). The macro system
2429 re-execution without having to type 'exec' every time). The macro system
2428 also allows you to re-execute previous lines which include magic
2430 also allows you to re-execute previous lines which include magic
2429 function calls (which require special processing). Type %macro? or see
2431 function calls (which require special processing). Type %macro? or see
2430 sec. 6.2 <#sec:magic> for more details on the macro system.
2432 sec. 6.2 <#sec:magic> for more details on the macro system.
2431
2433
2432 A history function %hist allows you to see any part of your input
2434 A history function %hist allows you to see any part of your input
2433 history by printing a range of the _i variables.
2435 history by printing a range of the _i variables.
2434
2436
2437 You can also search ('grep') through your history by typing
2438 '%hist -g somestring'. This also searches through the so called 'shadow history',
2439 which remembers all the commands (apart from multiline code blocks)
2440 you have ever entered. Handy for searching for svn/bzr URL's, IP adrresses
2441 etc. You can bring shadow history entries listed by '%hist -g' up for editing
2442 (or re-execution by just pressing ENTER) with %rep command. Shadow history
2443 entries are not available as _iNUMBER variables, and they are identified by
2444 the '0' prefix in %hist -g output. That is, history entry 12 is a normal
2445 history entry, but 0231 is a shadow history entry.
2446
2435 .. _output_caching:
2447 .. _output_caching:
2436
2448
2437 Output caching system
2449 Output caching system
2438 ---------------------
2450 ---------------------
2439
2451
2440 For output that is returned from actions, a system similar to the input
2452 For output that is returned from actions, a system similar to the input
2441 cache exists but using _ instead of _i. Only actions that produce a
2453 cache exists but using _ instead of _i. Only actions that produce a
2442 result (NOT assignments, for example) are cached. If you are familiar
2454 result (NOT assignments, for example) are cached. If you are familiar
2443 with Mathematica, IPython's _ variables behave exactly like
2455 with Mathematica, IPython's _ variables behave exactly like
2444 Mathematica's % variables.
2456 Mathematica's % variables.
2445
2457
2446 The following GLOBAL variables always exist (so don't overwrite them!):
2458 The following GLOBAL variables always exist (so don't overwrite them!):
2447
2459
2448 * [_] (a single underscore) : stores previous output, like Python's
2460 * [_] (a single underscore) : stores previous output, like Python's
2449 default interpreter.
2461 default interpreter.
2450 * [__] (two underscores): next previous.
2462 * [__] (two underscores): next previous.
2451 * [___] (three underscores): next-next previous.
2463 * [___] (three underscores): next-next previous.
2452
2464
2453 Additionally, global variables named _<n> are dynamically created (<n>
2465 Additionally, global variables named _<n> are dynamically created (<n>
2454 being the prompt counter), such that the result of output <n> is always
2466 being the prompt counter), such that the result of output <n> is always
2455 available as _<n> (don't use the angle brackets, just the number, e.g.
2467 available as _<n> (don't use the angle brackets, just the number, e.g.
2456 _21).
2468 _21).
2457
2469
2458 These global variables are all stored in a global dictionary (not a
2470 These global variables are all stored in a global dictionary (not a
2459 list, since it only has entries for lines which returned a result)
2471 list, since it only has entries for lines which returned a result)
2460 available under the names _oh and Out (similar to _ih and In). So the
2472 available under the names _oh and Out (similar to _ih and In). So the
2461 output from line 12 can be obtained as _12, Out[12] or _oh[12]. If you
2473 output from line 12 can be obtained as _12, Out[12] or _oh[12]. If you
2462 accidentally overwrite the Out variable you can recover it by typing
2474 accidentally overwrite the Out variable you can recover it by typing
2463 'Out=_oh' at the prompt.
2475 'Out=_oh' at the prompt.
2464
2476
2465 This system obviously can potentially put heavy memory demands on your
2477 This system obviously can potentially put heavy memory demands on your
2466 system, since it prevents Python's garbage collector from removing any
2478 system, since it prevents Python's garbage collector from removing any
2467 previously computed results. You can control how many results are kept
2479 previously computed results. You can control how many results are kept
2468 in memory with the option (at the command line or in your ipythonrc
2480 in memory with the option (at the command line or in your ipythonrc
2469 file) cache_size. If you set it to 0, the whole system is completely
2481 file) cache_size. If you set it to 0, the whole system is completely
2470 disabled and the prompts revert to the classic '>>>' of normal Python.
2482 disabled and the prompts revert to the classic '>>>' of normal Python.
2471
2483
2472
2484
2473 Directory history
2485 Directory history
2474 -----------------
2486 -----------------
2475
2487
2476 Your history of visited directories is kept in the global list _dh, and
2488 Your history of visited directories is kept in the global list _dh, and
2477 the magic %cd command can be used to go to any entry in that list. The
2489 the magic %cd command can be used to go to any entry in that list. The
2478 %dhist command allows you to view this history. do ``cd -<TAB`` to
2490 %dhist command allows you to view this history. Do ``cd -<TAB`` to
2479 conventiently view the directory history.
2491 conventiently view the directory history.
2480
2492
2481
2493
2482 Automatic parentheses and quotes
2494 Automatic parentheses and quotes
2483 --------------------------------
2495 --------------------------------
2484
2496
2485 These features were adapted from Nathan Gray's LazyPython. They are
2497 These features were adapted from Nathan Gray's LazyPython. They are
2486 meant to allow less typing for common situations.
2498 meant to allow less typing for common situations.
2487
2499
2488
2500
2489 Automatic parentheses
2501 Automatic parentheses
2490 ---------------------
2502 ---------------------
2491
2503
2492 Callable objects (i.e. functions, methods, etc) can be invoked like this
2504 Callable objects (i.e. functions, methods, etc) can be invoked like this
2493 (notice the commas between the arguments)::
2505 (notice the commas between the arguments)::
2494
2506
2495 >>> callable_ob arg1, arg2, arg3
2507 >>> callable_ob arg1, arg2, arg3
2496
2508
2497 and the input will be translated to this::
2509 and the input will be translated to this::
2498
2510
2499 -> callable_ob(arg1, arg2, arg3)
2511 -> callable_ob(arg1, arg2, arg3)
2500
2512
2501 You can force automatic parentheses by using '/' as the first character
2513 You can force automatic parentheses by using '/' as the first character
2502 of a line. For example::
2514 of a line. For example::
2503
2515
2504 >>> /globals # becomes 'globals()'
2516 >>> /globals # becomes 'globals()'
2505
2517
2506 Note that the '/' MUST be the first character on the line! This won't work::
2518 Note that the '/' MUST be the first character on the line! This won't work::
2507
2519
2508 >>> print /globals # syntax error
2520 >>> print /globals # syntax error
2509
2521
2510 In most cases the automatic algorithm should work, so you should rarely
2522 In most cases the automatic algorithm should work, so you should rarely
2511 need to explicitly invoke /. One notable exception is if you are trying
2523 need to explicitly invoke /. One notable exception is if you are trying
2512 to call a function with a list of tuples as arguments (the parenthesis
2524 to call a function with a list of tuples as arguments (the parenthesis
2513 will confuse IPython)::
2525 will confuse IPython)::
2514
2526
2515 In [1]: zip (1,2,3),(4,5,6) # won't work
2527 In [1]: zip (1,2,3),(4,5,6) # won't work
2516
2528
2517 but this will work::
2529 but this will work::
2518
2530
2519 In [2]: /zip (1,2,3),(4,5,6)
2531 In [2]: /zip (1,2,3),(4,5,6)
2520 ---> zip ((1,2,3),(4,5,6))
2532 ---> zip ((1,2,3),(4,5,6))
2521 Out[2]= [(1, 4), (2, 5), (3, 6)]
2533 Out[2]= [(1, 4), (2, 5), (3, 6)]
2522
2534
2523 IPython tells you that it has altered your command line by displaying
2535 IPython tells you that it has altered your command line by displaying
2524 the new command line preceded by ->. e.g.::
2536 the new command line preceded by ->. e.g.::
2525
2537
2526 In [18]: callable list
2538 In [18]: callable list
2527 ----> callable (list)
2539 ----> callable (list)
2528
2540
2529
2541
2530 Automatic quoting
2542 Automatic quoting
2531 -----------------
2543 -----------------
2532
2544
2533 You can force automatic quoting of a function's arguments by using ','
2545 You can force automatic quoting of a function's arguments by using ','
2534 or ';' as the first character of a line. For example::
2546 or ';' as the first character of a line. For example::
2535
2547
2536 >>> ,my_function /home/me # becomes my_function("/home/me")
2548 >>> ,my_function /home/me # becomes my_function("/home/me")
2537
2549
2538 If you use ';' instead, the whole argument is quoted as a single string
2550 If you use ';' instead, the whole argument is quoted as a single string
2539 (while ',' splits on whitespace)::
2551 (while ',' splits on whitespace)::
2540
2552
2541 >>> ,my_function a b c # becomes my_function("a","b","c")
2553 >>> ,my_function a b c # becomes my_function("a","b","c")
2542
2554
2543 >>> ;my_function a b c # becomes my_function("a b c")
2555 >>> ;my_function a b c # becomes my_function("a b c")
2544
2556
2545 Note that the ',' or ';' MUST be the first character on the line! This
2557 Note that the ',' or ';' MUST be the first character on the line! This
2546 won't work::
2558 won't work::
2547
2559
2548 >>> x = ,my_function /home/me # syntax error
2560 >>> x = ,my_function /home/me # syntax error
2549
2561
2550 IPython as your default Python environment
2562 IPython as your default Python environment
2551 ==========================================
2563 ==========================================
2552
2564
2553 Python honors the environment variable PYTHONSTARTUP and will execute at
2565 Python honors the environment variable PYTHONSTARTUP and will execute at
2554 startup the file referenced by this variable. If you put at the end of
2566 startup the file referenced by this variable. If you put at the end of
2555 this file the following two lines of code::
2567 this file the following two lines of code::
2556
2568
2557 import IPython
2569 import IPython
2558 IPython.Shell.IPShell().mainloop(sys_exit=1)
2570 IPython.Shell.IPShell().mainloop(sys_exit=1)
2559
2571
2560 then IPython will be your working environment anytime you start Python.
2572 then IPython will be your working environment anytime you start Python.
2561 The sys_exit=1 is needed to have IPython issue a call to sys.exit() when
2573 The sys_exit=1 is needed to have IPython issue a call to sys.exit() when
2562 it finishes, otherwise you'll be back at the normal Python '>>>'
2574 it finishes, otherwise you'll be back at the normal Python '>>>'
2563 prompt.
2575 prompt.
2564
2576
2565 This is probably useful to developers who manage multiple Python
2577 This is probably useful to developers who manage multiple Python
2566 versions and don't want to have correspondingly multiple IPython
2578 versions and don't want to have correspondingly multiple IPython
2567 versions. Note that in this mode, there is no way to pass IPython any
2579 versions. Note that in this mode, there is no way to pass IPython any
2568 command-line options, as those are trapped first by Python itself.
2580 command-line options, as those are trapped first by Python itself.
2569
2581
2570 .. _Embedding:
2582 .. _Embedding:
2571
2583
2572 Embedding IPython
2584 Embedding IPython
2573 =================
2585 =================
2574
2586
2575 It is possible to start an IPython instance inside your own Python
2587 It is possible to start an IPython instance inside your own Python
2576 programs. This allows you to evaluate dynamically the state of your
2588 programs. This allows you to evaluate dynamically the state of your
2577 code, operate with your variables, analyze them, etc. Note however that
2589 code, operate with your variables, analyze them, etc. Note however that
2578 any changes you make to values while in the shell do not propagate back
2590 any changes you make to values while in the shell do not propagate back
2579 to the running code, so it is safe to modify your values because you
2591 to the running code, so it is safe to modify your values because you
2580 won't break your code in bizarre ways by doing so.
2592 won't break your code in bizarre ways by doing so.
2581
2593
2582 This feature allows you to easily have a fully functional python
2594 This feature allows you to easily have a fully functional python
2583 environment for doing object introspection anywhere in your code with a
2595 environment for doing object introspection anywhere in your code with a
2584 simple function call. In some cases a simple print statement is enough,
2596 simple function call. In some cases a simple print statement is enough,
2585 but if you need to do more detailed analysis of a code fragment this
2597 but if you need to do more detailed analysis of a code fragment this
2586 feature can be very valuable.
2598 feature can be very valuable.
2587
2599
2588 It can also be useful in scientific computing situations where it is
2600 It can also be useful in scientific computing situations where it is
2589 common to need to do some automatic, computationally intensive part and
2601 common to need to do some automatic, computationally intensive part and
2590 then stop to look at data, plots, etc.
2602 then stop to look at data, plots, etc.
2591 Opening an IPython instance will give you full access to your data and
2603 Opening an IPython instance will give you full access to your data and
2592 functions, and you can resume program execution once you are done with
2604 functions, and you can resume program execution once you are done with
2593 the interactive part (perhaps to stop again later, as many times as
2605 the interactive part (perhaps to stop again later, as many times as
2594 needed).
2606 needed).
2595
2607
2596 The following code snippet is the bare minimum you need to include in
2608 The following code snippet is the bare minimum you need to include in
2597 your Python programs for this to work (detailed examples follow later)::
2609 your Python programs for this to work (detailed examples follow later)::
2598
2610
2599 from IPython.Shell import IPShellEmbed
2611 from IPython.Shell import IPShellEmbed
2600
2612
2601 ipshell = IPShellEmbed()
2613 ipshell = IPShellEmbed()
2602
2614
2603 ipshell() # this call anywhere in your program will start IPython
2615 ipshell() # this call anywhere in your program will start IPython
2604
2616
2605 You can run embedded instances even in code which is itself being run at
2617 You can run embedded instances even in code which is itself being run at
2606 the IPython interactive prompt with '%run <filename>'. Since it's easy
2618 the IPython interactive prompt with '%run <filename>'. Since it's easy
2607 to get lost as to where you are (in your top-level IPython or in your
2619 to get lost as to where you are (in your top-level IPython or in your
2608 embedded one), it's a good idea in such cases to set the in/out prompts
2620 embedded one), it's a good idea in such cases to set the in/out prompts
2609 to something different for the embedded instances. The code examples
2621 to something different for the embedded instances. The code examples
2610 below illustrate this.
2622 below illustrate this.
2611
2623
2612 You can also have multiple IPython instances in your program and open
2624 You can also have multiple IPython instances in your program and open
2613 them separately, for example with different options for data
2625 them separately, for example with different options for data
2614 presentation. If you close and open the same instance multiple times,
2626 presentation. If you close and open the same instance multiple times,
2615 its prompt counters simply continue from each execution to the next.
2627 its prompt counters simply continue from each execution to the next.
2616
2628
2617 Please look at the docstrings in the Shell.py module for more details on
2629 Please look at the docstrings in the Shell.py module for more details on
2618 the use of this system.
2630 the use of this system.
2619
2631
2620 The following sample file illustrating how to use the embedding
2632 The following sample file illustrating how to use the embedding
2621 functionality is provided in the examples directory as example-embed.py.
2633 functionality is provided in the examples directory as example-embed.py.
2622 It should be fairly self-explanatory::
2634 It should be fairly self-explanatory::
2623
2635
2624
2636
2625 #!/usr/bin/env python
2637 #!/usr/bin/env python
2626
2638
2627 """An example of how to embed an IPython shell into a running program.
2639 """An example of how to embed an IPython shell into a running program.
2628
2640
2629 Please see the documentation in the IPython.Shell module for more details.
2641 Please see the documentation in the IPython.Shell module for more details.
2630
2642
2631 The accompanying file example-embed-short.py has quick code fragments for
2643 The accompanying file example-embed-short.py has quick code fragments for
2632 embedding which you can cut and paste in your code once you understand how
2644 embedding which you can cut and paste in your code once you understand how
2633 things work.
2645 things work.
2634
2646
2635 The code in this file is deliberately extra-verbose, meant for learning."""
2647 The code in this file is deliberately extra-verbose, meant for learning."""
2636
2648
2637 # The basics to get you going:
2649 # The basics to get you going:
2638
2650
2639 # IPython sets the __IPYTHON__ variable so you can know if you have nested
2651 # IPython sets the __IPYTHON__ variable so you can know if you have nested
2640 # copies running.
2652 # copies running.
2641
2653
2642 # Try running this code both at the command line and from inside IPython (with
2654 # Try running this code both at the command line and from inside IPython (with
2643 # %run example-embed.py)
2655 # %run example-embed.py)
2644 try:
2656 try:
2645 __IPYTHON__
2657 __IPYTHON__
2646 except NameError:
2658 except NameError:
2647 nested = 0
2659 nested = 0
2648 args = ['']
2660 args = ['']
2649 else:
2661 else:
2650 print "Running nested copies of IPython."
2662 print "Running nested copies of IPython."
2651 print "The prompts for the nested copy have been modified"
2663 print "The prompts for the nested copy have been modified"
2652 nested = 1
2664 nested = 1
2653 # what the embedded instance will see as sys.argv:
2665 # what the embedded instance will see as sys.argv:
2654 args = ['-pi1','In <\\#>: ','-pi2',' .\\D.: ',
2666 args = ['-pi1','In <\\#>: ','-pi2',' .\\D.: ',
2655 '-po','Out<\\#>: ','-nosep']
2667 '-po','Out<\\#>: ','-nosep']
2656
2668
2657 # First import the embeddable shell class
2669 # First import the embeddable shell class
2658 from IPython.Shell import IPShellEmbed
2670 from IPython.Shell import IPShellEmbed
2659
2671
2660 # Now create an instance of the embeddable shell. The first argument is a
2672 # Now create an instance of the embeddable shell. The first argument is a
2661 # string with options exactly as you would type them if you were starting
2673 # string with options exactly as you would type them if you were starting
2662 # IPython at the system command line. Any parameters you want to define for
2674 # IPython at the system command line. Any parameters you want to define for
2663 # configuration can thus be specified here.
2675 # configuration can thus be specified here.
2664 ipshell = IPShellEmbed(args,
2676 ipshell = IPShellEmbed(args,
2665 banner = 'Dropping into IPython',
2677 banner = 'Dropping into IPython',
2666 exit_msg = 'Leaving Interpreter, back to program.')
2678 exit_msg = 'Leaving Interpreter, back to program.')
2667
2679
2668 # Make a second instance, you can have as many as you want.
2680 # Make a second instance, you can have as many as you want.
2669 if nested:
2681 if nested:
2670 args[1] = 'In2<\\#>'
2682 args[1] = 'In2<\\#>'
2671 else:
2683 else:
2672 args = ['-pi1','In2<\\#>: ','-pi2',' .\\D.: ',
2684 args = ['-pi1','In2<\\#>: ','-pi2',' .\\D.: ',
2673 '-po','Out<\\#>: ','-nosep']
2685 '-po','Out<\\#>: ','-nosep']
2674 ipshell2 = IPShellEmbed(args,banner = 'Second IPython instance.')
2686 ipshell2 = IPShellEmbed(args,banner = 'Second IPython instance.')
2675
2687
2676 print '\nHello. This is printed from the main controller program.\n'
2688 print '\nHello. This is printed from the main controller program.\n'
2677
2689
2678 # You can then call ipshell() anywhere you need it (with an optional
2690 # You can then call ipshell() anywhere you need it (with an optional
2679 # message):
2691 # message):
2680 ipshell('***Called from top level. '
2692 ipshell('***Called from top level. '
2681 'Hit Ctrl-D to exit interpreter and continue program.\n'
2693 'Hit Ctrl-D to exit interpreter and continue program.\n'
2682 'Note that if you use %kill_embedded, you can fully deactivate\n'
2694 'Note that if you use %kill_embedded, you can fully deactivate\n'
2683 'This embedded instance so it will never turn on again')
2695 'This embedded instance so it will never turn on again')
2684
2696
2685 print '\nBack in caller program, moving along...\n'
2697 print '\nBack in caller program, moving along...\n'
2686
2698
2687 #---------------------------------------------------------------------------
2699 #---------------------------------------------------------------------------
2688 # More details:
2700 # More details:
2689
2701
2690 # IPShellEmbed instances don't print the standard system banner and
2702 # IPShellEmbed instances don't print the standard system banner and
2691 # messages. The IPython banner (which actually may contain initialization
2703 # messages. The IPython banner (which actually may contain initialization
2692 # messages) is available as <instance>.IP.BANNER in case you want it.
2704 # messages) is available as <instance>.IP.BANNER in case you want it.
2693
2705
2694 # IPShellEmbed instances print the following information everytime they
2706 # IPShellEmbed instances print the following information everytime they
2695 # start:
2707 # start:
2696
2708
2697 # - A global startup banner.
2709 # - A global startup banner.
2698
2710
2699 # - A call-specific header string, which you can use to indicate where in the
2711 # - A call-specific header string, which you can use to indicate where in the
2700 # execution flow the shell is starting.
2712 # execution flow the shell is starting.
2701
2713
2702 # They also print an exit message every time they exit.
2714 # They also print an exit message every time they exit.
2703
2715
2704 # Both the startup banner and the exit message default to None, and can be set
2716 # Both the startup banner and the exit message default to None, and can be set
2705 # either at the instance constructor or at any other time with the
2717 # either at the instance constructor or at any other time with the
2706 # set_banner() and set_exit_msg() methods.
2718 # set_banner() and set_exit_msg() methods.
2707
2719
2708 # The shell instance can be also put in 'dummy' mode globally or on a per-call
2720 # The shell instance can be also put in 'dummy' mode globally or on a per-call
2709 # basis. This gives you fine control for debugging without having to change
2721 # basis. This gives you fine control for debugging without having to change
2710 # code all over the place.
2722 # code all over the place.
2711
2723
2712 # The code below illustrates all this.
2724 # The code below illustrates all this.
2713
2725
2714
2726
2715 # This is how the global banner and exit_msg can be reset at any point
2727 # This is how the global banner and exit_msg can be reset at any point
2716 ipshell.set_banner('Entering interpreter - New Banner')
2728 ipshell.set_banner('Entering interpreter - New Banner')
2717 ipshell.set_exit_msg('Leaving interpreter - New exit_msg')
2729 ipshell.set_exit_msg('Leaving interpreter - New exit_msg')
2718
2730
2719 def foo(m):
2731 def foo(m):
2720 s = 'spam'
2732 s = 'spam'
2721 ipshell('***In foo(). Try @whos, or print s or m:')
2733 ipshell('***In foo(). Try @whos, or print s or m:')
2722 print 'foo says m = ',m
2734 print 'foo says m = ',m
2723
2735
2724 def bar(n):
2736 def bar(n):
2725 s = 'eggs'
2737 s = 'eggs'
2726 ipshell('***In bar(). Try @whos, or print s or n:')
2738 ipshell('***In bar(). Try @whos, or print s or n:')
2727 print 'bar says n = ',n
2739 print 'bar says n = ',n
2728
2740
2729 # Some calls to the above functions which will trigger IPython:
2741 # Some calls to the above functions which will trigger IPython:
2730 print 'Main program calling foo("eggs")\n'
2742 print 'Main program calling foo("eggs")\n'
2731 foo('eggs')
2743 foo('eggs')
2732
2744
2733 # The shell can be put in 'dummy' mode where calls to it silently return. This
2745 # The shell can be put in 'dummy' mode where calls to it silently return. This
2734 # allows you, for example, to globally turn off debugging for a program with a
2746 # allows you, for example, to globally turn off debugging for a program with a
2735 # single call.
2747 # single call.
2736 ipshell.set_dummy_mode(1)
2748 ipshell.set_dummy_mode(1)
2737 print '\nTrying to call IPython which is now "dummy":'
2749 print '\nTrying to call IPython which is now "dummy":'
2738 ipshell()
2750 ipshell()
2739 print 'Nothing happened...'
2751 print 'Nothing happened...'
2740 # The global 'dummy' mode can still be overridden for a single call
2752 # The global 'dummy' mode can still be overridden for a single call
2741 print '\nOverriding dummy mode manually:'
2753 print '\nOverriding dummy mode manually:'
2742 ipshell(dummy=0)
2754 ipshell(dummy=0)
2743
2755
2744 # Reactivate the IPython shell
2756 # Reactivate the IPython shell
2745 ipshell.set_dummy_mode(0)
2757 ipshell.set_dummy_mode(0)
2746
2758
2747 print 'You can even have multiple embedded instances:'
2759 print 'You can even have multiple embedded instances:'
2748 ipshell2()
2760 ipshell2()
2749
2761
2750 print '\nMain program calling bar("spam")\n'
2762 print '\nMain program calling bar("spam")\n'
2751 bar('spam')
2763 bar('spam')
2752
2764
2753 print 'Main program finished. Bye!'
2765 print 'Main program finished. Bye!'
2754
2766
2755 #********************** End of file <example-embed.py> ***********************
2767 #********************** End of file <example-embed.py> ***********************
2756
2768
2757 Once you understand how the system functions, you can use the following
2769 Once you understand how the system functions, you can use the following
2758 code fragments in your programs which are ready for cut and paste::
2770 code fragments in your programs which are ready for cut and paste::
2759
2771
2760
2772
2761 """Quick code snippets for embedding IPython into other programs.
2773 """Quick code snippets for embedding IPython into other programs.
2762
2774
2763 See example-embed.py for full details, this file has the bare minimum code for
2775 See example-embed.py for full details, this file has the bare minimum code for
2764 cut and paste use once you understand how to use the system."""
2776 cut and paste use once you understand how to use the system."""
2765
2777
2766 #---------------------------------------------------------------------------
2778 #---------------------------------------------------------------------------
2767 # This code loads IPython but modifies a few things if it detects it's running
2779 # This code loads IPython but modifies a few things if it detects it's running
2768 # embedded in another IPython session (helps avoid confusion)
2780 # embedded in another IPython session (helps avoid confusion)
2769
2781
2770 try:
2782 try:
2771 __IPYTHON__
2783 __IPYTHON__
2772 except NameError:
2784 except NameError:
2773 argv = ['']
2785 argv = ['']
2774 banner = exit_msg = ''
2786 banner = exit_msg = ''
2775 else:
2787 else:
2776 # Command-line options for IPython (a list like sys.argv)
2788 # Command-line options for IPython (a list like sys.argv)
2777 argv = ['-pi1','In <\\#>:','-pi2',' .\\D.:','-po','Out<\\#>:']
2789 argv = ['-pi1','In <\\#>:','-pi2',' .\\D.:','-po','Out<\\#>:']
2778 banner = '*** Nested interpreter ***'
2790 banner = '*** Nested interpreter ***'
2779 exit_msg = '*** Back in main IPython ***'
2791 exit_msg = '*** Back in main IPython ***'
2780
2792
2781 # First import the embeddable shell class
2793 # First import the embeddable shell class
2782 from IPython.Shell import IPShellEmbed
2794 from IPython.Shell import IPShellEmbed
2783 # Now create the IPython shell instance. Put ipshell() anywhere in your code
2795 # Now create the IPython shell instance. Put ipshell() anywhere in your code
2784 # where you want it to open.
2796 # where you want it to open.
2785 ipshell = IPShellEmbed(argv,banner=banner,exit_msg=exit_msg)
2797 ipshell = IPShellEmbed(argv,banner=banner,exit_msg=exit_msg)
2786
2798
2787 #---------------------------------------------------------------------------
2799 #---------------------------------------------------------------------------
2788 # This code will load an embeddable IPython shell always with no changes for
2800 # This code will load an embeddable IPython shell always with no changes for
2789 # nested embededings.
2801 # nested embededings.
2790
2802
2791 from IPython.Shell import IPShellEmbed
2803 from IPython.Shell import IPShellEmbed
2792 ipshell = IPShellEmbed()
2804 ipshell = IPShellEmbed()
2793 # Now ipshell() will open IPython anywhere in the code.
2805 # Now ipshell() will open IPython anywhere in the code.
2794
2806
2795 #---------------------------------------------------------------------------
2807 #---------------------------------------------------------------------------
2796 # This code loads an embeddable shell only if NOT running inside
2808 # This code loads an embeddable shell only if NOT running inside
2797 # IPython. Inside IPython, the embeddable shell variable ipshell is just a
2809 # IPython. Inside IPython, the embeddable shell variable ipshell is just a
2798 # dummy function.
2810 # dummy function.
2799
2811
2800 try:
2812 try:
2801 __IPYTHON__
2813 __IPYTHON__
2802 except NameError:
2814 except NameError:
2803 from IPython.Shell import IPShellEmbed
2815 from IPython.Shell import IPShellEmbed
2804 ipshell = IPShellEmbed()
2816 ipshell = IPShellEmbed()
2805 # Now ipshell() will open IPython anywhere in the code
2817 # Now ipshell() will open IPython anywhere in the code
2806 else:
2818 else:
2807 # Define a dummy ipshell() so the same code doesn't crash inside an
2819 # Define a dummy ipshell() so the same code doesn't crash inside an
2808 # interactive IPython
2820 # interactive IPython
2809 def ipshell(): pass
2821 def ipshell(): pass
2810
2822
2811 #******************* End of file <example-embed-short.py> ********************
2823 #******************* End of file <example-embed-short.py> ********************
2812
2824
2813 Using the Python debugger (pdb)
2825 Using the Python debugger (pdb)
2814 ===============================
2826 ===============================
2815
2827
2816 Running entire programs via pdb
2828 Running entire programs via pdb
2817 -------------------------------
2829 -------------------------------
2818
2830
2819 pdb, the Python debugger, is a powerful interactive debugger which
2831 pdb, the Python debugger, is a powerful interactive debugger which
2820 allows you to step through code, set breakpoints, watch variables,
2832 allows you to step through code, set breakpoints, watch variables,
2821 etc. IPython makes it very easy to start any script under the control
2833 etc. IPython makes it very easy to start any script under the control
2822 of pdb, regardless of whether you have wrapped it into a 'main()'
2834 of pdb, regardless of whether you have wrapped it into a 'main()'
2823 function or not. For this, simply type '%run -d myscript' at an
2835 function or not. For this, simply type '%run -d myscript' at an
2824 IPython prompt. See the %run command's documentation (via '%run?' or
2836 IPython prompt. See the %run command's documentation (via '%run?' or
2825 in Sec. magic_ for more details, including how to control where pdb
2837 in Sec. magic_ for more details, including how to control where pdb
2826 will stop execution first.
2838 will stop execution first.
2827
2839
2828 For more information on the use of the pdb debugger, read the included
2840 For more information on the use of the pdb debugger, read the included
2829 pdb.doc file (part of the standard Python distribution). On a stock
2841 pdb.doc file (part of the standard Python distribution). On a stock
2830 Linux system it is located at /usr/lib/python2.3/pdb.doc, but the
2842 Linux system it is located at /usr/lib/python2.3/pdb.doc, but the
2831 easiest way to read it is by using the help() function of the pdb module
2843 easiest way to read it is by using the help() function of the pdb module
2832 as follows (in an IPython prompt):
2844 as follows (in an IPython prompt):
2833
2845
2834 In [1]: import pdb
2846 In [1]: import pdb
2835 In [2]: pdb.help()
2847 In [2]: pdb.help()
2836
2848
2837 This will load the pdb.doc document in a file viewer for you automatically.
2849 This will load the pdb.doc document in a file viewer for you automatically.
2838
2850
2839
2851
2840 Automatic invocation of pdb on exceptions
2852 Automatic invocation of pdb on exceptions
2841 -----------------------------------------
2853 -----------------------------------------
2842
2854
2843 IPython, if started with the -pdb option (or if the option is set in
2855 IPython, if started with the -pdb option (or if the option is set in
2844 your rc file) can call the Python pdb debugger every time your code
2856 your rc file) can call the Python pdb debugger every time your code
2845 triggers an uncaught exception. This feature
2857 triggers an uncaught exception. This feature
2846 can also be toggled at any time with the %pdb magic command. This can be
2858 can also be toggled at any time with the %pdb magic command. This can be
2847 extremely useful in order to find the origin of subtle bugs, because pdb
2859 extremely useful in order to find the origin of subtle bugs, because pdb
2848 opens up at the point in your code which triggered the exception, and
2860 opens up at the point in your code which triggered the exception, and
2849 while your program is at this point 'dead', all the data is still
2861 while your program is at this point 'dead', all the data is still
2850 available and you can walk up and down the stack frame and understand
2862 available and you can walk up and down the stack frame and understand
2851 the origin of the problem.
2863 the origin of the problem.
2852
2864
2853 Furthermore, you can use these debugging facilities both with the
2865 Furthermore, you can use these debugging facilities both with the
2854 embedded IPython mode and without IPython at all. For an embedded shell
2866 embedded IPython mode and without IPython at all. For an embedded shell
2855 (see sec. Embedding_), simply call the constructor with
2867 (see sec. Embedding_), simply call the constructor with
2856 '-pdb' in the argument string and automatically pdb will be called if an
2868 '-pdb' in the argument string and automatically pdb will be called if an
2857 uncaught exception is triggered by your code.
2869 uncaught exception is triggered by your code.
2858
2870
2859 For stand-alone use of the feature in your programs which do not use
2871 For stand-alone use of the feature in your programs which do not use
2860 IPython at all, put the following lines toward the top of your 'main'
2872 IPython at all, put the following lines toward the top of your 'main'
2861 routine::
2873 routine::
2862
2874
2863 import sys,IPython.ultraTB
2875 import sys,IPython.ultraTB
2864 sys.excepthook = IPython.ultraTB.FormattedTB(mode='Verbose',
2876 sys.excepthook = IPython.ultraTB.FormattedTB(mode='Verbose',
2865 color_scheme='Linux', call_pdb=1)
2877 color_scheme='Linux', call_pdb=1)
2866
2878
2867 The mode keyword can be either 'Verbose' or 'Plain', giving either very
2879 The mode keyword can be either 'Verbose' or 'Plain', giving either very
2868 detailed or normal tracebacks respectively. The color_scheme keyword can
2880 detailed or normal tracebacks respectively. The color_scheme keyword can
2869 be one of 'NoColor', 'Linux' (default) or 'LightBG'. These are the same
2881 be one of 'NoColor', 'Linux' (default) or 'LightBG'. These are the same
2870 options which can be set in IPython with -colors and -xmode.
2882 options which can be set in IPython with -colors and -xmode.
2871
2883
2872 This will give any of your programs detailed, colored tracebacks with
2884 This will give any of your programs detailed, colored tracebacks with
2873 automatic invocation of pdb.
2885 automatic invocation of pdb.
2874
2886
2875
2887
2876 Extensions for syntax processing
2888 Extensions for syntax processing
2877 ================================
2889 ================================
2878
2890
2879 This isn't for the faint of heart, because the potential for breaking
2891 This isn't for the faint of heart, because the potential for breaking
2880 things is quite high. But it can be a very powerful and useful feature.
2892 things is quite high. But it can be a very powerful and useful feature.
2881 In a nutshell, you can redefine the way IPython processes the user input
2893 In a nutshell, you can redefine the way IPython processes the user input
2882 line to accept new, special extensions to the syntax without needing to
2894 line to accept new, special extensions to the syntax without needing to
2883 change any of IPython's own code.
2895 change any of IPython's own code.
2884
2896
2885 In the IPython/Extensions directory you will find some examples
2897 In the IPython/Extensions directory you will find some examples
2886 supplied, which we will briefly describe now. These can be used 'as is'
2898 supplied, which we will briefly describe now. These can be used 'as is'
2887 (and both provide very useful functionality), or you can use them as a
2899 (and both provide very useful functionality), or you can use them as a
2888 starting point for writing your own extensions.
2900 starting point for writing your own extensions.
2889
2901
2890
2902
2891 Pasting of code starting with '>>> ' or '... '
2903 Pasting of code starting with '>>> ' or '... '
2892 ----------------------------------------------
2904 ----------------------------------------------
2893
2905
2894 In the python tutorial it is common to find code examples which have
2906 In the python tutorial it is common to find code examples which have
2895 been taken from real python sessions. The problem with those is that all
2907 been taken from real python sessions. The problem with those is that all
2896 the lines begin with either '>>> ' or '... ', which makes it impossible
2908 the lines begin with either '>>> ' or '... ', which makes it impossible
2897 to paste them all at once. One must instead do a line by line manual
2909 to paste them all at once. One must instead do a line by line manual
2898 copying, carefully removing the leading extraneous characters.
2910 copying, carefully removing the leading extraneous characters.
2899
2911
2900 This extension identifies those starting characters and removes them
2912 This extension identifies those starting characters and removes them
2901 from the input automatically, so that one can paste multi-line examples
2913 from the input automatically, so that one can paste multi-line examples
2902 directly into IPython, saving a lot of time. Please look at the file
2914 directly into IPython, saving a lot of time. Please look at the file
2903 InterpreterPasteInput.py in the IPython/Extensions directory for details
2915 InterpreterPasteInput.py in the IPython/Extensions directory for details
2904 on how this is done.
2916 on how this is done.
2905
2917
2906 IPython comes with a special profile enabling this feature, called
2918 IPython comes with a special profile enabling this feature, called
2907 tutorial. Simply start IPython via 'ipython -p tutorial' and the feature
2919 tutorial. Simply start IPython via 'ipython -p tutorial' and the feature
2908 will be available. In a normal IPython session you can activate the
2920 will be available. In a normal IPython session you can activate the
2909 feature by importing the corresponding module with:
2921 feature by importing the corresponding module with:
2910 In [1]: import IPython.Extensions.InterpreterPasteInput
2922 In [1]: import IPython.Extensions.InterpreterPasteInput
2911
2923
2912 The following is a 'screenshot' of how things work when this extension
2924 The following is a 'screenshot' of how things work when this extension
2913 is on, copying an example from the standard tutorial::
2925 is on, copying an example from the standard tutorial::
2914
2926
2915 IPython profile: tutorial
2927 IPython profile: tutorial
2916
2928
2917 *** Pasting of code with ">>>" or "..." has been enabled.
2929 *** Pasting of code with ">>>" or "..." has been enabled.
2918
2930
2919 In [1]: >>> def fib2(n): # return Fibonacci series up to n
2931 In [1]: >>> def fib2(n): # return Fibonacci series up to n
2920 ...: ... """Return a list containing the Fibonacci series up to
2932 ...: ... """Return a list containing the Fibonacci series up to
2921 n."""
2933 n."""
2922 ...: ... result = []
2934 ...: ... result = []
2923 ...: ... a, b = 0, 1
2935 ...: ... a, b = 0, 1
2924 ...: ... while b < n:
2936 ...: ... while b < n:
2925 ...: ... result.append(b) # see below
2937 ...: ... result.append(b) # see below
2926 ...: ... a, b = b, a+b
2938 ...: ... a, b = b, a+b
2927 ...: ... return result
2939 ...: ... return result
2928 ...:
2940 ...:
2929
2941
2930 In [2]: fib2(10)
2942 In [2]: fib2(10)
2931 Out[2]: [1, 1, 2, 3, 5, 8]
2943 Out[2]: [1, 1, 2, 3, 5, 8]
2932
2944
2933 Note that as currently written, this extension does not recognize
2945 Note that as currently written, this extension does not recognize
2934 IPython's prompts for pasting. Those are more complicated, since the
2946 IPython's prompts for pasting. Those are more complicated, since the
2935 user can change them very easily, they involve numbers and can vary in
2947 user can change them very easily, they involve numbers and can vary in
2936 length. One could however extract all the relevant information from the
2948 length. One could however extract all the relevant information from the
2937 IPython instance and build an appropriate regular expression. This is
2949 IPython instance and build an appropriate regular expression. This is
2938 left as an exercise for the reader.
2950 left as an exercise for the reader.
2939
2951
2940
2952
2941 Input of physical quantities with units
2953 Input of physical quantities with units
2942 ---------------------------------------
2954 ---------------------------------------
2943
2955
2944 The module PhysicalQInput allows a simplified form of input for physical
2956 The module PhysicalQInput allows a simplified form of input for physical
2945 quantities with units. This file is meant to be used in conjunction with
2957 quantities with units. This file is meant to be used in conjunction with
2946 the PhysicalQInteractive module (in the same directory) and
2958 the PhysicalQInteractive module (in the same directory) and
2947 Physics.PhysicalQuantities from Konrad Hinsen's ScientificPython
2959 Physics.PhysicalQuantities from Konrad Hinsen's ScientificPython
2948 (http://dirac.cnrs-orleans.fr/ScientificPython/).
2960 (http://dirac.cnrs-orleans.fr/ScientificPython/).
2949
2961
2950 The Physics.PhysicalQuantities module defines PhysicalQuantity objects,
2962 The Physics.PhysicalQuantities module defines PhysicalQuantity objects,
2951 but these must be declared as instances of a class. For example, to
2963 but these must be declared as instances of a class. For example, to
2952 define v as a velocity of 3 m/s, normally you would write::
2964 define v as a velocity of 3 m/s, normally you would write::
2953
2965
2954 In [1]: v = PhysicalQuantity(3,'m/s')
2966 In [1]: v = PhysicalQuantity(3,'m/s')
2955
2967
2956 Using the PhysicalQ_Input extension this can be input instead as:
2968 Using the PhysicalQ_Input extension this can be input instead as:
2957 In [1]: v = 3 m/s
2969 In [1]: v = 3 m/s
2958 which is much more convenient for interactive use (even though it is
2970 which is much more convenient for interactive use (even though it is
2959 blatantly invalid Python syntax).
2971 blatantly invalid Python syntax).
2960
2972
2961 The physics profile supplied with IPython (enabled via 'ipython -p
2973 The physics profile supplied with IPython (enabled via 'ipython -p
2962 physics') uses these extensions, which you can also activate with:
2974 physics') uses these extensions, which you can also activate with:
2963
2975
2964 from math import * # math MUST be imported BEFORE PhysicalQInteractive
2976 from math import * # math MUST be imported BEFORE PhysicalQInteractive
2965 from IPython.Extensions.PhysicalQInteractive import *
2977 from IPython.Extensions.PhysicalQInteractive import *
2966 import IPython.Extensions.PhysicalQInput
2978 import IPython.Extensions.PhysicalQInput
2967
2979
2968
2980
2969 Threading support
2981 Threading support
2970 =================
2982 =================
2971
2983
2972 WARNING: The threading support is still somewhat experimental, and it
2984 WARNING: The threading support is still somewhat experimental, and it
2973 has only seen reasonable testing under Linux. Threaded code is
2985 has only seen reasonable testing under Linux. Threaded code is
2974 particularly tricky to debug, and it tends to show extremely
2986 particularly tricky to debug, and it tends to show extremely
2975 platform-dependent behavior. Since I only have access to Linux machines,
2987 platform-dependent behavior. Since I only have access to Linux machines,
2976 I will have to rely on user's experiences and assistance for this area
2988 I will have to rely on user's experiences and assistance for this area
2977 of IPython to improve under other platforms.
2989 of IPython to improve under other platforms.
2978
2990
2979 IPython, via the -gthread , -qthread, -q4thread and -wthread options
2991 IPython, via the -gthread , -qthread, -q4thread and -wthread options
2980 (described in Sec. `Threading options`_), can run in
2992 (described in Sec. `Threading options`_), can run in
2981 multithreaded mode to support pyGTK, Qt3, Qt4 and WXPython applications
2993 multithreaded mode to support pyGTK, Qt3, Qt4 and WXPython applications
2982 respectively. These GUI toolkits need to control the python main loop of
2994 respectively. These GUI toolkits need to control the python main loop of
2983 execution, so under a normal Python interpreter, starting a pyGTK, Qt3,
2995 execution, so under a normal Python interpreter, starting a pyGTK, Qt3,
2984 Qt4 or WXPython application will immediately freeze the shell.
2996 Qt4 or WXPython application will immediately freeze the shell.
2985
2997
2986 IPython, with one of these options (you can only use one at a time),
2998 IPython, with one of these options (you can only use one at a time),
2987 separates the graphical loop and IPython's code execution run into
2999 separates the graphical loop and IPython's code execution run into
2988 different threads. This allows you to test interactively (with %run, for
3000 different threads. This allows you to test interactively (with %run, for
2989 example) your GUI code without blocking.
3001 example) your GUI code without blocking.
2990
3002
2991 A nice mini-tutorial on using IPython along with the Qt Designer
3003 A nice mini-tutorial on using IPython along with the Qt Designer
2992 application is available at the SciPy wiki:
3004 application is available at the SciPy wiki:
2993 http://www.scipy.org/Cookbook/Matplotlib/Qt_with_IPython_and_Designer.
3005 http://www.scipy.org/Cookbook/Matplotlib/Qt_with_IPython_and_Designer.
2994
3006
2995
3007
2996 Tk issues
3008 Tk issues
2997 ---------
3009 ---------
2998
3010
2999 As indicated in Sec. `Threading options`_, a special -tk option is
3011 As indicated in Sec. `Threading options`_, a special -tk option is
3000 provided to try and allow Tk graphical applications to coexist
3012 provided to try and allow Tk graphical applications to coexist
3001 interactively with WX, Qt or GTK ones. Whether this works at all,
3013 interactively with WX, Qt or GTK ones. Whether this works at all,
3002 however, is very platform and configuration dependent. Please
3014 however, is very platform and configuration dependent. Please
3003 experiment with simple test cases before committing to using this
3015 experiment with simple test cases before committing to using this
3004 combination of Tk and GTK/Qt/WX threading in a production environment.
3016 combination of Tk and GTK/Qt/WX threading in a production environment.
3005
3017
3006
3018
3007 I/O pitfalls
3019 I/O pitfalls
3008 ------------
3020 ------------
3009
3021
3010 Be mindful that the Python interpreter switches between threads every
3022 Be mindful that the Python interpreter switches between threads every
3011 $N$ bytecodes, where the default value as of Python 2.3 is $N=100.$ This
3023 $N$ bytecodes, where the default value as of Python 2.3 is $N=100.$ This
3012 value can be read by using the sys.getcheckinterval() function, and it
3024 value can be read by using the sys.getcheckinterval() function, and it
3013 can be reset via sys.setcheckinterval(N). This switching of threads can
3025 can be reset via sys.setcheckinterval(N). This switching of threads can
3014 cause subtly confusing effects if one of your threads is doing file I/O.
3026 cause subtly confusing effects if one of your threads is doing file I/O.
3015 In text mode, most systems only flush file buffers when they encounter a
3027 In text mode, most systems only flush file buffers when they encounter a
3016 '\n'. An instruction as simple as::
3028 '\n'. An instruction as simple as::
3017
3029
3018 print >> filehandle, ''hello world''
3030 print >> filehandle, ''hello world''
3019
3031
3020 actually consists of several bytecodes, so it is possible that the
3032 actually consists of several bytecodes, so it is possible that the
3021 newline does not reach your file before the next thread switch.
3033 newline does not reach your file before the next thread switch.
3022 Similarly, if you are writing to a file in binary mode, the file won't
3034 Similarly, if you are writing to a file in binary mode, the file won't
3023 be flushed until the buffer fills, and your other thread may see
3035 be flushed until the buffer fills, and your other thread may see
3024 apparently truncated files.
3036 apparently truncated files.
3025
3037
3026 For this reason, if you are using IPython's thread support and have (for
3038 For this reason, if you are using IPython's thread support and have (for
3027 example) a GUI application which will read data generated by files
3039 example) a GUI application which will read data generated by files
3028 written to from the IPython thread, the safest approach is to open all
3040 written to from the IPython thread, the safest approach is to open all
3029 of your files in unbuffered mode (the third argument to the file/open
3041 of your files in unbuffered mode (the third argument to the file/open
3030 function is the buffering value)::
3042 function is the buffering value)::
3031
3043
3032 filehandle = open(filename,mode,0)
3044 filehandle = open(filename,mode,0)
3033
3045
3034 This is obviously a brute force way of avoiding race conditions with the
3046 This is obviously a brute force way of avoiding race conditions with the
3035 file buffering. If you want to do it cleanly, and you have a resource
3047 file buffering. If you want to do it cleanly, and you have a resource
3036 which is being shared by the interactive IPython loop and your GUI
3048 which is being shared by the interactive IPython loop and your GUI
3037 thread, you should really handle it with thread locking and
3049 thread, you should really handle it with thread locking and
3038 syncrhonization properties. The Python documentation discusses these.
3050 syncrhonization properties. The Python documentation discusses these.
3039
3051
3040 .. _interactive_demos:
3052 .. _interactive_demos:
3041
3053
3042 Interactive demos with IPython
3054 Interactive demos with IPython
3043 ==============================
3055 ==============================
3044
3056
3045 IPython ships with a basic system for running scripts interactively in
3057 IPython ships with a basic system for running scripts interactively in
3046 sections, useful when presenting code to audiences. A few tags embedded
3058 sections, useful when presenting code to audiences. A few tags embedded
3047 in comments (so that the script remains valid Python code) divide a file
3059 in comments (so that the script remains valid Python code) divide a file
3048 into separate blocks, and the demo can be run one block at a time, with
3060 into separate blocks, and the demo can be run one block at a time, with
3049 IPython printing (with syntax highlighting) the block before executing
3061 IPython printing (with syntax highlighting) the block before executing
3050 it, and returning to the interactive prompt after each block. The
3062 it, and returning to the interactive prompt after each block. The
3051 interactive namespace is updated after each block is run with the
3063 interactive namespace is updated after each block is run with the
3052 contents of the demo's namespace.
3064 contents of the demo's namespace.
3053
3065
3054 This allows you to show a piece of code, run it and then execute
3066 This allows you to show a piece of code, run it and then execute
3055 interactively commands based on the variables just created. Once you
3067 interactively commands based on the variables just created. Once you
3056 want to continue, you simply execute the next block of the demo. The
3068 want to continue, you simply execute the next block of the demo. The
3057 following listing shows the markup necessary for dividing a script into
3069 following listing shows the markup necessary for dividing a script into
3058 sections for execution as a demo::
3070 sections for execution as a demo::
3059
3071
3060
3072
3061 """A simple interactive demo to illustrate the use of IPython's Demo class.
3073 """A simple interactive demo to illustrate the use of IPython's Demo class.
3062
3074
3063 Any python script can be run as a demo, but that does little more than showing
3075 Any python script can be run as a demo, but that does little more than showing
3064 it on-screen, syntax-highlighted in one shot. If you add a little simple
3076 it on-screen, syntax-highlighted in one shot. If you add a little simple
3065 markup, you can stop at specified intervals and return to the ipython prompt,
3077 markup, you can stop at specified intervals and return to the ipython prompt,
3066 resuming execution later.
3078 resuming execution later.
3067 """
3079 """
3068
3080
3069 print 'Hello, welcome to an interactive IPython demo.'
3081 print 'Hello, welcome to an interactive IPython demo.'
3070 print 'Executing this block should require confirmation before proceeding,'
3082 print 'Executing this block should require confirmation before proceeding,'
3071 print 'unless auto_all has been set to true in the demo object'
3083 print 'unless auto_all has been set to true in the demo object'
3072
3084
3073 # The mark below defines a block boundary, which is a point where IPython will
3085 # The mark below defines a block boundary, which is a point where IPython will
3074 # stop execution and return to the interactive prompt.
3086 # stop execution and return to the interactive prompt.
3075 # Note that in actual interactive execution,
3087 # Note that in actual interactive execution,
3076 # <demo> --- stop ---
3088 # <demo> --- stop ---
3077
3089
3078 x = 1
3090 x = 1
3079 y = 2
3091 y = 2
3080
3092
3081 # <demo> --- stop ---
3093 # <demo> --- stop ---
3082
3094
3083 # the mark below makes this block as silent
3095 # the mark below makes this block as silent
3084 # <demo> silent
3096 # <demo> silent
3085
3097
3086 print 'This is a silent block, which gets executed but not printed.'
3098 print 'This is a silent block, which gets executed but not printed.'
3087
3099
3088 # <demo> --- stop ---
3100 # <demo> --- stop ---
3089 # <demo> auto
3101 # <demo> auto
3090 print 'This is an automatic block.'
3102 print 'This is an automatic block.'
3091 print 'It is executed without asking for confirmation, but printed.'
3103 print 'It is executed without asking for confirmation, but printed.'
3092 z = x+y
3104 z = x+y
3093
3105
3094 print 'z=',x
3106 print 'z=',x
3095
3107
3096 # <demo> --- stop ---
3108 # <demo> --- stop ---
3097 # This is just another normal block.
3109 # This is just another normal block.
3098 print 'z is now:', z
3110 print 'z is now:', z
3099
3111
3100 print 'bye!'
3112 print 'bye!'
3101
3113
3102 In order to run a file as a demo, you must first make a Demo object out
3114 In order to run a file as a demo, you must first make a Demo object out
3103 of it. If the file is named myscript.py, the following code will make a
3115 of it. If the file is named myscript.py, the following code will make a
3104 demo::
3116 demo::
3105
3117
3106 from IPython.demo import Demo
3118 from IPython.demo import Demo
3107
3119
3108 mydemo = Demo('myscript.py')
3120 mydemo = Demo('myscript.py')
3109
3121
3110 This creates the mydemo object, whose blocks you run one at a time by
3122 This creates the mydemo object, whose blocks you run one at a time by
3111 simply calling the object with no arguments. If you have autocall active
3123 simply calling the object with no arguments. If you have autocall active
3112 in IPython (the default), all you need to do is type::
3124 in IPython (the default), all you need to do is type::
3113
3125
3114 mydemo
3126 mydemo
3115
3127
3116 and IPython will call it, executing each block. Demo objects can be
3128 and IPython will call it, executing each block. Demo objects can be
3117 restarted, you can move forward or back skipping blocks, re-execute the
3129 restarted, you can move forward or back skipping blocks, re-execute the
3118 last block, etc. Simply use the Tab key on a demo object to see its
3130 last block, etc. Simply use the Tab key on a demo object to see its
3119 methods, and call '?' on them to see their docstrings for more usage
3131 methods, and call '?' on them to see their docstrings for more usage
3120 details. In addition, the demo module itself contains a comprehensive
3132 details. In addition, the demo module itself contains a comprehensive
3121 docstring, which you can access via::
3133 docstring, which you can access via::
3122
3134
3123 from IPython import demo
3135 from IPython import demo
3124
3136
3125 demo?
3137 demo?
3126
3138
3127 Limitations: It is important to note that these demos are limited to
3139 Limitations: It is important to note that these demos are limited to
3128 fairly simple uses. In particular, you can not put division marks in
3140 fairly simple uses. In particular, you can not put division marks in
3129 indented code (loops, if statements, function definitions, etc.)
3141 indented code (loops, if statements, function definitions, etc.)
3130 Supporting something like this would basically require tracking the
3142 Supporting something like this would basically require tracking the
3131 internal execution state of the Python interpreter, so only top-level
3143 internal execution state of the Python interpreter, so only top-level
3132 divisions are allowed. If you want to be able to open an IPython
3144 divisions are allowed. If you want to be able to open an IPython
3133 instance at an arbitrary point in a program, you can use IPython's
3145 instance at an arbitrary point in a program, you can use IPython's
3134 embedding facilities, described in detail in Sec. 9
3146 embedding facilities, described in detail in Sec. 9
3135
3147
3136
3148
3137 .. _Matplotlib support:
3149 .. _Matplotlib support:
3138
3150
3139 Plotting with matplotlib
3151 Plotting with matplotlib
3140 ========================
3152 ========================
3141
3153
3142 The matplotlib library (http://matplotlib.sourceforge.net
3154 The matplotlib library (http://matplotlib.sourceforge.net
3143 http://matplotlib.sourceforge.net) provides high quality 2D plotting for
3155 http://matplotlib.sourceforge.net) provides high quality 2D plotting for
3144 Python. Matplotlib can produce plots on screen using a variety of GUI
3156 Python. Matplotlib can produce plots on screen using a variety of GUI
3145 toolkits, including Tk, GTK and WXPython. It also provides a number of
3157 toolkits, including Tk, GTK and WXPython. It also provides a number of
3146 commands useful for scientific computing, all with a syntax compatible
3158 commands useful for scientific computing, all with a syntax compatible
3147 with that of the popular Matlab program.
3159 with that of the popular Matlab program.
3148
3160
3149 IPython accepts the special option -pylab (see :ref:`here
3161 IPython accepts the special option -pylab (see :ref:`here
3150 <command_line_options>`). This configures it to support matplotlib, honoring
3162 <command_line_options>`). This configures it to support matplotlib, honoring
3151 the settings in the .matplotlibrc file. IPython will detect the user's choice
3163 the settings in the .matplotlibrc file. IPython will detect the user's choice
3152 of matplotlib GUI backend, and automatically select the proper threading model
3164 of matplotlib GUI backend, and automatically select the proper threading model
3153 to prevent blocking. It also sets matplotlib in interactive mode and modifies
3165 to prevent blocking. It also sets matplotlib in interactive mode and modifies
3154 %run slightly, so that any matplotlib-based script can be executed using %run
3166 %run slightly, so that any matplotlib-based script can be executed using %run
3155 and the final show() command does not block the interactive shell.
3167 and the final show() command does not block the interactive shell.
3156
3168
3157 The -pylab option must be given first in order for IPython to configure its
3169 The -pylab option must be given first in order for IPython to configure its
3158 threading mode. However, you can still issue other options afterwards. This
3170 threading mode. However, you can still issue other options afterwards. This
3159 allows you to have a matplotlib-based environment customized with additional
3171 allows you to have a matplotlib-based environment customized with additional
3160 modules using the standard IPython profile mechanism (see :ref:`here
3172 modules using the standard IPython profile mechanism (see :ref:`here
3161 <profiles>`): ``ipython -pylab -p myprofile`` will load the profile defined in
3173 <profiles>`): ``ipython -pylab -p myprofile`` will load the profile defined in
3162 ipythonrc-myprofile after configuring matplotlib.
3174 ipythonrc-myprofile after configuring matplotlib.
General Comments 0
You need to be logged in to leave comments. Login now