doc/manual_base.lyx

#LyX 1.4.3 created this file. For more info see http://www.lyx.org/
\lyxformat 245
\begin_document
\begin_header
\textclass article
\begin_preamble
%\usepackage{ae,aecompl}
\usepackage{color}

% A few colors to replace the defaults for certain link types
\definecolor{orange}{cmyk}{0,0.4,0.8,0.2}
\definecolor{darkorange}{rgb}{.71,0.21,0.01}
\definecolor{darkred}{rgb}{.52,0.08,0.01}
\definecolor{darkgreen}{rgb}{.12,.54,.11}

% Use and configure listings package for nicely formatted code
\usepackage{listings}
\lstset{
  language=Python,
  basicstyle=\small\ttfamily,
  commentstyle=\ttfamily\color{blue},
  stringstyle=\ttfamily\color{darkorange},
  showstringspaces=false,
  breaklines=true,
  postbreak = \space\dots
}

\usepackage[%pdftex,  % needed for pdflatex
  breaklinks=true,  % so long urls are correctly broken across lines
  colorlinks=true,
  urlcolor=blue,
  linkcolor=darkred,
  citecolor=darkgreen,
  ]{hyperref}

\usepackage{html}

% This helps prevent overly long lines that stretch beyond the margins
\sloppy

% Define a \codelist command which either uses listings for latex, or
% plain verbatim for html (since latex2html doesn't understand the 
% listings package).
\usepackage{verbatim}
\newcommand{\codelist}[1] {
\latex{\lstinputlisting{#1}}
\html{\verbatiminput{#1}}
}
\end_preamble
\language english
\inputencoding latin1
\fontscheme palatino
\graphics default
\paperfontsize 11
\spacing single
\papersize default
\use_geometry true
\use_amsmath 1
\cite_engine basic
\use_bibtopic false
\paperorientation portrait
\leftmargin 1in
\topmargin 1in
\rightmargin 1in
\bottommargin 1in
\secnumdepth 3
\tocdepth 3
\paragraph_separation skip
\defskip medskip
\quotes_language english
\papercolumns 1
\papersides 2
\paperpagestyle fancy
\tracking_changes false
\output_changes true
\end_header

\begin_body

\begin_layout Title
IPython
\newline

\size larger
An enhanced Interactive Python
\size large

\newline
User Manual, v.
 __version__
\end_layout

\begin_layout Author
Fernando P�rez
\begin_inset Foot
status collapsed

\begin_layout Standard

\size scriptsize
Department of Applied Mathematics, University of Colorado at Boulder.
 
\family typewriter
<[e-mail]>
\end_layout

\end_inset


\end_layout

\begin_layout Standard
\begin_inset ERT
status collapsed

\begin_layout Standard


\backslash
latex{
\end_layout

\end_inset


\begin_inset LatexCommand \tableofcontents{}

\end_inset


\begin_inset ERT
status collapsed

\begin_layout Standard

}
\end_layout

\end_inset


\end_layout

\begin_layout Standard
\begin_inset ERT
status open

\begin_layout Standard


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

\end_inset


\end_layout

\begin_layout Standard

\newpage

\end_layout

\begin_layout Section
Overview
\end_layout

\begin_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.
\end_layout

\begin_layout Standard
IPython is a free software project (released under the BSD license) which
 tries to:
\end_layout

\begin_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).
\end_layout

\begin_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.
\end_layout

\begin_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.
\end_layout

\begin_layout Enumerate
Allow interactive testing of threaded graphical toolkits.
 IPython has support for interactive, non-blocking control of GTK, Qt and
 WX applications via special threading flags.
 The normal Python shell can only do this for Tkinter applications.
\end_layout

\begin_layout Subsection
Main features
\end_layout

\begin_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
', and using `
\family typewriter
??
\family default
' provides additional detail).
\end_layout

\begin_layout Itemize
Searching through modules and namespaces with `
\family typewriter
*
\family default
' wildcards, both when using the `
\family typewriter
?
\family default
' system and via the 
\family typewriter
%psearch
\family default
 command.
\end_layout

\begin_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.
\end_layout

\begin_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.
\end_layout

\begin_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.
\end_layout

\begin_layout Itemize
Alias facility for defining your own system aliases.
\end_layout

\begin_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.
\end_layout

\begin_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
.
\end_layout

\begin_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
).
\end_layout

\begin_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.
\end_layout

\begin_layout Itemize
A lightweight persistence framework via the 
\family typewriter
%store
\family default
 command, which allows you to save arbitrary Python variables.
 These get restored automatically when your session restarts.
\end_layout

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

\begin_layout Itemize
Macro system for quickly re-executing multiple lines of previous input with
 a single name.
 Macros can be stored persistently via 
\family typewriter
%store
\family default
 and edited via 
\family typewriter
%edit
\family default
.
 
\end_layout

\begin_layout Itemize
Session logging (you can then later use these logs as code in your programs).
 Logs can optionally timestamp all input, and also store session output
 (marked as comments, so the log remains valid Python source code).
\end_layout

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

\begin_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).
\end_layout

\begin_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
'.
\end_layout

\begin_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\InsetSpace ~
b'
\family default
 becomes automatically 
\family typewriter
`my_function("a","b")'
\family default
, while 
\family typewriter
`;my_function a\InsetSpace ~
b'
\family default
 becomes 
\family typewriter
`my_function("a b")'
\family default
.
\end_layout

\begin_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.
\end_layout

\begin_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.
\end_layout

\begin_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).
\end_layout

\begin_layout Itemize
Easy debugger access.
 You can set IPython to call up an enhanced version of the Python debugger
 (
\family typewriter
pdb
\family default
) 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.
 This version of 
\family typewriter
pdb
\family default
 has IPython-specific improvements, including tab-completion and traceback
 coloring support.
\end_layout

\begin_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 standard 
\family typewriter
cProfile
\family default
 or 
\family typewriter
profile
\family default
 modules, 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.
\end_layout

\begin_layout Itemize
Doctest support.
 The special 
\family typewriter
%doctest_mode
\family default
 command toggles a mode that allows you to paste existing doctests (with
 leading `
\family typewriter
>>>
\family default
' prompts and whitespace) and uses doctest-compatible prompts and output,
 so you can use IPython sessions as doctest code.
\end_layout

\begin_layout Subsection
Portability and Python requirements
\end_layout

\begin_layout Standard

\series bold
Python requirements: 
\series default
IPython requires with Python version 2.3 or newer.
 If you are still using Python 2.2 and can not upgrade, the last version
 of IPython which worked with Python 2.2 was 0.6.15, so you will have to use
 that.
\end_layout

\begin_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).
\end_layout

\begin_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.
\end_layout

\begin_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.
\end_layout

\begin_layout Standard

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

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

\end_inset

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

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

\begin_layout Standard
Note, that I have very little access to and experience with Windows development.
 However, an excellent group of Win32 users (led by Ville Vainio), consistently
 contribute bugfixes and platform-specific enhancements, so they more than
 make up for my deficiencies on that front.
 In fact, Win32 users report using IPython as a system shell (see Sec.\InsetSpace ~

\begin_inset LatexCommand \ref{sec:IPython-as-shell}

\end_inset

 for details), as it offers a level of control and features which the default
 
\family typewriter
cmd.exe
\family default
 doesn't provide.
\end_layout

\begin_layout Subsection
Location
\end_layout

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

\end_inset

 by the Enthought, Inc and the SciPy project.
 This site offers downloads, subversion 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.
\end_layout

\begin_layout Section
\begin_inset LatexCommand \label{sec:install}

\end_inset

Installation
\end_layout

\begin_layout Subsection
Instant instructions
\end_layout

\begin_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.
\end_layout

\begin_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.
\end_layout

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

\end_inset

 for upgrading IPython versions.
\end_layout

\begin_layout Subsection
Detailed Unix instructions (Linux, Mac OS X, etc.)
\end_layout

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

\begin_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.
 
\end_layout

\begin_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.
\end_layout

\begin_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 
\begin_inset ERT
status collapsed

\begin_layout Standard


\backslash
verb|--home|
\end_layout

\end_inset

 option (or 
\begin_inset ERT
status collapsed

\begin_layout Standard


\backslash
verb|--prefix|
\end_layout

\end_inset

).
 For example:
\newline

\begin_inset ERT
status collapsed

\begin_layout Standard


\backslash
verb|$ python setup.py install --home $HOME/local|
\end_layout

\end_inset


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

\begin_inset ERT
status collapsed

\begin_layout Standard


\backslash
verb|$ python setup.py --help|
\end_layout

\end_inset

 
\newline
for more details.
\newline
Note that if you change the default location for 
\begin_inset ERT
status collapsed

\begin_layout Standard


\backslash
verb|--home|
\end_layout

\end_inset

 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 
\begin_inset ERT
status collapsed

\begin_layout Standard


\backslash
verb|--home|
\end_layout

\end_inset

 plus 
\family typewriter
/lib/python
\family default
).
\end_layout

\begin_layout Subsubsection
Mac OSX information
\end_layout

\begin_layout Standard
Under OSX, there is a choice you need to make.
 Apple ships its own build of Python, which lives in the core OSX filesystem
 hierarchy.
 You can also manually install a separate Python, either purely by hand
 (typically in 
\family typewriter
/usr/local
\family default
) or by using Fink, which puts everything under 
\family typewriter
/sw
\family default
.
 Which route to follow is a matter of personal preference, as I've seen
 users who favor each of the approaches.
 Here I will simply list the known installation issues under OSX, along
 with their solutions.
\end_layout

\begin_layout Standard
This page: 
\begin_inset LatexCommand \htmlurl{http://geosci.uchicago.edu/~tobis/pylab.html}

\end_inset

 contains information on this topic, with additional details on how to make
 IPython and matplotlib play nicely under OSX.
\end_layout

\begin_layout Subsubsection*
GUI problems
\end_layout

\begin_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.
\end_layout

\begin_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.
\end_layout

\begin_layout Standard
So when installing under OSX, it is best to use the following command:
\family typewriter

\newline

\family default

\begin_inset ERT
status collapsed

\begin_layout Standard


\backslash
verb|  $ sudo pythonw setup.py install --install-scripts=/usr/local/bin|
\end_layout

\end_inset


\newline
 or
\newline

\begin_inset ERT
status collapsed

\begin_layout Standard


\backslash
verb|  $ sudo pythonw setup.py install --install-scripts=/usr/bin|
\end_layout

\end_inset


\newline
depending on where you like to keep hand-installed executables.
\end_layout

\begin_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
.
 
\end_layout

\begin_layout Standard
It is also a good idea to use the special flag 
\begin_inset ERT
status collapsed

\begin_layout Standard


\backslash
verb|--install-scripts|
\end_layout

\end_inset

 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).
\end_layout

\begin_layout Subsubsection*
Readline problems
\end_layout

\begin_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

 
\end_layout

\begin_layout Standard
If you are using OSX 10.4 (Tiger), after installing this package you need
 to either: 
\end_layout

\begin_layout Enumerate
move 
\family typewriter
readline.so
\family default
 from 
\family typewriter
/Library/Python/2.3
\family default
 to 
\family typewriter
/Library/Python/2.3/site-packages
\family default
, or
\end_layout

\begin_layout Enumerate
install 
\begin_inset LatexCommand \htmlurl{http://pythonmac.org/packages/TigerPython23Compat.pkg.zip}

\end_inset


\end_layout

\begin_layout Standard
Users installing against Fink's Python or a properly hand-built one should
 not have this problem.
\end_layout

\begin_layout Subsubsection*
DarwinPorts
\end_layout

\begin_layout Standard
I report here a message from an OSX user, who suggests an alternative means
 of using IPython under this operating system with good results.
 Please let me know of any updates that may be useful for this section.
 His message is reproduced verbatim below:
\end_layout

\begin_layout Quote
From: Markus Banfi 
\family typewriter
<markus.banfi-AT-mospheira.net>
\end_layout

\begin_layout Quote
As a MacOS X (10.4.2) user I prefer to install software using DawinPorts instead
 of Fink.
 I had no problems installing ipython with DarwinPorts.
 It's just:
\end_layout

\begin_layout Quote

\family typewriter
sudo port install py-ipython
\end_layout

\begin_layout Quote
It automatically resolved all dependencies (python24, readline, py-readline).
 So far I did not encounter any problems with the DarwinPorts port of ipython.
 
\end_layout

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

\end_inset

Windows instructions
\end_layout

\begin_layout Standard
Some of IPython's very useful features are:
\end_layout

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

\begin_layout Itemize
Coloring of prompts, code and tracebacks.
\end_layout

\begin_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 originally implemented 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.
 
\end_layout

\begin_layout Standard
This library, now named 
\family typewriter
PyReadline
\family default
, has been absorbed by the IPython team (J�rgen Stenarson, in particular),
 and it continues to be developed with new features, as well as being distribute
d directly from the IPython site.
\end_layout

\begin_layout Standard
The
\family typewriter
 PyReadline
\family default
 extension requires 
\family typewriter
CTypes
\family default
 and the windows IPython installer needs 
\family typewriter
PyWin32
\family default
, so in all you need:
\end_layout

\begin_layout Enumerate

\family typewriter
PyWin32
\family default
 from 
\begin_inset LatexCommand \htmlurl{http://sourceforge.net/projects/pywin32}

\end_inset

.
\end_layout

\begin_layout Enumerate

\family typewriter
PyReadline
\family default
 for Windows from 
\begin_inset LatexCommand \htmlurl{http://ipython.scipy.org/moin/PyReadline/Intro}

\end_inset

.
 That page contains further details on using and configuring the system
 to your liking.
\end_layout

\begin_layout Enumerate
Finally, 
\emph on
only 
\emph default
if you are using Python 2.3 or 2.4, you need 
\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).
 This package is included in Python 2.5, so you don't need to manually get
 it if your Python version is 2.5 or newer.
\end_layout

\begin_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.
\end_layout

\begin_layout Subsubsection
Installation procedure
\end_layout

\begin_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.
 
\end_layout

\begin_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.
\end_layout

\begin_layout Paragraph
Upgrading
\end_layout

\begin_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.
\end_layout

\begin_layout Paragraph
Manual installation under Win32
\end_layout

\begin_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
.
 
\end_layout

\begin_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.
\end_layout

\begin_layout Subsection
\begin_inset LatexCommand \label{sec:upgrade}

\end_inset

Upgrading from a previous version
\end_layout

\begin_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.
\end_layout

\begin_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.
\end_layout

\begin_layout Section
\begin_inset LatexCommand \label{sec:good_config}

\end_inset


\begin_inset OptArg
status collapsed

\begin_layout Standard
Initial configuration
\begin_inset ERT
status collapsed

\begin_layout Standard


\backslash
ldots
\end_layout

\end_inset


\end_layout

\end_inset

Initial configuration of your environment
\end_layout

\begin_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
.
\end_layout

\begin_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.
\end_layout

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

\end_inset

Access to the Python help system
\end_layout

\begin_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.
 
\end_layout

\begin_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:
\end_layout

\begin_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
\end_layout

\begin_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.
\end_layout

\begin_layout Standard
Under Windows it seems that pydoc finds the documentation automatically,
 so no extra setup appears necessary.
\end_layout

\begin_layout Subsection
Editor
\end_layout

\begin_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.
 
\end_layout

\begin_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:
\end_layout

\begin_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

\begin_layout Standard


\backslash
hspace*{0mm}
\end_layout

\end_inset

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

\begin_inset ERT
status collapsed

\begin_layout Standard


\backslash
hspace*{0mm}
\end_layout

\end_inset

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

\begin_inset ERT
status collapsed

\begin_layout Standard


\backslash
hspace*{0mm}
\end_layout

\end_inset

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

\begin_inset ERT
status collapsed

\begin_layout Standard


\backslash
hspace*{0mm}
\end_layout

\end_inset

\InsetSpace ~
\InsetSpace ~
(add-hook 'kill-buffer-hook 'fp-kill-server-with-buffer-routine))
\end_layout

\begin_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).
\end_layout

\begin_layout Subsection
Color 
\end_layout

\begin_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.
\end_layout

\begin_layout Standard
The following terminals seem to handle the color sequences fine:
\end_layout

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

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

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

\end_inset

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

\begin_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.\InsetSpace ~

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

\end_inset

.
\end_layout

\begin_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.
\end_layout

\begin_layout Standard
These have shown problems:
\end_layout

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

\begin_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.
\end_layout

\begin_layout Standard
Currently the following color schemes are available:
\end_layout

\begin_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.
\end_layout

\begin_layout Itemize

\family typewriter
Linux
\family default
: works well in Linux console type environments: dark background with light
 fonts.
 It uses bright colors for information, so it is difficult to read if you
 have a light colored background.
\end_layout

\begin_layout Itemize

\family typewriter
LightBG
\family default
: the basic colors are similar to those in the 
\family typewriter
Linux
\family default
 scheme but darker.
 It is easy to read in terminals with light backgrounds.
\end_layout

\begin_layout Standard
IPython uses colors for two main groups of things: prompts and tracebacks
 which are directly printed to the terminal, and the object introspection
 system which passes large sets of data through a pager.
\end_layout

\begin_layout Subsubsection
Input/Output prompts and exception tracebacks
\end_layout

\begin_layout Standard
You can test whether the colored prompts and tracebacks work on your system
 interactively by typing 
\family typewriter
'%colors Linux'
\family default
 at the prompt (use '
\family typewriter
%colors LightBG'
\family default
 if your terminal has a light background).
 If the input prompt shows garbage like:
\newline

