root/ipython/branches/tzanko/doc/manual_base.lyx

#LyX 1.3 created this file. For more info see http://www.lyx.org/
\lyxformat 221
\textclass article
\begin_preamble
\usepackage{ae,aecompl}
\usepackage{hyperref}
\usepackage{html}
\end_preamble
\language english
\inputencoding latin1
\fontscheme default
\graphics default
\paperfontsize default
\spacing single 
\papersize Default
\paperpackage a4
\use_geometry 1
\use_amsmath 0
\use_natbib 0
\use_numerical_citations 0
\paperorientation portrait
\leftmargin 1.25in
\topmargin 1in
\rightmargin 1.25in
\bottommargin 1in
\secnumdepth 3
\tocdepth 3
\paragraph_separation skip
\defskip medskip
\quotes_language english
\quotes_times 2
\papercolumns 1
\papersides 1
\paperpagestyle fancy

\layout Title

IPython
\newline 

\size larger 
An enhanced Interactive Python
\size large 

\newline 
User Manual, v.
 __version__
\layout Author

Fernando Pérez
\layout Standard


\begin_inset ERT
status Collapsed

\layout Standard

\backslash 
latex{
\end_inset 


\begin_inset LatexCommand \tableofcontents{}

\end_inset 


\begin_inset ERT
status Collapsed

\layout Standard
}
\end_inset 


\layout Standard


\begin_inset ERT
status Open

\layout Standard

