##// END OF EJS Templates
corrected some quickref glitches
vivainio -
Show More
@@ -1,640 +1,641 b''
1 # -*- coding: utf-8 -*-
1 # -*- coding: utf-8 -*-
2 #*****************************************************************************
2 #*****************************************************************************
3 # Copyright (C) 2001-2004 Fernando Perez. <fperez@colorado.edu>
3 # Copyright (C) 2001-2004 Fernando Perez. <fperez@colorado.edu>
4 #
4 #
5 # Distributed under the terms of the BSD License. The full license is in
5 # Distributed under the terms of the BSD License. The full license is in
6 # the file COPYING, distributed as part of this software.
6 # the file COPYING, distributed as part of this software.
7 #*****************************************************************************
7 #*****************************************************************************
8
8
9 # $Id: usage.py 1092 2006-01-27 23:56:32Z vivainio $
9 # $Id: usage.py 1177 2006-02-24 16:40:24Z vivainio $
10
10
11 from IPython import Release
11 from IPython import Release
12 __author__ = '%s <%s>' % Release.authors['Fernando']
12 __author__ = '%s <%s>' % Release.authors['Fernando']
13 __license__ = Release.license
13 __license__ = Release.license
14 __version__ = Release.version
14 __version__ = Release.version
15
15
16 __doc__ = """
16 __doc__ = """
17 IPython -- An enhanced Interactive Python
17 IPython -- An enhanced Interactive Python
18 =========================================
18 =========================================
19
19
20 A Python shell with automatic history (input and output), dynamic object
20 A Python shell with automatic history (input and output), dynamic object
21 introspection, easier configuration, command completion, access to the system
21 introspection, easier configuration, command completion, access to the system
22 shell and more.
22 shell and more.
23
23
24 IPython can also be embedded in running programs. See EMBEDDING below.
24 IPython can also be embedded in running programs. See EMBEDDING below.
25
25
26
26
27 USAGE
27 USAGE
28 ipython [options] files
28 ipython [options] files
29
29
30 If invoked with no options, it executes all the files listed in
30 If invoked with no options, it executes all the files listed in
31 sequence and drops you into the interpreter while still acknowledging
31 sequence and drops you into the interpreter while still acknowledging
32 any options you may have set in your ipythonrc file. This behavior is
32 any options you may have set in your ipythonrc file. This behavior is
33 different from standard Python, which when called as python -i will
33 different from standard Python, which when called as python -i will
34 only execute one file and will ignore your configuration setup.
34 only execute one file and will ignore your configuration setup.
35
35
36 Please note that some of the configuration options are not available at
36 Please note that some of the configuration options are not available at
37 the command line, simply because they are not practical here. Look into
37 the command line, simply because they are not practical here. Look into
38 your ipythonrc configuration file for details on those. This file
38 your ipythonrc configuration file for details on those. This file
39 typically installed in the $HOME/.ipython directory.
39 typically installed in the $HOME/.ipython directory.
40
40
41 For Windows users, $HOME resolves to C:\\Documents and
41 For Windows users, $HOME resolves to C:\\Documents and
42 Settings\\YourUserName in most instances, and _ipython is used instead
42 Settings\\YourUserName in most instances, and _ipython is used instead
43 of .ipython, since some Win32 programs have problems with dotted names
43 of .ipython, since some Win32 programs have problems with dotted names
44 in directories.
44 in directories.
45
45
46 In the rest of this text, we will refer to this directory as
46 In the rest of this text, we will refer to this directory as
47 IPYTHONDIR.
47 IPYTHONDIR.
48
48
49
49
50 SPECIAL THREADING OPTIONS
50 SPECIAL THREADING OPTIONS
51 The following special options are ONLY valid at the beginning of the
51 The following special options are ONLY valid at the beginning of the
52 command line, and not later. This is because they control the initial-
52 command line, and not later. This is because they control the initial-
53 ization of ipython itself, before the normal option-handling mechanism
53 ization of ipython itself, before the normal option-handling mechanism
54 is active.
54 is active.
55
55
56 -gthread, -qthread, -wthread, -pylab
56 -gthread, -qthread, -wthread, -pylab
57
57
58 Only ONE of these can be given, and it can only be given as the
58 Only ONE of these can be given, and it can only be given as the
59 first option passed to IPython (it will have no effect in any
59 first option passed to IPython (it will have no effect in any
60 other position). They provide threading support for the GTK, QT
60 other position). They provide threading support for the GTK, QT
61 and WXWidgets toolkits, and for the matplotlib library.
61 and WXWidgets toolkits, and for the matplotlib library.
62
62
63 With any of the first three options, IPython starts running a
63 With any of the first three options, IPython starts running a
64 separate thread for the graphical toolkit's operation, so that
64 separate thread for the graphical toolkit's operation, so that
65 you can open and control graphical elements from within an
65 you can open and control graphical elements from within an
66 IPython command line, without blocking. All three provide
66 IPython command line, without blocking. All three provide
67 essentially the same functionality, respectively for GTK, QT and
67 essentially the same functionality, respectively for GTK, QT and
68 WXWidgets (via their Python interfaces).
68 WXWidgets (via their Python interfaces).
69
69
70 Note that with -wthread, you can additionally use the -wxversion
70 Note that with -wthread, you can additionally use the -wxversion
71 option to request a specific version of wx to be used. This
71 option to request a specific version of wx to be used. This
72 requires that you have the 'wxversion' Python module installed,
72 requires that you have the 'wxversion' Python module installed,
73 which is part of recent wxPython distributions.
73 which is part of recent wxPython distributions.
74
74
75 If -pylab is given, IPython loads special support for the mat-
75 If -pylab is given, IPython loads special support for the mat-
76 plotlib library (http://matplotlib.sourceforge.net), allowing
76 plotlib library (http://matplotlib.sourceforge.net), allowing
77 interactive usage of any of its backends as defined in the
77 interactive usage of any of its backends as defined in the
78 user's .matplotlibrc file. It automatically activates GTK, QT
78 user's .matplotlibrc file. It automatically activates GTK, QT
79 or WX threading for IPyhton if the choice of matplotlib backend
79 or WX threading for IPyhton if the choice of matplotlib backend
80 requires it. It also modifies the %run command to correctly
80 requires it. It also modifies the %run command to correctly
81 execute (without blocking) any matplotlib-based script which
81 execute (without blocking) any matplotlib-based script which
82 calls show() at the end.
82 calls show() at the end.
83
83
84 -tk The -g/q/wthread options, and -pylab (if matplotlib is
84 -tk The -g/q/wthread options, and -pylab (if matplotlib is
85 configured to use GTK, QT or WX), will normally block Tk
85 configured to use GTK, QT or WX), will normally block Tk
86 graphical interfaces. This means that when GTK, QT or WX
86 graphical interfaces. This means that when GTK, QT or WX
87 threading is active, any attempt to open a Tk GUI will result in
87 threading is active, any attempt to open a Tk GUI will result in
88 a dead window, and possibly cause the Python interpreter to
88 a dead window, and possibly cause the Python interpreter to
89 crash. An extra option, -tk, is available to address this
89 crash. An extra option, -tk, is available to address this
90 issue. It can ONLY be given as a SECOND option after any of the
90 issue. It can ONLY be given as a SECOND option after any of the
91 above (-gthread, -qthread, -wthread or -pylab).
91 above (-gthread, -qthread, -wthread or -pylab).
92
92
93 If -tk is given, IPython will try to coordinate Tk threading
93 If -tk is given, IPython will try to coordinate Tk threading
94 with GTK, QT or WX. This is however potentially unreliable, and
94 with GTK, QT or WX. This is however potentially unreliable, and
95 you will have to test on your platform and Python configuration
95 you will have to test on your platform and Python configuration
96 to determine whether it works for you. Debian users have
96 to determine whether it works for you. Debian users have
97 reported success, apparently due to the fact that Debian builds
97 reported success, apparently due to the fact that Debian builds
98 all of Tcl, Tk, Tkinter and Python with pthreads support. Under
98 all of Tcl, Tk, Tkinter and Python with pthreads support. Under
99 other Linux environments (such as Fedora Core 2/3), this option
99 other Linux environments (such as Fedora Core 2/3), this option
100 has caused random crashes and lockups of the Python interpreter.
100 has caused random crashes and lockups of the Python interpreter.
101 Under other operating systems (Mac OSX and Windows), you'll need
101 Under other operating systems (Mac OSX and Windows), you'll need
102 to try it to find out, since currently no user reports are
102 to try it to find out, since currently no user reports are
103 available.
103 available.
104
104
105 There is unfortunately no way for IPython to determine at run-
105 There is unfortunately no way for IPython to determine at run-
106 time whether -tk will work reliably or not, so you will need to
106 time whether -tk will work reliably or not, so you will need to
107 do some experiments before relying on it for regular work.
107 do some experiments before relying on it for regular work.
108
108
109 A WARNING ABOUT SIGNALS AND THREADS
109 A WARNING ABOUT SIGNALS AND THREADS
110
110
111 When any of the thread systems (GTK, QT or WX) are active, either
111 When any of the thread systems (GTK, QT or WX) are active, either
112 directly or via -pylab with a threaded backend, it is impossible to
112 directly or via -pylab with a threaded backend, it is impossible to
113 interrupt long-running Python code via Ctrl-C. IPython can not pass
113 interrupt long-running Python code via Ctrl-C. IPython can not pass
114 the KeyboardInterrupt exception (or the underlying SIGINT) across
114 the KeyboardInterrupt exception (or the underlying SIGINT) across
115 threads, so any long-running process started from IPython will run to
115 threads, so any long-running process started from IPython will run to
116 completion, or will have to be killed via an external (OS-based)
116 completion, or will have to be killed via an external (OS-based)
117 mechanism.
117 mechanism.
118
118
119 To the best of my knowledge, this limitation is imposed by the Python
119 To the best of my knowledge, this limitation is imposed by the Python
120 interpreter itself, and it comes from the difficulty of writing
120 interpreter itself, and it comes from the difficulty of writing
121 portable signal/threaded code. If any user is an expert on this topic
121 portable signal/threaded code. If any user is an expert on this topic
122 and can suggest a better solution, I would love to hear about it. In
122 and can suggest a better solution, I would love to hear about it. In
123 the IPython sources, look at the Shell.py module, and in particular at
123 the IPython sources, look at the Shell.py module, and in particular at
124 the runcode() method.
124 the runcode() method.
125
125
126 REGULAR OPTIONS
126 REGULAR OPTIONS
127 After the above threading options have been given, regular options can
127 After the above threading options have been given, regular options can
128 follow in any order. All options can be abbreviated to their shortest
128 follow in any order. All options can be abbreviated to their shortest
129 non-ambiguous form and are case-sensitive. One or two dashes can be
129 non-ambiguous form and are case-sensitive. One or two dashes can be
130 used. Some options have an alternate short form, indicated after a |.
130 used. Some options have an alternate short form, indicated after a |.
131
131
132 Most options can also be set from your ipythonrc configuration file.
132 Most options can also be set from your ipythonrc configuration file.
133 See the provided examples for assistance. Options given on the comman-
133 See the provided examples for assistance. Options given on the comman-
134 dline override the values set in the ipythonrc file.
134 dline override the values set in the ipythonrc file.
135
135
136 All options with a [no] prepended can be specified in negated form
136 All options with a [no] prepended can be specified in negated form
137 (using -nooption instead of -option) to turn the feature off.
137 (using -nooption instead of -option) to turn the feature off.
138
138
139 -h, --help
139 -h, --help
140 Show summary of options.
140 Show summary of options.
141
141
142 -pylab This can only be given as the first option passed to IPython (it
142 -pylab This can only be given as the first option passed to IPython (it
143 will have no effect in any other position). It adds special sup-
143 will have no effect in any other position). It adds special sup-
144 port for the matplotlib library (http://matplotlib.source-
144 port for the matplotlib library (http://matplotlib.source-
145 forge.net), allowing interactive usage of any of its backends as
145 forge.net), allowing interactive usage of any of its backends as
146 defined in the user’s .matplotlibrc file. It automatically
146 defined in the user’s .matplotlibrc file. It automatically
147 activates GTK or WX threading for IPyhton if the choice of mat-
147 activates GTK or WX threading for IPyhton if the choice of mat-
148 plotlib backend requires it. It also modifies the @run command
148 plotlib backend requires it. It also modifies the @run command
149 to correctly execute (without blocking) any matplotlib-based
149 to correctly execute (without blocking) any matplotlib-based
150 script which calls show() at the end.
150 script which calls show() at the end.
151
151
152 -autocall <val>
152 -autocall <val>
153 Make IPython automatically call any callable object even if you
153 Make IPython automatically call any callable object even if you
154 didn't type explicit parentheses. For example, 'str 43' becomes
154 didn't type explicit parentheses. For example, 'str 43' becomes
155 'str(43)' automatically. The value can be '0' to disable the
155 'str(43)' automatically. The value can be '0' to disable the
156 feature, '1' for 'smart' autocall, where it is not applied if
156 feature, '1' for 'smart' autocall, where it is not applied if
157 there are no more arguments on the line, and '2' for 'full'
157 there are no more arguments on the line, and '2' for 'full'
158 autocall, where all callable objects are automatically called
158 autocall, where all callable objects are automatically called
159 (even if no arguments are present). The default is '1'.
159 (even if no arguments are present). The default is '1'.
160
160
161 -[no]autoindent
161 -[no]autoindent
162 Turn automatic indentation on/off.
162 Turn automatic indentation on/off.
163
163
164 -[no]automagic
164 -[no]automagic
165 Make magic commands automatic (without needing their first char-
165 Make magic commands automatic (without needing their first char-
166 acter to be %). Type %magic at the IPython prompt for more
166 acter to be %). Type %magic at the IPython prompt for more
167 information.
167 information.
168
168
169 -[no]autoedit_syntax
169 -[no]autoedit_syntax
170 When a syntax error occurs after editing a file, automatically
170 When a syntax error occurs after editing a file, automatically
171 open the file to the trouble causing line for convenient fixing.
171 open the file to the trouble causing line for convenient fixing.
172
172
173 -[no]banner
173 -[no]banner
174 Print the intial information banner (default on).
174 Print the intial information banner (default on).
175
175
176 -c <command>
176 -c <command>
177 Execute the given command string, and set sys.argv to [’c’].
177 Execute the given command string, and set sys.argv to [’c’].
178 This is similar to the -c option in the normal Python inter-
178 This is similar to the -c option in the normal Python inter-
179 preter.
179 preter.
180
180
181 -cache_size|cs <n>
181 -cache_size|cs <n>
182 Size of the output cache (maximum number of entries to hold in
182 Size of the output cache (maximum number of entries to hold in
183 memory). The default is 1000, you can change it permanently in
183 memory). The default is 1000, you can change it permanently in
184 your config file. Setting it to 0 completely disables the
184 your config file. Setting it to 0 completely disables the
185 caching system, and the minimum value accepted is 20 (if you
185 caching system, and the minimum value accepted is 20 (if you
186 provide a value less than 20, it is reset to 0 and a warning is
186 provide a value less than 20, it is reset to 0 and a warning is
187 issued). This limit is defined because otherwise you’ll spend
187 issued). This limit is defined because otherwise you’ll spend
188 more time re-flushing a too small cache than working.
188 more time re-flushing a too small cache than working.
189
189
190 -classic|cl
190 -classic|cl
191 Gives IPython a similar feel to the classic Python prompt.
191 Gives IPython a similar feel to the classic Python prompt.
192
192
193 -colors <scheme>
193 -colors <scheme>
194 Color scheme for prompts and exception reporting. Currently
194 Color scheme for prompts and exception reporting. Currently
195 implemented: NoColor, Linux, and LightBG.
195 implemented: NoColor, Linux, and LightBG.
196
196
197 -[no]color_info
197 -[no]color_info
198 IPython can display information about objects via a set of func-
198 IPython can display information about objects via a set of func-
199 tions, and optionally can use colors for this, syntax highlight-
199 tions, and optionally can use colors for this, syntax highlight-
200 ing source code and various other elements. However, because
200 ing source code and various other elements. However, because
201 this information is passed through a pager (like ’less’) and
201 this information is passed through a pager (like ’less’) and
202 many pagers get confused with color codes, this option is off by
202 many pagers get confused with color codes, this option is off by
203 default. You can test it and turn it on permanently in your
203 default. You can test it and turn it on permanently in your
204 ipythonrc file if it works for you. As a reference, the ’less’
204 ipythonrc file if it works for you. As a reference, the ’less’
205 pager supplied with Mandrake 8.2 works ok, but that in RedHat
205 pager supplied with Mandrake 8.2 works ok, but that in RedHat
206 7.2 doesn’t.
206 7.2 doesn’t.
207
207
208 Test it and turn it on permanently if it works with your system.
208 Test it and turn it on permanently if it works with your system.
209 The magic function @color_info allows you to toggle this inter-
209 The magic function @color_info allows you to toggle this inter-
210 actively for testing.
210 actively for testing.
211
211
212 -[no]confirm_exit
212 -[no]confirm_exit
213 Set to confirm when you try to exit IPython with an EOF (Con-
213 Set to confirm when you try to exit IPython with an EOF (Con-
214 trol-D in Unix, Control-Z/Enter in Windows). Note that using the
214 trol-D in Unix, Control-Z/Enter in Windows). Note that using the
215 magic functions @Exit or @Quit you can force a direct exit,
215 magic functions @Exit or @Quit you can force a direct exit,
216 bypassing any confirmation.
216 bypassing any confirmation.
217
217
218 -[no]debug
218 -[no]debug
219 Show information about the loading process. Very useful to pin
219 Show information about the loading process. Very useful to pin
220 down problems with your configuration files or to get details
220 down problems with your configuration files or to get details
221 about session restores.
221 about session restores.
222
222
223 -[no]deep_reload
223 -[no]deep_reload
224 IPython can use the deep_reload module which reloads changes in
224 IPython can use the deep_reload module which reloads changes in
225 modules recursively (it replaces the reload() function, so you
225 modules recursively (it replaces the reload() function, so you
226 don’t need to change anything to use it). deep_reload() forces a
226 don’t need to change anything to use it). deep_reload() forces a
227 full reload of modules whose code may have changed, which the
227 full reload of modules whose code may have changed, which the
228 default reload() function does not.
228 default reload() function does not.
229
229
230 When deep_reload is off, IPython will use the normal reload(),
230 When deep_reload is off, IPython will use the normal reload(),
231 but deep_reload will still be available as dreload(). This fea-
231 but deep_reload will still be available as dreload(). This fea-
232 ture is off by default [which means that you have both normal
232 ture is off by default [which means that you have both normal
233 reload() and dreload()].
233 reload() and dreload()].
234
234
235 -editor <name>
235 -editor <name>
236 Which editor to use with the @edit command. By default, IPython
236 Which editor to use with the @edit command. By default, IPython
237 will honor your EDITOR environment variable (if not set, vi is
237 will honor your EDITOR environment variable (if not set, vi is
238 the Unix default and notepad the Windows one). Since this editor
238 the Unix default and notepad the Windows one). Since this editor
239 is invoked on the fly by IPython and is meant for editing small
239 is invoked on the fly by IPython and is meant for editing small
240 code snippets, you may want to use a small, lightweight editor
240 code snippets, you may want to use a small, lightweight editor
241 here (in case your default EDITOR is something like Emacs).
241 here (in case your default EDITOR is something like Emacs).
242
242
243 -ipythondir <name>
243 -ipythondir <name>
244 The name of your IPython configuration directory IPYTHONDIR.
244 The name of your IPython configuration directory IPYTHONDIR.
245 This can also be specified through the environment variable
245 This can also be specified through the environment variable
246 IPYTHONDIR.
246 IPYTHONDIR.
247
247
248 -log|l Generate a log file of all input. The file is named
248 -log|l Generate a log file of all input. The file is named
249 ipython_log.py in your current directory (which prevents logs
249 ipython_log.py in your current directory (which prevents logs
250 from multiple IPython sessions from trampling each other). You
250 from multiple IPython sessions from trampling each other). You
251 can use this to later restore a session by loading your logfile
251 can use this to later restore a session by loading your logfile
252 as a file to be executed with option -logplay (see below).
252 as a file to be executed with option -logplay (see below).
253
253
254 -logfile|lf
254 -logfile|lf
255 Specify the name of your logfile.
255 Specify the name of your logfile.
256
256
257 -logplay|lp
257 -logplay|lp
258 Replay a previous log. For restoring a session as close as pos-
258 Replay a previous log. For restoring a session as close as pos-
259 sible to the state you left it in, use this option (don’t just
259 sible to the state you left it in, use this option (don’t just
260 run the logfile). With -logplay, IPython will try to reconstruct
260 run the logfile). With -logplay, IPython will try to reconstruct
261 the previous working environment in full, not just execute the
261 the previous working environment in full, not just execute the
262 commands in the logfile.
262 commands in the logfile.
263 When a session is restored, logging is automatically turned on
263 When a session is restored, logging is automatically turned on
264 again with the name of the logfile it was invoked with (it is
264 again with the name of the logfile it was invoked with (it is
265 read from the log header). So once you’ve turned logging on for
265 read from the log header). So once you’ve turned logging on for
266 a session, you can quit IPython and reload it as many times as
266 a session, you can quit IPython and reload it as many times as
267 you want and it will continue to log its history and restore
267 you want and it will continue to log its history and restore
268 from the beginning every time.
268 from the beginning every time.
269
269
270 Caveats: there are limitations in this option. The history vari-
270 Caveats: there are limitations in this option. The history vari-
271 ables _i*,_* and _dh don’t get restored properly. In the future
271 ables _i*,_* and _dh don’t get restored properly. In the future
272 we will try to implement full session saving by writing and
272 we will try to implement full session saving by writing and
273 retrieving a failed because of inherent limitations of Python’s
273 retrieving a failed because of inherent limitations of Python’s
274 Pickle module, so this may have to wait.
274 Pickle module, so this may have to wait.
275
275
276 -[no]messages
276 -[no]messages
277 Print messages which IPython collects about its startup process
277 Print messages which IPython collects about its startup process
278 (default on).
278 (default on).
279
279
280 -[no]pdb
280 -[no]pdb
281 Automatically call the pdb debugger after every uncaught excep-
281 Automatically call the pdb debugger after every uncaught excep-
282 tion. If you are used to debugging using pdb, this puts you
282 tion. If you are used to debugging using pdb, this puts you
283 automatically inside of it after any call (either in IPython or
283 automatically inside of it after any call (either in IPython or
284 in code called by it) which triggers an exception which goes
284 in code called by it) which triggers an exception which goes
285 uncaught.
285 uncaught.
286
286
287 -[no]pprint
287 -[no]pprint
288 IPython can optionally use the pprint (pretty printer) module
288 IPython can optionally use the pprint (pretty printer) module
289 for displaying results. pprint tends to give a nicer display of
289 for displaying results. pprint tends to give a nicer display of
290 nested data structures. If you like it, you can turn it on per-
290 nested data structures. If you like it, you can turn it on per-
291 manently in your config file (default off).
291 manently in your config file (default off).
292
292
293 -profile|p <name>
293 -profile|p <name>
294 Assume that your config file is ipythonrc-<name> (looks in cur-
294 Assume that your config file is ipythonrc-<name> (looks in cur-
295 rent dir first, then in IPYTHONDIR). This is a quick way to keep
295 rent dir first, then in IPYTHONDIR). This is a quick way to keep
296 and load multiple config files for different tasks, especially
296 and load multiple config files for different tasks, especially
297 if you use the include option of config files. You can keep a
297 if you use the include option of config files. You can keep a
298 basic IPYTHONDIR/ipythonrc file and then have other ’profiles’
298 basic IPYTHONDIR/ipythonrc file and then have other ’profiles’
299 which include this one and load extra things for particular
299 which include this one and load extra things for particular
300 tasks. For example:
300 tasks. For example:
301
301
302 1) $HOME/.ipython/ipythonrc : load basic things you always want.
302 1) $HOME/.ipython/ipythonrc : load basic things you always want.
303 2) $HOME/.ipython/ipythonrc-math : load (1) and basic math-
303 2) $HOME/.ipython/ipythonrc-math : load (1) and basic math-
304 related modules.
304 related modules.
305 3) $HOME/.ipython/ipythonrc-numeric : load (1) and Numeric and
305 3) $HOME/.ipython/ipythonrc-numeric : load (1) and Numeric and
306 plotting modules.
306 plotting modules.
307
307
308 Since it is possible to create an endless loop by having circu-
308 Since it is possible to create an endless loop by having circu-
309 lar file inclusions, IPython will stop if it reaches 15 recur-
309 lar file inclusions, IPython will stop if it reaches 15 recur-
310 sive inclusions.
310 sive inclusions.
311
311
312 -prompt_in1|pi1 <string>
312 -prompt_in1|pi1 <string>
313 Specify the string used for input prompts. Note that if you are
313 Specify the string used for input prompts. Note that if you are
314 using numbered prompts, the number is represented with a ’\#’ in
314 using numbered prompts, the number is represented with a ’\#’ in
315 the string. Don’t forget to quote strings with spaces embedded
315 the string. Don’t forget to quote strings with spaces embedded
316 in them. Default: ’In [\#]:’.
316 in them. Default: ’In [\#]:’.
317
317
318 Most bash-like escapes can be used to customize IPython’s
318 Most bash-like escapes can be used to customize IPython’s
319 prompts, as well as a few additional ones which are IPython-spe-
319 prompts, as well as a few additional ones which are IPython-spe-
320 cific. All valid prompt escapes are described in detail in the
320 cific. All valid prompt escapes are described in detail in the
321 Customization section of the IPython HTML/PDF manual.
321 Customization section of the IPython HTML/PDF manual.
322
322
323 -prompt_in2|pi2 <string>
323 -prompt_in2|pi2 <string>
324 Similar to the previous option, but used for the continuation
324 Similar to the previous option, but used for the continuation
325 prompts. The special sequence ’\D’ is similar to ’\#’, but with
325 prompts. The special sequence ’\D’ is similar to ’\#’, but with
326 all digits replaced dots (so you can have your continuation
326 all digits replaced dots (so you can have your continuation
327 prompt aligned with your input prompt). Default: ’ .\D.:’
327 prompt aligned with your input prompt). Default: ’ .\D.:’
328 (note three spaces at the start for alignment with ’In [\#]’).
328 (note three spaces at the start for alignment with ’In [\#]’).
329
329
330 -prompt_out|po <string>
330 -prompt_out|po <string>
331 String used for output prompts, also uses numbers like
331 String used for output prompts, also uses numbers like
332 prompt_in1. Default: ’Out[\#]:’.
332 prompt_in1. Default: ’Out[\#]:’.
333
333
334 -quick Start in bare bones mode (no config file loaded).
334 -quick Start in bare bones mode (no config file loaded).
335
335
336 -rcfile <name>
336 -rcfile <name>
337 Name of your IPython resource configuration file. normally
337 Name of your IPython resource configuration file. normally
338 IPython loads ipythonrc (from current directory) or
338 IPython loads ipythonrc (from current directory) or
339 IPYTHONDIR/ipythonrc. If the loading of your config file fails,
339 IPYTHONDIR/ipythonrc. If the loading of your config file fails,
340 IPython starts with a bare bones configuration (no modules
340 IPython starts with a bare bones configuration (no modules
341 loaded at all).
341 loaded at all).
342
342
343 -[no]readline
343 -[no]readline
344 Use the readline library, which is needed to support name com-
344 Use the readline library, which is needed to support name com-
345 pletion and command history, among other things. It is enabled
345 pletion and command history, among other things. It is enabled
346 by default, but may cause problems for users of X/Emacs in
346 by default, but may cause problems for users of X/Emacs in
347 Python comint or shell buffers.
347 Python comint or shell buffers.
348
348
349 Note that emacs ’eterm’ buffers (opened with M-x term) support
349 Note that emacs ’eterm’ buffers (opened with M-x term) support
350 IPython’s readline and syntax coloring fine, only ’emacs’ (M-x
350 IPython’s readline and syntax coloring fine, only ’emacs’ (M-x
351 shell and C-c !) buffers do not.
351 shell and C-c !) buffers do not.
352
352
353 -screen_length|sl <n>
353 -screen_length|sl <n>
354 Number of lines of your screen. This is used to control print-
354 Number of lines of your screen. This is used to control print-
355 ing of very long strings. Strings longer than this number of
355 ing of very long strings. Strings longer than this number of
356 lines will be sent through a pager instead of directly printed.
356 lines will be sent through a pager instead of directly printed.
357
357
358 The default value for this is 0, which means IPython will auto-
358 The default value for this is 0, which means IPython will auto-
359 detect your screen size every time it needs to print certain
359 detect your screen size every time it needs to print certain
360 potentially long strings (this doesn’t change the behavior of
360 potentially long strings (this doesn’t change the behavior of
361 the ’print’ keyword, it’s only triggered internally). If for
361 the ’print’ keyword, it’s only triggered internally). If for
362 some reason this isn’t working well (it needs curses support),
362 some reason this isn’t working well (it needs curses support),
363 specify it yourself. Otherwise don’t change the default.
363 specify it yourself. Otherwise don’t change the default.
364
364
365 -separate_in|si <string>
365 -separate_in|si <string>
366 Separator before input prompts. Default ’0.
366 Separator before input prompts. Default ’0.
367
367
368 -separate_out|so <string>
368 -separate_out|so <string>
369 Separator before output prompts. Default: 0 (nothing).
369 Separator before output prompts. Default: 0 (nothing).
370
370
371 -separate_out2|so2 <string>
371 -separate_out2|so2 <string>
372 Separator after output prompts. Default: 0 (nothing).
372 Separator after output prompts. Default: 0 (nothing).
373
373
374 -nosep Shorthand for ’-separate_in 0 -separate_out 0 -separate_out2 0’.
374 -nosep Shorthand for ’-separate_in 0 -separate_out 0 -separate_out2 0’.
375 Simply removes all input/output separators.
375 Simply removes all input/output separators.
376
376
377 -upgrade
377 -upgrade
378 Allows you to upgrade your IPYTHONDIR configuration when you
378 Allows you to upgrade your IPYTHONDIR configuration when you
379 install a new version of IPython. Since new versions may
379 install a new version of IPython. Since new versions may
380 include new command lines options or example files, this copies
380 include new command lines options or example files, this copies
381 updated ipythonrc-type files. However, it backs up (with a .old
381 updated ipythonrc-type files. However, it backs up (with a .old
382 extension) all files which it overwrites so that you can merge
382 extension) all files which it overwrites so that you can merge
383 back any custimizations you might have in your personal files.
383 back any custimizations you might have in your personal files.
384
384
385 -Version
385 -Version
386 Print version information and exit.
386 Print version information and exit.
387
387
388 -wxversion <string>
388 -wxversion <string>
389 Select a specific version of wxPython (used in conjunction with
389 Select a specific version of wxPython (used in conjunction with
390 -wthread). Requires the wxversion module, part of recent
390 -wthread). Requires the wxversion module, part of recent
391 wxPython distributions.
391 wxPython distributions.
392
392
393 -xmode <modename>
393 -xmode <modename>
394 Mode for exception reporting. The valid modes are Plain, Con-
394 Mode for exception reporting. The valid modes are Plain, Con-
395 text, and Verbose.
395 text, and Verbose.
396
396
397 - Plain: similar to python’s normal traceback printing.
397 - Plain: similar to python’s normal traceback printing.
398
398
399 - Context: prints 5 lines of context source code around each
399 - Context: prints 5 lines of context source code around each
400 line in the traceback.
400 line in the traceback.
401
401
402 - Verbose: similar to Context, but additionally prints the vari-
402 - Verbose: similar to Context, but additionally prints the vari-
403 ables currently visible where the exception happened (shortening
403 ables currently visible where the exception happened (shortening
404 their strings if too long). This can potentially be very slow,
404 their strings if too long). This can potentially be very slow,
405 if you happen to have a huge data structure whose string repre-
405 if you happen to have a huge data structure whose string repre-
406 sentation is complex to compute. Your computer may appear to
406 sentation is complex to compute. Your computer may appear to
407 freeze for a while with cpu usage at 100%. If this occurs, you
407 freeze for a while with cpu usage at 100%. If this occurs, you
408 can cancel the traceback with Ctrl-C (maybe hitting it more than
408 can cancel the traceback with Ctrl-C (maybe hitting it more than
409 once).
409 once).
410
410
411
411
412 EMBEDDING
412 EMBEDDING
413 It is possible to start an IPython instance inside your own Python pro-
413 It is possible to start an IPython instance inside your own Python pro-
414 grams. In the documentation example files there are some illustrations
414 grams. In the documentation example files there are some illustrations
415 on how to do this.
415 on how to do this.
416
416
417 This feature allows you to evalutate dynamically the state of your
417 This feature allows you to evalutate dynamically the state of your
418 code, operate with your variables, analyze them, etc. Note however
418 code, operate with your variables, analyze them, etc. Note however
419 that any changes you make to values while in the shell do NOT propagate
419 that any changes you make to values while in the shell do NOT propagate
420 back to the running code, so it is safe to modify your values because
420 back to the running code, so it is safe to modify your values because
421 you won’t break your code in bizarre ways by doing so.
421 you won’t break your code in bizarre ways by doing so.
422 """
422 """
423
423
424 cmd_line_usage = __doc__
424 cmd_line_usage = __doc__
425
425
426 #---------------------------------------------------------------------------
426 #---------------------------------------------------------------------------
427 interactive_usage = """
427 interactive_usage = """
428 IPython -- An enhanced Interactive Python
428 IPython -- An enhanced Interactive Python
429 =========================================
429 =========================================
430
430
431 IPython offers a combination of convenient shell features, special commands
431 IPython offers a combination of convenient shell features, special commands
432 and a history mechanism for both input (command history) and output (results
432 and a history mechanism for both input (command history) and output (results
433 caching, similar to Mathematica). It is intended to be a fully compatible
433 caching, similar to Mathematica). It is intended to be a fully compatible
434 replacement for the standard Python interpreter, while offering vastly
434 replacement for the standard Python interpreter, while offering vastly
435 improved functionality and flexibility.
435 improved functionality and flexibility.
436
436
437 At your system command line, type 'ipython -help' to see the command line
437 At your system command line, type 'ipython -help' to see the command line
438 options available. This document only describes interactive features.
438 options available. This document only describes interactive features.
439
439
440 Warning: IPython relies on the existence of a global variable called __IP which
440 Warning: IPython relies on the existence of a global variable called __IP which
441 controls the shell itself. If you redefine __IP to anything, bizarre behavior
441 controls the shell itself. If you redefine __IP to anything, bizarre behavior
442 will quickly occur.
442 will quickly occur.
443
443
444 MAIN FEATURES
444 MAIN FEATURES
445
445
446 * Access to the standard Python help. As of Python 2.1, a help system is
446 * Access to the standard Python help. As of Python 2.1, a help system is
447 available with access to object docstrings and the Python manuals. Simply
447 available with access to object docstrings and the Python manuals. Simply
448 type 'help' (no quotes) to access it.
448 type 'help' (no quotes) to access it.
449
449
450 * Magic commands: type %magic for information on the magic subsystem.
450 * Magic commands: type %magic for information on the magic subsystem.
451
451
452 * System command aliases, via the %alias command or the ipythonrc config file.
452 * System command aliases, via the %alias command or the ipythonrc config file.
453
453
454 * Dynamic object information:
454 * Dynamic object information:
455
455
456 Typing ?word or word? prints detailed information about an object. If
456 Typing ?word or word? prints detailed information about an object. If
457 certain strings in the object are too long (docstrings, code, etc.) they get
457 certain strings in the object are too long (docstrings, code, etc.) they get
458 snipped in the center for brevity.
458 snipped in the center for brevity.
459
459
460 Typing ??word or word?? gives access to the full information without
460 Typing ??word or word?? gives access to the full information without
461 snipping long strings. Long strings are sent to the screen through the less
461 snipping long strings. Long strings are sent to the screen through the less
462 pager if longer than the screen, printed otherwise.
462 pager if longer than the screen, printed otherwise.
463
463
464 The ?/?? system gives access to the full source code for any object (if
464 The ?/?? system gives access to the full source code for any object (if
465 available), shows function prototypes and other useful information.
465 available), shows function prototypes and other useful information.
466
466
467 If you just want to see an object's docstring, type '%pdoc object' (without
467 If you just want to see an object's docstring, type '%pdoc object' (without
468 quotes, and without % if you have automagic on).
468 quotes, and without % if you have automagic on).
469
469
470 Both %pdoc and ?/?? give you access to documentation even on things which are
470 Both %pdoc and ?/?? give you access to documentation even on things which are
471 not explicitely defined. Try for example typing {}.get? or after import os,
471 not explicitely defined. Try for example typing {}.get? or after import os,
472 type os.path.abspath??. The magic functions %pdef, %source and %file operate
472 type os.path.abspath??. The magic functions %pdef, %source and %file operate
473 similarly.
473 similarly.
474
474
475 * Completion in the local namespace, by typing TAB at the prompt.
475 * Completion in the local namespace, by typing TAB at the prompt.
476
476
477 At any time, hitting tab will complete any available python commands or
477 At any time, hitting tab will complete any available python commands or
478 variable names, and show you a list of the possible completions if there's
478 variable names, and show you a list of the possible completions if there's
479 no unambiguous one. It will also complete filenames in the current directory.
479 no unambiguous one. It will also complete filenames in the current directory.
480
480
481 This feature requires the readline and rlcomplete modules, so it won't work
481 This feature requires the readline and rlcomplete modules, so it won't work
482 if your Python lacks readline support (such as under Windows).
482 if your Python lacks readline support (such as under Windows).
483
483
484 * Search previous command history in two ways (also requires readline):
484 * Search previous command history in two ways (also requires readline):
485
485
486 - Start typing, and then use Ctrl-p (previous,up) and Ctrl-n (next,down) to
486 - Start typing, and then use Ctrl-p (previous,up) and Ctrl-n (next,down) to
487 search through only the history items that match what you've typed so
487 search through only the history items that match what you've typed so
488 far. If you use Ctrl-p/Ctrl-n at a blank prompt, they just behave like
488 far. If you use Ctrl-p/Ctrl-n at a blank prompt, they just behave like
489 normal arrow keys.
489 normal arrow keys.
490
490
491 - Hit Ctrl-r: opens a search prompt. Begin typing and the system searches
491 - Hit Ctrl-r: opens a search prompt. Begin typing and the system searches
492 your history for lines that match what you've typed so far, completing as
492 your history for lines that match what you've typed so far, completing as
493 much as it can.
493 much as it can.
494
494
495 * Persistent command history across sessions (readline required).
495 * Persistent command history across sessions (readline required).
496
496
497 * Logging of input with the ability to save and restore a working session.
497 * Logging of input with the ability to save and restore a working session.
498
498
499 * System escape with !. Typing !ls will run 'ls' in the current directory.
499 * System escape with !. Typing !ls will run 'ls' in the current directory.
500
500
501 * The reload command does a 'deep' reload of a module: changes made to the
501 * The reload command does a 'deep' reload of a module: changes made to the
502 module since you imported will actually be available without having to exit.
502 module since you imported will actually be available without having to exit.
503
503
504 * Verbose and colored exception traceback printouts. See the magic xmode and
504 * Verbose and colored exception traceback printouts. See the magic xmode and
505 xcolor functions for details (just type %magic).
505 xcolor functions for details (just type %magic).
506
506
507 * Input caching system:
507 * Input caching system:
508
508
509 IPython offers numbered prompts (In/Out) with input and output caching. All
509 IPython offers numbered prompts (In/Out) with input and output caching. All
510 input is saved and can be retrieved as variables (besides the usual arrow
510 input is saved and can be retrieved as variables (besides the usual arrow
511 key recall).
511 key recall).
512
512
513 The following GLOBAL variables always exist (so don't overwrite them!):
513 The following GLOBAL variables always exist (so don't overwrite them!):
514 _i: stores previous input.
514 _i: stores previous input.
515 _ii: next previous.
515 _ii: next previous.
516 _iii: next-next previous.
516 _iii: next-next previous.
517 _ih : a list of all input _ih[n] is the input from line n.
517 _ih : a list of all input _ih[n] is the input from line n.
518
518
519 Additionally, global variables named _i<n> are dynamically created (<n>
519 Additionally, global variables named _i<n> are dynamically created (<n>
520 being the prompt counter), such that _i<n> == _ih[<n>]
520 being the prompt counter), such that _i<n> == _ih[<n>]
521
521
522 For example, what you typed at prompt 14 is available as _i14 and _ih[14].
522 For example, what you typed at prompt 14 is available as _i14 and _ih[14].
523
523
524 You can create macros which contain multiple input lines from this history,
524 You can create macros which contain multiple input lines from this history,
525 for later re-execution, with the %macro function.
525 for later re-execution, with the %macro function.
526
526
527 The history function %hist allows you to see any part of your input history
527 The history function %hist allows you to see any part of your input history
528 by printing a range of the _i variables. Note that inputs which contain
528 by printing a range of the _i variables. Note that inputs which contain
529 magic functions (%) appear in the history with a prepended comment. This is
529 magic functions (%) appear in the history with a prepended comment. This is
530 because they aren't really valid Python code, so you can't exec them.
530 because they aren't really valid Python code, so you can't exec them.
531
531
532 * Output caching system:
532 * Output caching system:
533
533
534 For output that is returned from actions, a system similar to the input
534 For output that is returned from actions, a system similar to the input
535 cache exists but using _ instead of _i. Only actions that produce a result
535 cache exists but using _ instead of _i. Only actions that produce a result
536 (NOT assignments, for example) are cached. If you are familiar with
536 (NOT assignments, for example) are cached. If you are familiar with
537 Mathematica, IPython's _ variables behave exactly like Mathematica's %
537 Mathematica, IPython's _ variables behave exactly like Mathematica's %
538 variables.
538 variables.
539
539
540 The following GLOBAL variables always exist (so don't overwrite them!):
540 The following GLOBAL variables always exist (so don't overwrite them!):
541 _ (one underscore): previous output.
541 _ (one underscore): previous output.
542 __ (two underscores): next previous.
542 __ (two underscores): next previous.
543 ___ (three underscores): next-next previous.
543 ___ (three underscores): next-next previous.
544
544
545 Global variables named _<n> are dynamically created (<n> being the prompt
545 Global variables named _<n> are dynamically created (<n> being the prompt
546 counter), such that the result of output <n> is always available as _<n>.
546 counter), such that the result of output <n> is always available as _<n>.
547
547
548 Finally, a global dictionary named _oh exists with entries for all lines
548 Finally, a global dictionary named _oh exists with entries for all lines
549 which generated output.
549 which generated output.
550
550
551 * Directory history:
551 * Directory history:
552
552
553 Your history of visited directories is kept in the global list _dh, and the
553 Your history of visited directories is kept in the global list _dh, and the
554 magic %cd command can be used to go to any entry in that list.
554 magic %cd command can be used to go to any entry in that list.
555
555
556 * Auto-parentheses and auto-quotes (adapted from Nathan Gray's LazyPython)
556 * Auto-parentheses and auto-quotes (adapted from Nathan Gray's LazyPython)
557
557
558 1. Auto-parentheses
558 1. Auto-parentheses
559 Callable objects (i.e. functions, methods, etc) can be invoked like
559 Callable objects (i.e. functions, methods, etc) can be invoked like
560 this (notice the commas between the arguments):
560 this (notice the commas between the arguments):
561 >>> callable_ob arg1, arg2, arg3
561 >>> callable_ob arg1, arg2, arg3
562 and the input will be translated to this:
562 and the input will be translated to this:
563 --> callable_ob(arg1, arg2, arg3)
563 --> callable_ob(arg1, arg2, arg3)
564 You can force auto-parentheses by using '/' as the first character
564 You can force auto-parentheses by using '/' as the first character
565 of a line. For example:
565 of a line. For example:
566 >>> /globals # becomes 'globals()'
566 >>> /globals # becomes 'globals()'
567 Note that the '/' MUST be the first character on the line! This
567 Note that the '/' MUST be the first character on the line! This
568 won't work:
568 won't work:
569 >>> print /globals # syntax error
569 >>> print /globals # syntax error
570
570
571 In most cases the automatic algorithm should work, so you should
571 In most cases the automatic algorithm should work, so you should
572 rarely need to explicitly invoke /. One notable exception is if you
572 rarely need to explicitly invoke /. One notable exception is if you
573 are trying to call a function with a list of tuples as arguments (the
573 are trying to call a function with a list of tuples as arguments (the
574 parenthesis will confuse IPython):
574 parenthesis will confuse IPython):
575 In [1]: zip (1,2,3),(4,5,6) # won't work
575 In [1]: zip (1,2,3),(4,5,6) # won't work
576 but this will work:
576 but this will work:
577 In [2]: /zip (1,2,3),(4,5,6)
577 In [2]: /zip (1,2,3),(4,5,6)
578 ------> zip ((1,2,3),(4,5,6))
578 ------> zip ((1,2,3),(4,5,6))
579 Out[2]= [(1, 4), (2, 5), (3, 6)]
579 Out[2]= [(1, 4), (2, 5), (3, 6)]
580
580
581 IPython tells you that it has altered your command line by
581 IPython tells you that it has altered your command line by
582 displaying the new command line preceded by -->. e.g.:
582 displaying the new command line preceded by -->. e.g.:
583 In [18]: callable list
583 In [18]: callable list
584 -------> callable (list)
584 -------> callable (list)
585
585
586 2. Auto-Quoting
586 2. Auto-Quoting
587 You can force auto-quoting of a function's arguments by using ',' as
587 You can force auto-quoting of a function's arguments by using ',' as
588 the first character of a line. For example:
588 the first character of a line. For example:
589 >>> ,my_function /home/me # becomes my_function("/home/me")
589 >>> ,my_function /home/me # becomes my_function("/home/me")
590
590
591 If you use ';' instead, the whole argument is quoted as a single
591 If you use ';' instead, the whole argument is quoted as a single
592 string (while ',' splits on whitespace):
592 string (while ',' splits on whitespace):
593 >>> ,my_function a b c # becomes my_function("a","b","c")
593 >>> ,my_function a b c # becomes my_function("a","b","c")
594 >>> ;my_function a b c # becomes my_function("a b c")
594 >>> ;my_function a b c # becomes my_function("a b c")
595
595
596 Note that the ',' MUST be the first character on the line! This
596 Note that the ',' MUST be the first character on the line! This
597 won't work:
597 won't work:
598 >>> x = ,my_function /home/me # syntax error
598 >>> x = ,my_function /home/me # syntax error
599 """
599 """
600
600
601 quick_reference = r"""
601 quick_reference = r"""
602 IPython -- An enhanced Interactive Python - Quick Reference Card
602 IPython -- An enhanced Interactive Python - Quick Reference Card
603 ================================================================
603 ================================================================
604
604
605 obj?, obj??, ?obj,??obj : Get help, or more help for object
605 obj?, obj??, ?obj,??obj : Get help, or more help for object
606 ?os.p* : List names in os starting with p
606 ?os.p* : List names in os starting with p
607
607
608 Example magic:
608 Example magic:
609
609
610 %alias d ls -F : 'd' is now an alias for 'ls -F'
610 %alias d ls -F : 'd' is now an alias for 'ls -F'
611 alias d ls -F : Works if 'alias' not a python name
611 alias d ls -F : Works if 'alias' not a python name
612 alist = %alias : Get list of aliases to 'alist'
612 alist = %alias : Get list of aliases to 'alist'
613
613
614 System commands:
614 System commands:
615
615
616 !cp a.txt b/ : System command escape, calls os.system()
616 !cp a.txt b/ : System command escape, calls os.system()
617 cp a.txt b/ : after %rehash, most system commands work without !
617 cp a.txt b/ : after %rehashx, most system commands work without !
618 cp ${f}.txt $bar : Variable expansion in magics and system commands
618 cp ${f}.txt $bar : Variable expansion in magics and system commands
619 files = ls /usr : Capture sytem command output
619 files = !ls /usr : Capture sytem command output
620 files.s, files.l, files.n: "a b c", ['a','b','c'], 'a\nb\nc'
620 files.s, files.l, files.n: "a b c", ['a','b','c'], 'a\nb\nc'
621 cd /usr/share : Obvious, also 'cd d:\home\_ipython' works
621 cd /usr/share : Obvious, also 'cd d:\home\_ipython' works
622
622
623 History:
623 History:
624
624
625 _i, _ii, _iii : Previous, next previous, next next previous input
625 _i, _ii, _iii : Previous, next previous, next next previous input
626 _ih[4], _ih[2:5] : Input history line 4, lines 2-4
626 _ih[4], _ih[2:5] : Input history line 4, lines 2-4
627 _, __, ___ : previous, next previous, next next previous output
627 _, __, ___ : previous, next previous, next next previous output
628 _dh : Directory history
628 _dh : Directory history
629 _oh : Output history
629 _oh : Output history
630 %hist : Command history
630 %hist : Command history
631
631
632 Autocall:
632 Autocall:
633
633
634 f 1 2 : f(1,2)
634 f 1,2 : f(1,2)
635 /f 1,2 : f(1,2) (forced autoparen)
635 ,f 1 2 : f("1","2")
636 ,f 1 2 : f("1","2")
636 ;f 1 2 : f("1 2")
637 ;f 1 2 : f("1 2")
637
638
638 """
639 """
639
640
640
641
General Comments 0
You need to be logged in to leave comments. Login now