\family typewriter
[0;32mIn [[1;32m1[0;32m]: [0;00m
\family default

\newline
instead of (in color) something like:
\newline

\family typewriter
In [1]:
\family default
 
\newline
this means that your terminal doesn't properly handle color escape sequences.
 You can go to a 'no color' mode by typing '
\family typewriter
%colors NoColor
\family default
'.
 
\end_layout

\begin_layout Standard
You can try using a different terminal emulator program (Emacs users, see
 below).
 To permanently set your color preferences, edit the file
\family typewriter
 $HOME/.ipython/ipythonrc 
\family default
and set the 
\family typewriter
colors
\family default
 option to the desired value.
\end_layout

\begin_layout Subsubsection
Object details (types, docstrings, source code, etc.)
\end_layout

\begin_layout Standard
IPython has a set of special functions for studying the objects you are
 working with, discussed in detail in Sec.
 
\begin_inset LatexCommand \ref{sec:dyn-object-info}

\end_inset

.
 But this system relies on passing information which is longer than your
 screen through a data pager, such as the common Unix 
\family typewriter
less
\family default
 and 
\family typewriter
more
\family default
 programs.
 In order to be able to see this information in color, your pager needs
 to be properly configured.
 I strongly recommend using 
\family typewriter
less
\family default
 instead of 
\family typewriter
more
\family default
, as it seems that 
\family typewriter
more
\family default
 simply can not understand colored text correctly.
\end_layout

\begin_layout Standard
In order to configure 
\family typewriter
less
\family default
 as your default pager, do the following:
\end_layout

\begin_layout Enumerate
Set the environment 
\family typewriter
PAGER
\family default
 variable to 
\family typewriter
less
\family default
.
\end_layout

\begin_layout Enumerate
Set the environment 
\family typewriter
LESS
\family default
 variable to 
\family typewriter
-r
\family default
 (plus any other options you always want to pass to 
\family typewriter
less
\family default
 by default).
 This tells 
\family typewriter
less
\family default
 to properly interpret control sequences, which is how color information
 is given to your terminal.
\end_layout

\begin_layout Standard
For the 
\family typewriter
csh
\family default
 or 
\family typewriter
tcsh
\family default
 shells, add to your 
\family typewriter
~/.cshrc
\family default
 file the lines:
\end_layout

\begin_layout Standard

\family typewriter
setenv PAGER less
\newline
setenv LESS -r
\end_layout

\begin_layout Standard
There is similar syntax for other Unix shells, look at your system documentation
 for details.
\end_layout

\begin_layout Standard
If you are on a system which lacks proper data pagers (such as Windows),
 IPython will use a very limited builtin pager.
\end_layout

\begin_layout Subsection
\begin_inset LatexCommand \label{sec:emacs}

\end_inset

(X)Emacs configuration
\end_layout

\begin_layout Standard
Thanks to the work of Alexander Schmolck and Prabhu Ramachandran, currently
 (X)Emacs and IPython get along very well.
 
\end_layout

\begin_layout Standard

\series bold
Important note:
\series default
 You will need to use a recent enough version of 
\family typewriter
python-mode.el
\family default
, along with the file 
\family typewriter
ipython.el
\family default
.
 You can check that the version you have of 
\family typewriter
python-mode.el
\family default
 is new enough by either looking at the revision number in the file itself,
 or asking for it in (X)Emacs via 
\family typewriter
M-x py-version
\family default
.
 Versions 4.68 and newer contain the necessary fixes for proper IPython support.
\end_layout

\begin_layout Standard
The file 
\family typewriter
ipython.el
\family default
 is included with the IPython distribution, in the documentation directory
 (where this manual resides in PDF and HTML formats).
\end_layout

\begin_layout Standard
Once you put these files in your Emacs path, all you need in your 
\family typewriter
.emacs
\family default
 file is:
\end_layout

\begin_layout LyX-Code
(require 'ipython)
\end_layout

\begin_layout Standard
This should give you full support for executing code snippets via IPython,
 opening IPython as your Python shell via 
\family typewriter
C-c\InsetSpace ~
!
\family default
, etc.
 
\end_layout

\begin_layout Standard
If you happen to get garbage instead of colored prompts as described in
 the previous section, you may need to set also in your 
\family typewriter
.emacs
\family default
 file:
\end_layout

\begin_layout LyX-Code
(setq ansi-color-for-comint-mode t)
\end_layout

\begin_layout Subsubsection*
Notes
\end_layout

\begin_layout Itemize
There is one caveat you should be aware of: you must start the IPython shell
 
\emph on
before
\emph default
 attempting to execute any code regions via 
\family typewriter
C-c\InsetSpace ~
|
\family default
.
 Simply type 
\family typewriter
C-c\InsetSpace ~
!
\family default
 to start IPython before passing any code regions to the interpreter, and
 you shouldn't experience any problems.
\newline
This is due to a bug in Python itself,
 which has been fixed for Python 2.3, but exists as of Python 2.2.2 (reported
 as SF bug [ 737947 ]).
\end_layout

\begin_layout Itemize
The (X)Emacs support is maintained by Alexander Schmolck, so all comments/reques
ts should be directed to him through the IPython mailing lists.
 
\end_layout

\begin_layout Itemize
This code is still somewhat experimental so it's a bit rough around the
 edges (although in practice, it works quite well).
\end_layout

\begin_layout Itemize
Be aware that if you customize 
\family typewriter
py-python-command
\family default
 previously, this value will override what 
\family typewriter
ipython.el
\family default
 does (because loading the customization variables comes later).
\end_layout

\begin_layout Section
\begin_inset LatexCommand \label{sec:quick_tips}

\end_inset

Quick tips
\end_layout

\begin_layout Standard
IPython can be used as an improved replacement for the Python prompt, and
 for that you don't really need to read any more of this manual.
 But in this section we'll try to summarize a few tips on how to make the
 most effective use of it for everyday Python development, highlighting
 things you might miss in the rest of the manual (which is getting long).
 We'll give references to parts in the manual which provide more detail
 when appropriate.
\end_layout

\begin_layout Standard
The following article by Jeremy Jones provides an introductory tutorial
 about IPython:
\newline

\begin_inset LatexCommand \htmlurl{http://www.onlamp.com/pub/a/python/2005/01/27/ipython.html}

\end_inset


\end_layout

\begin_layout Itemize
The TAB key.
 TAB-completion, especially for attributes, is a convenient way to explore
 the structure of any object you're dealing with.
 Simply type 
\family typewriter
object_name.<TAB>
\family default
 and a list of the object's attributes will be printed (see sec.
 
\begin_inset LatexCommand \ref{sec:readline}

\end_inset

 for more).
 Tab completion also works on file and directory names, which combined with
 IPython's alias system allows you to do from within IPython many of the
 things you normally would need the system shell for.
 
\end_layout

\begin_layout Itemize
Explore your objects.
 Typing 
\family typewriter
object_name?
\family default
 will print all sorts of details about any object, including docstrings,
 function definition lines (for call arguments) and constructor details
 for classes.
 The magic commands 
\family typewriter
%pdoc
\family default
, 
\family typewriter
%pdef
\family default
, 
\family typewriter
%psource
\family default
 and 
\family typewriter
%pfile
\family default
 will respectively print the docstring, function definition line, full source
 code and the complete file for any object (when they can be found).
 If automagic is on (it is by default), you don't need to type the '
\family typewriter
%
\family default
' explicitly.
 See sec.
 
\begin_inset LatexCommand \ref{sec:dyn-object-info}

\end_inset

 for more.
\end_layout

\begin_layout Itemize
The 
\family typewriter
%run
\family default
 magic command allows you to run any python script and load all of its data
 directly into the interactive namespace.
 Since the file is re-read from disk each time, changes you make to it are
 reflected immediately (in contrast to the behavior of 
\family typewriter
import
\family default
).
 I rarely use 
\family typewriter
import
\family default
 for code I am testing, relying on 
\family typewriter
%run
\family default
 instead.
 See sec.
 
\begin_inset LatexCommand \ref{sec:magic}

\end_inset

 for more on this and other magic commands, or type the name of any magic
 command and ? to get details on it.
 See also sec.
 
\begin_inset LatexCommand \ref{sec:dreload}

\end_inset

 for a recursive reload command.
\newline

\family typewriter
%run
\family default
 also has special flags for timing the execution of your scripts (
\family typewriter
-t
\family default
) and for executing them under the control of either Python's 
\family typewriter
pdb 
\family default
debugger (
\family typewriter
-d
\family default
) or profiler (
\family typewriter
-p
\family default
).
 With all of these, 
\family typewriter
%run
\family default
 can be used as the main tool for efficient interactive development of code
 which you write in your editor of choice.
\end_layout

\begin_layout Itemize
Use the Python debugger, 
\family typewriter
pdb
\family default

\begin_inset Foot
status collapsed

\begin_layout Standard
Thanks to Christian Hart and Matthew Arnison for the suggestions leading
 to IPython's improved debugger and profiler support.
\end_layout

\end_inset

.
 The 
\family typewriter
%pdb
\family default
 command allows you to toggle on and off the automatic invocation of an
 IPython-enhanced 
\family typewriter
pdb
\family default
 debugger (with coloring, tab completion and more) at any uncaught exception.
 The advantage of this is that 
\family typewriter
pdb
\family default
 starts 
\emph on
inside
\emph default
 the function where the exception occurred, with all data still available.
 You can print variables, see code, execute statements and even walk up
 and down the call stack to track down the true source of the problem (which
 often is many layers in the stack above where the exception gets triggered).
\newline
Runn
ing programs with 
\family typewriter
%run
\family default
 and pdb active can be an efficient to develop and debug code, in many cases
 eliminating the need for 
\family typewriter
print
\family default
 statements or external debugging tools.
 I often simply put a 
\family typewriter
1/0
\family default
 in a place where I want to take a look so that pdb gets called, quickly
 view whatever variables I need to or test various pieces of code and then
 remove the 
\family typewriter
1/0
\family default
.
\newline
Note also that `
\family typewriter
%run -d
\family default
' activates 
\family typewriter
pdb
\family default
 and automatically sets initial breakpoints for you to step through your
 code, watch variables, etc.
 See Sec.\InsetSpace ~

\begin_inset LatexCommand \ref{sec:cache_output}

\end_inset

 for details.
\end_layout

\begin_layout Itemize
Use the output cache.
 All output results are automatically stored in a global dictionary named
 
\family typewriter
Out
\family default
 and variables named 
\family typewriter
_1
\family default
, 
\family typewriter
_2
\family default
, etc.
 alias them.
 For example, the result of input line 4 is available either as 
\family typewriter
Out[4]
\family default
 or as 
\family typewriter
_4
\family default
.
 Additionally, three variables named 
\family typewriter
_
\family default
, 
\family typewriter
__
\family default
 and 
\family typewriter
___
\family default
 are always kept updated with the for the last three results.
 This allows you to recall any previous result and further use it for new
 calculations.
 See Sec.\InsetSpace ~

\begin_inset LatexCommand \ref{sec:cache_output}

\end_inset

 for more.
\end_layout

\begin_layout Itemize
Put a '
\family typewriter
;
\family default
' at the end of a line to supress the printing of output.
 This is useful when doing calculations which generate long output you are
 not interested in seeing.
 The 
\family typewriter
_*
\family default
 variables and the 
\family typewriter
Out[]
\family default
 list do get updated with the contents of the output, even if it is not
 printed.
 You can thus still access the generated results this way for further processing.
\end_layout

\begin_layout Itemize
A similar system exists for caching input.
 All input is stored in a global list called 
\family typewriter
In
\family default
 , so you can re-execute lines 22 through 28 plus line 34 by typing 
\family typewriter
'exec In[22:29]+In[34]'
\family default
 (using Python slicing notation).
 If you need to execute the same set of lines often, you can assign them
 to a macro with the 
\family typewriter
%macro
\family default
 
\family typewriter
function.
 
\family default
See sec.
 
\begin_inset LatexCommand \ref{sec:cache_input}

\end_inset

 for more.
\end_layout

\begin_layout Itemize
Use your input history.
 The 
\family typewriter
%hist
\family default
 command can show you all previous input, without line numbers if desired
 (option 
\family typewriter
-n
\family default
) so you can directly copy and paste code either back in IPython or in a
 text editor.
 You can also save all your history by turning on logging via 
\family typewriter
%logstart
\family default
; these logs can later be either reloaded as IPython sessions or used as
 code for your programs.
\end_layout

\begin_layout Itemize
Define your own system aliases.
 Even though IPython gives you access to your system shell via the 
\family typewriter
!
\family default
 prefix, it is convenient to have aliases to the system commands you use
 most often.
 This allows you to work seamlessly from inside IPython with the same commands
 you are used to in your system shell.
\newline
IPython comes with some pre-defined
 aliases and a complete system for changing directories, both via a stack
 (see 
\family typewriter
%pushd
\family default
, 
\family typewriter
%popd
\family default
 and 
\family typewriter
%dhist
\family default
) and via direct 
\family typewriter
%cd
\family default
.
 The latter keeps a history of visited directories and allows you to go
 to any previously visited one.
\end_layout

\begin_layout Itemize
Use Python to manipulate the results of system commands.
 The `
\family typewriter
!!
\family default
' special syntax, and the 
\family typewriter
%sc
\family default
 and 
\family typewriter
%sx
\family default
 magic commands allow you to capture system output into Python variables.
\end_layout

\begin_layout Itemize
Expand python variables when calling the shell (either via 
\family typewriter
`!'
\family default
 and 
\family typewriter
`!!'
\family default
 or via aliases) by prepending a 
\family typewriter
$
\family default
 in front of them.
 You can also expand complete python expressions.
 See sec.\InsetSpace ~

\begin_inset LatexCommand \ref{sub:System-shell-access}

\end_inset

 for more.
\end_layout

\begin_layout Itemize
Use profiles to maintain different configurations (modules to load, function
 definitions, option settings) for particular tasks.
 You can then have customized versions of IPython for specific purposes.
 See sec.\InsetSpace ~

\begin_inset LatexCommand \ref{sec:profiles}

\end_inset

 for more.
\end_layout

\begin_layout Itemize
Embed IPython in your programs.
 A few lines of code are enough to load a complete IPython inside your own
 programs, giving you the ability to work with your data interactively after
 automatic processing has been completed.
 See sec.\InsetSpace ~

\begin_inset LatexCommand \ref{sec:embed}

\end_inset

 for more.
\end_layout

\begin_layout Itemize
Use the Python profiler.
 When dealing with performance issues, the 
\family typewriter
%run
\family default
 command with a 
\family typewriter
-p
\family default
 option allows you to run complete programs under the control of the Python
 profiler.
 The 
\family typewriter
%prun
\family default
 command does a similar job for single Python expressions (like function
 calls).
\end_layout

\begin_layout Itemize
Use the IPython.demo.Demo class to load any Python script as an interactive
 demo.
 With a minimal amount of simple markup, you can control the execution of
 the script, stopping as needed.
 See sec.\InsetSpace ~

\begin_inset LatexCommand \ref{sec:interactive-demos}

\end_inset

 for more.
\end_layout

\begin_layout Itemize
Run your doctests from within IPython for development and debugging.
 The special 
\family typewriter
%doctest_mode
\family default
 command toggles a mode where the prompt, output and exceptions display
 matches as closely as possible that of the default Python interpreter.
 In addition, this mode allows you to directly paste in code that contains
 leading `
\family typewriter
>>>
\family default
' prompts, even if they have extra leading whitespace (as is common in doctest
 files).
 This combined with the `
\family typewriter
%history -t
\family default
n' call to see your translated history (with these extra prompts removed
 and no line numbers) allows for an easy doctest workflow, where you can
 go from doctest to interactive execution to pasting into valid Python code
 as needed.
\end_layout

\begin_layout Subsection
Source code handling tips
\end_layout

\begin_layout Standard
IPython is a line-oriented program, without full control of the terminal.
 Therefore, it doesn't support true multiline editing.
 However, it has a number of useful tools to help you in dealing effectively
 with more complex editing.
\end_layout

\begin_layout Standard
The 
\family typewriter
%edit
\family default
 command gives a reasonable approximation of multiline editing, by invoking
 your favorite editor on the spot.
 IPython will execute the code you type in there as if it were typed interactive
ly.
 Type 
\family typewriter
%edit?
\family default
 for the full details on the edit command.
\end_layout

\begin_layout Standard
If you have typed various commands during a session, which you'd like to
 reuse, IPython provides you with a number of tools.
 Start by using 
\family typewriter
%hist
\family default
 to see your input history, so you can see the line numbers of all input.
 Let us say that you'd like to reuse lines 10 through 20, plus lines 24
 and 28.
 All the commands below can operate on these with the syntax
\end_layout

\begin_layout LyX-Code
%command 10-20 24 28
\end_layout

\begin_layout Standard
where the command given can be:
\end_layout

\begin_layout Itemize

\family typewriter
%macro <macroname>
\family default
: this stores the lines into a variable which, when called at the prompt,
 re-executes the input.
 Macros can be edited later using 
\family typewriter
`%edit macroname
\family default
', and they can be stored persistently across sessions with `
\family typewriter
%store macroname
\family default
' (the storage system is per-profile).
 The combination of quick macros, persistent storage and editing, allows
 you to easily refine quick-and-dirty interactive input into permanent utilities
, always available both in IPython and as files for general reuse.
\end_layout

\begin_layout Itemize

\family typewriter
%edit
\family default
: this will open a text editor with those lines pre-loaded for further modificat
ion.
 It will then execute the resulting file's contents as if you had typed
 it at the prompt.
\end_layout

\begin_layout Itemize

\family typewriter
%save <filename>
\family default
: this saves the lines directly to a named file on disk.
\end_layout

\begin_layout Standard
While 
\family typewriter
%macro
\family default
 saves input lines into memory for interactive re-execution, sometimes you'd
 like to save your input directly to a file.
 The 
\family typewriter
%save
\family default
 magic does this: its input sytnax is the same as 
\family typewriter
%macro
\family default
, but it saves your input directly to a Python file.
 Note that the 
\family typewriter
%logstart
\family default
 command also saves input, but it logs 
\emph on
all
\emph default
 input to disk (though you can temporarily suspend it and reactivate it
 with 
\family typewriter
%logoff/%logon
\family default
); 
\family typewriter
%save
\family default
 allows you to select which lines of input you need to save.
\end_layout

\begin_layout Subsubsection*
Lightweight 'version control'
\end_layout

\begin_layout Standard
When you call 
\family typewriter
%edit
\family default
 with no arguments, IPython opens an empty editor with a temporary file,
 and it returns the contents of your editing session as a string variable.
 Thanks to IPython's output caching mechanism, this is automatically stored:
\end_layout

\begin_layout LyX-Code
In [1]: %edit
\end_layout

\begin_layout LyX-Code
IPython will make a temporary file named: /tmp/ipython_edit_yR-HCN.py
\end_layout

\begin_layout LyX-Code
Editing...
 done.
 Executing edited code...
\end_layout

\begin_layout LyX-Code
hello - this is a temporary file
\end_layout

\begin_layout LyX-Code
Out[1]: "print 'hello - this is a temporary file'
\backslash
n"
\end_layout

\begin_layout Standard
Now, if you call 
\family typewriter
`%edit -p'
\family default
, IPython tries to open an editor with the same data as the last time you
 used 
\family typewriter
%edit
\family default
.
 So if you haven't used 
\family typewriter
%edit
\family default
 in the meantime, this same contents will reopen; however, it will be done
 in a 
\emph on
new file
\emph default
.
 This means that if you make changes and you later want to find an old version,
 you can always retrieve it by using its output number, via 
\family typewriter
`%edit _NN'
\family default
, where 
\family typewriter
NN
\family default
 is the number of the output prompt.
\end_layout

\begin_layout Standard
Continuing with the example above, this should illustrate this idea:
\end_layout

\begin_layout LyX-Code
In [2]: edit -p
\end_layout

\begin_layout LyX-Code
IPython will make a temporary file named: /tmp/ipython_edit_nA09Qk.py
\end_layout

\begin_layout LyX-Code
Editing...
 done.
 Executing edited code...
\end_layout

\begin_layout LyX-Code
hello - now I made some changes
\end_layout

\begin_layout LyX-Code
Out[2]: "print 'hello - now I made some changes'
\backslash
n"
\end_layout

\begin_layout LyX-Code
In [3]: edit _1
\end_layout

\begin_layout LyX-Code
IPython will make a temporary file named: /tmp/ipython_edit_gy6-zD.py
\end_layout

\begin_layout LyX-Code
Editing...
 done.
 Executing edited code...
\end_layout

\begin_layout LyX-Code
hello - this is a temporary file
\end_layout

\begin_layout LyX-Code
IPython version control at work :)
\end_layout

\begin_layout LyX-Code
Out[3]: "print 'hello - this is a temporary file'
\backslash
nprint 'IPython version control at work :)'
\backslash
n"
\end_layout

\begin_layout Standard
This section was written after a contribution by Alexander Belchenko on
 the IPython user list.
\end_layout

\begin_layout LyX-Code

\end_layout

\begin_layout Subsection
Effective logging
\end_layout

\begin_layout Standard
A very useful suggestion sent in by Robert Kern follows:
\end_layout

\begin_layout Standard
I recently happened on a nifty way to keep tidy per-project log files.
 I made a profile for my project (which is called "parkfield").
\end_layout

\begin_layout LyX-Code
include ipythonrc
\end_layout

\begin_layout LyX-Code
# cancel earlier logfile invocation:
\end_layout

\begin_layout LyX-Code
logfile ''
\end_layout

\begin_layout LyX-Code
execute import time
\end_layout

\begin_layout LyX-Code
execute __cmd = '/Users/kern/research/logfiles/parkfield-%s.log rotate'
\end_layout

\begin_layout LyX-Code
execute __IP.magic_logstart(__cmd % time.strftime('%Y-%m-%d'))
\end_layout

\begin_layout Standard
I also added a shell alias for convenience:
\end_layout

\begin_layout LyX-Code
alias parkfield="ipython -pylab -profile parkfield"
\end_layout

\begin_layout Standard
Now I have a nice little directory with everything I ever type in, organized
 by project and date.
\end_layout

\begin_layout Standard

\series bold
Contribute your own: 
\series default
If you have your own favorite tip on using IPython efficiently for a certain
 task (especially things which can't be done in the normal Python interpreter),
 don't hesitate to send it!
\end_layout

\begin_layout Section
Command-line use
\end_layout

\begin_layout Standard
You start IPython with the command:
\end_layout

\begin_layout Standard

\family typewriter
$ ipython [options] files
\end_layout

\begin_layout Standard
If invoked with no options, it executes all the files listed in sequence
 and drops you into the interpreter while still acknowledging any options
 you may have set in your ipythonrc file.
 This behavior is different from standard Python, which when called as 
\family typewriter
python -i
\family default
 will only execute one file and ignore your configuration setup.
\end_layout

\begin_layout Standard
Please note that some of the configuration options are not available at
 the command line, simply because they are not practical here.
 Look into your ipythonrc configuration file for details on those.
 This file typically installed in the 
\family typewriter
$HOME/.ipython
\family default
 directory.
 For Windows users, 
\family typewriter
$HOME
\family default
 resolves to 
\family typewriter
C:
\backslash

\backslash
Documents and Settings
\backslash

\backslash
YourUserName
\family default
 in most instances.
 In the rest of this text, we will refer to this directory as 
\family typewriter
IPYTHONDIR
\family default
.
\end_layout

\begin_layout Subsection
\begin_inset LatexCommand \label{sec:threading-opts}

\end_inset

Special Threading Options
\end_layout

\begin_layout Standard
The following special options are ONLY valid at the beginning of the command
 line, and not later.
 This is because they control the initial- ization of ipython itself, before
 the normal option-handling mechanism is active.
\end_layout

\begin_layout List
\labelwidthstring 00.00.0000

\family typewriter
\series bold
-gthread,\InsetSpace ~
-qthread,\InsetSpace ~
-q4thread,\InsetSpace ~
-wthread,\InsetSpace ~
-pylab:
\family default
\series default
 Only 
\emph on
one
\emph default
 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, Qt (versions 3 and 4) and WXPython
 toolkits, and for the matplotlib library.
\end_layout

\begin_layout List
\labelwidthstring 00.00.0000
\InsetSpace ~
 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).
\end_layout

\begin_layout List
\labelwidthstring 00.00.0000
\InsetSpace ~
 Note that with 
\family typewriter
-wthread
\family default
, you can additionally use the -wxversion option to request a specific version
 of wx to be used.
 This requires that you have the 
\family typewriter
wxversion
\family default
 Python module installed, which is part of recent wxPython distributions.
\end_layout

\begin_layout List
\labelwidthstring 00.00.0000
\InsetSpace ~
 If 
\family typewriter
-pylab
\family default
 is given, IPython loads special support for the mat plotlib library (
\begin_inset LatexCommand \htmlurl{http://matplotlib.sourceforge.net}

\end_inset

), allowing interactive usage of any of its backends as defined in the user's
 
\family typewriter
~/.matplotlib/matplotlibrc
\family default
 file.
 It automatically activates GTK, Qt or WX threading for IPyhton if the choice
 of matplotlib backend requires it.
 It also modifies the 
\family typewriter
%run
\family default
 command to correctly execute (without blocking) any matplotlib-based script
 which calls 
\family typewriter
show()
\family default
 at the end.
 
\end_layout

\begin_layout List
\labelwidthstring 00.00.0000

\family typewriter
\series bold
-tk
\family default
\series default
 The 
\family typewriter
-g/q/q4/wthread
\family default
 options, and 
\family typewriter
-pylab
\family default
 (if matplotlib is configured to use GTK, Qt3, Qt4 or WX), will normally
 block Tk graphical interfaces.
 This means that when either 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, 
\family typewriter
-tk
\family default
, is available to address this issue.
 It can 
\emph on
only
\emph default
 be given as a 
\emph on
second
\emph default
 option after any of the above (
\family typewriter
-gthread
\family default
, 
\family typewriter
-wthread
\family default
 or 
\family typewriter
-pylab
\family default
).
\end_layout

\begin_layout List
\labelwidthstring 00.00.0000
\InsetSpace ~
 If 
\family typewriter
-tk
\family default
 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/3), 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.
\end_layout

\begin_layout List
\labelwidthstring 00.00.0000
\InsetSpace ~
 There is unfortunately no way for IPython to determine at run time whether
 
\family typewriter
-tk
\family default
 will work reliably or not, so you will need to do some experiments before
 relying on it for regular work.
 
\end_layout

\begin_layout Subsection
\begin_inset LatexCommand \label{sec:cmd-line-opts}

\end_inset

Regular Options
\end_layout

\begin_layout Standard
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 
\family typewriter
|
\family default
.
\end_layout

\begin_layout Standard
Most options can also be set from your ipythonrc configuration file.
 See the provided example for more details on what the options do.
 Options given at the command line override the values set in the ipythonrc
 file.
\end_layout

\begin_layout Standard
All options with a 
\family typewriter
[no]
\family default
 prepended can be specified in negated form (
\family typewriter
-nooption
\family default
 instead of 
\family typewriter
-option
\family default
) to turn the feature off.
\end_layout

\begin_layout List
\labelwidthstring 00.00.0000

\family typewriter
\series bold
-help
\family default
\series default
: print a help message and exit.
\end_layout

\begin_layout List
\labelwidthstring 00.00.0000

\family typewriter
\series bold
-pylab:
\family default
\series default
 this can 
\emph on
only
\emph default
 be given as the 
\emph on
first
\emph default
 option passed to IPython (it will have no effect in any other position).
 It adds special support for the matplotlib library (
\begin_inset LatexCommand \htmlurl[http://matplotlib.sourceforge.net]{http://matplotlib.sourceforge.net}

\end_inset

), allowing interactive usage of any of its backends as defined in the user's
 
\family typewriter
.matplotlibrc
\family default
 file.
 It automatically activates GTK or WX threading for IPyhton if the choice
 of matplotlib backend requires it.
 It also modifies the 
\family typewriter
%run
\family default
 command to correctly execute (without blocking) any matplotlib-based script
 which calls 
\family typewriter
show()
\family default
 at the end.
 See Sec.\InsetSpace ~

\begin_inset LatexCommand \ref{sec:matplotlib-support}

\end_inset

 for more details.
\end_layout

\begin_layout List
\labelwidthstring 00.00.0000

\family typewriter
\series bold
-autocall <val>:
\family default
\series default
 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 
\emph on
smart
\emph default
 autocall, where it is not applied if there are no more arguments on the
 line, and `2' for 
\emph on
full
\emph default
 autocall, where all callable objects are automatically called (even if
 no arguments are present).
 The default is `1'.
\end_layout

\begin_layout List
\labelwidthstring 00.00.0000

\family typewriter
\series bold
-[no]autoindent:
\family default
\series default
 Turn automatic indentation on/off.
\end_layout

\begin_layout List
\labelwidthstring 00.00.0000

\family typewriter
\series bold
-[no]automagic
\series default
:
\family default
 make magic commands automatic (without needing their first character to
 be 
\family typewriter
%
\family default
).
 Type 
\family typewriter
%magic
\family default
 at the IPython prompt for more information.
\end_layout

\begin_layout List
\labelwidthstring 00.00.0000

\family typewriter
\series bold
-[no]autoedit_syntax:
\family default
\series default
 When a syntax error occurs after editing a file, automatically open the
 file to the trouble causing line for convenient fixing.
 
\end_layout

\begin_layout List
\labelwidthstring 00.00.0000

\family typewriter
\series bold
-[no]banner
\series default
:
\family default
 Print the initial information banner (default on).
\end_layout

\begin_layout List
\labelwidthstring 00.00.0000

\family typewriter
\series bold
-c\InsetSpace ~
<command>:
\family default
\series default
 execute the given command string, and set sys.argv to 
\family typewriter
['c']
\family default
.
 This is similar to the 
\family typewriter
-c
\family default
 option in the normal Python interpreter.
 
\end_layout

\begin_layout List
\labelwidthstring 00.00.0000

\family typewriter
\series bold
-cache_size|cs\InsetSpace ~
<n>
\series default
:
\family default
 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.
\end_layout

\begin_layout List
\labelwidthstring 00.00.0000

\family typewriter
\series bold
-classic|cl
\series default
:
\family default
 Gives IPython a similar feel to the classic Python prompt.
\end_layout

\begin_layout List
\labelwidthstring 00.00.0000

\family typewriter
\series bold
-colors\InsetSpace ~
<scheme>:
\family default
\series default
 Color scheme for prompts and exception reporting.
 Currently implemented: NoColor, Linux and LightBG.
\end_layout

\begin_layout List
\labelwidthstring 00.00.0000

\family typewriter
\series bold
-[no]color_info:
\family default
\series default
 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.
\end_layout

\begin_layout List
\labelwidthstring 00.00.0000
\InsetSpace ~
 Test it and turn it on permanently if it works with your system.
 The magic function 
\family typewriter
%color_info
\family default
 allows you to toggle this interactively for testing.
\end_layout

\begin_layout List
\labelwidthstring 00.00.0000

\family typewriter
\series bold
-[no]debug
\family default
\series default
: Show information about the loading process.
 Very useful to pin down problems with your configuration files or to get
 details about session restores.
\end_layout

\begin_layout List
\labelwidthstring 00.00.0000

\family typewriter
\series bold
-[no]deep_reload
\series default
:
\family default
 IPython can use the 
\family typewriter
deep_reload
\family default
 module which reloads changes in modules recursively (it replaces the 
\family typewriter
reload()
\family default
 function, so you don't need to change anything to use it).
 
\family typewriter
deep_reload()
\family default
 forces a full reload of modules whose code may have changed, which the
 default 
\family typewriter
reload()
\family default
 function does not.
\end_layout

\begin_layout List
\labelwidthstring 00.00.0000
\InsetSpace ~
 When deep_reload is off, IPython will use the normal 
\family typewriter
reload()
\family default
, but deep_reload will still be available as 
\family typewriter
dreload()
\family default
.
 This feature is off by default [which means that you have both normal 
\family typewriter
reload()
\family default
 and 
\family typewriter
dreload()
\family default
].
\end_layout

\begin_layout List
\labelwidthstring 00.00.0000

\family typewriter
\series bold
-editor\InsetSpace ~
<name>
\family default
\series default
: Which editor to use with the 
\family typewriter
%edit
\family default
 command.
 By default, IPython will honor your 
\family typewriter
EDITOR
\family default
 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 
\family typewriter
EDITOR
\family default
 is something like Emacs).
\end_layout

\begin_layout List
\labelwidthstring 00.00.0000

\family typewriter
\series bold
-ipythondir\InsetSpace ~
<name>
\series default
:
\family default
 name of your IPython configuration directory 
\family typewriter
IPYTHONDIR
\family default
.
 This can also be specified through the environment variable 
\family typewriter
IPYTHONDIR
\family default
.
\end_layout

\begin_layout List
\labelwidthstring 00.00.0000

\family typewriter
\series bold
-log|l
\family default
\series default
: generate a log file of all input.
 The file is named 
\family typewriter
ipython_log.py
\family default
 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 
\family typewriter
-logplay
\family default
 (see below).
\end_layout

\begin_layout List
\labelwidthstring 00.00.0000

\family typewriter
\series bold
-logfile|lf\InsetSpace ~
<name>
\series default
: 
\family default
specify the name of your logfile.
\end_layout

\begin_layout List
\labelwidthstring 00.00.0000

\family typewriter
\series bold
-logplay|lp\InsetSpace ~
<name>
\series default
:
\family default
 you can 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 
\family typewriter
-logplay
\family default
, IPython will try to reconstruct the previous working environment in full,
 not just execute the commands in the logfile.
\end_layout

\begin_layout List
\labelwidthstring 00.00.0000
\InsetSpace ~
 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.
\end_layout

\begin_layout List
\labelwidthstring 00.00.0000
\InsetSpace ~
 Caveats: there are limitations in this option.
 The history variables 
\family typewriter
_i*
\family default
,
\family typewriter
_*
\family default
 and 
\family typewriter
_dh
\family default
 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.
\end_layout

\begin_layout List
\labelwidthstring 00.00.0000

\family typewriter
\series bold
-[no]messages
\series default
:
\family default
 Print messages which IPython collects about its startup process (default
 on).
\end_layout

\begin_layout List
\labelwidthstring 00.00.0000

\family typewriter
\series bold
-[no]pdb
\family default
\series default
: 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.
\end_layout

\begin_layout List
\labelwidthstring 00.00.0000

\family typewriter
\series bold
-[no]pprint
\series default
:
\family default
 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).
\end_layout

\begin_layout List
\labelwidthstring 00.00.0000

\family typewriter
\series bold
-profile|p <name>
\series default
:
\family default
 assume that your config file is 
\family typewriter
ipythonrc-<name>
\family default
 (looks in current dir first, then in 
\family typewriter
IPYTHONDIR
\family default
).
 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 
\family typewriter
IPYTHONDIR/ipythonrc
\family default
 file and then have other 'profiles' which include this one and load extra
 things for particular tasks.
 For example:
\end_layout

\begin_layout List
\labelwidthstring 00.00.0000

\family typewriter
\InsetSpace ~
 
\family default
1.

\family typewriter
 $HOME/.ipython/ipythonrc
\family default
 : load basic things you always want.
\end_layout

\begin_layout List
\labelwidthstring 00.00.0000

\family typewriter
\InsetSpace ~
 
\family default
2.

\family typewriter
 $HOME/.ipython/ipythonrc-math
\family default
 : load (1) and basic math-related modules.
 
\end_layout

\begin_layout List
\labelwidthstring 00.00.0000

\family typewriter
\InsetSpace ~
 
\family default
3.

\family typewriter
 $HOME/.ipython/ipythonrc-numeric
\family default
 : load (1) and Numeric and plotting modules.
\end_layout

\begin_layout List
\labelwidthstring 00.00.0000
\InsetSpace ~
 Since it is possible to create an endless loop by having circular file
 inclusions, IPython will stop if it reaches 15 recursive inclusions.
\end_layout

\begin_layout List
\labelwidthstring 00.00.0000

\family typewriter
\series bold
-prompt_in1|pi1\InsetSpace ~
<string>:
\family default
\series default
 Specify the string used for input prompts.
 Note that if you are using numbered prompts, the number is represented
 with a '
\backslash
#' in the string.
 Don't forget to quote strings with spaces embedded in them.
 Default: '
\family typewriter
In\InsetSpace ~
[
\backslash
#]:
\family default
'.
 Sec.\InsetSpace ~

\begin_inset LatexCommand \ref{sec:prompts}

\end_inset

 discusses in detail all the available escapes to customize your prompts.
\end_layout

\begin_layout List
\labelwidthstring 00.00.0000

\family typewriter
\series bold
-prompt_in2|pi2\InsetSpace ~
<string>:
\family default
\series default
 Similar to the previous option, but used for the continuation prompts.
 The special sequence '
\family typewriter

\backslash
D
\family default
' is similar to '
\family typewriter

\backslash
#
\family default
', but with all digits replaced dots (so you can have your continuation
 prompt aligned with your input prompt).
 Default: '
\family typewriter
\InsetSpace ~
\InsetSpace ~
\InsetSpace ~
.
\backslash
D.:
\family default
' (note three spaces at the start for alignment with '
\family typewriter
In\InsetSpace ~
[
\backslash
#]
\family default
').
\end_layout

\begin_layout List
\labelwidthstring 00.00.0000

\family typewriter
\series bold
-prompt_out|po\InsetSpace ~
<string>:
\family default
\series default
 String used for output prompts, also uses numbers like 
\family typewriter
prompt_in1
\family default
.
 Default: '
\family typewriter
Out[
\backslash
#]:
\family default
'
\end_layout

\begin_layout List
\labelwidthstring 00.00.0000

\family typewriter
\series bold
-quick
\family default
\series default
: start in bare bones mode (no config file loaded).
\end_layout

\begin_layout List
\labelwidthstring 00.00.0000

\family typewriter
\series bold
-rcfile\InsetSpace ~
<name>
\series default
:
\family default
 name of your IPython resource configuration file.
 Normally IPython loads ipythonrc (from current directory) or
\family typewriter
 IPYTHONDIR/ipythonrc
\family default
.
\end_layout

\begin_layout List
\labelwidthstring 00.00.0000
\InsetSpace ~
 If the loading of your config file fails, IPython starts with a bare bones
 configuration (no modules loaded at all).
\end_layout

\begin_layout List
\labelwidthstring 00.00.0000

\family typewriter
\series bold
-[no]readline
\family default
\series default
: 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.
\end_layout

\begin_layout List
\labelwidthstring 00.00.0000
\InsetSpace ~
 Note that X/Emacs 'eterm' buffers (opened with 
\family typewriter
M-x\InsetSpace ~
term
\family default
) support IPython's readline and syntax coloring fine, only 'emacs' (
\family typewriter
M-x\InsetSpace ~
shell
\family default
 and 
\family typewriter
C-c\InsetSpace ~
!
\family default
) buffers do not.
\end_layout

\begin_layout List
\labelwidthstring 00.00.0000

\family typewriter
\series bold
-screen_length|sl\InsetSpace ~
<n>
\series default
:
\family default
 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.
\end_layout

\begin_layout List
\labelwidthstring 00.00.0000
\InsetSpace ~
 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.
\end_layout

\begin_layout List
\labelwidthstring 00.00.0000

\family typewriter
\series bold
-separate_in|si\InsetSpace ~
<string>
\series default
:
\family default
 separator before input prompts.
 Default: '
\family typewriter

\backslash
n
\family default
'
\end_layout

\begin_layout List
\labelwidthstring 00.00.0000

\family typewriter
\series bold
-separate_out|so\InsetSpace ~
<string>
\family default
\series default
: separator before output prompts.
 Default: nothing.
\end_layout

\begin_layout List
\labelwidthstring 00.00.0000

\family typewriter
\series bold
-separate_out2|so2\InsetSpace ~
<string>
\series default
:
\family default
 separator after output prompts.
 Default: nothing.
\end_layout

\begin_layout List
\labelwidthstring 00.00.0000
\InsetSpace ~
 For these three options, use the value 0 to specify no separator.
\end_layout

\begin_layout List
\labelwidthstring 00.00.0000

\family typewriter
\series bold
-nosep
\series default
: 
\family default
shorthand for 
\family typewriter
'-SeparateIn 0 -SeparateOut 0 -SeparateOut2 0'
\family default
.
 Simply removes all input/output separators.
\end_layout

\begin_layout List
\labelwidthstring 00.00.0000

\family typewriter
\series bold
-upgrade
\family default
\series default
: allows you to upgrade your 
\family typewriter
IPYTHONDIR
\family default
 configuration when you install a new version of IPython.
 Since new versions may include new command line options or example files,
 this copies updated ipythonrc-type files.
 However, it backs up (with a 
\family typewriter
.old
\family default
 extension) all files which it overwrites so that you can merge back any
 customizations you might have in your personal files.
\end_layout

\begin_layout List
\labelwidthstring 00.00.0000

\family typewriter
\series bold
-Version
\series default
:
\family default
 print version information and exit.
\end_layout

\begin_layout List
\labelwidthstring 00.00.0000

\family typewriter
\series bold
-wxversion\InsetSpace ~
<string>:
\family default
\series default
 Select a specific version of wxPython (used in conjunction with 
\family typewriter
-wthread
\family default
).
 Requires the wxversion module, part of recent wxPython distributions
\end_layout

\begin_layout List
\labelwidthstring 00.00.0000

\family typewriter
\series bold
-xmode\InsetSpace ~
<modename>
\series default
:
\family default
 Mode for exception reporting.
\end_layout

\begin_layout List
\labelwidthstring 00.00.0000
\InsetSpace ~
 Valid modes: Plain, Context and Verbose.
\end_layout

\begin_layout List
\labelwidthstring 00.00.0000
\InsetSpace ~
 Plain: similar to python's normal traceback printing.
\end_layout

\begin_layout List
\labelwidthstring 00.00.0000
\InsetSpace ~
 Context: prints 5 lines of context source code around each line in the
 traceback.
\end_layout

\begin_layout List
\labelwidthstring 00.00.0000
\InsetSpace ~
 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).
\end_layout

\begin_layout Section
Interactive use
\end_layout

\begin_layout Standard

\series bold
Warning
\series default
: IPython relies on the existence of a global variable called 
\family typewriter
__IP
\family default
 which controls the shell itself.
 If you redefine 
\family typewriter
__IP
\family default
 to anything, bizarre behavior will quickly occur.
\end_layout

\begin_layout Standard
Other than the above warning, IPython is meant to work as a drop-in replacement
 for the standard interactive interpreter.
 As such, any code which is valid python should execute normally under IPython
 (cases where this is not true should be reported as bugs).
 It does, however, offer many features which are not available at a standard
 python prompt.
 What follows is a list of these.
\end_layout

\begin_layout Subsection
Caution for Windows users
\end_layout

\begin_layout Standard
Windows, unfortunately, uses the `
\family typewriter

\backslash

\family default
' character as a path separator.
 This is a terrible choice, because `
\family typewriter

\backslash

\family default
' also represents the escape character in most modern programming languages,
 including Python.
 For this reason, issuing many of the commands discussed below (especially
 magics which affect the filesystem) with `
\family typewriter

\backslash

\family default
' in them will cause strange errors.
\end_layout

\begin_layout Standard
A partial solution is to use instead the `
\family typewriter
/
\family default
' character as a path separator, which Windows recognizes in 
\emph on
most
\emph default
 situations.
 However, in Windows commands `
\family typewriter
/
\family default
' flags options, so you can not use it for the root directory.
 This means that paths beginning at the root must be typed in a contrived
 manner like:
\newline

\family typewriter
%copy 
\backslash
opt/foo/bar.txt 
\backslash
tmp
\end_layout

\begin_layout Standard
There is no sensible thing IPython can do to truly work around this flaw
 in Windows
\begin_inset Foot
status collapsed

\begin_layout Standard
If anyone comes up with a 
\emph on
clean
\emph default
 solution which works consistently and does not negatively impact other
 platforms at all, I'll gladly accept a patch.
\end_layout

\end_inset

.
\end_layout

\begin_layout Subsection
\begin_inset LatexCommand \label{sec:magic}

\end_inset

Magic command system
\end_layout

\begin_layout Standard
IPython will treat any line whose first character is a 
\family typewriter
%
\family default
 as a special call to a 'magic' function.
 These allow you to control the behavior of IPython itself, plus a lot of
 system-type features.
 They are all prefixed with a 
\family typewriter
%
\family default
 character, but parameters are given without parentheses or quotes.
\end_layout

\begin_layout Standard
Example: typing 
\family typewriter
'%cd mydir'
\family default
 (without the quotes) changes you working directory to 
\family typewriter
'mydir'
\family default
, if it exists.
\end_layout

\begin_layout Standard
If you have 'automagic' enabled (in your 
\family typewriter
ipythonrc
\family default
 file, via the command line option 
\family typewriter
-automagic 
\family default
or with the 
\family typewriter
%automagic
\family default
 function), you don't need to type in the 
\family typewriter
%
\family default
 explicitly.
 IPython will scan its internal list of magic functions and call one if
 it exists.
 With automagic on you can then just type '
\family typewriter
cd mydir
\family default
' to go to directory '
\family typewriter
mydir
\family default
'.
 The automagic system has the lowest possible precedence in name searches,
 so defining an identifier with the same name as an existing magic function
 will shadow it for automagic use.
 You can still access the shadowed magic function by explicitly using the
 
\family typewriter
%
\family default
 character at the beginning of the line.
\end_layout

\begin_layout Standard
An example (with automagic on) should clarify all this:
\end_layout

\begin_layout LyX-Code
In [1]: cd ipython # %cd is called by automagic
\end_layout

\begin_layout LyX-Code
/home/fperez/ipython
\end_layout

\begin_layout LyX-Code
In [2]: cd=1 # now cd is just a variable
\end_layout

\begin_layout LyX-Code
In [3]: cd ..
 # and doesn't work as a function anymore
\end_layout

\begin_layout LyX-Code
------------------------------------------------------------
\end_layout

\begin_layout LyX-Code
    File "<console>", line 1
\end_layout

\begin_layout LyX-Code
      cd ..
\end_layout

\begin_layout LyX-Code
          ^
\end_layout

\begin_layout LyX-Code
SyntaxError: invalid syntax
\end_layout

\begin_layout LyX-Code

\end_layout

\begin_layout LyX-Code
In [4]: %cd ..
 # but %cd always works
\end_layout

\begin_layout LyX-Code
/home/fperez
\end_layout

\begin_layout LyX-Code
In [5]: del cd # if you remove the cd variable
\end_layout

\begin_layout LyX-Code
In [6]: cd ipython # automagic can work again
\end_layout

\begin_layout LyX-Code
/home/fperez/ipython
\end_layout

\begin_layout Standard
You can define your own magic functions to extend the system.
 The following example defines a new magic command, 
\family typewriter
%impall
\family default
:
\end_layout

\begin_layout LyX-Code
import IPython.ipapi 
\end_layout

\begin_layout LyX-Code
ip = IPython.ipapi.get()
\end_layout

\begin_layout LyX-Code

\end_layout

\begin_layout LyX-Code
def doimp(self, arg):
\end_layout

\begin_layout LyX-Code
    ip = self.api
\end_layout

\begin_layout LyX-Code
    ip.ex("import %s; reload(%s); from %s import *" % (
\end_layout

\begin_layout LyX-Code
    arg,arg,arg)
\end_layout

\begin_layout LyX-Code
    )
\end_layout

\begin_layout LyX-Code
ip.expose_magic('impall', doimp)
\end_layout

\begin_layout Standard
You can also define your own aliased names for magic functions.
 In your 
\family typewriter
ipythonrc
\family default
 file, placing a line like:
\end_layout

\begin_layout Standard

\family typewriter
execute __IP.magic_cl = __IP.magic_clear
\end_layout

\begin_layout Standard
will define 
\family typewriter
%cl
\family default
 as a new name for 
\family typewriter
%clear
\family default
.
\end_layout

\begin_layout Standard
Type 
\family typewriter
%magic
\family default
 for more information, including a list of all available magic functions
 at any time and their docstrings.
 You can also type 
\family typewriter
%magic_function_name?
\family default
 (see sec.
 
\begin_inset LatexCommand \ref{sec:dyn-object-info}

\end_inset

 for information on the 
\family typewriter
'?'
\family default
 system) to get information about any particular magic function you are
 interested in.
\end_layout

\begin_layout Subsubsection
Magic commands
\end_layout

\begin_layout Standard
The rest of this section is automatically generated for each release from
 the docstrings in the IPython code.
 Therefore the formatting is somewhat minimal, but this method has the advantage
 of having information always in sync with the code.
\end_layout

\begin_layout Standard
A list of all the magic commands available in IPython's 
\emph on
default
\emph default
 installation follows.
 This is similar to what you'll see by simply typing 
\family typewriter
%magic
\family default
 at the prompt, but that will also give you information about magic commands
 you may have added as part of your personal customizations.
\end_layout

\begin_layout Standard
\begin_inset Include \input{magic.tex}
preview false

\end_inset


\end_layout

\begin_layout Subsection
Access to the standard Python help
\end_layout

\begin_layout Standard
As of Python 2.1, a help system is available with access to object docstrings
 and the Python manuals.
 Simply type 
\family typewriter
'help'
\family default
 (no quotes) to access it.
 You can also type 
\family typewriter
help(object)
\family default
 to obtain information about a given object, and 
\family typewriter
help('keyword')
\family default
 for information on a keyword.
 As noted in sec.
 
\begin_inset LatexCommand \ref{sec:help-access}

\end_inset

, you need to properly configure your environment variable 
\family typewriter
PYTHONDOCS
\family default
 for this feature to work correctly.
\end_layout

\begin_layout Subsection
\begin_inset LatexCommand \label{sec:dyn-object-info}

\end_inset

Dynamic object information
\end_layout

\begin_layout Standard
Typing 
\family typewriter
?word
\family default
 or 
\family typewriter
word?
\family default
 prints detailed information about an object.
 If certain strings in the object are too long (docstrings, code, etc.) they
 get snipped in the center for brevity.
 This system gives access variable types and values, full source code for
 any object (if available), function prototypes and other useful information.
\end_layout

\begin_layout Standard
Typing 
\family typewriter
??word
\family default
 or 
\family typewriter
word??
\family default
 gives access to the full information without snipping long strings.
 Long strings are sent to the screen through the 
\family typewriter
less
\family default
 pager if longer than the screen and printed otherwise.
 On systems lacking the 
\family typewriter
less
\family default
 command, IPython uses a very basic internal pager.
\end_layout

\begin_layout Standard
The following magic functions are particularly useful for gathering information
 about your working environment.
 You can get more details by typing 
\family typewriter
%magic
\family default
 or querying them individually (use 
\family typewriter
%function_name?
\family default
 with or without the 
\family typewriter
%
\family default
), this is just a summary:
\end_layout

\begin_layout List
\labelwidthstring 00.00.0000

\family typewriter
\series bold
%pdoc\InsetSpace ~
<object>
\family default
\series default
: Print (or run through a pager if too long) the docstring for an object.
 If the given object is a class, it will print both the class and the constructo
r docstrings.
\end_layout

\begin_layout List
\labelwidthstring 00.00.0000

\family typewriter
\series bold
%pdef\InsetSpace ~
<object>
\family default
\series default
: Print the definition header for any callable object.
 If the object is a class, print the constructor information.
\end_layout

\begin_layout List
\labelwidthstring 00.00.0000

\family typewriter
\series bold
%psource\InsetSpace ~
<object>
\family default
\series default
: Print (or run through a pager if too long) the source code for an object.
\end_layout

\begin_layout List
\labelwidthstring 00.00.0000

\family typewriter
\series bold
%pfile\InsetSpace ~
<object>
\family default
\series default
: Show the entire source file where an object was defined via a pager, opening
 it at the line where the object definition begins.
\end_layout

\begin_layout List
\labelwidthstring 00.00.0000

\family typewriter
\series bold
%who/%whos
\family default
\series default
: These functions give information about identifiers you have defined interactiv
ely (not things you loaded or defined in your configuration files).
 
\family typewriter
%who
\family default
 just prints a list of identifiers and 
\family typewriter
%whos
\family default
 prints a table with some basic details about each identifier.
\end_layout

\begin_layout Standard
Note that the dynamic object information functions (
\family typewriter
?/??, %pdoc, %pfile, %pdef, %psource
\family default
) give you access to documentation even on things which are not really defined
 as separate identifiers.
 Try for example typing 
\family typewriter
{}.get?
\family default
 or after doing 
\family typewriter
import os
\family default
, type 
\family typewriter
os.path.abspath??
\family default
.
\end_layout

\begin_layout Subsection
\begin_inset LatexCommand \label{sec:readline}

\end_inset

Readline-based features
\end_layout

\begin_layout Standard
These features require the GNU readline library, so they won't work if your
 Python installation lacks readline support.
 We will first describe the default behavior IPython uses, and then how
 to change it to suit your preferences.
\end_layout

\begin_layout Subsubsection
Command line completion
\end_layout

\begin_layout Standard
At any time, hitting TAB will complete any available python commands or
 variable names, and show you a list of the possible completions if there's
 no unambiguous one.
 It will also complete filenames in the current directory if no python names
 match what you've typed so far.
\end_layout

\begin_layout Subsubsection
Search command history
\end_layout

\begin_layout Standard
IPython provides two ways for searching through previous input and thus
 reduce the need for repetitive typing:
\end_layout

\begin_layout Enumerate
Start typing, and then use 
\family typewriter
Ctrl-p
\family default
 (previous,up) and 
\family typewriter
Ctrl-n
\family default
 (next,down) to search through only the history items that match what you've
 typed so far.
 If you use 
\family typewriter
Ctrl-p/Ctrl-n
\family default
 at a blank prompt, they just behave like normal arrow keys.
\end_layout

\begin_layout Enumerate
Hit 
\family typewriter
Ctrl-r
\family default
: opens a search prompt.
 Begin typing and the system searches your history for lines that contain
 what you've typed so far, completing as much as it can.
\end_layout

\begin_layout Subsubsection
Persistent command history across sessions
\end_layout

\begin_layout Standard
IPython will save your input history when it leaves and reload it next time
 you restart it.
 By default, the history file is named 
\family typewriter
$IPYTHONDIR/history
\family default
, but if you've loaded a named profile, '
\family typewriter
-PROFILE_NAME
\family default
' is appended to the name.
 This allows you to keep separate histories related to various tasks: commands
 related to numerical work will not be clobbered by a system shell history,
 for example.
\end_layout

\begin_layout Subsubsection
Autoindent
\end_layout

\begin_layout Standard
IPython can recognize lines ending in ':' and indent the next line, while
 also un-indenting automatically after 'raise' or 'return'.
 
\end_layout

\begin_layout Standard
This feature uses the readline library, so it will honor your 
\family typewriter
~/.inputrc
\family default
 configuration (or whatever file your 
\family typewriter
INPUTRC
\family default
 variable points to).
 Adding the following lines to your 
\family typewriter
.inputrc
\family default
 file can make indenting/unindenting more convenient (
\family typewriter
M-i
\family default
 indents, 
\family typewriter
M-u
\family default
 unindents):
\end_layout

\begin_layout Standard

\family typewriter
$if Python
\newline
"
\backslash
M-i": "\InsetSpace ~
\InsetSpace ~
\InsetSpace ~
\InsetSpace ~
" 
\newline
"
\backslash
M-u": "
\backslash
d
\backslash
d
\backslash
d
\backslash
d" 
\newline
$endif
\end_layout

\begin_layout Standard
Note that there are 4 spaces between the quote marks after 
\family typewriter
"M-i"
\family default
 above.
\end_layout

\begin_layout Standard

\series bold
Warning:
\series default
 this feature is ON by default, but it can cause problems with the pasting
 of multi-line indented code (the pasted code gets re-indented on each line).
 A magic function 
\family typewriter
%autoindent
\family default
 allows you to toggle it on/off at runtime.
 You can also disable it permanently on in your 
\family typewriter
ipythonrc
\family default
 file (set 
\family typewriter
autoindent 0
\family default
).
\end_layout

\begin_layout Subsubsection
Customizing readline behavior
\end_layout

\begin_layout Standard
All these features are based on the GNU readline library, which has an extremely
 customizable interface.
 Normally, readline is configured via a file which defines the behavior
 of the library; the details of the syntax for this can be found in the
 readline documentation available with your system or on the Internet.
 IPython doesn't read this file (if it exists) directly, but it does support
 passing to readline valid options via a simple interface.
 In brief, you can customize readline by setting the following options in
 your 
\family typewriter
ipythonrc
\family default
 configuration file (note that these options can 
\emph on
not
\emph default
 be specified at the command line):
\end_layout

\begin_layout List
\labelwidthstring 00.00.0000

\family typewriter
\series bold
readline_parse_and_bind:
\family default
\series default
 this option can appear as many times as you want, each time defining a
 string to be executed via a 
\family typewriter
readline.parse_and_bind()
\family default
 command.
 The syntax for valid commands of this kind can be found by reading the
 documentation for the GNU readline library, as these commands are of the
 kind which readline accepts in its configuration file.
\end_layout

\begin_layout List
\labelwidthstring 00.00.0000

\family typewriter
\series bold
readline_remove_delims:
\family default
\series default
 a string of characters to be removed from the default word-delimiters list
 used by readline, so that completions may be performed on strings which
 contain them.
 Do not change the default value unless you know what you're doing.
\end_layout

\begin_layout List
\labelwidthstring 00.00.0000

\family typewriter
\series bold
readline_omit__names
\family default
\series default
: when tab-completion is enabled, hitting 
\family typewriter
<tab>
\family default
 after a '
\family typewriter
.
\family default
' in a name will complete all attributes of an object, including all the
 special methods whose names include double underscores (like 
\family typewriter
__getitem__
\family default
 or 
\family typewriter
__class__
\family default
).
 If you'd rather not see these names by default, you can set this option
 to 1.
 Note that even when this option is set, you can still see those names by
 explicitly typing a 
\family typewriter
_
\family default
 after the period and hitting 
\family typewriter
<tab>
\family default
: '
\family typewriter
name._<tab>
\family default
' will always complete attribute names starting with '
\family typewriter
_
\family default
'.
\end_layout

\begin_layout List
\labelwidthstring 00.00.0000
\InsetSpace ~
 This option is off by default so that new users see all attributes of any
 objects they are dealing with.
\end_layout

\begin_layout Standard
You will find the default values along with a corresponding detailed explanation
 in your 
\family typewriter
ipythonrc
\family default
 file.
\end_layout

\begin_layout Subsection
Session logging and restoring
\end_layout

\begin_layout Standard
You can log all input from a session either by starting IPython with the
 command line switches 
\family typewriter
-log
\family default
 or 
\family typewriter
-logfile 
\family default
(see sec.
 
\begin_inset LatexCommand \ref{sec:cmd-line-opts}

\end_inset

)or by activating the logging at any moment with the magic function 
\family typewriter
%logstart
\family default
.
 
\end_layout

\begin_layout Standard
Log files can later be reloaded with the 
\family typewriter
-logplay
\family default
 option and IPython will attempt to 'replay' the log by executing all the
 lines in it, thus restoring the state of a previous session.
 This feature is not quite perfect, but can still be useful in many cases.
\end_layout

\begin_layout Standard
The log files can also be used as a way to have a permanent record of any
 code you wrote while experimenting.
 Log files are regular text files which you can later open in your favorite
 text editor to extract code or to 'clean them up' before using them to
 replay a session.
\end_layout

\begin_layout Standard
The 
\family typewriter
%logstart
\family default
 function for activating logging in mid-session is used as follows:
\end_layout

\begin_layout Standard

\family typewriter
%logstart [log_name [log_mode]]
\end_layout

\begin_layout Standard
If no name is given, it defaults to a file named 
\family typewriter
'log'
\family default
 in your IPYTHONDIR directory, in 
\family typewriter
'rotate'
\family default
 mode (see below).
\end_layout

\begin_layout Standard
'
\family typewriter
%logstart name
\family default
' saves to file 
\family typewriter
'name'
\family default
 in 
\family typewriter
'backup'
\family default
 mode.
 It saves your history up to that point and then continues logging.
\end_layout

\begin_layout Standard

\family typewriter
%logstart
\family default
 takes a second optional parameter: logging mode.
 This can be one of (note that the modes are given unquoted):
\end_layout

\begin_layout List
\labelwidthstring 00.00.0000

\family typewriter
over
\family default
: overwrite existing 
\family typewriter
log_name
\family default
.
\end_layout

\begin_layout List
\labelwidthstring 00.00.0000

\family typewriter
backup
\family default
: rename (if exists) to 
\family typewriter
log_name~
\family default
 and start 
\family typewriter
log_name
\family default
.
\end_layout

\begin_layout List
\labelwidthstring 00.00.0000

\family typewriter
append
\family default
: well, that says it.
\end_layout

\begin_layout List
\labelwidthstring 00.00.0000

\family typewriter
rotate
\family default
: create rotating logs 
\family typewriter
log_name
\family default
.
\family typewriter
1~
\family default
, 
\family typewriter
log_name.2~
\family default
, etc.
\end_layout

\begin_layout Standard
The 
\family typewriter
%logoff
\family default
 and 
\family typewriter
%logon
\family default
 functions allow you to temporarily stop and resume logging to a file which
 had previously been started with 
\family typewriter
%logstart
\family default
.
 They will fail (with an explanation) if you try to use them before logging
 has been started.
\end_layout

\begin_layout Subsection
\begin_inset LatexCommand \label{sub:System-shell-access}

\end_inset

System shell access
\end_layout

\begin_layout Standard
Any input line beginning with a 
\family typewriter
!
\family default
 character is passed verbatim (minus the 
\family typewriter
!
\family default
, of course) to the underlying operating system.
 For example, typing 
\family typewriter
!ls
\family default
 will run 
\family typewriter
'ls'
\family default
 in the current directory.
\end_layout

\begin_layout Subsubsection
Manual capture of command output
\end_layout

\begin_layout Standard
If the input line begins with 
\emph on
two
\emph default
 exclamation marks, 
\family typewriter
!!
\family default
, the command is executed but its output is captured and returned as a python
 list, split on newlines.
 Any output sent by the subprocess to standard error is printed separately,
 so that the resulting list only captures standard output.
 The 
\family typewriter
!!
\family default
 syntax is a shorthand for the 
\family typewriter
%sx
\family default
 magic command.
\end_layout

\begin_layout Standard
Finally, the 
\family typewriter
%sc
\family default
 magic (short for `shell capture') is similar to 
\family typewriter
%sx
\family default
, but allowing more fine-grained control of the capture details, and storing
 the result directly into a named variable.
\end_layout

\begin_layout Standard
See Sec.\InsetSpace ~

\begin_inset LatexCommand \ref{sec:magic}

\end_inset

 for details on the magics 
\family typewriter
%sc
\family default
 and 
\family typewriter
%sx
\family default
, or use IPython's own help (
\family typewriter
sc?
\family default
 and 
\family typewriter
sx?
\family default
) for further details.
\end_layout

\begin_layout Standard
IPython also allows you to expand the value of python variables when making
 system calls.
 Any python variable or expression which you prepend with 
\family typewriter
$
\family default
 will get expanded before the system call is made.
 
\end_layout

\begin_layout Standard

\family typewriter
In [1]: pyvar='Hello world'
\newline
In [2]: !echo "A python variable: $pyvar" 
\newline
A python
 variable: Hello world
\end_layout

\begin_layout Standard
If you want the shell to actually see a literal 
\family typewriter
$
\family default
, you need to type it twice:
\end_layout

\begin_layout Standard

\family typewriter
In [3]: !echo "A system variable: $$HOME" 
\newline
A system variable: /home/fperez
\end_layout

\begin_layout Standard
You can pass arbitrary expressions, though you'll need to delimit them with
 
\family typewriter
{}
\family default
 if there is ambiguity as to the extent of the expression:
\end_layout

\begin_layout Standard

\family typewriter
In [5]: x=10
\newline
In [6]: y=20
\newline
In [13]: !echo $x+y 
\newline
10+y 
\newline
In [7]: !echo ${x+y} 
\newline
30
 
\end_layout

\begin_layout Standard
Even object attributes can be expanded:
\end_layout

\begin_layout Standard

\family typewriter
In [12]: !echo $sys.argv 
\newline
[/home/fperez/usr/bin/ipython] 
\end_layout

\begin_layout Subsection
System command aliases
\end_layout

\begin_layout Standard
The 
\family typewriter
%alias
\family default
 magic function and the 
\family typewriter
alias
\family default
 option in the 
\family typewriter
ipythonrc
\family default
 configuration file allow you to define magic functions which are in fact
 system shell commands.
 These aliases can have parameters.
 
\end_layout

\begin_layout Standard
'
\family typewriter
%alias alias_name cmd
\family default
' defines '
\family typewriter
alias_name
\family default
' as an alias for '
\family typewriter
cmd
\family default
' 
\end_layout

\begin_layout Standard
Then, typing '
\family typewriter
%alias_name params
\family default
' will execute the system command '
\family typewriter
cmd params
\family default
' (from your underlying operating system).
 
\end_layout

\begin_layout Standard
You can also define aliases with parameters using 
\family typewriter
%s
\family default
 specifiers (one per parameter).
 The following example defines the 
\family typewriter
%parts
\family default
 function as an alias to the command '
\family typewriter
echo first %s second %s
\family default
' where each 
\family typewriter
%s
\family default
 will be replaced by a positional parameter to the call to 
\family typewriter
%parts:
\end_layout

\begin_layout Standard

\family typewriter
In [1]: alias parts echo first %s second %s
\newline
In [2]: %parts A B
\newline
first A second
 B 
\newline
In [3]: %parts A 
\newline
Incorrect number of arguments: 2 expected.
 
\newline
parts is an alias to: 'echo first %s second %s' 
\end_layout

\begin_layout Standard
If called with no parameters, 
\family typewriter
%alias
\family default
 prints the table of currently defined aliases.
\end_layout

\begin_layout Standard
The 
\family typewriter
%rehash/rehashx
\family default
 magics allow you to load your entire 
\family typewriter
$PATH
\family default
 as ipython aliases.
 See their respective docstrings (or sec.\InsetSpace ~

\begin_inset LatexCommand \ref{sec:magic}

\end_inset

 for further details).
\end_layout

\begin_layout Subsection
\begin_inset LatexCommand \label{sec:dreload}

\end_inset

Recursive reload
\end_layout

\begin_layout Standard
The 
\family typewriter
dreload
\family default
 function does a recursive reload of a module: changes made to the module
 since you imported will actually be available without having to exit.
\end_layout

\begin_layout Subsection
Verbose and colored exception traceback printouts
\end_layout

\begin_layout Standard
IPython provides the option to see very detailed exception tracebacks, which
 can be especially useful when debugging large programs.
 You can run any Python file with the 
\family typewriter
%run
\family default
 function to benefit from these detailed tracebacks.
 Furthermore, both normal and verbose tracebacks can be colored (if your
 terminal supports it) which makes them much easier to parse visually.
\end_layout

\begin_layout Standard
See the magic 
\family typewriter
xmode
\family default
 and 
\family typewriter
colors
\family default
 functions for details (just type 
\family typewriter
%magic
\family default
).
\end_layout

\begin_layout Standard
These features are basically a terminal version of Ka-Ping Yee's 
\family typewriter
cgitb
\family default
 module, now part of the standard Python library.
\end_layout

\begin_layout Subsection
\begin_inset LatexCommand \label{sec:cache_input}

\end_inset

Input caching system
\end_layout

\begin_layout Standard
IPython offers numbered prompts (In/Out) with input and output caching.
 All input is saved and can be retrieved as variables (besides the usual
 arrow key recall).
\end_layout

\begin_layout Standard
The following GLOBAL variables always exist (so don't overwrite them!):
 
\family typewriter
_i
\family default
: stores previous input.
 
\family typewriter
_ii
\family default
: next previous.
 
\family typewriter
_iii
\family default
: next-next previous.
 
\family typewriter
_ih
\family default
 : a list of all input 
\family typewriter
_ih[n]
\family default
 is the input from line 
\family typewriter
n
\family default
 and this list is aliased to the global variable 
\family typewriter
In
\family default
.
 If you overwrite 
\family typewriter
In
\family default
 with a variable of your own, you can remake the assignment to the internal
 list with a simple 
\family typewriter
'In=_ih'
\family default
.
\end_layout

\begin_layout Standard
Additionally, global variables named 
\family typewriter
_i<n>
\family default
 are dynamically created (
\family typewriter
<n>
\family default
 being the prompt counter), such that 
\newline

\family typewriter
_i<n> == _ih[<n>] == In[<n>].
\end_layout

\begin_layout Standard
For example, what you typed at prompt 14 is available as 
\family typewriter
_i14,
\family default
 
\family typewriter
_ih[14]
\family default
 and 
\family typewriter
In[14]
\family default
.
\end_layout

\begin_layout Standard
This allows you to easily cut and paste multi line interactive prompts by
 printing them out: they print like a clean string, without prompt characters.
 You can also manipulate them like regular variables (they are strings),
 modify or exec them (typing 
\family typewriter
'exec _i9'
\family default
 will re-execute the contents of input prompt 9, '
\family typewriter
exec In[9:14]+In[18]
\family default
' will re-execute lines 9 through 13 and line 18).
\end_layout

\begin_layout Standard
You can also re-execute multiple lines of input easily by using the magic
 
\family typewriter
%macro
\family default
 function (which automates the process and allows re-execution without having
 to type '
\family typewriter
exec
\family default
' every time).
 The macro system also allows you to re-execute previous lines which include
 magic function calls (which require special processing).
 Type 
\family typewriter
%macro?
\family default
 or see sec.
 
\begin_inset LatexCommand \ref{sec:magic}

\end_inset

 for more details on the macro system.
\end_layout

\begin_layout Standard
A history function 
\family typewriter
%hist
\family default
 allows you to see any part of your input history by printing a range of
 the 
\family typewriter
_i
\family default
 variables.
\end_layout

\begin_layout Subsection
\begin_inset LatexCommand \label{sec:cache_output}

\end_inset

Output caching system
\end_layout

\begin_layout Standard
For output that is returned from actions, a system similar to the input
 cache exists but using 
\family typewriter
_
\family default
 instead of 
\family typewriter
_i
\family default
.
 Only actions that produce a result (NOT assignments, for example) are cached.
 If you are familiar with Mathematica, IPython's 
\family typewriter
_
\family default
 variables behave exactly like Mathematica's 
\family typewriter
%
\family default
 variables.
\end_layout

\begin_layout Standard
The following GLOBAL variables always exist (so don't overwrite them!):
 
\end_layout

\begin_layout List
\labelwidthstring 00.00.0000

\family typewriter
\series bold
_
\family default
\series default
 (a 
\emph on
single
\emph default
 underscore) : stores previous output, like Python's default interpreter.
\end_layout

\begin_layout List
\labelwidthstring 00.00.0000

\family typewriter
\series bold
__
\family default
\series default
 (two underscores): next previous.
\end_layout

\begin_layout List
\labelwidthstring 00.00.0000

\family typewriter
\series bold
___
\family default
\series default
 (three underscores): next-next previous.
\end_layout

\begin_layout Standard
Additionally, global variables named 
\family typewriter
_<n> 
\family default
are dynamically created (
\family typewriter
<n>
\family default
 being the prompt counter), such that the result of output 
\family typewriter
<n>
\family default
 is always available as 
\family typewriter
_<n>
\family default
 (don't use the angle brackets, just the number, e.g.
 
\family typewriter
_21
\family default
).
\end_layout

\begin_layout Standard
These global variables are all stored in a global dictionary (not a list,
 since it only has entries for lines which returned a result) available
 under the names 
\family typewriter
_oh
\family default
 and 
\family typewriter
Out
\family default
 (similar to 
\family typewriter
_ih
\family default
 and 
\family typewriter
In
\family default
).
 So the output from line 12 can be obtained as 
\family typewriter
_12
\family default
, 
\family typewriter
Out[12]
\family default
 or 
\family typewriter
_oh[12]
\family default
.
 If you accidentally overwrite the 
\family typewriter
Out
\family default
 variable you can recover it by typing 
\family typewriter
'Out=_oh
\family default
' at the prompt.
\end_layout

\begin_layout Standard
This system obviously can potentially put heavy memory demands on your system,
 since it prevents Python's garbage collector from removing any previously
 computed results.
 You can control how many results are kept in memory with the option (at
 the command line or in your 
\family typewriter
ipythonrc
\family default
 file) 
\family typewriter
cache_size
\family default
.
 If you set it to 0, the whole system is completely disabled and the prompts
 revert to the classic 
\family typewriter
'>>>'
\family default
 of normal Python.
\end_layout

\begin_layout Subsection
Directory history
\end_layout

\begin_layout Standard
Your history of visited directories is kept in the global list 
\family typewriter
_dh
\family default
, and the magic 
\family typewriter
%cd
\family default
 command can be used to go to any entry in that list.
 The 
\family typewriter
%dhist
\family default
 command allows you to view this history.
\end_layout

\begin_layout Subsection
Automatic parentheses and quotes
\end_layout

\begin_layout Standard
These features were adapted from Nathan Gray's LazyPython.
 They are meant to allow less typing for common situations.
\end_layout

\begin_layout Subsubsection
Automatic parentheses
\end_layout

\begin_layout Standard
Callable objects (i.e.
 functions, methods, etc) can be invoked like this (notice the commas between
 the arguments):
\end_layout

\begin_layout Standard

\family typewriter
>>> callable_ob arg1, arg2, arg3 
\end_layout

\begin_layout Standard
and the input will be translated to this: 
\end_layout

\begin_layout Standard

\family typewriter
--> callable_ob(arg1, arg2, arg3) 
\end_layout

\begin_layout Standard
You can force automatic parentheses by using '/' as the first character
 of a line.
 For example:
\end_layout

\begin_layout Standard

\family typewriter
>>> /globals # becomes 'globals()' 
\end_layout

\begin_layout Standard
Note that the '/' MUST be the first character on the line! This won't work:
 
\end_layout

\begin_layout Standard

\family typewriter
>>> print /globals # syntax error
\end_layout

\begin_layout Standard
In most cases the automatic algorithm should work, so you should rarely
 need to explicitly invoke /.
 One notable exception is if you are trying to call a function with a list
 of tuples as arguments (the parenthesis will confuse IPython): 
\end_layout

\begin_layout Standard

\family typewriter
In [1]: zip (1,2,3),(4,5,6) # won't work 
\end_layout

\begin_layout Standard
but this will work: 
\end_layout

\begin_layout Standard

\family typewriter
In [2]: /zip (1,2,3),(4,5,6)
\newline
------> zip ((1,2,3),(4,5,6)) 
\newline
Out[2]= [(1, 4),
 (2, 5), (3, 6)] 
\end_layout

\begin_layout Standard
IPython tells you that it has altered your command line by displaying the
 new command line preceded by 
\family typewriter
-->
\family default
.
 e.g.: 
\end_layout

\begin_layout Standard

\family typewriter
In [18]: callable list
\newline
-------> callable (list)
\end_layout

\begin_layout Subsubsection
Automatic quoting 
\end_layout

\begin_layout Standard
You can force automatic quoting of a function's arguments by using 
\family typewriter
`,'
\family default
 or 
\family typewriter
`;'
\family default
 as the first character of a line.
 For example: 
\end_layout

\begin_layout Standard

\family typewriter
>>> ,my_function /home/me # becomes my_function("/home/me") 
\end_layout

\begin_layout Standard
If you use 
\family typewriter
`;'
\family default
 instead, the whole argument is quoted as a single string (while 
\family typewriter
`,'
\family default
 splits on whitespace):
\end_layout

\begin_layout Standard

\family typewriter
>>> ,my_function a b c # becomes my_function("a","b","c")
\end_layout

\begin_layout Standard

\family typewriter
>>> ;my_function a b c # becomes my_function("a b c")
\end_layout

\begin_layout Standard
Note that the `
\family typewriter
,
\family default
' or `
\family typewriter
;
\family default
' MUST be the first character on the line! This won't work: 
\end_layout

\begin_layout Standard

\family typewriter
>>> x = ,my_function /home/me # syntax error
\end_layout

\begin_layout Section
\begin_inset LatexCommand \label{sec:customization}

\end_inset

Customization
\end_layout

\begin_layout Standard
As we've already mentioned, IPython reads a configuration file which can
 be specified at the command line (
\family typewriter
-rcfile
\family default
) or which by default is assumed to be called 
\family typewriter
ipythonrc
\family default
.
 Such a file is looked for in the current directory where IPython is started
 and then in your 
\family typewriter
IPYTHONDIR
\family default
, which allows you to have local configuration files for specific projects.
 In this section we will call these types of configuration files simply
 rcfiles (short for resource configuration file).
\end_layout

\begin_layout Standard
The syntax of an rcfile is one of key-value pairs separated by whitespace,
 one per line.
 Lines beginning with a 
\family typewriter
#
\family default
 are ignored as comments, but comments can 
\series bold
not
\series default
 be put on lines with data (the parser is fairly primitive).
 Note that these are not python files, and this is deliberate, because it
 allows us to do some things which would be quite tricky to implement if
 they were normal python files.
\end_layout

\begin_layout Standard
First, an rcfile can contain permanent default values for almost all command
 line options (except things like 
\family typewriter
-help
\family default
 or 
\family typewriter
-Version
\family default
).
 Sec\InsetSpace ~

\begin_inset LatexCommand \ref{sec:cmd-line-opts}

\end_inset

 contains a description of all command-line options.
 However, values you explicitly specify at the command line override the
 values defined in the rcfile.
\end_layout

\begin_layout Standard
Besides command line option values, the rcfile can specify values for certain
 extra special options which are not available at the command line.
 These options are briefly described below.
 
\end_layout

\begin_layout Standard
Each of these options may appear as many times as you need it in the file.
\end_layout

\begin_layout List
\labelwidthstring 00.00.0000

\family typewriter
\series bold
include\InsetSpace ~
<file1>\InsetSpace ~
<file2>\InsetSpace ~
...
\family default
\series default
: you can name 
\emph on
other 
\emph default
rcfiles you want to recursively load up to 15 levels (don't use the 
\family typewriter
<>
\family default
 brackets in your names!).
 This feature allows you to define a 'base' rcfile with general options
 and special-purpose files which can be loaded only when needed with particular
 configuration options.
 To make this more convenient, IPython accepts the 
\family typewriter
-profile <name>
\family default
 option (abbreviates to 
\family typewriter
-p <name
\family default
>)
\family typewriter
 which
\family default
 tells it to look for an rcfile named 
\family typewriter
ipythonrc-<name>
\family default
.
 
\end_layout

\begin_layout List
\labelwidthstring 00.00.0000

\family typewriter
\series bold
import_mod\InsetSpace ~
<mod1>\InsetSpace ~
<mod2>\InsetSpace ~
...
\family default
\series default
: import modules with '
\family typewriter
import
\family default
 
\family typewriter
<mod1>,<mod2>,...
\family default
' 
\end_layout

\begin_layout List
\labelwidthstring 00.00.0000

\family typewriter
\series bold
import_some\InsetSpace ~
<mod>\InsetSpace ~
<f1>\InsetSpace ~
<f2>\InsetSpace ~
...
\family default
\series default
: import functions with '
\family typewriter
from <mod> import
\family default
 
\family typewriter
<f1>,<f2>,...
\family default
' 
\end_layout

\begin_layout List
\labelwidthstring 00.00.0000

\family typewriter
\series bold
import_all\InsetSpace ~
<mod1>\InsetSpace ~
<mod2>\InsetSpace ~
...
\family default
\series default
: for each module listed import functions with '
\family typewriter
from <mod> import *
\family default
' 
\end_layout

\begin_layout List
\labelwidthstring 00.00.0000

\family typewriter
\series bold
execute\InsetSpace ~
<python\InsetSpace ~
code>
\family default
\series default
: give any single-line python code to be executed.
\end_layout

\begin_layout List
\labelwidthstring 00.00.0000

\family typewriter
\series bold
execfile\InsetSpace ~
<filename>
\family default
\series default
: execute the python file given with an '
\family typewriter
execfile(filename)
\family default
' command.
 Username expansion is performed on the given names.
 So if you need any amount of extra fancy customization that won't fit in
 any of the above 'canned' options, you can just put it in a separate python
 file and execute it.
\end_layout

\begin_layout List
\labelwidthstring 00.00.0000

\family typewriter
\series bold
alias\InsetSpace ~
<alias_def>
\family default
\series default
: this is equivalent to calling '
\family typewriter
%alias\InsetSpace ~
<alias_def>
\family default
' at the IPython command line.
 This way, from within IPython you can do common system tasks without having
 to exit it or use the 
\family typewriter
!
\family default
 escape.
 IPython isn't meant to be a shell replacement, but it is often very useful
 to be able to do things with files while testing code.
 This gives you the flexibility to have within IPython any aliases you may
 be used to under your normal system shell.
\end_layout

\begin_layout Subsection
\begin_inset LatexCommand \label{sec:ipytonrc-sample}

\end_inset

Sample 
\family typewriter
ipythonrc
\family default
 file
\end_layout

\begin_layout Standard
The default rcfile, called 
\family typewriter
ipythonrc
\family default
 and supplied in your 
\family typewriter
IPYTHONDIR 
\family default
directory contains lots of comments on all of these options.
 We reproduce it here for reference:
\end_layout

\begin_layout Standard
\begin_inset ERT
status open

\begin_layout Standard


\backslash
codelist{../IPython/UserConfig/ipythonrc}
\end_layout

\end_inset


\end_layout

\begin_layout Subsection
\begin_inset LatexCommand \label{sec:prompts}

\end_inset

Fine-tuning your prompt
\end_layout

\begin_layout Standard
IPython's prompts can be customized using a syntax similar to that of the
 
\family typewriter
bash
\family default
 shell.
 Many of 
\family typewriter
bash
\family default
's escapes are supported, as well as a few additional ones.
 We list them below:
\end_layout

\begin_layout Description

\backslash
# the prompt/history count number.
 This escape is automatically wrapped in the coloring codes for the currently
 active color scheme.
\end_layout

\begin_layout Description

\backslash
N the 'naked' prompt/history count number: this is just the number itself,
 without any coloring applied to it.
 This lets you produce numbered prompts with your own colors.
\end_layout

\begin_layout Description

\backslash
D the prompt/history count, with the actual digits replaced by dots.
 Used mainly in continuation prompts (prompt_in2)
\end_layout

\begin_layout Description

\backslash
w the current working directory
\end_layout

\begin_layout Description

\backslash
W the basename of current working directory
\end_layout

\begin_layout Description

\backslash
X
\emph on
n
\emph default
 where 
\begin_inset Formula $n=0\ldots5.$
\end_inset

 The current working directory, with 
\family typewriter
$HOME
\family default
 replaced by 
\family typewriter
~
\family default
, and filtered out to contain only 
\begin_inset Formula $n$
\end_inset

 path elements
\end_layout

\begin_layout Description

\backslash
Y
\emph on
n
\emph default
 Similar to 
\backslash
X
\emph on
n
\emph default
, but with the 
\begin_inset Formula $n+1$
\end_inset

 element included if it is 
\family typewriter
~
\family default
 (this is similar to the behavior of the %c
\emph on
n
\emph default
 escapes in 
\family typewriter
tcsh
\family default
)
\end_layout

\begin_layout Description

\backslash
u the username of the current user
\end_layout

\begin_layout Description

\backslash
$ if the effective UID is 0, a #, otherwise a $
\end_layout

\begin_layout Description

\backslash
h the hostname up to the first `.'
\end_layout

\begin_layout Description

\backslash
H the hostname
\end_layout

\begin_layout Description

\backslash
n a newline
\end_layout

\begin_layout Description

\backslash
r a carriage return
\end_layout

\begin_layout Description

\backslash
v IPython version string
\end_layout

\begin_layout Standard
In addition to these, ANSI color escapes can be insterted into the prompts,
 as 
\family typewriter

\backslash
C_
\emph on
ColorName
\family default
\emph default
.
 The list of valid color names is: Black, Blue, Brown, Cyan, DarkGray, Green,
 LightBlue, LightCyan, LightGray, LightGreen, LightPurple, LightRed, NoColor,
 Normal, Purple, Red, White, Yellow.
\end_layout

\begin_layout Standard
Finally, IPython supports the evaluation of arbitrary expressions in your
 prompt string.
 The prompt strings are evaluated through the syntax of PEP 215, but basically
 you can use 
\family typewriter
$x.y
\family default
 to expand the value of 
\family typewriter
x.y
\family default
, and for more complicated expressions you can use braces: 
\family typewriter
${foo()+x}
\family default
 will call function 
\family typewriter
foo
\family default
 and add to it the value of 
\family typewriter
x
\family default
, before putting the result into your prompt.
 For example, using 
\newline

\family typewriter
prompt_in1 '${commands.getoutput("uptime")}
\backslash
nIn [
\backslash
#]: '
\newline

\family default
will print the result of the uptime command on each prompt (assuming the
 
\family typewriter
commands
\family default
 module has been imported in your 
\family typewriter
ipythonrc
\family default
 file).
\end_layout

\begin_layout Subsubsection
Prompt examples
\end_layout

\begin_layout Standard
The following options in an ipythonrc file will give you IPython's default
 prompts:
\end_layout

\begin_layout Standard

\family typewriter
prompt_in1 'In [
\backslash
#]:'
\newline
prompt_in2 '\InsetSpace ~
\InsetSpace ~
\InsetSpace ~
.
\backslash
D.:'
\newline
prompt_out 'Out[
\backslash
#]:'
\end_layout

\begin_layout Standard
which look like this:
\end_layout

\begin_layout Standard

\family typewriter
In [1]: 1+2
\newline
Out[1]: 3
\end_layout

\begin_layout Standard

\family typewriter
In [2]: for i in (1,2,3):
\newline

\begin_inset ERT
status collapsed

\begin_layout Standard


\backslash
hspace*{0mm}
\end_layout

\end_inset

\InsetSpace ~
\InsetSpace ~
\InsetSpace ~
...: \InsetSpace ~
\InsetSpace ~
\InsetSpace ~
\InsetSpace ~
print i,
\newline

\begin_inset ERT
status collapsed

\begin_layout Standard


\backslash
hspace*{0mm}
\end_layout

\end_inset

\InsetSpace ~
\InsetSpace ~
\InsetSpace ~
...:
\newline
1 2 3
\end_layout

\begin_layout Standard
These will give you a very colorful prompt with path information:
\end_layout

\begin_layout Standard

\family typewriter
#prompt_in1 '
\backslash
C_Red
\backslash
u
\backslash
C_Blue[
\backslash
C_Cyan
\backslash
Y1
\backslash
C_Blue]
\backslash
C_LightGreen
\backslash
#>'
\newline
prompt_in2 ' ..
\backslash
D>'
\newline
prompt_out '<
\backslash
#>' 
\end_layout

\begin_layout Standard
which look like this:
\end_layout

\begin_layout Standard

\family typewriter
\color red
fperez
\color blue
[
\color cyan
~/ipython
\color blue
]
\color green
1>
\color none
 1+2
\newline

\begin_inset ERT
status collapsed

\begin_layout Standard


\backslash
hspace*{0mm}
\end_layout

\end_inset

\InsetSpace ~
\InsetSpace ~
\InsetSpace ~
\InsetSpace ~
\InsetSpace ~
\InsetSpace ~
\InsetSpace ~
\InsetSpace ~
\InsetSpace ~
\InsetSpace ~
\InsetSpace ~
\InsetSpace ~
\InsetSpace ~
\InsetSpace ~
\InsetSpace ~
\InsetSpace ~

\color red
<1>
\color none
 3
\newline

\color red
fperez
\color blue
[
\color cyan
~/ipython
\color blue
]
\color green
2>
\color none
 for i in (1,2,3):
\newline

\begin_inset ERT
status collapsed

\begin_layout Standard


\backslash
hspace*{0mm}
\end_layout

\end_inset

\InsetSpace ~
\InsetSpace ~
\InsetSpace ~
\InsetSpace ~
\InsetSpace ~
\InsetSpace ~
\InsetSpace ~
\InsetSpace ~
\InsetSpace ~
\InsetSpace ~
\InsetSpace ~
\InsetSpace ~
\InsetSpace ~
\InsetSpace ~
\InsetSpace ~

\color green
...>
\color none
 \InsetSpace ~
\InsetSpace ~
\InsetSpace ~
\InsetSpace ~
print i,
\newline

\begin_inset ERT
status collapsed

\begin_layout Standard


\backslash
hspace*{0mm}
\end_layout

\end_inset

\InsetSpace ~
\InsetSpace ~
\InsetSpace ~
\InsetSpace ~
\InsetSpace ~
\InsetSpace ~
\InsetSpace ~
\InsetSpace ~
\InsetSpace ~
\InsetSpace ~
\InsetSpace ~
\InsetSpace ~
\InsetSpace ~
\InsetSpace ~
\InsetSpace ~

\color green
...>
\color none

\newline
1 2 3
\end_layout

\begin_layout Standard
The following shows the usage of dynamic expression evaluation:
\end_layout

\begin_layout Subsection
\begin_inset LatexCommand \label{sec:profiles}

\end_inset

IPython profiles
\end_layout

\begin_layout Standard
As we already mentioned, IPython supports the 
\family typewriter
-profile
\family default
 command-line option (see sec.
 
\begin_inset LatexCommand \ref{sec:cmd-line-opts}

\end_inset

).
 A profile is nothing more than a particular configuration file like your
 basic 
\family typewriter
ipythonrc
\family default
 one, but with particular customizations for a specific purpose.
 When you start IPython with '
\family typewriter
ipython -profile <name>
\family default
', it assumes that in your 
\family typewriter
IPYTHONDIR
\family default
 there is a file called 
\family typewriter
ipythonrc-<name>
\family default
, and loads it instead of the normal 
\family typewriter
ipythonrc
\family default
.
\end_layout

\begin_layout Standard
This system allows you to maintain multiple configurations which load modules,
 set options, define functions, etc.
 suitable for different tasks and activate them in a very simple manner.
 In order to avoid having to repeat all of your basic options (common things
 that don't change such as your color preferences, for example), any profile
 can include another configuration file.
 The most common way to use profiles is then to have each one include your
 basic 
\family typewriter
ipythonrc
\family default
 file as a starting point, and then add further customizations.
\end_layout

\begin_layout Standard
In sections 
\begin_inset LatexCommand \ref{sec:syntax-extensions}

\end_inset

 and 
\begin_inset LatexCommand \ref{sec:Gnuplot}

\end_inset

 we discuss some particular profiles which come as part of the standard
 IPython distribution.
 You may also look in your 
\family typewriter
IPYTHONDIR
\family default
 directory, any file whose name begins with 
\family typewriter
ipythonrc-
\family default
 is a profile.
 You can use those as examples for further customizations to suit your own
 needs.
\end_layout

\begin_layout Section
\begin_inset OptArg
status open

\begin_layout Standard
IPython as default...
\end_layout

\end_inset

IPython as your default Python environment
\end_layout

\begin_layout Standard
Python honors the environment variable 
\family typewriter
PYTHONSTARTUP 
\family default
and will execute at startup the file referenced by this variable.
 If you put at the end of this file the following two lines of code:
\end_layout

\begin_layout Standard

\family typewriter
import IPython
\newline
IPython.Shell.IPShell().mainloop(sys_exit=1)
\end_layout

\begin_layout Standard
then IPython will be your working environment anytime you start Python.
 The 
\family typewriter
sys_exit=1
\family default
 is needed to have IPython issue a call to 
\family typewriter
sys.exit()
\family default
 when it finishes, otherwise you'll be back at the normal Python '
\family typewriter
>>>
\family default
' prompt
\begin_inset Foot
status collapsed

\begin_layout Standard
Based on an idea by Holger Krekel.
\end_layout

\end_inset

.
\end_layout

\begin_layout Standard
This is probably useful to developers who manage multiple Python versions
 and don't want to have correspondingly multiple IPython versions.
 Note that in this mode, there is no way to pass IPython any command-line
 options, as those are trapped first by Python itself.
\end_layout

\begin_layout Section
\begin_inset LatexCommand \label{sec:embed}

\end_inset

Embedding IPython
\end_layout

\begin_layout Standard
It is possible to start an IPython instance 
\emph on
inside
\emph default
 your own Python programs.
 This allows you to evaluate 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
 
\emph on
not
\emph default
 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.
\end_layout

\begin_layout Standard
This feature allows you to easily have a fully functional python environment
 for doing object introspection anywhere in your code with a simple function
 call.
 In some cases a simple print statement is enough, but if you need to do
 more detailed analysis of a code fragment this feature can be very valuable.
\end_layout

\begin_layout Standard
It can also be useful in scientific computing situations where it is common
 to need to do some automatic, computationally intensive part and then stop
 to look at data, plots, etc
\begin_inset Foot
status collapsed

\begin_layout Standard
This functionality was inspired by IDL's combination of the 
\family typewriter
stop
\family default
 keyword and the 
\family typewriter
.continue
\family default
 executive command, which I have found very useful in the past, and by a
 posting on comp.lang.python by cmkl <cmkleffner-AT-gmx.de> on Dec.
 06/01 concerning similar uses of pyrepl.
\end_layout

\end_inset

.
 Opening an IPython instance will give you full access to your data and
 functions, and you can resume program execution once you are done with
 the interactive part (perhaps to stop again later, as many times as needed).
\end_layout

\begin_layout Standard
The following code snippet is the bare minimum you need to include in your
 Python programs for this to work (detailed examples follow later):
\end_layout

\begin_layout LyX-Code
from IPython.Shell import IPShellEmbed
\end_layout

\begin_layout LyX-Code
ipshell = IPShellEmbed()
\end_layout

\begin_layout LyX-Code
ipshell() # this call anywhere in your program will start IPython
\end_layout

\begin_layout Standard
You can run embedded instances even in code which is itself being run at
 the IPython interactive prompt with '
\family typewriter
%run\InsetSpace ~
<filename>
\family default
'.
 Since it's easy to get lost as to where you are (in your top-level IPython
 or in your embedded one), it's a good idea in such cases to set the in/out
 prompts to something different for the embedded instances.
 The code examples below illustrate this.
\end_layout

\begin_layout Standard
You can also have multiple IPython instances in your program and open them
 separately, for example with different options for data presentation.
 If you close and open the same instance multiple times, its prompt counters
 simply continue from each execution to the next.
\end_layout

\begin_layout Standard
Please look at the docstrings in the 
\family typewriter
Shell.py
\family default
 module for more details on the use of this system.
\end_layout

\begin_layout Standard
The following sample file illustrating how to use the embedding functionality
 is provided in the examples directory as 
\family typewriter
example-embed.py
\family default
.
 It should be fairly self-explanatory:
\end_layout

\begin_layout Standard
\begin_inset ERT
status open

\begin_layout Standard


\backslash
codelist{examples/example-embed.py}
\end_layout

\end_inset


\end_layout

\begin_layout Standard
Once you understand how the system functions, you can use the following
 code fragments in your programs which are ready for cut and paste:
\end_layout

\begin_layout Standard
\begin_inset ERT
status open

\begin_layout Standard


\backslash
codelist{examples/example-embed-short.py}
\end_layout

\end_inset


\end_layout

\begin_layout Section
\begin_inset LatexCommand \label{sec:using-pdb}

\end_inset

Using the Python debugger (
\family typewriter
pdb
\family default
)
\end_layout

\begin_layout Subsection
Running entire programs via 
\family typewriter
pdb
\end_layout

\begin_layout Standard

\family typewriter
pdb
\family default
, the Python debugger, is a powerful interactive debugger which allows you
 to step through code, set breakpoints, watch variables, etc.
 IPython makes it very easy to start any script under the control of 
\family typewriter
pdb
\family default
, regardless of whether you have wrapped it into a 
\family typewriter
`main()'
\family default
 function or not.
 For this, simply type 
\family typewriter
`%run -d myscript'
\family default
 at an IPython prompt.
 See the 
\family typewriter
%run
\family default
 command's documentation (via 
\family typewriter
`%run?'
\family default
 or in Sec.\InsetSpace ~

\begin_inset LatexCommand \ref{sec:magic}

\end_inset

) for more details, including how to control where 
\family typewriter
pdb
\family default
 will stop execution first.
\end_layout

\begin_layout Standard
For more information on the use of the 
\family typewriter
pdb
\family default
 debugger, read the included 
\family typewriter
pdb.doc
\family default
 file (part of the standard Python distribution).
 On a stock Linux system it is located at 
\family typewriter
/usr/lib/python2.3/pdb.doc
\family default
, but the easiest way to read it is by using the 
\family typewriter
help()
\family default
 function of the 
\family typewriter
pdb
\family default
 module as follows (in an IPython prompt):
\end_layout

\begin_layout Standard

\family typewriter
In [1]: import pdb
\newline
In [2]: pdb.help()
\end_layout

\begin_layout Standard
This will load the 
\family typewriter
pdb.doc
\family default
 document in a file viewer for you automatically.
\end_layout

\begin_layout Subsection
Automatic invocation of 
\family typewriter
pdb
\family default
 on exceptions
\end_layout

\begin_layout Standard
IPython, if started with the 
\family typewriter
-pdb
\family default
 option (or if the option is set in your rc file) can call the Python 
\family typewriter
pdb
\family default
 debugger every time your code triggers an uncaught exception
\begin_inset Foot
status collapsed

\begin_layout Standard
Many thanks to Christopher Hart for the request which prompted adding this
 feature to IPython.
\end_layout

\end_inset

.
 This feature can also be toggled at any time with the 
\family typewriter
%pdb
\family default
 magic command.
 This can be extremely useful in order to find the origin of subtle bugs,
 because 
\family typewriter
pdb
\family default
 opens up at the point in your code which triggered the exception, and while
 your program is at this point `dead', all the data is still available and
 you can walk up and down the stack frame and understand the origin of the
 problem.
\end_layout

\begin_layout Standard
Furthermore, you can use these debugging facilities both with the embedded
 IPython mode and without IPython at all.
 For an embedded shell (see sec.
 
\begin_inset LatexCommand \ref{sec:embed}

\end_inset

), simply call the constructor with 
\family typewriter
`-pdb'
\family default
 in the argument string and automatically 
\family typewriter
pdb
\family default
 will be called if an uncaught exception is triggered by your code.
 
\end_layout

\begin_layout Standard
For stand-alone use of the feature in your programs which do not use IPython
 at all, put the following lines toward the top of your `main' routine:
\end_layout

\begin_layout Standard
\align left

\family typewriter
import sys,IPython.ultraTB 
\newline
sys.excepthook = IPython.ultraTB.FormattedTB(mode=`Verbos
e', color_scheme=`Linux', call_pdb=1)
\end_layout

\begin_layout Standard
The 
\family typewriter
mode
\family default
 keyword can be either 
\family typewriter
`Verbose'
\family default
 or 
\family typewriter
`Plain'
\family default
, giving either very detailed or normal tracebacks respectively.
 The 
\family typewriter
color_scheme
\family default
 keyword can be one of 
\family typewriter
`NoColor'
\family default
, 
\family typewriter
`Linux'
\family default
 (default) or 
\family typewriter
`LightBG'
\family default
.
 These are the same options which can be set in IPython with 
\family typewriter
-colors
\family default
 and 
\family typewriter
-xmode
\family default
.
\end_layout

\begin_layout Standard
This will give any of your programs detailed, colored tracebacks with automatic
 invocation of 
\family typewriter
pdb
\family default
.
\end_layout

\begin_layout Section
\begin_inset LatexCommand \label{sec:syntax-extensions}

\end_inset

Extensions for syntax processing
\end_layout

\begin_layout Standard
This isn't for the faint of heart, because the potential for breaking things
 is quite high.
 But it can be a very powerful and useful feature.
 In a nutshell, you can redefine the way IPython processes the user input
 line to accept new, special extensions to the syntax without needing to
 change any of IPython's own code.
\end_layout

\begin_layout Standard
In the 
\family typewriter
IPython/Extensions
\family default
 directory you will find some examples supplied, which we will briefly describe
 now.
 These can be used `as is' (and both provide very useful functionality),
 or you can use them as a starting point for writing your own extensions.
\end_layout

\begin_layout Subsection
Pasting of code starting with 
\family typewriter
`>>> 
\family default
' or 
\family typewriter
`...
 
\family default
'
\end_layout

\begin_layout Standard
In the python tutorial it is common to find code examples which have been
 taken from real python sessions.
 The problem with those is that all the lines begin with either 
\family typewriter
`>>> 
\family default
' or 
\family typewriter
`...
 
\family default
', which makes it impossible to paste them all at once.
 One must instead do a line by line manual copying, carefully removing the
 leading extraneous characters.
\end_layout

\begin_layout Standard
This extension identifies those starting characters and removes them from
 the input automatically, so that one can paste multi-line examples directly
 into IPython, saving a lot of time.
 Please look at the file 
\family typewriter
InterpreterPasteInput.py
\family default
 in the 
\family typewriter
IPython/Extensions
\family default
 directory for details on how this is done.
\end_layout

\begin_layout Standard
IPython comes with a special profile enabling this feature, called 
\family typewriter
tutorial
\family default
\emph on
.

\emph default
 Simply start IPython via 
\family typewriter
`ipython\InsetSpace ~
-p\InsetSpace ~
tutorial'
\family default
 and the feature will be available.
 In a normal IPython session you can activate the feature by importing the
 corresponding module with:
\newline

\family typewriter
In [1]: import IPython.Extensions.InterpreterPasteInput
\end_layout

\begin_layout Standard
The following is a 'screenshot' of how things work when this extension is
 on, copying an example from the standard tutorial:
\end_layout

\begin_layout Standard

\family typewriter
IPython profile: tutorial
\newline
\InsetSpace ~

\newline
*** Pasting of code with ">>>" or "..." has been enabled.
\newline
\InsetSpace ~

\newline
In
 [1]: >>> def fib2(n): # return Fibonacci series up to n
\newline

\begin_inset ERT
status collapsed

\begin_layout Standard


\backslash
hspace*{0mm}
\end_layout

\end_inset

\InsetSpace ~
\InsetSpace ~
 ...: ...\InsetSpace ~
\InsetSpace ~
\InsetSpace ~
\InsetSpace ~
 """Return a list containing the Fibonacci series up to n."""
\newline

\begin_inset ERT
status collapsed

\begin_layout Standard


\backslash
hspace*{0mm}
\end_layout

\end_inset

\InsetSpace ~
\InsetSpace ~
 ...: ...\InsetSpace ~
\InsetSpace ~
\InsetSpace ~
\InsetSpace ~
 result = []
\newline

\begin_inset ERT
status collapsed

\begin_layout Standard


\backslash
hspace*{0mm}
\end_layout

\end_inset

\InsetSpace ~
\InsetSpace ~
 ...: ...\InsetSpace ~
\InsetSpace ~
\InsetSpace ~
\InsetSpace ~
 a, b = 0, 1
\newline

\begin_inset ERT
status collapsed

\begin_layout Standard


\backslash
hspace*{0mm}
\end_layout

\end_inset

\InsetSpace ~
\InsetSpace ~
 ...: ...\InsetSpace ~
\InsetSpace ~
\InsetSpace ~
\InsetSpace ~
 while b < n:
\newline

\begin_inset ERT
status collapsed

\begin_layout Standard


\backslash
hspace*{0mm}
\end_layout

\end_inset

\InsetSpace ~
\InsetSpace ~
 ...: ...\InsetSpace ~
\InsetSpace ~
\InsetSpace ~
\InsetSpace ~
\InsetSpace ~
\InsetSpace ~
\InsetSpace ~
\InsetSpace ~
 result.append(b)\InsetSpace ~
\InsetSpace ~
\InsetSpace ~
 # see below
\newline

\begin_inset ERT
status collapsed

\begin_layout Standard


\backslash
hspace*{0mm}
\end_layout

\end_inset

\InsetSpace ~
\InsetSpace ~
 ...: ...\InsetSpace ~
\InsetSpace ~
\InsetSpace ~
\InsetSpace ~
\InsetSpace ~
\InsetSpace ~
\InsetSpace ~
\InsetSpace ~
 a, b = b, a+b
\newline

\begin_inset ERT
status collapsed

\begin_layout Standard


\backslash
hspace*{0mm}
\end_layout

\end_inset

\InsetSpace ~
\InsetSpace ~
 ...: ...\InsetSpace ~
\InsetSpace ~
\InsetSpace ~
\InsetSpace ~
 return result
\newline

\begin_inset ERT
status collapsed

\begin_layout Standard


\backslash
hspace*{0mm}
\end_layout

\end_inset

\InsetSpace ~
\InsetSpace ~
 ...:
\newline
\InsetSpace ~

\newline
In [2]: fib2(10)
\newline
Out[2]: [1, 1, 2, 3, 5, 8]
\end_layout

\begin_layout Standard
Note that as currently written, this extension does 
\emph on
not 
\emph default
recognize IPython's prompts for pasting.
 Those are more complicated, since the user can change them very easily,
 they involve numbers and can vary in length.
 One could however extract all the relevant information from the IPython
 instance and build an appropriate regular expression.
 This is left as an exercise for the reader.
\end_layout

\begin_layout Subsection
Input of physical quantities with units
\end_layout

\begin_layout Standard
The module 
\family typewriter
PhysicalQInput
\family default
 allows a simplified form of input for physical quantities with units.
 This file is meant to be used in conjunction with the 
\family typewriter
PhysicalQInteractive
\family default
 module (in the same directory) and 
\family typewriter
Physics.PhysicalQuantities
\family default
 from Konrad Hinsen's ScientificPython (
\begin_inset LatexCommand \htmlurl{http://dirac.cnrs-orleans.fr/ScientificPython/}

\end_inset

).
\end_layout

\begin_layout Standard
The 
\family typewriter
Physics.PhysicalQuantities
\family default
 module defines 
\family typewriter
PhysicalQuantity
\family default
 objects, but these must be declared as instances of a class.
 For example, to define 
\family typewriter
v
\family default
 as a velocity of 3\InsetSpace ~
m/s, normally you would write:
\family typewriter

\newline
In [1]: v = PhysicalQuantity(3,'m/s')
\end_layout

\begin_layout Standard
Using the 
\family typewriter
PhysicalQ_Input
\family default
 extension this can be input instead as:
\family typewriter

\newline
In [1]: v = 3 m/s
\family default

\newline
which is much more convenient for interactive use (even though it is blatantly
 invalid Python syntax).
\end_layout

\begin_layout Standard
The 
\family typewriter
physics
\family default
 profile supplied with IPython (enabled via 
\family typewriter
'ipython -p physics'
\family default
) uses these extensions, which you can also activate with:
\end_layout

\begin_layout Standard

\family typewriter
from math import * # math MUST be imported BEFORE PhysicalQInteractive
\newline
from
 IPython.Extensions.PhysicalQInteractive import *
\newline
import IPython.Extensions.PhysicalQ
Input
\end_layout

\begin_layout Section
\begin_inset LatexCommand \label{sec:IPython-as-shell}

\end_inset

IPython as a system shell
\end_layout

\begin_layout Standard
IPython ships with a special profile called 
\family typewriter
pysh
\family default
, which you can activate at the command line as 
\family typewriter
`ipython -p pysh'
\family default
.
 This loads 
\family typewriter
InterpreterExec
\family default
, along with some additional facilities and a prompt customized for filesystem
 navigation.
\end_layout

\begin_layout Standard
Note that this does 
\emph on
not
\emph default
 make IPython a full-fledged system shell.
 In particular, it has no job control, so if you type Ctrl-Z (under Unix),
 you'll suspend pysh itself, not the process you just started.
 
\end_layout

\begin_layout Standard
What the shell profile allows you to do is to use the convenient and powerful
 syntax of Python to do quick scripting at the command line.
 Below we describe some of its features.
\end_layout

\begin_layout Subsection
Aliases
\end_layout

\begin_layout Standard
All of your 
\family typewriter
$PATH
\family default
 has been loaded as IPython aliases, so you should be able to type any normal
 system command and have it executed.
 See 
\family typewriter
%alias?
\family default
 and 
\family typewriter
%unalias?
\family default
 for details on the alias facilities.
 See also 
\family typewriter
%rehash?
\family default
 and 
\family typewriter
%rehashx? 
\family default
for details on the mechanism used to load 
\family typewriter
$PATH
\family default
.
\end_layout

\begin_layout Subsection
Special syntax
\end_layout

\begin_layout Standard
Any lines which begin with 
\family typewriter
`~'
\family default
, 
\family typewriter
`/'
\family default
 and 
\family typewriter
`.'
\family default
 will be executed as shell commands instead of as Python code.
 The special escapes below are also recognized.
 
\family typewriter
!cmd
\family default
 is valid in single or multi-line input, all others are only valid in single-lin
e input:
\end_layout

\begin_layout Description

\family typewriter
!cmd
\family default
 pass `cmd' directly to the shell 
\end_layout

\begin_layout Description

\family typewriter
!!cmd
\family default
 execute `cmd' and return output as a list (split on `
\backslash
n') 
\end_layout

\begin_layout Description

\family typewriter
$var=cmd
\family default
 capture output of cmd into var, as a string 
\end_layout

\begin_layout Description

\family typewriter
$$var=cmd
\family default
 capture output of cmd into var, as a list (split on `
\backslash
n')
\end_layout

\begin_layout Standard
The 
\family typewriter
$
\family default
/
\family typewriter
$$
\family default
 syntaxes make Python variables from system output, which you can later
 use for further scripting.
 The converse is also possible: when executing an alias or calling to the
 system via 
\family typewriter
!
\family default
/
\family typewriter
!!
\family default
, you can expand any python variable or expression by prepending it with
 
\family typewriter
$
\family default
.
 Full details of the allowed syntax can be found in Python's PEP 215.
\end_layout

\begin_layout Standard
A few brief examples will illustrate these (note that the indentation below
 may be incorrectly displayed):
\end_layout

\begin_layout Standard

\family typewriter
fperez[~/test]|3> !ls *s.py 
\newline
scopes.py strings.py
\end_layout

\begin_layout Standard
ls is an internal alias, so there's no need to use 
\family typewriter
!
\family default
: 
\end_layout

\begin_layout Standard

\family typewriter
fperez[~/test]|4> ls *s.py 
\newline
scopes.py* strings.py
\end_layout

\begin_layout Standard
!!ls will return the output into a Python variable: 
\end_layout

\begin_layout Standard

\family typewriter
fperez[~/test]|5> !!ls *s.py 
\newline

\begin_inset ERT
status collapsed

\begin_layout Standard


\backslash
hspace*{0mm}
\end_layout

\end_inset

\InsetSpace ~
\InsetSpace ~
\InsetSpace ~
\InsetSpace ~
\InsetSpace ~
\InsetSpace ~
\InsetSpace ~
\InsetSpace ~
\InsetSpace ~
\InsetSpace ~
\InsetSpace ~
\InsetSpace ~
\InsetSpace ~
\InsetSpace ~
<5> ['scopes.py', 'strings.py'] 
\newline
fperez[~/test]|6> print _5 
\newline
['scopes.py', 'strings.py
']
\end_layout

\begin_layout Standard

\family typewriter
$
\family default
 and 
\family typewriter
$$
\family default
 allow direct capture to named variables: 
\end_layout

\begin_layout Standard

\family typewriter
fperez[~/test]|7> $astr = ls *s.py 
\newline
fperez[~/test]|8> astr 
\newline

\begin_inset ERT
status collapsed

\begin_layout Standard


\backslash
hspace*{0mm}
\end_layout

\end_inset

\InsetSpace ~
\InsetSpace ~
\InsetSpace ~
\InsetSpace ~
\InsetSpace ~
\InsetSpace ~
\InsetSpace ~
\InsetSpace ~
\InsetSpace ~
\InsetSpace ~
\InsetSpace ~
\InsetSpace ~
\InsetSpace ~
\InsetSpace ~
<8> 'scopes.py
\backslash
nstrings.py'
\end_layout

\begin_layout Standard

\family typewriter
fperez[~/test]|9> $$alist = ls *s.py 
\newline
fperez[~/test]|10> alist 
\newline

\begin_inset ERT
status collapsed

\begin_layout Standard


\backslash
hspace*{0mm}
\end_layout

\end_inset

\InsetSpace ~
\InsetSpace ~
\InsetSpace ~
\InsetSpace ~
\InsetSpace ~
\InsetSpace ~
\InsetSpace ~
\InsetSpace ~
\InsetSpace ~
\InsetSpace ~
\InsetSpace ~
\InsetSpace ~
\InsetSpace ~
\InsetSpace ~
<10> ['scopes.py', 'strings.py']
\end_layout

\begin_layout Standard
alist is now a normal python list you can loop over.
 Using 
\family typewriter
$
\family default
 will expand back the python values when alias calls are made:
\end_layout

\begin_layout Standard

\family typewriter
fperez[~/test]|11> for f in alist: 
\newline

\begin_inset ERT
status collapsed

\begin_layout Standard


\backslash
hspace*{0mm}
\end_layout

\end_inset

\InsetSpace ~
\InsetSpace ~
\InsetSpace ~
\InsetSpace ~
\InsetSpace ~
\InsetSpace ~
\InsetSpace ~
\InsetSpace ~
\InsetSpace ~
\InsetSpace ~
\InsetSpace ~
\InsetSpace ~
\InsetSpace ~
\InsetSpace ~
|..> \InsetSpace ~
\InsetSpace ~
\InsetSpace ~
\InsetSpace ~
print 'file',f, 
\newline

\begin_inset ERT
status collapsed

\begin_layout Standard


\backslash
hspace*{0mm}
\end_layout

\end_inset

\InsetSpace ~
\InsetSpace ~
\InsetSpace ~
\InsetSpace ~
\InsetSpace ~
\InsetSpace ~
\InsetSpace ~
\InsetSpace ~
\InsetSpace ~
\InsetSpace ~
\InsetSpace ~
\InsetSpace ~
\InsetSpace ~
\InsetSpace ~
|..> \InsetSpace ~
\InsetSpace ~
\InsetSpace ~
\InsetSpace ~
wc -l $f 
\newline

\begin_inset ERT
status collapsed

\begin_layout Standard


\backslash
hspace*{0mm}
\end_layout

\end_inset

\InsetSpace ~
\InsetSpace ~
\InsetSpace ~
\InsetSpace ~
\InsetSpace ~
\InsetSpace ~
\InsetSpace ~
\InsetSpace ~
\InsetSpace ~
\InsetSpace ~
\InsetSpace ~
\InsetSpace ~
\InsetSpace ~
\InsetSpace ~
|..> 
\newline
file scopes.py 13 scopes.py 
\newline
file strings.py 4 strings.py
\end_layout

\begin_layout Standard
Note that you may need to protect your variables with braces if you want
 to append strings to their names.
 To copy all files in alist to 
\family typewriter
.bak
\family default
 extensions, you must use: 
\end_layout

\begin_layout Standard

\family typewriter
fperez[~/test]|12> for f in alist: 
\newline

\begin_inset ERT
status collapsed

\begin_layout Standard


\backslash
hspace*{0mm}
\end_layout

\end_inset

\InsetSpace ~
\InsetSpace ~
\InsetSpace ~
\InsetSpace ~
\InsetSpace ~
\InsetSpace ~
\InsetSpace ~
\InsetSpace ~
\InsetSpace ~
\InsetSpace ~
\InsetSpace ~
\InsetSpace ~
\InsetSpace ~
\InsetSpace ~
|..> \InsetSpace ~
\InsetSpace ~
\InsetSpace ~
\InsetSpace ~
cp $f ${f}.bak
\end_layout

\begin_layout Standard
If you try using 
\family typewriter
$f.bak
\family default
, you'll get an AttributeError exception saying that your string object
 doesn't have a 
\family typewriter
.bak
\family default
 attribute.
 This is because the 
\family typewriter
$
\family default
 expansion mechanism allows you to expand full Python expressions: 
\end_layout

\begin_layout Standard

\family typewriter
fperez[~/test]|13> echo "sys.platform is: $sys.platform" 
\newline
sys.platform is: linux2
\end_layout

\begin_layout Standard
IPython's input history handling is still active, which allows you to rerun
 a single block of multi-line input by simply using exec: 
\newline

\family typewriter
fperez[~/test]|14> $$alist = ls *.eps 
\newline
fperez[~/test]|15> exec _i11 
\newline
file image2.eps
 921 image2.eps 
\newline
file image.eps 921 image.eps
\end_layout

\begin_layout Standard
While these are new special-case syntaxes, they are designed to allow very
 efficient use of the shell with minimal typing.
 At an interactive shell prompt, conciseness of expression wins over readability.
\end_layout

\begin_layout Subsection
Useful functions and modules
\end_layout

\begin_layout Standard
The os, sys and shutil modules from the Python standard library are automaticall
y loaded.
 Some additional functions, useful for shell usage, are listed below.
 You can request more help about them with `
\family typewriter
?
\family default
'.
\end_layout

\begin_layout Description

\family typewriter
shell
\family default
 - execute a command in the underlying system shell 
\end_layout

\begin_layout Description

\family typewriter
system
\family default
 - like 
\family typewriter
shell()
\family default
, but return the exit status of the command
\end_layout

\begin_layout Description

\family typewriter
sout
\family default
 - capture the output of a command as a string
\end_layout

\begin_layout Description

\family typewriter
lout
\family default
 - capture the output of a command as a list (split on `
\backslash
n')
\end_layout

\begin_layout Description

\family typewriter
getoutputerror
\family default
 - capture (output,error) of a shell commandss
\end_layout

\begin_layout Standard

\family typewriter
sout
\family default
/
\family typewriter
lout
\family default
 are the functional equivalents of 
\family typewriter
$
\family default
/
\family typewriter
$$
\family default
.
 They are provided to allow you to capture system output in the middle of
 true python code, function definitions, etc (where 
\family typewriter
$
\family default
 and 
\family typewriter
$$
\family default
 are invalid).
\end_layout

\begin_layout Subsection
Directory management
\end_layout

\begin_layout Standard
Since each command passed by pysh to the underlying system is executed in
 a subshell which exits immediately, you can NOT use !cd to navigate the
 filesystem.
\end_layout

\begin_layout Standard
Pysh provides its own builtin 
\family typewriter
`%cd
\family default
' magic command to move in the filesystem (the 
\family typewriter
%
\family default
 is not required with automagic on).
 It also maintains a list of visited directories (use 
\family typewriter
%dhist
\family default
 to see it) and allows direct switching to any of them.
 Type 
\family typewriter
`cd?
\family default
' for more details.
\end_layout

\begin_layout Standard

\family typewriter
%pushd
\family default
, 
\family typewriter
%popd
\family default
 and 
\family typewriter
%dirs
\family default
 are provided for directory stack handling.
\end_layout

\begin_layout Subsection
Prompt customization
\end_layout

\begin_layout Standard
The supplied 
\family typewriter
ipythonrc-pysh
\family default
 profile comes with an example of a very colored and detailed prompt, mainly
 to serve as an illustration.
 The valid escape sequences, besides color names, are:
\end_layout

\begin_layout Description

\backslash
# - Prompt number, wrapped in the color escapes for the input prompt (determined
 by the current color scheme).
\end_layout

\begin_layout Description

\backslash
N - Just the prompt counter number, 
\emph on
without
\emph default
 any coloring wrappers.
 You can thus customize the actual prompt colors manually.
\end_layout

\begin_layout Description

\backslash
D - Dots, as many as there are digits in 
\backslash
# (so they align).
\end_layout

\begin_layout Description

\backslash
w - Current working directory (cwd).
\end_layout

\begin_layout Description

\backslash
W - Basename of current working directory.
\end_layout

\begin_layout Description

\backslash
X
\emph on
N
\emph default
 - Where 
\emph on
N
\emph default
=0..5.
 N terms of the cwd, with $HOME written as ~.
\end_layout

\begin_layout Description

\backslash
Y
\emph on
N
\emph default
 - Where 
\emph on
N
\emph default
=0..5.
 Like X
\emph on
N
\emph default
, but if ~ is term 
\emph on
N
\emph default
+1 it's also shown.
\end_layout

\begin_layout Description

\backslash
u - Username.
\end_layout

\begin_layout Description

\backslash
H - Full hostname.
\end_layout

\begin_layout Description

\backslash
h - Hostname up to first '.'
\end_layout

\begin_layout Description

\backslash
$ - Root symbol ($ or #).
 
\end_layout

\begin_layout Description

\backslash
t - Current time, in H:M:S format.
\end_layout

\begin_layout Description

\backslash
v - IPython release version.
 
\end_layout

\begin_layout Description

\backslash
n - Newline.
 
\end_layout

\begin_layout Description

\backslash
r - Carriage return.
 
\end_layout

\begin_layout Description

\backslash

\backslash
 - An explicitly escaped '
\backslash
'.
\end_layout

\begin_layout Standard
You can configure your prompt colors using any ANSI color escape.
 Each color escape sets the color for any subsequent text, until another
 escape comes in and changes things.
 The valid color escapes are:
\end_layout

\begin_layout Description

\backslash
C_Black
\end_layout

\begin_layout Description

\backslash
C_Blue
\end_layout

\begin_layout Description

\backslash
C_Brown
\end_layout

\begin_layout Description

\backslash
C_Cyan
\end_layout

\begin_layout Description

\backslash
C_DarkGray
\end_layout

\begin_layout Description

\backslash
C_Green
\end_layout

\begin_layout Description

\backslash
C_LightBlue
\end_layout

\begin_layout Description

\backslash
C_LightCyan
\end_layout

\begin_layout Description

\backslash
C_LightGray
\end_layout

\begin_layout Description

\backslash
C_LightGreen
\end_layout

\begin_layout Description

\backslash
C_LightPurple
\end_layout

\begin_layout Description

\backslash
C_LightRed
\end_layout

\begin_layout Description

\backslash
C_Purple
\end_layout

\begin_layout Description

\backslash
C_Red
\end_layout

\begin_layout Description

\backslash
C_White
\end_layout

\begin_layout Description

\backslash
C_Yellow
\end_layout

\begin_layout Description

\backslash
C_Normal Stop coloring, defaults to your terminal settings.
\end_layout

\begin_layout Section
\begin_inset LatexCommand \label{sec:Threading-support}

\end_inset

Threading support
\end_layout

\begin_layout Standard

\series bold
WARNING: 
\series default
The threading support is still somewhat experimental, and it has only seen
 reasonable testing under Linux.
 Threaded code is particularly tricky to debug, and it tends to show extremely
 platform-dependent behavior.
 Since I only have access to Linux machines, I will have to rely on user's
 experiences and assistance for this area of IPython to improve under other
 platforms.
\end_layout

\begin_layout Standard
IPython, via the 
\family typewriter
-gthread
\family default
 , 
\family typewriter
-qthread
\family default
, 
\family typewriter
-q4thread
\family default
 and 
\family typewriter
-wthread
\family default
 options (described in Sec.\InsetSpace ~

\begin_inset LatexCommand \ref{sec:threading-opts}

\end_inset

), can run in multithreaded mode to support pyGTK, Qt3, Qt4 and WXPython
 applications respectively.
 These GUI toolkits need to control the python main loop of execution, so
 under a normal Python interpreter, starting a pyGTK, Qt3, Qt4 or WXPython
 application will immediately freeze the shell.
 
\end_layout

\begin_layout Standard
IPython, with one of these options (you can only use one at a time), separates
 the graphical loop and IPython's code execution run into different threads.
 This allows you to test interactively (with 
\family typewriter
%run
\family default
, for example) your GUI code without blocking.
\end_layout

\begin_layout Standard
A nice mini-tutorial on using IPython along with the Qt Designer application
 is available at the SciPy wiki: 
\begin_inset LatexCommand \htmlurl{http://www.scipy.org/Cookbook/Matplotlib/Qt_with_IPython_and_Designer}

\end_inset

.
\end_layout

\begin_layout Subsection
Tk issues
\end_layout

\begin_layout Standard
As indicated in Sec.\InsetSpace ~

\begin_inset LatexCommand \ref{sec:threading-opts}

\end_inset

, a special 
\family typewriter
-tk
\family default
 option is provided to try and allow Tk graphical applications to coexist
 interactively with WX, Qt or GTK ones.
 Whether this works at all, however, is very platform and configuration
 dependent.
 Please experiment with simple test cases before committing to using this
 combination of Tk and GTK/Qt/WX threading in a production environment.
\end_layout

\begin_layout Subsection
I/O pitfalls
\end_layout

\begin_layout Standard
Be mindful that the Python interpreter switches between threads every 
\begin_inset Formula $N$
\end_inset

 bytecodes, where the default value as of Python\InsetSpace ~
2.3 is 
\begin_inset Formula $N=100.$
\end_inset

 This value can be read by using the 
\family typewriter
sys.getcheckinterval()
\family default
 function, and it can be reset via 
\family typewriter
sys.setcheckinterval(
\emph on
N
\emph default
)
\family default
.
 This switching of threads can cause subtly confusing effects if one of
 your threads is doing file I/O.
 In text mode, most systems only flush file buffers when they encounter
 a 
\family typewriter
`
\backslash
n'
\family default
.
 An instruction as simple as
\family typewriter

\newline
\InsetSpace ~
\InsetSpace ~
print >> filehandle, 
\begin_inset Quotes eld
\end_inset

hello world
\begin_inset Quotes erd
\end_inset


\family default

\newline
actually consists of several bytecodes, so it is possible that the newline
 does not reach your file before the next thread switch.
 Similarly, if you are writing to a file in binary mode, the file won't
 be flushed until the buffer fills, and your other thread may see apparently
 truncated files.
 
\end_layout

\begin_layout Standard
For this reason, if you are using IPython's thread support and have (for
 example) a GUI application which will read data generated by files written
 to from the IPython thread, the safest approach is to open all of your
 files in unbuffered mode (the third argument to the 
\family typewriter
file/open
\family default
 function is the buffering value):
\newline

\family typewriter
\InsetSpace ~
\InsetSpace ~
filehandle = open(filename,mode,0)
\end_layout

\begin_layout Standard
This is obviously a brute force way of avoiding race conditions with the
 file buffering.
 If you want to do it cleanly, and you have a resource which is being shared
 by the interactive IPython loop and your GUI thread, you should really
 handle it with thread locking and syncrhonization properties.
 The Python documentation discusses these.
\end_layout

\begin_layout Section
\begin_inset LatexCommand \label{sec:interactive-demos}

\end_inset

Interactive demos with IPython
\end_layout

\begin_layout Standard
IPython ships with a basic system for running scripts interactively in sections,
 useful when presenting code to audiences.
 A few tags embedded in comments (so that the script remains valid Python
 code) divide a file into separate blocks, and the demo can be run one block
 at a time, with IPython printing (with syntax highlighting) the block before
 executing it, and returning to the interactive prompt after each block.
 The interactive namespace is updated after each block is run with the contents
 of the demo's namespace.
\end_layout

\begin_layout Standard
This allows you to show a piece of code, run it and then execute interactively
 commands based on the variables just created.
 Once you want to continue, you simply execute the next block of the demo.
 The following listing shows the markup necessary for dividing a script
 into sections for execution as a demo.
\end_layout

\begin_layout Standard
\begin_inset ERT
status open

\begin_layout Standard


\backslash
codelist{examples/example-demo.py}
\end_layout

\end_inset


\end_layout

\begin_layout Standard
In order to run a file as a demo, you must first make a 
\family typewriter
Demo
\family default
 object out of it.
 If the file is named 
\family typewriter
myscript.py
\family default
, the following code will make a demo:
\end_layout

\begin_layout LyX-Code
from IPython.demo import Demo
\end_layout

\begin_layout LyX-Code
mydemo = Demo('myscript.py')
\end_layout

\begin_layout Standard
This creates the 
\family typewriter
mydemo
\family default
 object, whose blocks you run one at a time by simply calling the object
 with no arguments.
 If you have autocall active in IPython (the default), all you need to do
 is type
\end_layout

\begin_layout LyX-Code
mydemo
\end_layout

\begin_layout Standard
and IPython will call it, executing each block.
 Demo objects can be restarted, you can move forward or back skipping blocks,
 re-execute the last block, etc.
 Simply use the Tab key on a demo object to see its methods, and call 
\family typewriter
`?'
\family default
 on them to see their docstrings for more usage details.
 In addition, the 
\family typewriter
demo
\family default
 module itself contains a comprehensive docstring, which you can access
 via
\end_layout

\begin_layout LyX-Code
from IPython import demo
\end_layout

\begin_layout LyX-Code
demo?
\end_layout

\begin_layout Standard

\series bold
Limitations:
\series default
 It is important to note that these demos are limited to fairly simple uses.
 In particular, you can 
\emph on
not
\emph default
 put division marks in indented code (loops, if statements, function definitions
, etc.) Supporting something like this would basically require tracking the
 internal execution state of the Python interpreter, so only top-level divisions
 are allowed.
 If you want to be able to open an IPython instance at an arbitrary point
 in a program, you can use IPython's embedding facilities, described in
 detail in Sec\SpecialChar \@.
\InsetSpace ~

\begin_inset LatexCommand \ref{sec:embed}

\end_inset

.
\end_layout

\begin_layout Section
\begin_inset LatexCommand \label{sec:matplotlib-support}

\end_inset

Plotting with 
\family typewriter
matplotlib
\family default
 
\end_layout

\begin_layout Standard
The matplotlib library (
\begin_inset LatexCommand \htmlurl[http://matplotlib.sourceforge.net]{http://matplotlib.sourceforge.net}

\end_inset

) provides high quality 2D plotting for Python.
 Matplotlib can produce plots on screen using a variety of GUI toolkits,
 including Tk, GTK and WXPython.
 It also provides a number of commands useful for scientific computing,
 all with a syntax compatible with that of the popular Matlab program.
\end_layout

\begin_layout Standard
IPython accepts the special option 
\family typewriter
-pylab
\family default
 (Sec.\InsetSpace ~

\begin_inset LatexCommand \ref{sec:cmd-line-opts}

\end_inset

).
 This configures it to support matplotlib, honoring the settings in the
 
\family typewriter
.matplotlibrc
\family default
 file.
 IPython will detect the user's choice of matplotlib GUI backend, and automatica
lly select the proper threading model to prevent blocking.
 It also sets matplotlib in interactive mode and modifies 
\family typewriter
%run
\family default
 slightly, so that any matplotlib-based script can be executed using 
\family typewriter
%run
\family default
 and the final 
\family typewriter
show()
\family default
 command does not block the interactive shell.
\end_layout

\begin_layout Standard
The 
\family typewriter
-pylab
\family default
 option must be given first in order for IPython to configure its threading
 mode.
 However, you can still issue other options afterwards.
 This allows you to have a matplotlib-based environment customized with
 additional modules using the standard IPython profile mechanism (Sec.\InsetSpace ~

\begin_inset LatexCommand \ref{sec:profiles}

\end_inset

): ``
\family typewriter
ipython -pylab -p myprofile
\family default
'' will load the profile defined in 
\family typewriter
ipythonrc-myprofile
\family default
 after configuring matplotlib.
\end_layout

\begin_layout Section
\begin_inset LatexCommand \label{sec:Gnuplot}

\end_inset

Plotting with 
\family typewriter
Gnuplot
\end_layout

\begin_layout Standard
Through the magic extension system described in sec.
 
\begin_inset LatexCommand \ref{sec:magic}

\end_inset

, IPython incorporates a mechanism for conveniently interfacing with the
 Gnuplot system (
\begin_inset LatexCommand \htmlurl{http://www.gnuplot.info}

\end_inset

).
 Gnuplot is a very complete 2D and 3D plotting package available for many
 operating systems and commonly included in modern Linux distributions.
 
\end_layout

\begin_layout Standard
Besides having Gnuplot installed, this functionality requires the 
\family typewriter
Gnuplot.py
\family default
 module for interfacing python with Gnuplot.
 It can be downloaded from: 
\begin_inset LatexCommand \htmlurl{http://gnuplot-py.sourceforge.net}

\end_inset

.
\end_layout

\begin_layout Subsection
Proper Gnuplot configuration
\end_layout

\begin_layout Standard
As of version 4.0, Gnuplot has excellent mouse and interactive keyboard support.
 However, as of 
\family typewriter
Gnuplot.py
\family default
 version 1.7, a new option was added to communicate between Python and Gnuplot
 via FIFOs (pipes).
 This mechanism, while fast, also breaks the mouse system.
 You must therefore set the variable 
\family typewriter
prefer_fifo_data
\family default
 to 
\family typewriter
0
\family default
 in file 
\family typewriter
gp_unix.py
\family default
 if you wish to keep the interactive mouse and keyboard features working
 properly (
\family typewriter
prefer_inline_data
\family default
 also must be 
\family typewriter
0
\family default
, but this is the default so unless you've changed it manually you should
 be fine).
\end_layout

\begin_layout Standard
'Out of the box', Gnuplot is configured with a rather poor set of size,
 color and linewidth choices which make the graphs fairly hard to read on
 modern high-resolution displays (although they work fine on old 640x480
 ones).
 Below is a section of my 
\family typewriter
.Xdefaults
\family default
 file which I use for having a more convenient Gnuplot setup.
 Remember to load it by running 
\family typewriter
`xrdb .Xdefaults`
\family default
:
\end_layout

\begin_layout Standard

\family typewriter
!******************************************************************
\newline
! gnuplot
 options
\newline
! modify this for a convenient window size
\newline
gnuplot*geometry: 780x580
\end_layout

\begin_layout Standard

\family typewriter
! on-screen font (not for PostScript)
\newline
gnuplot*font: -misc-fixed-bold-r-normal--15
-120-100-100-c-90-iso8859-1
\end_layout

\begin_layout Standard

\family typewriter
! color options
\newline
gnuplot*background: black
\newline
gnuplot*textColor: white
\newline
gnuplot*borderCo
lor: white
\newline
gnuplot*axisColor: white
\newline
gnuplot*line1Color: red
\newline
gnuplot*line2Color:
 green
\newline
gnuplot*line3Color: blue
\newline
gnuplot*line4Color: magenta
\newline
gnuplot*line5Color:
 cyan
\newline
gnuplot*line6Color: sienna
\newline
gnuplot*line7Color: orange
\newline
gnuplot*line8Color:
 coral
\end_layout

\begin_layout Standard

\family typewriter
! multiplicative factor for point styles
\newline
gnuplot*pointsize: 2
\end_layout

\begin_layout Standard

\family typewriter
! line width options (in pixels)
\newline
gnuplot*borderWidth: 2
\newline
gnuplot*axisWidth:
 2
\newline
gnuplot*line1Width: 2
\newline
gnuplot*line2Width: 2
\newline
gnuplot*line3Width: 2
\newline
gnuplot*line4Wi
dth: 2
\newline
gnuplot*line5Width: 2
\newline
gnuplot*line6Width: 2
\newline
gnuplot*line7Width: 2
\newline
gnuplot*lin
e8Width: 2
\end_layout

\begin_layout Subsection
The 
\family typewriter
IPython.GnuplotRuntime
\family default
 module
\end_layout

\begin_layout Standard
IPython includes a module called 
\family typewriter
Gnuplot2.py
\family default
 which extends and improves the default 
\family typewriter
Gnuplot
\family default
.
\family typewriter
py
\family default
 (which it still relies upon).
 For example, the new 
\family typewriter
plot
\family default
 function adds several improvements to the original making it more convenient
 for interactive use, and 
\family typewriter
hardcopy
\family default
 fixes a bug in the original which under some circumstances blocks the creation
 of PostScript output.
\end_layout

\begin_layout Standard
For scripting use, 
\family typewriter
GnuplotRuntime.py
\family default
 is provided, which wraps 
\family typewriter
Gnuplot2.py
\family default
 and creates a series of global aliases.
 These make it easy to control Gnuplot plotting jobs through the Python
 language.
\end_layout

\begin_layout Standard
Below is some example code which illustrates how to configure Gnuplot inside
 your own programs but have it available for further interactive use through
 an embedded IPython instance.
 Simply run this file at a system prompt.
 This file is provided as 
\family typewriter
example-gnuplot.py
\family default
 in the examples directory:
\end_layout

\begin_layout Standard
\begin_inset ERT
status open

\begin_layout Standard


\backslash
codelist{examples/example-gnuplot.py}
\end_layout

\end_inset


\end_layout

\begin_layout Subsection
The 
\family typewriter
numeric
\family default
 profile: a scientific computing environment
\end_layout

\begin_layout Standard
The 
\family typewriter
numeric
\family default
 IPython profile, which you can activate with 
\family typewriter
`ipython -p numeric
\family default
' will automatically load the IPython Gnuplot extensions (plus Numeric and
 other useful things for numerical computing), contained in the 
\family typewriter
IPython.GnuplotInteractive
\family default
 module.
 This will create the globals 
\family typewriter
Gnuplot 
\family default
(an alias to the improved Gnuplot2 module), 
\family typewriter
gp
\family default
 (a Gnuplot active instance), the new magic commands 
\family typewriter
%gpc
\family default
 and 
\family typewriter
%gp_set_instance
\family default
 and several other convenient globals.
 Type 
\family typewriter
gphelp()
\family default
 for further details.
\end_layout

\begin_layout Standard
This should turn IPython into a convenient environment for numerical computing,
 with all the functions in the NumPy library and the Gnuplot facilities
 for plotting.
 Further improvements can be obtained by loading the SciPy libraries for
 scientific computing, available at 
\begin_inset LatexCommand \htmlurl{http://scipy.org}

\end_inset

.
\end_layout

\begin_layout Standard
If you are in the middle of a working session with numerical objects and
 need to plot them but you didn't start the 
\family typewriter
numeric
\family default
 profile, you can load these extensions at any time by typing
\newline

\family typewriter
from IPython.GnuplotInteractive import *
\newline

\family default
at the IPython prompt.
 This will allow you to keep your objects intact and start using Gnuplot
 to view them.
\end_layout

\begin_layout Section
Reporting bugs
\end_layout

\begin_layout Subsection*
Automatic crash reports
\end_layout

\begin_layout Standard
Ideally, IPython itself shouldn't crash.
 It will catch exceptions produced by you, but bugs in its internals will
 still crash it.
\end_layout

\begin_layout Standard
In such a situation, IPython will leave a file named 
\family typewriter
IPython_crash_report.txt
\family default
 in your IPYTHONDIR directory (that way if crashes happen several times
 it won't litter many directories, the post-mortem file is always located
 in the same place and new occurrences just overwrite the previous one).
 If you can mail this file to the developers (see sec.
 
\begin_inset LatexCommand \ref{sec:credits}

\end_inset

 for names and addresses), it will help us 
\emph on
a lot
\emph default
 in understanding the cause of the problem and fixing it sooner.
\end_layout

\begin_layout Subsection*
The bug tracker
\end_layout

\begin_layout Standard
IPython also has an online bug-tracker, located at 
\begin_inset LatexCommand \htmlurl{http://projects.scipy.org/ipython/ipython/report/1}

\end_inset

.
 In addition to mailing the developers, it would be a good idea to file
 a bug report here.
 This will ensure that the issue is properly followed to conclusion.
 To report new bugs you will have to register first.
\end_layout

\begin_layout Standard
You can also use this bug tracker to file feature requests.
\end_layout

\begin_layout Section
Brief history
\end_layout

\begin_layout Subsection
Origins
\end_layout

\begin_layout Standard
The current IPython system grew out of the following three projects:
\end_layout

\begin_layout List
\labelwidthstring 00.00.0000
ipython by Fernando P
\begin_inset ERT
status collapsed

\begin_layout Standard


\backslash
'{e}
\end_layout

\end_inset

rez.
 I was working on adding Mathematica-type prompts and a flexible configuration
 system (something better than 
\family typewriter
$PYTHONSTARTUP
\family default
) to the standard Python interactive interpreter.
\end_layout

\begin_layout List
\labelwidthstring 00.00.0000
IPP by Janko Hauser.
 Very well organized, great usability.
 Had an old help system.
 IPP was used as the `container' code into which I added the functionality
 from ipython and LazyPython.
\end_layout

\begin_layout List
\labelwidthstring 00.00.0000
LazyPython by Nathan Gray.
 Simple but 
\emph on
very
\emph default
 powerful.
 The quick syntax (auto parens, auto quotes) and verbose/colored tracebacks
 were all taken from here.
\end_layout

\begin_layout Standard
When I found out (see sec.
 
\begin_inset LatexCommand \ref{figgins}

\end_inset

) about IPP and LazyPython I tried to join all three into a unified system.
 I thought this could provide a very nice working environment, both for
 regular programming and scientific computing: shell-like features, IDL/Matlab
 numerics, Mathematica-type prompt history and great object introspection
 and help facilities.
 I think it worked reasonably well, though it was a lot more work than I
 had initially planned.
\end_layout

\begin_layout Subsection
Current status
\end_layout

\begin_layout Standard
The above listed features work, and quite well for the most part.
 But until a major internal restructuring is done (see below), only bug
 fixing will be done, no other features will be added (unless very minor
 and well localized in the cleaner parts of the code).
\end_layout

\begin_layout Standard
IPython consists of some 18000 lines of pure python code, of which roughly
 two thirds is reasonably clean.
 The rest is, messy code which needs a massive restructuring before any
 further major work is done.
 Even the messy code is fairly well documented though, and most of the problems
 in the (non-existent) class design are well pointed to by a PyChecker run.
 So the rewriting work isn't that bad, it will just be time-consuming.
\end_layout

\begin_layout Subsection
Future
\end_layout

\begin_layout Standard
See the separate 
\family typewriter
new_design
\family default
 document for details.
 Ultimately, I would like to see IPython become part of the standard Python
 distribution as a `big brother with batteries' to the standard Python interacti
ve interpreter.
 But that will never happen with the current state of the code, so all contribut
ions are welcome.
\end_layout

\begin_layout Section
License
\end_layout

\begin_layout Standard
IPython is released under the terms of the BSD license, whose general form
 can be found at: 
\begin_inset LatexCommand \htmlurl{http://www.opensource.org/licenses/bsd-license.php}

\end_inset

.
 The full text of the IPython license is reproduced below:
\end_layout

\begin_layout Quote

\family typewriter
\size small
IPython is released under a BSD-type license.
\end_layout

\begin_layout Quote

\family typewriter
\size small
Copyright (c) 2001, 2002, 2003, 2004 Fernando Perez <[e-mail]>.
\end_layout

\begin_layout Quote

\family typewriter
\size small
Copyright (c) 2001 Janko Hauser <[e-mail]> and 
\newline
Nathaniel Gray <n8gray@ca
ltech.edu>.
\end_layout

\begin_layout Quote

\family typewriter
\size small
All rights reserved.
\end_layout

\begin_layout Quote

\family typewriter
\size small
Redistribution and use in source and binary forms, with or without modification,
 are permitted provided that the following conditions are met:
\end_layout

\begin_layout Quote

\family typewriter
\size small
a.
 Redistributions of source code must retain the above copyright notice,
 this list of conditions and the following disclaimer.
\end_layout

\begin_layout Quote

\family typewriter
\size small
b.
 Redistributions in binary form must reproduce the above copyright notice,
 this list of conditions and the following disclaimer in the documentation
 and/or other materials provided with the distribution.
\end_layout

\begin_layout Quote

\family typewriter
\size small
c.
 Neither the name of the copyright holders nor the names of any contributors
 to this software may be used to endorse or promote products derived from
 this software without specific prior written permission.
\end_layout

\begin_layout Quote

\family typewriter
\size small
THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS
 IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO,
 THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
 PURPOSE ARE DISCLAIMED.
 IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT,
 INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING,
 BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF
 USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON
 ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
 (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF
 THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
 
\end_layout

\begin_layout Standard
Individual authors are the holders of the copyright for their code and are
 listed in each file.
\end_layout

\begin_layout Standard
Some files (
\family typewriter
DPyGetOpt.py
\family default
, for example) may be licensed under different conditions.
 Ultimately each file indicates clearly the conditions under which its author/au
thors have decided to publish the code.
\end_layout

\begin_layout Standard
Versions of IPython up to and including 0.6.3 were released under the GNU
 Lesser General Public License (LGPL), available at 
\begin_inset LatexCommand \htmlurl{http://www.gnu.org/copyleft/lesser.html}

\end_inset

.
\end_layout

\begin_layout Section
\begin_inset LatexCommand \label{sec:credits}

\end_inset

Credits
\end_layout

\begin_layout Standard
IPython is mainly developed by Fernando P
\begin_inset ERT
status collapsed

\begin_layout Standard


\backslash
'{e}
\end_layout

\end_inset

rez 
\family typewriter
<[e-mail]>
\family default
, but the project was born from mixing in Fernando's code with the IPP project
 by Janko Hauser 
\family typewriter
<jhauser-AT-zscout.de>
\family default
 and LazyPython by Nathan Gray 
\family typewriter
<n8gray-AT-caltech.edu>
\family default
.
 For all IPython-related requests, please contact Fernando.
 
\end_layout

\begin_layout Standard
As of early 2006, the following developers have joined the core team:
\end_layout

\begin_layout List
\labelwidthstring 00.00.0000
Robert\InsetSpace ~
Kern 
\family typewriter
<rkern-AT-enthought.com>
\family default
: co-mentored the 2005 Google Summer of Code project to develop python interacti
ve notebooks (XML documents) and graphical interface.
 This project was awarded to the students Tzanko Matev 
\family typewriter
<tsanko-AT-gmail.com>
\family default
 and Toni Alatalo 
\family typewriter
<antont-AT-an.org>
\end_layout

\begin_layout List
\labelwidthstring 00.00.0000
Brian\InsetSpace ~
Granger 
\family typewriter
<bgranger-AT-scu.edu>
\family default
: extending IPython to allow support for interactive parallel computing.
\end_layout

\begin_layout List
\labelwidthstring 00.00.0000
Ville\InsetSpace ~
Vainio 
\family typewriter
<vivainio-AT-gmail.com>
\family default
: Ville is the new maintainer for the main trunk of IPython after version
 0.7.1.
\end_layout

\begin_layout Standard
User or development help should be requested via the IPython mailing lists:
\end_layout

\begin_layout Description
User\InsetSpace ~
list: 
\begin_inset LatexCommand \htmlurl{http://scipy.net/mailman/listinfo/ipython-user}

\end_inset


\end_layout

\begin_layout Description
Developer's\InsetSpace ~
list: 
\begin_inset LatexCommand \htmlurl{http://scipy.net/mailman/listinfo/ipython-dev}

\end_inset


\end_layout

\begin_layout Standard
The IPython project is also very grateful to
\begin_inset Foot
status collapsed

\begin_layout Standard
I've mangled email addresses to reduce spam, since the IPython manuals can
 be accessed online.
\end_layout

\end_inset

:
\end_layout

\begin_layout Standard
Bill Bumgarner 
\family typewriter
<bbum-AT-friday.com>
\family default
: for providing the DPyGetOpt module which gives very powerful and convenient
 handling of command-line options (light years ahead of what Python 2.1.1's
 getopt module does).
\end_layout

\begin_layout Standard
Ka-Ping Yee 
\family typewriter
<ping-AT-lfw.org>
\family default
: for providing the Itpl module for convenient and powerful string interpolation
 with a much nicer syntax than formatting through the '%' operator.
\end_layout

\begin_layout Standard
Arnd Baecker 
\family typewriter
<baecker-AT-physik.tu-dresden.de>
\family default
: for his many very useful suggestions and comments, and lots of help with
 testing and documentation checking.
 Many of IPython's newer features are a result of discussions with him (bugs
 are still my fault, not his).
\end_layout

\begin_layout Standard
Obviously Guido van\InsetSpace ~
Rossum and the whole Python development team, that goes
 without saying.
\end_layout

\begin_layout Standard
IPython's website is generously hosted at 
\begin_inset LatexCommand \htmlurl{http://ipython.scipy.org}

\end_inset

 by Enthought (
\begin_inset LatexCommand \htmlurl{http://www.enthought.com}

\end_inset

).
 I am very grateful to them and all of the SciPy team for their contribution.
\end_layout

\begin_layout Standard
\begin_inset LatexCommand \label{figgins}

\end_inset

Fernando would also like to thank Stephen Figgins 
\family typewriter
<fig-AT-monitor.net>
\family default
, an O'Reilly Python editor.
 His Oct/11/2001 article about IPP and LazyPython, was what got this project
 started.
 You can read it at: 
\begin_inset LatexCommand \htmlurl{http://www.onlamp.com/pub/a/python/2001/10/11/pythonnews.html}

\end_inset

.
\end_layout

\begin_layout Standard
And last but not least, all the kind IPython users who have emailed new
 code, bug reports, fixes, comments and ideas.
 A brief list follows, please let me know if I have ommitted your name by
 accident: 
\end_layout

\begin_layout List
\labelwidthstring 00.00.0000
Jack\InsetSpace ~
Moffit 
\family typewriter
<jack-AT-xiph.org>
\family default
 Bug fixes, including the infamous color problem.
 This bug alone caused many lost hours and frustration, many thanks to him
 for the fix.
 I've always been a fan of Ogg & friends, now I have one more reason to
 like these folks.
\newline
Jack is also contributing with Debian packaging and many
 other things.
\end_layout

\begin_layout List
\labelwidthstring 00.00.0000
Alexander\InsetSpace ~
Schmolck 
\family typewriter
<a.schmolck-AT-gmx.net> 
\family default
Emacs work, bug reports, bug fixes, ideas, lots more.
 The ipython.el mode for (X)Emacs is Alex's code, providing full support
 for IPython under (X)Emacs.
\end_layout

\begin_layout List
\labelwidthstring 00.00.0000
Andrea\InsetSpace ~
Riciputi 
\family typewriter
<andrea.riciputi-AT-libero.it>
\family default
 Mac OSX information, Fink package management.
\end_layout

\begin_layout List
\labelwidthstring 00.00.0000
Gary\InsetSpace ~
Bishop 
\family typewriter
<gb-AT-cs.unc.edu>
\family default
 Bug reports, and patches to work around the exception handling idiosyncracies
 of WxPython.
 Readline and color support for Windows.
\end_layout

\begin_layout List
\labelwidthstring 00.00.0000
Jeffrey\InsetSpace ~
Collins 
\family typewriter
<Jeff.Collins-AT-vexcel.com>
\family default
 Bug reports.
 Much improved readline support, including fixes for Python 2.3.
\end_layout

\begin_layout List
\labelwidthstring 00.00.0000
Dryice\InsetSpace ~
Liu 
\family typewriter
<dryice-AT-liu.com.cn>
\family default
 FreeBSD port.
\end_layout

\begin_layout List
\labelwidthstring 00.00.0000
Mike\InsetSpace ~
Heeter 
\family typewriter
<korora-AT-SDF.LONESTAR.ORG>
\end_layout

\begin_layout List
\labelwidthstring 00.00.0000
Christopher\InsetSpace ~
Hart 
\family typewriter
<hart-AT-caltech.edu>
\family default
 PDB integration.
\end_layout

\begin_layout List
\labelwidthstring 00.00.0000
Milan\InsetSpace ~
Zamazal 
\family typewriter
<pdm-AT-zamazal.org>
\family default
 Emacs info.
\end_layout

\begin_layout List
\labelwidthstring 00.00.0000
Philip\InsetSpace ~
Hisley 
\family typewriter
<compsys-AT-starpower.net>
\end_layout

\begin_layout List
\labelwidthstring 00.00.0000
Holger\InsetSpace ~
Krekel 
\family typewriter
<pyth-AT-devel.trillke.net>
\family default
 Tab completion, lots more.
\end_layout

\begin_layout List
\labelwidthstring 00.00.0000
Robin\InsetSpace ~
Siebler 
\family typewriter
<robinsiebler-AT-starband.net>
\end_layout

\begin_layout List
\labelwidthstring 00.00.0000
Ralf\InsetSpace ~
Ahlbrink
\family typewriter
 <ralf_ahlbrink-AT-web.de>
\end_layout

\begin_layout List
\labelwidthstring 00.00.0000
Thorsten\InsetSpace ~
Kampe 
\family typewriter
<thorsten-AT-thorstenkampe.de>
\end_layout

\begin_layout List
\labelwidthstring 00.00.0000
Fredrik\InsetSpace ~
Kant 
\family typewriter
<fredrik.kant-AT-front.com>
\family default
 Windows setup.
\end_layout

\begin_layout List
\labelwidthstring 00.00.0000
Syver\InsetSpace ~
Enstad 
\family typewriter
<syver-en-AT-online.no>
\family default
 Windows setup.
\end_layout

\begin_layout List
\labelwidthstring 00.00.0000
Richard 
\family typewriter
<rxe-AT-renre-europe.com>
\family default
 Global embedding.
\end_layout

\begin_layout List
\labelwidthstring 00.00.0000
Hayden\InsetSpace ~
Callow 
\family typewriter
<h.callow-AT-elec.canterbury.ac.nz>
\family default
 Gnuplot.py 1.6 compatibility.
\end_layout

\begin_layout List
\labelwidthstring 00.00.0000
Leonardo\InsetSpace ~
Santagada 
\family typewriter
<retype-AT-terra.com.br>
\family default
 Fixes for Windows installation.
\end_layout

\begin_layout List
\labelwidthstring 00.00.0000
Christopher\InsetSpace ~
Armstrong 
\family typewriter
<radix-AT-twistedmatrix.com>
\family default
 Bugfixes.
\end_layout

\begin_layout List
\labelwidthstring 00.00.0000
Francois\InsetSpace ~
Pinard 
\family typewriter
<pinard-AT-iro.umontreal.ca>
\family default
 Code and documentation fixes.
\end_layout

\begin_layout List
\labelwidthstring 00.00.0000
Cory\InsetSpace ~
Dodt 
\family typewriter
<cdodt-AT-fcoe.k12.ca.us>
\family default
 Bug reports and Windows ideas.
 Patches for Windows installer.
\end_layout

\begin_layout List
\labelwidthstring 00.00.0000
Olivier\InsetSpace ~
Aubert 
\family typewriter
<oaubert-AT-bat710.univ-lyon1.fr>
\family default
 New magics.
\end_layout

\begin_layout List
\labelwidthstring 00.00.0000
King\InsetSpace ~
C.\InsetSpace ~
Shu 
\family typewriter
<kingshu-AT-myrealbox.com>
\family default
 Autoindent patch.
\end_layout

\begin_layout List
\labelwidthstring 00.00.0000
Chris\InsetSpace ~
Drexler 
\family typewriter
<chris-AT-ac-drexler.de>
\family default
 Readline packages for Win32/CygWin.
\end_layout

\begin_layout List
\labelwidthstring 00.00.0000
Gustavo\InsetSpace ~
Cordova\InsetSpace ~
Avila 
\family typewriter
<gcordova-AT-sismex.com>
\family default
 EvalDict code for nice, lightweight string interpolation.
\end_layout

\begin_layout List
\labelwidthstring 00.00.0000
Kasper\InsetSpace ~
Souren 
\family typewriter
<Kasper.Souren-AT-ircam.fr>
\family default
 Bug reports, ideas.
\end_layout

\begin_layout List
\labelwidthstring 00.00.0000
Gever\InsetSpace ~
Tulley 
\family typewriter
<gever-AT-helium.com>
\family default
 Code contributions.
\end_layout

\begin_layout List
\labelwidthstring 00.00.0000
Ralf\InsetSpace ~
Schmitt 
\family typewriter
<ralf-AT-brainbot.com>
\family default
 Bug reports & fixes.
\end_layout

\begin_layout List
\labelwidthstring 00.00.0000
Oliver\InsetSpace ~
Sander 
\family typewriter
<osander-AT-gmx.de>
\family default
 Bug reports.
\end_layout

\begin_layout List
\labelwidthstring 00.00.0000
Rod\InsetSpace ~
Holland 
\family typewriter
<rhh-AT-structurelabs.com>
\family default
 Bug reports and fixes to logging module.
\end_layout

\begin_layout List
\labelwidthstring 00.00.0000
Daniel\InsetSpace ~
'Dang'\InsetSpace ~
Griffith 
\family typewriter
<pythondev-dang-AT-lazytwinacres.net>
\family default
 Fixes, enhancement suggestions for system shell use.
\end_layout

\begin_layout List
\labelwidthstring 00.00.0000
Viktor\InsetSpace ~
Ransmayr 
\family typewriter
<viktor.ransmayr-AT-t-online.de>
\family default
 Tests and reports on Windows installation issues.
 Contributed a true Windows binary installer.
\end_layout

\begin_layout List
\labelwidthstring 00.00.0000
Mike\InsetSpace ~
Salib 
\family typewriter
<msalib-AT-mit.edu>
\family default
 Help fixing a subtle bug related to traceback printing.
\end_layout

\begin_layout List
\labelwidthstring 00.00.0000
W.J.\InsetSpace ~
van\InsetSpace ~
der\InsetSpace ~
Laan 
\family typewriter
<gnufnork-AT-hetdigitalegat.nl>
\family default
 Bash-like prompt specials.
\end_layout

\begin_layout List
\labelwidthstring 00.00.0000
Antoon\InsetSpace ~
Pardon 
\family typewriter
<Antoon.Pardon-AT-rece.vub.ac.be>
\family default
 Critical fix for the multithreaded IPython.
\end_layout

\begin_layout List
\labelwidthstring 00.00.0000
John\InsetSpace ~
Hunter 
\family typewriter
<jdhunter-AT-nitace.bsd.uchicago.edu>
\family default
 Matplotlib author, helped with all the development of support for matplotlib
 in IPyhton, including making necessary changes to matplotlib itself.
\end_layout

\begin_layout List
\labelwidthstring 00.00.0000
Matthew\InsetSpace ~
Arnison 
\family typewriter
<maffew-AT-cat.org.au>
\family default
 Bug reports, `
\family typewriter
%run -d
\family default
' idea.
\end_layout

\begin_layout List
\labelwidthstring 00.00.0000
Prabhu\InsetSpace ~
Ramachandran 
\family typewriter
<prabhu_r-AT-users.sourceforge.net>
\family default
 Help with (X)Emacs support, threading patches, ideas...
\end_layout

\begin_layout List
\labelwidthstring 00.00.0000
Norbert\InsetSpace ~
Tretkowski 
\family typewriter
<tretkowski-AT-inittab.de>
\family default
 help with Debian packaging and distribution.
\end_layout

\begin_layout List
\labelwidthstring 00.00.0000
George\InsetSpace ~
Sakkis <
\family typewriter
gsakkis-AT-eden.rutgers.edu>
\family default
 New matcher for tab-completing named arguments of user-defined functions.
\end_layout

\begin_layout List
\labelwidthstring 00.00.0000
J�rgen\InsetSpace ~
Stenarson 
\family typewriter
<jorgen.stenarson-AT-bostream.nu>
\family default
 Wildcard support implementation for searching namespaces.
\end_layout

\begin_layout List
\labelwidthstring 00.00.0000
Vivian\InsetSpace ~
De\InsetSpace ~
Smedt 
\family typewriter
<vivian-AT-vdesmedt.com>
\family default
 Debugger enhancements, so that when pdb is activated from within IPython,
 coloring, tab completion and other features continue to work seamlessly.
\end_layout

\begin_layout List
\labelwidthstring 00.00.0000
Scott\InsetSpace ~
Tsai 
\family typewriter
<scottt958-AT-yahoo.com.tw>
\family default
 Support for automatic editor invocation on syntax errors (see 
\begin_inset LatexCommand \htmlurl{http://www.scipy.net/roundup/ipython/issue36}

\end_inset

).
\end_layout

\begin_layout List
\labelwidthstring 00.00.0000
Alexander\InsetSpace ~
Belchenko 
\family typewriter
<bialix-AT-ukr.net>
\family default
 Improvements for win32 paging system.
\end_layout

\begin_layout List
\labelwidthstring 00.00.0000
Will\InsetSpace ~
Maier 
\family typewriter
<willmaier-AT-ml1.net>
\family default
 Official OpenBSD port.
\end_layout

\end_body
\end_document