|
|
.\" 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, \-twisted
|
|
|
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, for the
|
|
|
matplotlib library and Twisted reactor.
|
|
|
.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 \-twisted is given, IPython start a Twisted reactor and runs IPython mainloop
|
|
|
in a dedicated thread, passing commands to be run inside the Twisted reactor.
|
|
|
.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).
|
|
|
|
