##// END OF EJS Templates
apply ondrej's man page patch to clean up lintian checks
Ville M. Vainio -
Show More
@@ -1,395 +1,395 b''
1 1 .\" Hey, EMACS: -*- nroff -*-
2 2 .\" First parameter, NAME, should be all caps
3 3 .\" Second parameter, SECTION, should be 1-8, maybe w/ subsection
4 4 .\" other parameters are allowed: see man(7), man(1)
5 5 .TH IPYTHON 1 "November 30, 2004"
6 6 .\" Please adjust this date whenever revising the manpage.
7 7 .\"
8 8 .\" Some roff macros, for reference:
9 9 .\" .nh disable hyphenation
10 10 .\" .hy enable hyphenation
11 11 .\" .ad l left justify
12 12 .\" .ad b justify to both left and right margins
13 13 .\" .nf disable filling
14 14 .\" .fi enable filling
15 15 .\" .br insert line break
16 16 .\" .sp <n> insert n+1 empty lines
17 17 .\" for manpage-specific macros, see man(7) and groff_man(7)
18 18 .\" .SH section heading
19 19 .\" .SS secondary section heading
20 20 .\"
21 21 .\"
22 22 .\" To preview this page as plain text: nroff -man ipython.1
23 23 .\"
24 24 .SH NAME
25 25 ipython \- An Enhanced Interactive Python
26 26 .SH SYNOPSIS
27 27 .B ipython
28 28 .RI [ options ] " files" ...
29 29 .SH DESCRIPTION
30 30 An interactive Python shell with automatic history (input and output),
31 31 dynamic object introspection, easier configuration, command
32 32 completion, access to the system shell, integration with numerical and
33 33 scientific computing tools, and more.
34 34 .SH SPECIAL THREADING OPTIONS
35 35 The following special options are ONLY valid at the beginning of the command
36 36 line, and not later. This is because they control the initialization of
37 37 ipython itself, before the normal option-handling mechanism is active.
38 38 .TP
39 39 .B \-gthread, \-qthread, \-q4thread, \-wthread, \-pylab
40 40 Only ONE of these can be given, and it can only be given as the first option
41 41 passed to IPython (it will have no effect in any other position). They provide
42 42 threading support for the GTK, QT3, QT4 and WXWidgets toolkits, for the
43 43 matplotlib library and Twisted reactor.
44 44 .br
45 45 .sp 1
46 46 With any of the first four options, IPython starts running a separate thread
47 47 for the graphical toolkit's operation, so that you can open and control
48 48 graphical elements from within an IPython command line, without blocking. All
49 49 four provide essentially the same functionality, respectively for GTK, QT3, QT4
50 50 and WXWidgets (via their Python interfaces).
51 51 .br
52 52 .sp 1
53 53 Note that with \-wthread, you can additionally use the \-wxversion option to
54 54 request a specific version of wx to be used. This requires that you have the
55 'wxversion' Python module installed, which is part of recent wxPython
55 wxversion Python module installed, which is part of recent wxPython
56 56 distributions.
57 57 .br
58 58 .sp 1
59 59 If \-pylab is given, IPython loads special support for the matplotlib library
60 60 (http://matplotlib.sourceforge.net), allowing interactive usage of any of its
61 61 backends as defined in the user's .matplotlibrc file. It automatically
62 62 activates GTK, QT or WX threading for IPyhton if the choice of matplotlib
63 63 backend requires it. It also modifies the %run command to correctly execute
64 64 (without blocking) any matplotlib-based script which calls show() at the end.
65 65 .TP
66 66 .B \-tk
67 67 The \-g/q/q4/wthread options, and \-pylab (if matplotlib is configured to use
68 68 GTK, QT or WX), will normally block Tk graphical interfaces. This means that
69 69 when GTK, QT or WX threading is active, any attempt to open a Tk GUI will
70 70 result in a dead window, and possibly cause the Python interpreter to crash.
71 71 An extra option, \-tk, is available to address this issue. It can ONLY be
72 72 given as a SECOND option after any of the above (\-gthread, \-qthread,
73 73 \-wthread or \-pylab).
74 74 .br
75 75 .sp 1
76 76 If \-tk is given, IPython will try to coordinate Tk threading with GTK, QT or
77 77 WX. This is however potentially unreliable, and you will have to test on your
78 78 platform and Python configuration to determine whether it works for you.
79 79 Debian users have reported success, apparently due to the fact that Debian
80 80 builds all of Tcl, Tk, Tkinter and Python with pthreads support. Under other
81 81 Linux environments (such as Fedora Core 2), this option has caused random
82 82 crashes and lockups of the Python interpreter. Under other operating systems
83 83 (Mac OSX and Windows), you'll need to try it to find out, since currently no
84 84 user reports are available.
85 85 .br
86 86 .sp 1
87 87 There is unfortunately no way for IPython to determine at runtime whether \-tk
88 88 will work reliably or not, so you will need to do some experiments before
89 89 relying on it for regular work.
90 90 .
91 91 .SH REGULAR OPTIONS
92 92 After the above threading options have been given, regular options can follow
93 93 in any order. All options can be abbreviated to their shortest non-ambiguous
94 94 form and are case-sensitive. One or two dashes can be used. Some options
95 95 have an alternate short form, indicated after a |.
96 96 .br
97 97 .sp 1
98 98 Most options can also be set from your ipythonrc configuration file.
99 99 See the provided examples for assistance. Options given on the
100 100 commandline override the values set in the ipythonrc file.
101 101 .br
102 102 .sp 1
103 103 All options with a [no] prepended can be specified in negated form
104 104 (\-nooption instead of \-option) to turn the feature off.
105 105 .TP
106 106 .B \-h, \-\-help
107 107 Show summary of options.
108 108 .TP
109 109 .B \-autocall <val>
110 110 Make IPython automatically call any callable object even if you didn't type
111 111 explicit parentheses. For example, 'str 43' becomes
112 'str(43)' automatically. The value can be '0' to disable the
112 str(43) automatically. The value can be '0' to disable the
113 113 feature, '1' for 'smart' autocall, where it is not applied if
114 114 there are no more arguments on the line, and '2' for 'full'
115 115 autocall, where all callable objects are automatically called
116 116 (even if no arguments are present). The default is '1'.
117 117 .TP
118 118 .B \-[no]autoindent
119 119 Turn automatic indentation on/off.
120 120 .TP
121 121 .B \-[no]automagic
122 122 Make magic commands automatic (without needing their first character
123 123 to be %). Type %magic at the IPython prompt for more information.
124 124 .TP
125 125 .B \-[no]autoedit_syntax
126 126 When a syntax error occurs after editing a file, automatically open the file
127 127 to the trouble causing line for convenient fixing.
128 128 .TP
129 129 .B \-[no]banner
130 130 Print the intial information banner (default on).
131 131 .TP
132 132 .B \-c <command>
133 133 Execute the given command string, and set sys.argv to ['c']. This is similar
134 134 to the \-c option in the normal Python interpreter.
135 135 .TP
136 136 .B \-cache_size|cs <n>
137 137 Size of the output cache (maximum number of entries to hold in
138 138 memory). The default is 1000, you can change it permanently in your
139 139 config file. Setting it to 0 completely disables the caching system,
140 140 and the minimum value accepted is 20 (if you provide a value less than
141 141 20, it is reset to 0 and a warning is issued). This limit is defined
142 142 because otherwise you'll spend more time re-flushing a too small cache
143 143 than working.
144 144 .TP
145 145 .B \-classic|cl
146 146 Gives IPython a similar feel to the classic Python prompt.
147 147 .TP
148 148 .B \-colors <scheme>
149 149 Color scheme for prompts and exception reporting. Currently
150 150 implemented: NoColor, Linux, and LightBG.
151 151 .TP
152 152 .B \-[no]color_info
153 153 IPython can display information about objects via a set of functions,
154 154 and optionally can use colors for this, syntax highlighting source
155 155 code and various other elements. However, because this information is
156 156 passed through a pager (like 'less') and many pagers get confused with
157 157 color codes, this option is off by default. You can test it and turn
158 158 it on permanently in your ipythonrc file if it works for you. As a
159 159 reference, the 'less' pager supplied with Mandrake 8.2 works ok, but
160 160 that in RedHat 7.2 doesn't.
161 161 .br
162 162 .sp 1
163 163 Test it and turn it on permanently if it works with your system. The
164 164 magic function @color_info allows you to toggle this interactively for
165 165 testing.
166 166 .TP
167 167 .B \-[no]confirm_exit
168 168 Set to confirm when you try to exit IPython with an EOF (Control-D in
169 169 Unix, Control-Z/Enter in Windows). Note that using the magic functions
170 170 @Exit or @Quit you can force a direct exit, bypassing any
171 171 confirmation.
172 172 .TP
173 173 .B \-[no]debug
174 174 Show information about the loading process. Very useful to pin down
175 175 problems with your configuration files or to get details about session
176 176 restores.
177 177 .TP
178 178 .B \-[no]deep_reload
179 179 IPython can use the deep_reload module which reloads changes in
180 180 modules recursively (it replaces the reload() function, so you don't
181 181 need to change anything to use it). deep_reload() forces a full reload
182 182 of modules whose code may have changed, which the default reload()
183 183 function does not.
184 184 .br
185 185 .sp 1
186 186 When deep_reload is off, IPython will use the normal reload(), but
187 187 deep_reload will still be available as dreload(). This feature is off
188 188 by default [which means that you have both normal reload() and
189 189 dreload()].
190 190 .TP
191 191 .B \-editor <name>
192 192 Which editor to use with the @edit command. By default, IPython will
193 193 honor your EDITOR environment variable (if not set, vi is the Unix
194 194 default and notepad the Windows one). Since this editor is invoked on
195 195 the fly by IPython and is meant for editing small code snippets, you
196 196 may want to use a small, lightweight editor here (in case your default
197 197 EDITOR is something like Emacs).
198 198 .TP
199 199 .B \-ipythondir <name>
200 200 The name of your IPython configuration directory IPYTHONDIR. This can
201 201 also be specified through the environment variable IPYTHONDIR.
202 202 .TP
203 203 .B \-log|l
204 204 Generate a log file of all input. The file is named ipython_log.py in your
205 205 current directory (which prevents logs from multiple IPython sessions from
206 206 trampling each other). You can use this to later restore a session by loading
207 207 your logfile as a file to be executed with option -logplay (see below).
208 208 .TP
209 209 .B \-logfile|lf
210 210 Specify the name of your logfile.
211 211 .TP
212 212 .B \-logplay|lp
213 213 Replay a previous log. For restoring a session as close as possible to
214 214 the state you left it in, use this option (don't just run the
215 215 logfile). With \-logplay, IPython will try to reconstruct the previous
216 216 working environment in full, not just execute the commands in the
217 217 logfile.
218 218 .br
219 .sh 1
219 .sp 1
220 220 When a session is restored, logging is automatically turned on again
221 221 with the name of the logfile it was invoked with (it is read from the
222 222 log header). So once you've turned logging on for a session, you can
223 223 quit IPython and reload it as many times as you want and it will
224 224 continue to log its history and restore from the beginning every time.
225 225 .br
226 226 .sp 1
227 227 Caveats: there are limitations in this option. The history variables
228 228 _i*,_* and _dh don't get restored properly. In the future we will try
229 229 to implement full session saving by writing and retrieving a
230 'snapshot' of the memory state of IPython. But our first attempts
230 snapshot of the memory state of IPython. But our first attempts
231 231 failed because of inherent limitations of Python's Pickle module, so
232 232 this may have to wait.
233 233 .TP
234 234 .B \-[no]messages
235 235 Print messages which IPython collects about its startup process
236 236 (default on).
237 237 .TP
238 238 .B \-[no]pdb
239 239 Automatically call the pdb debugger after every uncaught exception. If
240 240 you are used to debugging using pdb, this puts you automatically
241 241 inside of it after any call (either in IPython or in code called by
242 242 it) which triggers an exception which goes uncaught.
243 243 .TP
244 244 .B \-pydb
245 245 Makes IPython use the third party "pydb" package as debugger,
246 246 instead of pdb. Requires that pydb is installed.
247 247 .TP
248 248 .B \-[no]pprint
249 249 IPython can optionally use the pprint (pretty printer) module for
250 250 displaying results. pprint tends to give a nicer display of nested
251 251 data structures. If you like it, you can turn it on permanently in
252 252 your config file (default off).
253 253 .TP
254 254 .B \-profile|p <name>
255 255 Assume that your config file is ipythonrc-<name> (looks in current dir
256 256 first, then in IPYTHONDIR). This is a quick way to keep and load
257 257 multiple config files for different tasks, especially if you use the
258 258 include option of config files. You can keep a basic
259 259 IPYTHONDIR/ipythonrc file and then have other 'profiles' which include
260 260 this one and load extra things for particular tasks. For example:
261 261 .br
262 262 .sp 1
263 263 1) $HOME/.ipython/ipythonrc : load basic things you always want.
264 264 .br
265 265 2) $HOME/.ipython/ipythonrc-math : load (1) and basic math-related
266 266 modules.
267 267 .br
268 268 3) $HOME/.ipython/ipythonrc-numeric : load (1) and Numeric and
269 269 plotting modules.
270 270 .br
271 271 .sp 1
272 272 Since it is possible to create an endless loop by having circular file
273 273 inclusions, IPython will stop if it reaches 15 recursive inclusions.
274 274 .TP
275 275 .B \-prompt_in1|pi1 <string>
276 276 Specify the string used for input prompts. Note that if you are using
277 277 numbered prompts, the number is represented with a '\\#' in the
278 278 string. Don't forget to quote strings with spaces embedded in
279 279 them. Default: 'In [\\#]: '.
280 280 .br
281 281 .sp 1
282 282 Most bash-like escapes can be used to customize IPython's prompts, as well as
283 283 a few additional ones which are IPython-specific. All valid prompt escapes
284 284 are described in detail in the Customization section of the IPython HTML/PDF
285 285 manual.
286 286 .TP
287 287 .B \-prompt_in2|pi2 <string>
288 288 Similar to the previous option, but used for the continuation prompts. The
289 289 special sequence '\\D' is similar to '\\#', but with all digits replaced dots
290 290 (so you can have your continuation prompt aligned with your input
291 291 prompt). Default: ' .\\D.: ' (note three spaces at the start for alignment
292 292 with 'In [\\#]').
293 293 .TP
294 294 .B \-prompt_out|po <string>
295 295 String used for output prompts, also uses numbers like prompt_in1.
296 296 Default: 'Out[\\#]:'.
297 297 .TP
298 298 .B \-quick
299 299 Start in bare bones mode (no config file loaded).
300 300 .TP
301 301 .B \-rcfile <name>
302 302 Name of your IPython resource configuration file. normally IPython
303 303 loads ipythonrc (from current directory) or IPYTHONDIR/ipythonrc. If
304 304 the loading of your config file fails, IPython starts with a bare
305 305 bones configuration (no modules loaded at all).
306 306 .TP
307 307 .B \-[no]readline
308 308 Use the readline library, which is needed to support name completion
309 309 and command history, among other things. It is enabled by default, but
310 310 may cause problems for users of X/Emacs in Python comint or shell
311 311 buffers.
312 312 .br
313 313 .sp 1
314 314 Note that emacs 'eterm' buffers (opened with M-x term) support
315 315 IPython's readline and syntax coloring fine, only 'emacs' (M-x shell
316 316 and C-c !) buffers do not.
317 317 .TP
318 318 .B \-screen_length|sl <n>
319 319 Number of lines of your screen. This is used to control printing of
320 320 very long strings. Strings longer than this number of lines will be
321 321 sent through a pager instead of directly printed.
322 322 .br
323 323 .sp 1
324 324 The default value for this is 0, which means IPython will auto-detect
325 325 your screen size every time it needs to print certain potentially long
326 326 strings (this doesn't change the behavior of the 'print' keyword, it's
327 327 only triggered internally). If for some reason this isn't working well
328 328 (it needs curses support), specify it yourself. Otherwise don't change
329 329 the default.
330 330 .TP
331 331 .B \-separate_in|si <string>
332 332 Separator before input prompts. Default '\n'.
333 333 .TP
334 334 .B \-separate_out|so <string>
335 335 Separator before output prompts. Default: 0 (nothing).
336 336 .TP
337 337 .B \-separate_out2|so2 <string>
338 338 Separator after output prompts. Default: 0 (nothing).
339 339 .TP
340 340 .B \-nosep
341 341 Shorthand for '\-separate_in 0 \-separate_out 0 \-separate_out2 0'.
342 342 Simply removes all input/output separators.
343 343 .TP
344 344 .B \-upgrade
345 345 Allows you to upgrade your IPYTHONDIR configuration when you install a
346 346 new version of IPython. Since new versions may include new command
347 347 lines options or example files, this copies updated ipythonrc-type
348 348 files. However, it backs up (with a .old extension) all files which
349 349 it overwrites so that you can merge back any custimizations you might
350 350 have in your personal files.
351 351 .TP
352 352 .B \-Version
353 353 Print version information and exit.
354 354 .TP
355 355 .B -wxversion <string>
356 356 Select a specific version of wxPython (used in conjunction with
357 357 \-wthread). Requires the wxversion module, part of recent wxPython
358 358 distributions.
359 359 .TP
360 360 .B \-xmode <modename>
361 361 Mode for exception reporting. The valid modes are Plain, Context, and
362 362 Verbose.
363 363 .br
364 364 .sp 1
365 365 \- Plain: similar to python's normal traceback printing.
366 366 .br
367 367 .sp 1
368 368 \- Context: prints 5 lines of context source code around each line in the
369 369 traceback.
370 370 .br
371 371 .sp 1
372 372 \- Verbose: similar to Context, but additionally prints the variables
373 373 currently visible where the exception happened (shortening their strings if
374 374 too long). This can potentially be very slow, if you happen to have a huge
375 375 data structure whose string representation is complex to compute. Your
376 376 computer may appear to freeze for a while with cpu usage at 100%. If this
377 377 occurs, you can cancel the traceback with Ctrl-C (maybe hitting it more than
378 378 once).
379 379 .
380 380 .SH EMBEDDING
381 381 It is possible to start an IPython instance inside your own Python
382 382 programs. In the documentation example files there are some
383 383 illustrations on how to do this.
384 384 .br
385 385 .sp 1
386 386 This feature allows you to evalutate dynamically the state of your
387 387 code, operate with your variables, analyze them, etc. Note however
388 388 that any changes you make to values while in the shell do NOT
389 389 propagate back to the running code, so it is safe to modify your
390 390 values because you won't break your code in bizarre ways by doing so.
391 391 .SH AUTHOR
392 392 IPython was written by Fernando Perez <fperez@colorado.edu>, based on earlier
393 393 code by Janko Hauser <jh@comunit.de> and Nathaniel Gray
394 394 <n8gray@caltech.edu>. This manual page was written by Jack Moffitt
395 395 <jack@xiph.org>, for the Debian project (but may be used by others).
General Comments 0
You need to be logged in to leave comments. Login now