ipython.1
391 lines
| 16.1 KiB
| application/x-troff
|
GroffLexer
/ doc / ipython.1
Ville M. Vainio
|
r1032 | .\" Hey, EMACS: -*- nroff -*- | ||
.\" First parameter, NAME, should be all caps | ||||
.\" Second parameter, SECTION, should be 1-8, maybe w/ subsection | ||||
.\" other parameters are allowed: see man(7), man(1) | ||||
.TH IPYTHON 1 "November 30, 2004" | ||||
.\" Please adjust this date whenever revising the manpage. | ||||
.\" | ||||
.\" Some roff macros, for reference: | ||||
.\" .nh disable hyphenation | ||||
.\" .hy enable hyphenation | ||||
.\" .ad l left justify | ||||
.\" .ad b justify to both left and right margins | ||||
.\" .nf disable filling | ||||
.\" .fi enable filling | ||||
.\" .br insert line break | ||||
.\" .sp <n> insert n+1 empty lines | ||||
.\" for manpage-specific macros, see man(7) and groff_man(7) | ||||
.\" .SH section heading | ||||
.\" .SS secondary section heading | ||||
.\" | ||||
.\" | ||||
.\" To preview this page as plain text: nroff -man ipython.1 | ||||
.\" | ||||
.SH NAME | ||||
ipython \- An Enhanced Interactive Python | ||||
.SH SYNOPSIS | ||||
.B ipython | ||||
.RI [ options ] " files" ... | ||||
.SH DESCRIPTION | ||||
An interactive Python shell with automatic history (input and output), | ||||
dynamic object introspection, easier configuration, command | ||||
completion, access to the system shell, integration with numerical and | ||||
scientific computing tools, and more. | ||||
.SH SPECIAL THREADING OPTIONS | ||||
The following special options are ONLY valid at the beginning of the command | ||||
line, and not later. This is because they control the initialization of | ||||
ipython itself, before the normal option-handling mechanism is active. | ||||
.TP | ||||
.B \-gthread, \-qthread, \-q4thread, \-wthread, \-pylab | ||||
Only ONE of these can be given, and it can only be given as the first option | ||||
passed to IPython (it will have no effect in any other position). They provide | ||||
threading support for the GTK, QT3, QT4 and WXWidgets toolkits, and for the | ||||
matplotlib library. | ||||
.br | ||||
.sp 1 | ||||
With any of the first four options, IPython starts running a separate thread | ||||
for the graphical toolkit's operation, so that you can open and control | ||||
graphical elements from within an IPython command line, without blocking. All | ||||
four provide essentially the same functionality, respectively for GTK, QT3, QT4 | ||||
and WXWidgets (via their Python interfaces). | ||||
.br | ||||
.sp 1 | ||||
Note that with \-wthread, you can additionally use the \-wxversion option to | ||||
request a specific version of wx to be used. This requires that you have the | ||||
'wxversion' Python module installed, which is part of recent wxPython | ||||
distributions. | ||||
.br | ||||
.sp 1 | ||||
If \-pylab is given, IPython loads special support for the matplotlib library | ||||
(http://matplotlib.sourceforge.net), allowing interactive usage of any of its | ||||
backends as defined in the user's .matplotlibrc file. It automatically | ||||
activates GTK, QT or WX threading for IPyhton if the choice of matplotlib | ||||
backend requires it. It also modifies the %run command to correctly execute | ||||
(without blocking) any matplotlib-based script which calls show() at the end. | ||||
.TP | ||||
.B \-tk | ||||
The \-g/q/q4/wthread options, and \-pylab (if matplotlib is configured to use | ||||
GTK, QT or WX), will normally block Tk graphical interfaces. This means that | ||||
when GTK, QT or WX threading is active, any attempt to open a Tk GUI will | ||||
result in a dead window, and possibly cause the Python interpreter to crash. | ||||
An extra option, \-tk, is available to address this issue. It can ONLY be | ||||
given as a SECOND option after any of the above (\-gthread, \-qthread, | ||||
\-wthread or \-pylab). | ||||
.br | ||||
.sp 1 | ||||
If \-tk is given, IPython will try to coordinate Tk threading with GTK, QT or | ||||
WX. This is however potentially unreliable, and you will have to test on your | ||||
platform and Python configuration to determine whether it works for you. | ||||
Debian users have reported success, apparently due to the fact that Debian | ||||
builds all of Tcl, Tk, Tkinter and Python with pthreads support. Under other | ||||
Linux environments (such as Fedora Core 2), this option has caused random | ||||
crashes and lockups of the Python interpreter. Under other operating systems | ||||
(Mac OSX and Windows), you'll need to try it to find out, since currently no | ||||
user reports are available. | ||||
.br | ||||
.sp 1 | ||||
There is unfortunately no way for IPython to determine at runtime whether \-tk | ||||
will work reliably or not, so you will need to do some experiments before | ||||
relying on it for regular work. | ||||
. | ||||
.SH REGULAR OPTIONS | ||||
After the above threading options have been given, regular options can follow | ||||
in any order. All options can be abbreviated to their shortest non-ambiguous | ||||
form and are case-sensitive. One or two dashes can be used. Some options | ||||
have an alternate short form, indicated after a |. | ||||
.br | ||||
.sp 1 | ||||
Most options can also be set from your ipythonrc configuration file. | ||||
See the provided examples for assistance. Options given on the | ||||
commandline override the values set in the ipythonrc file. | ||||
.br | ||||
.sp 1 | ||||
All options with a [no] prepended can be specified in negated form | ||||
(\-nooption instead of \-option) to turn the feature off. | ||||
.TP | ||||
.B \-h, \-\-help | ||||
Show summary of options. | ||||
.TP | ||||
.B \-autocall <val> | ||||
Make IPython automatically call any callable object even if you didn't type | ||||
explicit parentheses. For example, 'str 43' becomes | ||||
'str(43)' automatically. The value can be '0' to disable the | ||||
feature, '1' for 'smart' autocall, where it is not applied if | ||||
there are no more arguments on the line, and '2' for 'full' | ||||
autocall, where all callable objects are automatically called | ||||
(even if no arguments are present). The default is '1'. | ||||
.TP | ||||
.B \-[no]autoindent | ||||
Turn automatic indentation on/off. | ||||
.TP | ||||
.B \-[no]automagic | ||||
Make magic commands automatic (without needing their first character | ||||
to be %). Type %magic at the IPython prompt for more information. | ||||
.TP | ||||
.B \-[no]autoedit_syntax | ||||
When a syntax error occurs after editing a file, automatically open the file | ||||
to the trouble causing line for convenient fixing. | ||||
.TP | ||||
.B \-[no]banner | ||||
Print the intial information banner (default on). | ||||
.TP | ||||
.B \-c <command> | ||||
Execute the given command string, and set sys.argv to ['c']. This is similar | ||||
to the \-c option in the normal Python interpreter. | ||||
.TP | ||||
.B \-cache_size|cs <n> | ||||
Size of the output cache (maximum number of entries to hold in | ||||
memory). The default is 1000, you can change it permanently in your | ||||
config file. Setting it to 0 completely disables the caching system, | ||||
and the minimum value accepted is 20 (if you provide a value less than | ||||
20, it is reset to 0 and a warning is issued). This limit is defined | ||||
because otherwise you'll spend more time re-flushing a too small cache | ||||
than working. | ||||
.TP | ||||
.B \-classic|cl | ||||
Gives IPython a similar feel to the classic Python prompt. | ||||
.TP | ||||
.B \-colors <scheme> | ||||
Color scheme for prompts and exception reporting. Currently | ||||
implemented: NoColor, Linux, and LightBG. | ||||
.TP | ||||
.B \-[no]color_info | ||||
IPython can display information about objects via a set of functions, | ||||
and optionally can use colors for this, syntax highlighting source | ||||
code and various other elements. However, because this information is | ||||
passed through a pager (like 'less') and many pagers get confused with | ||||
color codes, this option is off by default. You can test it and turn | ||||
it on permanently in your ipythonrc file if it works for you. As a | ||||
reference, the 'less' pager supplied with Mandrake 8.2 works ok, but | ||||
that in RedHat 7.2 doesn't. | ||||
.br | ||||
.sp 1 | ||||
Test it and turn it on permanently if it works with your system. The | ||||
magic function @color_info allows you to toggle this interactively for | ||||
testing. | ||||
.TP | ||||
.B \-[no]confirm_exit | ||||
Set to confirm when you try to exit IPython with an EOF (Control-D in | ||||
Unix, Control-Z/Enter in Windows). Note that using the magic functions | ||||
@Exit or @Quit you can force a direct exit, bypassing any | ||||
confirmation. | ||||
.TP | ||||
.B \-[no]debug | ||||
Show information about the loading process. Very useful to pin down | ||||
problems with your configuration files or to get details about session | ||||
restores. | ||||
.TP | ||||
.B \-[no]deep_reload | ||||
IPython can use the deep_reload module which reloads changes in | ||||
modules recursively (it replaces the reload() function, so you don't | ||||
need to change anything to use it). deep_reload() forces a full reload | ||||
of modules whose code may have changed, which the default reload() | ||||
function does not. | ||||
.br | ||||
.sp 1 | ||||
When deep_reload is off, IPython will use the normal reload(), but | ||||
deep_reload will still be available as dreload(). This feature is off | ||||
by default [which means that you have both normal reload() and | ||||
dreload()]. | ||||
.TP | ||||
.B \-editor <name> | ||||
Which editor to use with the @edit command. By default, IPython will | ||||
honor your EDITOR environment variable (if not set, vi is the Unix | ||||
default and notepad the Windows one). Since this editor is invoked on | ||||
the fly by IPython and is meant for editing small code snippets, you | ||||
may want to use a small, lightweight editor here (in case your default | ||||
EDITOR is something like Emacs). | ||||
.TP | ||||
.B \-ipythondir <name> | ||||
The name of your IPython configuration directory IPYTHONDIR. This can | ||||
also be specified through the environment variable IPYTHONDIR. | ||||
.TP | ||||
.B \-log|l | ||||
Generate a log file of all input. The file is named ipython_log.py in your | ||||
current directory (which prevents logs from multiple IPython sessions from | ||||
trampling each other). You can use this to later restore a session by loading | ||||
your logfile as a file to be executed with option -logplay (see below). | ||||
.TP | ||||
.B \-logfile|lf | ||||
Specify the name of your logfile. | ||||
.TP | ||||
.B \-logplay|lp | ||||
Replay a previous log. For restoring a session as close as possible to | ||||
the state you left it in, use this option (don't just run the | ||||
logfile). With \-logplay, IPython will try to reconstruct the previous | ||||
working environment in full, not just execute the commands in the | ||||
logfile. | ||||
.br | ||||
.sh 1 | ||||
When a session is restored, logging is automatically turned on again | ||||
with the name of the logfile it was invoked with (it is read from the | ||||
log header). So once you've turned logging on for a session, you can | ||||
quit IPython and reload it as many times as you want and it will | ||||
continue to log its history and restore from the beginning every time. | ||||
.br | ||||
.sp 1 | ||||
Caveats: there are limitations in this option. The history variables | ||||
_i*,_* and _dh don't get restored properly. In the future we will try | ||||
to implement full session saving by writing and retrieving a | ||||
'snapshot' of the memory state of IPython. But our first attempts | ||||
failed because of inherent limitations of Python's Pickle module, so | ||||
this may have to wait. | ||||
.TP | ||||
.B \-[no]messages | ||||
Print messages which IPython collects about its startup process | ||||
(default on). | ||||
.TP | ||||
.B \-[no]pdb | ||||
Automatically call the pdb debugger after every uncaught exception. If | ||||
you are used to debugging using pdb, this puts you automatically | ||||
inside of it after any call (either in IPython or in code called by | ||||
it) which triggers an exception which goes uncaught. | ||||
.TP | ||||
.B \-[no]pprint | ||||
IPython can optionally use the pprint (pretty printer) module for | ||||
displaying results. pprint tends to give a nicer display of nested | ||||
data structures. If you like it, you can turn it on permanently in | ||||
your config file (default off). | ||||
.TP | ||||
.B \-profile|p <name> | ||||
Assume that your config file is ipythonrc-<name> (looks in current dir | ||||
first, then in IPYTHONDIR). This is a quick way to keep and load | ||||
multiple config files for different tasks, especially if you use the | ||||
include option of config files. You can keep a basic | ||||
IPYTHONDIR/ipythonrc file and then have other 'profiles' which include | ||||
this one and load extra things for particular tasks. For example: | ||||
.br | ||||
.sp 1 | ||||
1) $HOME/.ipython/ipythonrc : load basic things you always want. | ||||
.br | ||||
2) $HOME/.ipython/ipythonrc-math : load (1) and basic math-related | ||||
modules. | ||||
.br | ||||
3) $HOME/.ipython/ipythonrc-numeric : load (1) and Numeric and | ||||
plotting modules. | ||||
.br | ||||
.sp 1 | ||||
Since it is possible to create an endless loop by having circular file | ||||
inclusions, IPython will stop if it reaches 15 recursive inclusions. | ||||
.TP | ||||
.B \-prompt_in1|pi1 <string> | ||||
Specify the string used for input prompts. Note that if you are using | ||||
numbered prompts, the number is represented with a '\\#' in the | ||||
string. Don't forget to quote strings with spaces embedded in | ||||
them. Default: 'In [\\#]: '. | ||||
.br | ||||
.sp 1 | ||||
Most bash-like escapes can be used to customize IPython's prompts, as well as | ||||
a few additional ones which are IPython-specific. All valid prompt escapes | ||||
are described in detail in the Customization section of the IPython HTML/PDF | ||||
manual. | ||||
.TP | ||||
.B \-prompt_in2|pi2 <string> | ||||
Similar to the previous option, but used for the continuation prompts. The | ||||
special sequence '\\D' is similar to '\\#', but with all digits replaced dots | ||||
(so you can have your continuation prompt aligned with your input | ||||
prompt). Default: ' .\\D.: ' (note three spaces at the start for alignment | ||||
with 'In [\\#]'). | ||||
.TP | ||||
.B \-prompt_out|po <string> | ||||
String used for output prompts, also uses numbers like prompt_in1. | ||||
Default: 'Out[\\#]:'. | ||||
.TP | ||||
.B \-quick | ||||
Start in bare bones mode (no config file loaded). | ||||
.TP | ||||
.B \-rcfile <name> | ||||
Name of your IPython resource configuration file. normally IPython | ||||
loads ipythonrc (from current directory) or IPYTHONDIR/ipythonrc. If | ||||
the loading of your config file fails, IPython starts with a bare | ||||
bones configuration (no modules loaded at all). | ||||
.TP | ||||
.B \-[no]readline | ||||
Use the readline library, which is needed to support name completion | ||||
and command history, among other things. It is enabled by default, but | ||||
may cause problems for users of X/Emacs in Python comint or shell | ||||
buffers. | ||||
.br | ||||
.sp 1 | ||||
Note that emacs 'eterm' buffers (opened with M-x term) support | ||||
IPython's readline and syntax coloring fine, only 'emacs' (M-x shell | ||||
and C-c !) buffers do not. | ||||
.TP | ||||
.B \-screen_length|sl <n> | ||||
Number of lines of your screen. This is used to control printing of | ||||
very long strings. Strings longer than this number of lines will be | ||||
sent through a pager instead of directly printed. | ||||
.br | ||||
.sp 1 | ||||
The default value for this is 0, which means IPython will auto-detect | ||||
your screen size every time it needs to print certain potentially long | ||||
strings (this doesn't change the behavior of the 'print' keyword, it's | ||||
only triggered internally). If for some reason this isn't working well | ||||
(it needs curses support), specify it yourself. Otherwise don't change | ||||
the default. | ||||
.TP | ||||
.B \-separate_in|si <string> | ||||
Separator before input prompts. Default '\n'. | ||||
.TP | ||||
.B \-separate_out|so <string> | ||||
Separator before output prompts. Default: 0 (nothing). | ||||
.TP | ||||
.B \-separate_out2|so2 <string> | ||||
Separator after output prompts. Default: 0 (nothing). | ||||
.TP | ||||
.B \-nosep | ||||
Shorthand for '\-separate_in 0 \-separate_out 0 \-separate_out2 0'. | ||||
Simply removes all input/output separators. | ||||
.TP | ||||
.B \-upgrade | ||||
Allows you to upgrade your IPYTHONDIR configuration when you install a | ||||
new version of IPython. Since new versions may include new command | ||||
lines options or example files, this copies updated ipythonrc-type | ||||
files. However, it backs up (with a .old extension) all files which | ||||
it overwrites so that you can merge back any custimizations you might | ||||
have in your personal files. | ||||
.TP | ||||
.B \-Version | ||||
Print version information and exit. | ||||
.TP | ||||
.B -wxversion <string> | ||||
Select a specific version of wxPython (used in conjunction with | ||||
\-wthread). Requires the wxversion module, part of recent wxPython | ||||
distributions. | ||||
.TP | ||||
.B \-xmode <modename> | ||||
Mode for exception reporting. The valid modes are Plain, Context, and | ||||
Verbose. | ||||
.br | ||||
.sp 1 | ||||
\- Plain: similar to python's normal traceback printing. | ||||
.br | ||||
.sp 1 | ||||
\- Context: prints 5 lines of context source code around each line in the | ||||
traceback. | ||||
.br | ||||
.sp 1 | ||||
\- Verbose: similar to Context, but additionally prints the variables | ||||
currently visible where the exception happened (shortening their strings if | ||||
too long). This can potentially be very slow, if you happen to have a huge | ||||
data structure whose string representation is complex to compute. Your | ||||
computer may appear to freeze for a while with cpu usage at 100%. If this | ||||
occurs, you can cancel the traceback with Ctrl-C (maybe hitting it more than | ||||
once). | ||||
. | ||||
.SH EMBEDDING | ||||
It is possible to start an IPython instance inside your own Python | ||||
programs. In the documentation example files there are some | ||||
illustrations on how to do this. | ||||
.br | ||||
.sp 1 | ||||
This feature allows you to evalutate dynamically the state of your | ||||
code, operate with your variables, analyze them, etc. Note however | ||||
that any changes you make to values while in the shell do NOT | ||||
propagate back to the running code, so it is safe to modify your | ||||
values because you won't break your code in bizarre ways by doing so. | ||||
.SH AUTHOR | ||||
IPython was written by Fernando Perez <fperez@colorado.edu>, based on earlier | ||||
code by Janko Hauser <jh@comunit.de> and Nathaniel Gray | ||||
<n8gray@caltech.edu>. This manual page was written by Jack Moffitt | ||||
<jack@xiph.org>, for the Debian project (but may be used by others). | ||||