\backslash 
html{
\backslash 
bodytext{bgcolor=#ffffff}}
\end_inset 


\layout Section
\pagebreak_top 
Overview
\layout Standard

One of Python's most useful features is its interactive interpreter.
 This system allows very fast testing of ideas without the overhead of creating
 test files as is typical in most programming languages.
 However, the interpreter supplied with the standard Python distribution
 is somewhat limited for extended interactive use.
\layout Standard

IPython is a free software project (released under the BSD license) which
 tries to:
\layout Enumerate

Provide an interactive shell superior to Python's default.
 IPython has many features for object introspection, system shell access,
 and its own special command system for adding functionality when working
 interactively.
 It tries to be a very efficient environment both for Python code development
 and for exploration of problems using Python objects (in situations like
 data analysis).
\layout Enumerate

Serve as an embeddable, ready to use interpreter for your own programs.
 IPython can be started with a single call from inside another program,
 providing access to the current namespace.
 This can be very useful both for debugging purposes and for situations
 where a blend of batch-processing and interactive exploration are needed.
\layout Enumerate

Offer a flexible framework which can be used as the base environment for
 other systems with Python as the underlying language.
 Specifically scientific environments like Mathematica, IDL and Matlab inspired
 its design, but similar ideas can be useful in many fields.
\layout Subsection

Main features
\layout Itemize

Dynamic object introspection.
 One can access docstrings, function definition prototypes, source code,
 source files and other details of any object accessible to the interpreter
 with a single keystroke (`
\family typewriter 
?
\family default 
').
\layout Itemize

Completion in the local namespace, by typing TAB at the prompt.
 This works for keywords, methods, variables and files in the current directory.
 This is supported via the readline library, and full access to configuring
 readline's behavior is provided.
\layout Itemize

Numbered input/output prompts with command history (persistent across sessions
 and tied to each profile), full searching in this history and caching of
 all input and output.
\layout Itemize

User-extensible `magic' commands.
 A set of commands prefixed with 
\family typewriter 
%
\family default 
 is available for controlling IPython itself and provides directory control,
 namespace information and many aliases to common system shell commands.
\layout Itemize

Alias facility for defining your own system aliases.
\layout Itemize

Complete system shell access.
 Lines starting with ! are passed directly to the system shell, and using
 !! captures shell output into python variables for further use.
\layout Itemize

All calls to the system (via aliases or via !) have their standard output/error
 automatically stored as strings, and also available as lists.
\layout Itemize

Background execution of Python commands in a separate thread.
 IPython has an internal job manager called 
\family typewriter 
jobs
\family default 
, and a conveninence backgrounding magic function called 
\family typewriter 
%bg
\family default 
.
\layout Itemize

The ability to expand python variables when calling the system shell.
 In a shell command, any python variable prefixed with 
\family typewriter 
$
\family default 
 is expanded.
 A double 
\family typewriter 
$$
\family default 
 allows passing a literal 
\family typewriter 
$
\family default 
 to the shell (for access to shell and environment variables like 
\family typewriter 
$PATH
\family default 
).
\layout Itemize

Filesystem navigation, via a magic 
\family typewriter 
%cd
\family default 
 command, along with a persistent bookmark system (using 
\family typewriter 
%bookmark
\family default 
) for fast access to frequently visited directories.
\layout Itemize

Automatic indentation (optional) of code as you type (through the readline
 library).
\layout Itemize

Macro system for quickly re-executing multiple lines of previous input with
 a single name.
\layout Itemize

Session logging (you can then later use these logs as code in your programs).
\layout Itemize

Session restoring: logs can be replayed to restore a previous session to
 the state where you left it.
\layout Itemize

Verbose and colored exception traceback printouts.
 Easier to parse visually, and in verbose mode they produce a lot of useful
 debugging information (basically a terminal version of the cgitb module).
\layout Itemize

Auto-parentheses: callable objects can be executed without parentheses:
 
\family typewriter 
`sin 3'
\family default 
 is automatically converted to 
\family typewriter 
`sin(3)
\family default 
'.
\layout Itemize

Auto-quoting: using `
\family typewriter 
,
\family default 
' or `
\family typewriter 
;
\family default 
' as the first character forces auto-quoting of the rest of the line: 
\family typewriter 
`,my_function a\SpecialChar ~
b'
\family default 
 becomes automatically 
\family typewriter 
`my_function("a","b")'
\family default 
, while 
\family typewriter 
`;my_function a\SpecialChar ~
b'
\family default 
 becomes 
\family typewriter 
`my_function("a b")'
\family default 
.
\layout Itemize

Extensible input syntax.
 You can define filters that pre-process user input to simplify input in
 special situations.
 This allows for example pasting multi-line code fragments which start with
 
\family typewriter 
`>>>'
\family default 
 or 
\family typewriter 
`...'
\family default 
 such as those from other python sessions or the standard Python documentation.
\layout Itemize

Flexible configuration system.
 It uses a configuration file which allows permanent setting of all command-line
 options, module loading, code and file execution.
 The system allows recursive file inclusion, so you can have a base file
 with defaults and layers which load other customizations for particular
 projects.
\layout Itemize

Embeddable.
 You can call IPython as a python shell inside your own python programs.
 This can be used both for debugging code or for providing interactive abilities
 to your programs with knowledge about the local namespaces (very useful
 in debugging and data analysis situations).
\layout Itemize

Easy debugger access.
 You can set IPython to call up the Python debugger (pdb) every time there
 is an uncaught exception.
 This drops you inside the code which triggered the exception with all the
 data live and it is possible to navigate the stack to rapidly isolate the
 source of a bug.
 The 
\family typewriter 
%run
\family default 
 magic command --with the 
\family typewriter 
-d
\family default 
 option-- can run any script under 
\family typewriter 
pdb
\family default 
's control, automatically setting initial breakpoints for you.
\layout Itemize

Profiler support.
 You can run single statements (similar to 
\family typewriter 
profile.run()
\family default 
) or complete programs under the profiler's control.
 While this is possible with the standard 
\family typewriter 
profile
\family default 
 module, IPython wraps this functionality with magic commands (see 
\family typewriter 
`%prun'
\family default 
 and 
\family typewriter 
`%run -p
\family default 
') convenient for rapid interactive work.
\layout Subsection

Portability and Python requirements
\layout Standard


\series bold 
Python requirements: 
\series default 
IPython works with Python version 2.2 or newer.
 It has been tested with Python 2.4 and no problems have been reported.
 Support for Python 2.1 hasn't been recently tested, since I don't have access
 to it on any of my systems.
 But I suspect there may be some problems with Python 2.1, because some of
 the newer code may use 2.2 features.
\layout Standard

IPython is developed under 
\series bold 
Linux
\series default 
, but it should work in any reasonable Unix-type system (tested OK under
 Solaris and the *BSD family, for which a port exists thanks to Dryice Liu).
\layout Standard


\series bold 
Mac OS X
\series default 
: it works, apparently without any problems (thanks to Jim Boyle at Lawrence
 Livermore for the information).
 Thanks to Andrea Riciputi, Fink support is available.
\layout Standard


\series bold 
CygWin
\series default 
: it works mostly OK, though some users have reported problems with prompt
 coloring.
 No satisfactory solution to this has been found so far, you may want to
 disable colors permanently in the 
\family typewriter 
ipythonrc
\family default 
 configuration file if you experience problems.
 If you have proper color support under cygwin, please post to the IPython
 mailing list so this issue can be resolved for all users.
\layout Standard


\series bold 
Windows
\series default 
: it works well under Windows XP/2k, and I suspect NT should behave similarly.
 Section\SpecialChar ~

\begin_inset LatexCommand \ref{sub:Under-Windows}

\end_inset 

 describes installation details for Windows, including some additional tools
 needed on this platform.
\layout Standard

Windows 9x support is present, and has been reported to work fine (at least
 on WinME).
\layout Standard

Please note, however, that I have very little access to and experience with
 Windows development.
 For this reason, Windows-specific bugs tend to linger far longer than I
 would like, and often I just can't find a satisfactory solution.
 If any Windows user wants to join in with development help, all hands are
 always welcome.
\layout Subsection

Location
\layout Standard

IPython is generously hosted at 
\begin_inset LatexCommand \htmlurl{http://ipython.scipy.org}

\end_inset 

 by the SciPy project.
 This site offers downloads, CVS access, mailing lists and a bug tracking
 system.
 I am very grateful to Enthought (
\begin_inset LatexCommand \htmlurl{http://www.enthought.com}

\end_inset 

) and all of the SciPy team for their contribution.
\layout Section


\begin_inset LatexCommand \label{sec:install}

\end_inset 

Installation
\layout Subsection

Instant instructions
\layout Standard

If you are of the impatient kind, under Linux/Unix simply untar/unzip the
 download, then install with 
\family typewriter 
`python setup.py install'
\family default 
.
 Under Windows, double-click on the provided 
\family typewriter 
.exe
\family default 
 binary installer.
\layout Standard

Then, take a look at Sections 
\begin_inset LatexCommand \ref{sec:good_config}

\end_inset 

 for configuring things optimally and 
\begin_inset LatexCommand \ref{sec:quick_tips}

\end_inset 

 for quick tips on efficient use of IPython.
 You can later refer to the rest of the manual for all the gory details.
\layout Standard

See the notes in sec.
 
\begin_inset LatexCommand \ref{sec:upgrade}

\end_inset 

 for upgrading IPython versions.
\layout Subsection

Detailed Unix instructions (Linux, Mac OS X, etc.)
\layout Standard


\begin_inset ERT
status Open

\layout Standard

\backslash 
html{ 
\backslash 
textbf{A warning to readers of the HTML version of this manual}: all options below are preceded with with TWO dashes and no intervening space between the dashes (e.g. Dash-Dash-home). The default HTML conversion tools mangle these into a single dash.}
\end_inset 


\layout Standard

For RPM based systems, simply install the supplied package in the usual
 manner.
 If you download the tar archive, the process is:
\layout Enumerate

Unzip/untar the 
\family typewriter 
ipython-XXX.tar.gz
\family default 
 file wherever you want (
\family typewriter 
XXX
\family default 
 is the version number).
 It will make a directory called 
\family typewriter 
ipython-XXX.
 
\family default 
Change into that directory where you will find the files 
\family typewriter 
README
\family default 
 and 
\family typewriter 
setup.py
\family default 
.

\family typewriter 
 O
\family default 
nce you've completed the installation, you can safely remove this directory.
 
\layout Enumerate

If you are installing over a previous installation of version 0.2.0 or earlier,
 first remove your 
\family typewriter 
$HOME/.ipython
\family default 
 directory, since the configuration file format has changed somewhat (the
 '=' were removed from all option specifications).
 Or you can call ipython with the 
\family typewriter 
-upgrade
\family default 
 option and it will do this automatically for you.
\layout Enumerate

IPython uses distutils, so you can install it by simply typing at the system
 prompt (don't type the 
\family typewriter 
$
\family default 
)
\newline 

\family typewriter 
$ python setup.py install
\family default 

\newline 
Note that this assumes you have root access to your machine.
 If you don't have root access or don't want IPython to go in the default
 python directories, you'll need to use the 
\family typewriter 
--home
\family default 
 option (or 
\family typewriter 
--prefix
\family default 
).
 For example:
\newline 

\family typewriter 
$ python setup.py install --home $HOME/local
\family default 

\newline 
will install
\begin_inset Foot
collapsed true

\layout Standard

If you are reading these instructions in HTML format, please note that the
 option is --home, with 
\emph on 
two
\emph default 
 dashes.
 The automatic HTML conversion program seems to eat up one of the dashes,
 unfortunately (it's ok in the PDF version).
\end_inset 

 IPython into 
\family typewriter 
$HOME/local 
\family default 
and its subdirectories (creating them if necessary).
\newline 
You can type
\newline 

\family typewriter 
$ python setup.py --help
\family default 

\newline 
for more details.
\newline 
Note that if you change the default location for 
\family typewriter 
--home
\family default 
 at installation, IPython may end up installed at a location which is not
 part of your 
\family typewriter 
$PYTHONPATH
\family default 
 environment variable.
 In this case, you'll need to configure this variable to include the actual
 directory where the 
\family typewriter 
IPython/
\family default 
 directory ended (typically the value you give to 
\family typewriter 
--home
\family default 
 plus 
\family typewriter 
/lib/python
\family default 
).
\layout Subsubsection

Mac OSX information
\layout Subsubsection*

GUI problems
\layout Standard

The following instructions apply to an install of IPython under OSX from
 unpacking the 
\family typewriter 
.tar.gz
\family default 
 distribution and installing it for the default Python interpreter shipped
 by Apple.
 If you are using a fink install, fink will take care of these details for
 you, by installing IPython against fink's Python.
\layout Standard

IPython offers various forms of support for interacting with graphical applicati
ons from the command line, from simple Tk apps (which are in principle always
 supported by Python) to interactive control of WX, QT and GTK apps.
 Under OSX, however, this requires that ipython is installed by calling
 the special 
\family typewriter 
pythonw
\family default 
 script at installation time, which takes care of coordinating things with
 Apple's graphical environment.
\layout Standard

So when installing under OSX, it is best to use the following command
\begin_inset ERT
status Collapsed

\layout Standard

\backslash 
html{ 
\backslash 
emph{[Again, in the HTML manual, the option is called -~-install=scripts, with TWO dashes and no intervening space between the dashes]}}
\end_inset 

:
\family typewriter 

\newline 
\SpecialChar ~
\SpecialChar ~
$ sudo pythonw setup.py install --install-scripts=/usr/local/bin
\family default 

\newline 
or
\family typewriter 

\newline 
\SpecialChar ~
\SpecialChar ~
$ sudo pythonw setup.py install --install-scripts=/usr/bin
\newline 

\family default 
depending on where you like to keep hand-installed executables.
\layout Standard

The resulting script will have an appropriate shebang line (the first line
 in the script whic begins with 
\family typewriter 
#!...
\family default 
) such that the ipython interpreter can interact with the OS X GUI.
 If the installed version does not work and has a shebang line that points
 to, for example, just 
\family typewriter 
/usr/bin/python
\family default 
, then you might have a stale, cached version in your 
\family typewriter 
build/scripts-<python-version>
\family default 
 directory.
 Delete that directory and rerun the 
\family typewriter 
setup.py
\family default 
.
 
\layout Standard

It is also a good idea to use the special flag 
\family typewriter 
--install-scripts
\family default 
 as indicated above, to ensure that the ipython scripts end up in a location
 which is part of your 
\family typewriter 
$PATH
\family default 
.
 Otherwise Apple's Python will put the scripts in an internal directory
 not available by default at the command line (if you use 
\family typewriter 
/usr/local/bin
\family default 
, you need to make sure this is in your 
\family typewriter 
$PATH
\family default 
, which may not be true by default).
\layout Subsubsection*

Readline problems
\layout Standard

By default, the Python version shipped by Apple does 
\emph on 
not
\emph default 
 include the readline library, so central to IPython's behavior.
 If you install IPython against Apple's Python, you will not have arrow
 keys, tab completion, etc.
 For Mac OSX 10.3 (Panther), you can find a prebuilt readline library here:
\newline 

\begin_inset LatexCommand \htmlurl{http://pythonmac.org/packages/readline-5.0-py2.3-macosx10.3.zip}

\end_inset 

 
\layout Standard

At this point I don't know of such a released version for OSX 10.4 (Tiger),
 or if the problem even occurs with Tiger at all (feedback welcome).
\layout Standard

Users installing against fink's Python or a properly hand-built one should
 not have this problem.
\layout Subsection


\begin_inset LatexCommand \label{sub:Under-Windows}

\end_inset 

Windows instructions
\layout Standard

While you can use IPython under Windows with only a stock Python installation,
 there is one extension, 
\family typewriter 
readline
\family default 
, which will make the whole experience a lot more pleasant.
 It is almost a requirement, since IPython will complain in its absence
 (though it will function).
 
\layout Standard

The
\family typewriter 
 readline
\family default 
 extension needs two other libraries to work, so in all you need:
\layout Enumerate


\family typewriter 
PyWin32
\family default 
 from 
\begin_inset LatexCommand \htmlurl{http://starship.python.net/crew/mhammond}

\end_inset 

.
\layout Enumerate


\family typewriter 
CTypes
\family default 
 from 
\begin_inset LatexCommand \htmlurl{http://starship.python.net/crew/theller/ctypes}

\end_inset 

 (you 
\emph on 
must
\emph default 
 use version 0.9.1 or newer).
\layout Enumerate


\family typewriter 
Readline
\family default 
 for Windows from 
\begin_inset LatexCommand \htmlurl{http://sourceforge.net/projects/uncpythontools}

\end_inset 

.
\layout Standard


\series bold 
Warning about a broken readline-like library:
\series default 
 several users have reported problems stemming from using the pseudo-readline
 library at 
\begin_inset LatexCommand \htmlurl{http://newcenturycomputers.net/projects/readline.html}

\end_inset 

.
 This is a broken library which, while called readline, only implements
 an incomplete subset of the readline API.
 Since it is still called readline, it fools IPython's detection mechanisms
 and causes unpredictable crashes later.
 If you wish to use IPython under Windows, you must NOT use this library,
 which for all purposes is (at least as of version 1.6) terminally broken.
\layout Subsubsection

Gary Bishop's readline and color support for Windows
\layout Standard

Some of IPython's very useful features are:
\layout Itemize

Integrated readline support (Tab-based file, object and attribute completion,
 input history across sessions, editable command line, etc.)
\layout Itemize

Coloring of prompts, code and tracebacks.
\layout Standard

These, by default, are only available under Unix-like operating systems.
 However, thanks to Gary Bishop's work, Windows XP/2k users can also benefit
 from them.
 His readline library implements both GNU readline functionality and color
 support, so that IPython under Windows XP/2k can be as friendly and powerful
 as under Unix-like environments.
\layout Standard

You can find Gary's tools at 
\begin_inset LatexCommand \htmlurl{http://sourceforge.net/projects/uncpythontools}

\end_inset 

; Gary's 
\family typewriter 
readline
\family default 
 requires in turn the 
\family typewriter 
ctypes
\family default 
 library by Thomas Heller, available at 
\begin_inset LatexCommand \htmlurl{http://starship.python.net/crew/theller/ctypes}

\end_inset 

, and Mark Hammond's 
\family typewriter 
PyWin32
\family default 
 from 
\begin_inset LatexCommand \htmlurl{http://starship.python.net/crew/mhammond}

\end_inset 

 (
\family typewriter 
PyWin32
\family default 
 is great for anything Windows-related anyway, so you might as well get
 it).
\layout Standard

Under MS\SpecialChar ~
Windows, IPython will complain if it can not find this 
\family typewriter 
readline
\family default 
 library at startup and any time the 
\family typewriter 
%colors
\family default 
 command is issued, so you can consider it to be a quasi-requirement.
\layout Subsubsection

Installation procedure
\layout Standard

Once you have the above installed, from the IPython download directory grab
 the 
\family typewriter 
ipython-XXX.win32.exe
\family default 
 file, where 
\family typewriter 
XXX
\family default 
 represents the version number.
 This is a regular windows executable installer, which you can simply double-cli
ck to install.
 It will add an entry for IPython to your Start Menu, as well as registering
 IPython in the Windows list of applications, so you can later uninstall
 it from the Control Panel.
 
\layout Standard

IPython tries to install the configuration information in a directory named
 
\family typewriter 
.ipython
\family default 
 (
\family typewriter 
_ipython
\family default 
 under Windows) located in your `home' directory.
 IPython sets this directory by looking for a 
\family typewriter 
HOME
\family default 
 environment variable; if such a variable does not exist, it uses 
\family typewriter 
HOMEDRIVE
\backslash 
HOMEPATH 
\family default 
(these are always defined by Windows).
 This typically gives something like 
\family typewriter 
C:
\backslash 
Documents and Settings
\backslash 
YourUserName
\family default 
, but your local details may vary.
 In this directory you will find all the files that configure IPython's
 defaults, and you can put there your profiles and extensions.
 This directory is automatically added by IPython to 
\family typewriter 
sys.path
\family default 
, so anything you place there can be found by 
\family typewriter 
import
\family default 
 statements.
\layout Paragraph

Upgrading
\layout Standard

For an IPython upgrade, you should first uninstall the previous version.
 This will ensure that all files and directories (such as the documentation)
 which carry embedded version strings in their names are properly removed.
\layout Paragraph

Manual installation under Win32
\layout Standard

In case the automatic installer does not work for some reason, you can download
 the 
\family typewriter 
ipython-XXX.tar.gz
\family default 
 file, which contains the full IPython source distribution (the popular
 WinZip can read 
\family typewriter 
.tar.gz
\family default 
 files).
 After uncompressing the archive, you can install it at a command terminal
 just like any other Python module, by using 
\family typewriter 
`python setup.py install'
\family default 
.
 
\layout Standard

After the installation, run the supplied 
\family typewriter 
win32_manual_post_install.py 
\family default 
script, which creates the necessary Start Menu shortcuts for you.
\layout Subsection


\begin_inset LatexCommand \label{sec:upgrade}

\end_inset 

Upgrading from a previous version
\layout Standard

If you are upgrading from a previous version of IPython, after doing the
 routine installation described above, you should call IPython with the
 
\family typewriter 
-upgrade
\family default 
 option the first time you run your new copy.
 This will automatically update your configuration directory while preserving
 copies of your old files.
 You can then later merge back any personal customizations you may have
 made into the new files.
 It is a good idea to do this as there may be new options available in the
 new configuration files which you will not have.
\layout Standard

Under Windows, if you don't know how to call python scripts with arguments
 from a command line, simply delete the old config directory and IPython
 will make a new one.
 Win2k and WinXP users will find it in 
\family typewriter 
C:
\backslash 
Documents and Settings
\backslash 
YourUserName
\backslash 
.ipython
\family default 
, and Win 9x users under 
\family typewriter 
C:
\backslash 
Program Files
\backslash 
IPython
\backslash 
.ipython.
\layout Section


\begin_inset LatexCommand \label{sec:good_config}

\end_inset 


\begin_inset OptArg
collapsed true

\layout Standard

Initial configuration
\begin_inset ERT
status Collapsed

\layout Standard

\backslash 
ldots
\end_inset 


\end_inset 

Initial configuration of your environment
\layout Standard

This section will help you set various things in your environment for your
 IPython sessions to be as efficient as possible.
 All of IPython's configuration information, along with several example
 files, is stored in a directory named by default 
\family typewriter 
$HOME/.ipython
\family default 
.
 You can change this by defining the environment variable 
\family typewriter 
IPYTHONDIR
\family default 
, or at runtime with the command line option 
\family typewriter 
-ipythondir
\family default 
.
\layout Standard

If all goes well, the first time you run IPython it should automatically
 create a user copy of the config directory for you, based on its builtin
 defaults.
 You can look at the files it creates to learn more about configuring the
 system.
 The main file you will modify to configure IPython's behavior is called
 
\family typewriter 
ipythonrc
\family default 
 (with a 
\family typewriter 
.ini
\family default 
 extension under Windows), included for reference in Sec.
 
\begin_inset LatexCommand \ref{sec:ipytonrc-sample}

\end_inset 

.
 This file is very commented and has many variables you can change to suit
 your taste, you can find more details in Sec.
 
\begin_inset LatexCommand \ref{sec:customization}

\end_inset 

.
 Here we discuss the basic things you will want to make sure things are
 working properly from the beginning.
\layout Subsection


\begin_inset LatexCommand \label{sec:help-access}

\end_inset 

Access to the Python help system
\layout Standard

This is true for Python in general (not just for IPython): you should have
 an environment variable called 
\family typewriter 
PYTHONDOCS
\family default 
 pointing to the directory where your HTML Python documentation lives.
 In my system it's 
\family typewriter 
/usr/share/doc/python-docs-2.3.4/html
\family default 
, check your local details or ask your systems administrator.
 
\layout Standard

This is the directory which holds the HTML version of the Python manuals.
 Unfortunately it seems that different Linux distributions package these
 files differently, so you may have to look around a bit.
 Below I show the contents of this directory on my system for reference:
\layout Standard


\family typewriter 
[html]> ls
\newline 
about.dat acks.html dist/ ext/ index.html lib/ modindex.html stdabout.dat tut/
 about.html api/ doc/ icons/ inst/ mac/ ref/ style.css
\layout Standard

You should really make sure this variable is correctly set so that Python's
 pydoc-based help system works.
 It is a powerful and convenient system with full access to the Python manuals
 and all modules accessible to you.
\layout Standard

Under Windows it seems that pydoc finds the documentation automatically,
 so no extra setup appears necessary.
\layout Subsection

Editor
\layout Standard

The 
\family typewriter 
%edit
\family default 
 command (and its alias 
\family typewriter 
%ed
\family default 
) will invoke the editor set in your environment as 
\family typewriter 
EDITOR
\family default 
.
 If this variable is not set, it will default to 
\family typewriter 
vi
\family default 
 under Linux/Unix and to 
\family typewriter 
notepad
\family default 
 under Windows.
 You may want to set this variable properly and to a lightweight editor
 which doesn't take too long to start (that is, something other than a new
 instance of 
\family typewriter 
Emacs
\family default 
).
 This way you can edit multi-line code quickly and with the power of a real
 editor right inside IPython.
 
\layout Standard

If you are a dedicated 
\family typewriter 
Emacs
\family default 
 user, you should set up the 
\family typewriter 
Emacs
\family default 
 server so that new requests are handled by the original process.
 This means that almost no time is spent in handling the request (assuming
 an 
\family typewriter 
Emacs
\family default 
 process is already running).
 For this to work, you need to set your 
\family typewriter 
EDITOR 
\family default 
environment variable to 
\family typewriter 
'emacsclient'
\family default 
.

\family typewriter 
 
\family default 
The code below, supplied by Francois Pinard, can then be used in your 
\family typewriter 
.emacs
\family default 
 file to enable the server:
\layout Standard


\family typewriter 
(defvar server-buffer-clients)
\newline 
(when (and (fboundp 'server-start) (string-equal (getenv "TERM") 'xterm))
\newline 

\begin_inset ERT
status Collapsed

\layout Standard

\backslash 
hspace*{0mm}
\end_inset 

\SpecialChar ~
\SpecialChar ~
(server-start)
\newline 

\begin_inset ERT
status Collapsed

\layout Standard

\backslash 
hspace*{0mm}
\end_inset 

\SpecialChar ~
\SpecialChar ~
(defun fp-kill-server-with-buffer-routine ()
\newline 

\begin_inset ERT
status Collapsed

\layout Standard

\backslash 
hspace*{0mm}
\end_inset 

\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
(and server-buffer-clients (server-done)))
\newline 

\begin_inset ERT
status Collapsed

\layout Standard

\backslash 
hspace*{0mm}
\end_inset 

\SpecialChar ~
\SpecialChar ~
(add-hook 'kill-buffer-hook 'fp-kill-server-with-buffer-routine))
\layout Standard

You can also set the value of this editor via the commmand-line option '-
\family typewriter 
editor'
\family default 
 or in your 
\family typewriter 
ipythonrc
\family default 
 file.
 This is useful if you wish to use specifically for IPython an editor different
 from your typical default (and for Windows users who tend to use fewer
 environment variables).
\layout Subsection

Color 
\layout Standard

The default IPython configuration has most bells and whistles turned on
 (they're pretty safe).
 But there's one that 
\emph on 
may
\emph default 
 cause problems on some systems: the use of color on screen for displaying
 information.
 This is very useful, since IPython can show prompts and exception tracebacks
 with various colors, display syntax-highlighted source code, and in general
 make it easier to visually parse information.
\layout Standard

The following terminals seem to handle the color sequences fine:
\layout Itemize

Linux main text console, KDE Konsole, Gnome Terminal, E-term, rxvt, xterm.
\layout Itemize

CDE terminal (tested under Solaris).
 This one boldfaces light colors.
\layout Itemize

(X)Emacs buffers.
 See sec.
\begin_inset LatexCommand \ref{sec:emacs}

\end_inset 

 for more details on using IPython with (X)Emacs.
\layout Itemize

A Windows (XP/2k) command prompt 
\emph on 
with Gary Bishop's support extensions
\emph default 
.
 Gary's extensions are discussed in Sec.\SpecialChar ~

\begin_inset LatexCommand \ref{sub:Under-Windows}

\end_inset 

.
\layout Itemize

A Windows (XP/2k) CygWin shell.
 Although some users have reported problems; it is not clear whether there
 is an issue for everyone or only under specific configurations.
 If you have full color support under cygwin, please post to the IPython
 mailing list so this issue can be resolved for all users.
\layout Standard

These have shown problems:
\layout Itemize

Windows command prompt in WinXP/2k logged into a Linux machine via telnet
 or ssh.
\layout Itemize

Windows native command prompt in WinXP/2k, 
\emph on 
without 
\emph default 
Gary Bishop's extensions.
 Once Gary's readline library is installed, the normal WinXP/2k command
 prompt works perfectly.
\layout Standard

Currently the following color schemes are available:
\layout Itemize


\family typewriter 
NoColor
\family default 
: uses no color escapes at all (all escapes are empty 
\begin_inset Quotes eld
\end_inset 

 
\begin_inset Quotes eld
\end_inset 

 strings).
 This 'scheme' is thus fully safe to use in any terminal.