initial checkin of ipython.rst (rst version of ipython0 docs), with some touching up. still has some warnings

doc/ipython.rst

@@ -0,0 +1,5026 b''
+.. IPython documentation master file, created by sphinx-quickstart.py on Mon Mar 24 17:01:34 2008.
+   You can adapt this file completely to your liking, but it should at least
+   contain the root 'toctree' directive.
+
+Welcome to IPython's documentation!
+===================================
+
+Contents:
+
+.. toctree::
+   :maxdepth: 2
+
+Indices and tables
+==================
+
+* :ref:`genindex`
+* :ref:`modindex`
+* :ref:`search`
+
+Overview
+========
+
+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.
+
+IPython is a free software project (released under the BSD license)
+which tries to:
+
+   1. 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).
+   2. 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.
+   3. 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.
+   4. 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.
+
+
+    Main features
+
+    * 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 ('?', and using '??' provides additional detail).
+    * Searching through modules and namespaces with '*' wildcards, both
+      when using the '?' system and via the %psearch command.
+    * 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.
+    * 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.
+    * User-extensible 'magic' commands. A set of commands prefixed with
+      % is available for controlling IPython itself and provides
+      directory control, namespace information and many aliases to
+      common system shell commands.
+    * Alias facility for defining your own system aliases.
+    * 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.
+    * Background execution of Python commands in a separate thread.
+      IPython has an internal job manager called jobs, and a
+      conveninence backgrounding magic function called %bg.
+    * The ability to expand python variables when calling the system
+      shell. In a shell command, any python variable prefixed with $ is
+      expanded. A double $$ allows passing a literal $ to the shell (for
+      access to shell and environment variables like $PATH).
+    * Filesystem navigation, via a magic %cd command, along with a
+      persistent bookmark system (using %bookmark) for fast access to
+      frequently visited directories.
+    * A lightweight persistence framework via the %store command, which
+      allows you to save arbitrary Python variables. These get restored
+      automatically when your session restarts.
+    * Automatic indentation (optional) of code as you type (through the
+      readline library).
+    * Macro system for quickly re-executing multiple lines of previous
+      input with a single name. Macros can be stored persistently via
+      %store and edited via %edit.
+    * 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).
+    * Session restoring: logs can be replayed to restore a previous
+      session to the state where you left it.
+    * 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).
+    * Auto-parentheses: callable objects can be executed without
+      parentheses: 'sin 3' is automatically converted to 'sin(3)'.
+    * Auto-quoting: using ',' or ';' as the first character forces
+      auto-quoting of the rest of the line: ',my_function a b' becomes
+      automatically 'my_function("a","b")', while ';my_function a b'
+      becomes 'my_function("a b")'.
+    * 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
+      '>>>' or '...' such as those from other python sessions or the
+      standard Python documentation.
+    * 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.
+    * 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).
+    * Easy debugger access. You can set IPython to call up an enhanced
+      version of the Python debugger (pdb) every time there is an
+      uncaught exception. This drops you inside the code which triggered
+      the exception with all the data live and it is possible to
+      navigate the stack to rapidly isolate the source of a bug. The
+      %run magic command -with the -d option- can run any script under
+      pdb's control, automatically setting initial breakpoints for you.
+      This version of pdb has IPython-specific improvements, including
+      tab-completion and traceback coloring support.
+    * Profiler support. You can run single statements (similar to
+      profile.run()) or complete programs under the profiler's control.
+      While this is possible with standard cProfile or profile modules,
+      IPython wraps this functionality with magic commands (see '%prun'
+      and '%run -p') convenient for rapid interactive work.
+    * Doctest support. The special %doctest_mode command toggles a mode
+      that allows you to paste existing doctests (with leading '>>>'
+      prompts and whitespace) and uses doctest-compatible prompts and
+      output, so you can use IPython sessions as doctest code.
+
+
+Portability and Python requirements
+-----------------------------------
+
+Python requirements: 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.
+
+IPython is developed under Linux, 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).
+
+Mac OS X: it works, apparently without any problems (thanks to Jim Boyle
+at Lawrence Livermore for the information). Thanks to Andrea Riciputi,
+Fink support is available.
+
+CygWin: 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 ipythonrc
+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.
+
+Windows: it works well under Windows XP/2k, and I suspect NT should
+behave similarly. Section 2.3 <node2.html#sub:Under-Windows> describes
+installation details for Windows, including some additional tools needed
+on this platform.
+
+Windows 9x support is present, and has been reported to work fine (at
+least on WinME).
+
+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. 12 <node12.html#sec:IPython-as-shell> for details), as it offers a
+level of control and features which the default cmd.exe doesn't provide.
+
+
+Location
+========
+
+IPython is generously hosted at http://ipython.scipy.org 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 (http://www.enthought.com) and all of the SciPy
+team for their contribution.
+
+Installation
+============
+
+Instant instructions
+--------------------
+
+If you are of the impatient kind, under Linux/Unix simply untar/unzip
+the download, then install with 'python setup.py install'. Under
+Windows, double-click on the provided .exe binary installer.
+
+Then, take a look at Sections 3 <node3.html#sec:good_config> for
+configuring things optimally and 4 <node4.html#sec:quick_tips> for quick
+tips on efficient use of IPython. You can later refer to the rest of the
+manual for all the gory details.
+
+See the notes in sec. 2.4 <#sec:upgrade> for upgrading IPython versions.
+
+
+    Detailed Unix instructions (Linux, Mac OS X, etc.)
+
+For RPM based systems, simply install the supplied package in the usual
+manner. If you download the tar archive, the process is:
+
+   1. Unzip/untar the ipython-XXX.tar.gz file wherever you want (XXX is
+      the version number). It will make a directory called ipython-XXX.
+      Change into that directory where you will find the files README
+      and setup.py. Once you've completed the installation, you can
+      safely remove this directory.
+   2. If you are installing over a previous installation of version
+      0.2.0 or earlier, first remove your $HOME/.ipython directory,
+      since the configuration file format has changed somewhat (the '='
+      were removed from all option specifications). Or you can call
+      ipython with the -upgrade option and it will do this automatically
+      for you.
+   3. IPython uses distutils, so you can install it by simply typing at
+      the system prompt (don't type the $)
+      $ python setup.py install
+      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 |--home| option
+      (or |--prefix|). For example:
+      |$ python setup.py install --home $HOME/local|
+      will install IPython into $HOME/local and its subdirectories
+      (creating them if necessary).
+      You can type
+      |$ python setup.py --help|
+      for more details.
+      Note that if you change the default location for |--home| at
+      installation, IPython may end up installed at a location which is
+      not part of your $PYTHONPATH environment variable. In this case,
+      you'll need to configure this variable to include the actual
+      directory where the IPython/ directory ended (typically the value
+      you give to |--home| plus /lib/python).
+
+
+Mac OSX information
+-------------------
+
+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 /usr/local) or by using Fink, which puts everything under
+/sw. 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.
+
+This page: http://geosci.uchicago.edu/~tobis/pylab.html contains
+information on this topic, with additional details on how to make
+IPython and matplotlib play nicely under OSX.
+
+
+GUI problems
+------------
+
+The following instructions apply to an install of IPython under OSX from
+unpacking the .tar.gz 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.
+
+IPython offers various forms of support for interacting with graphical
+applications 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 pythonw script at installation time,
+which takes care of coordinating things with Apple's graphical environment.
+
+So when installing under OSX, it is best to use the following command: 
+| $ sudo pythonw setup.py install --install-scripts=/usr/local/bin|
+or
+| $ sudo pythonw setup.py install --install-scripts=/usr/bin|
+depending on where you like to keep hand-installed executables.
+
+The resulting script will have an appropriate shebang line (the first
+line in the script whic begins with #!...) 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
+/usr/bin/python, then you might have a stale, cached version in your
+build/scripts-<python-version> directory. Delete that directory and
+rerun the setup.py.
+
+It is also a good idea to use the special flag |--install-scripts| as
+indicated above, to ensure that the ipython scripts end up in a location
+which is part of your $PATH. Otherwise Apple's Python will put the
+scripts in an internal directory not available by default at the command
+line (if you use /usr/local/bin, you need to make sure this is in your
+$PATH, which may not be true by default).
+
+
+Readline problems
+-----------------
+
+By default, the Python version shipped by Apple does not 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:
+http://pythonmac.org/packages/readline-5.0-py2.3-macosx10.3.zip
+
+If you are using OSX 10.4 (Tiger), after installing this package you
+need to either:
+
+   1. move readline.so from /Library/Python/2.3 to
+      /Library/Python/2.3/site-packages, or
+   2. install http://pythonmac.org/packages/TigerPython23Compat.pkg.zip
+
+Users installing against Fink's Python or a properly hand-built one
+should not have this problem.
+
+
+DarwinPorts
+-----------
+
+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:
+
+    From: Markus Banfi <markus.banfi-AT-mospheira.net> 
+
+    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: 
+
+    sudo port install py-ipython 
+
+    It automatically resolved all dependencies (python24, readline,
+    py-readline). So far I did not encounter any problems with the
+    DarwinPorts port of ipython. 
+
+
+
+Windows instructions
+--------------------
+
+Some of IPython's very useful features are:
+
+    * Integrated readline support (Tab-based file, object and attribute
+      completion, input history across sessions, editable command line,
+      etc.)
+    * Coloring of prompts, code and tracebacks.
+
+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.
+
+This library, now named PyReadline, 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 distributed directly from the
+IPython site.
+
+The PyReadline extension requires CTypes and the windows IPython
+installer needs PyWin32, so in all you need:
+
+   1. PyWin32 from http://sourceforge.net/projects/pywin32.
+   2. PyReadline for Windows from
+      http://ipython.scipy.org/moin/PyReadline/Intro. That page contains
+      further details on using and configuring the system to your liking.
+   3. Finally, only if you are using Python 2.3 or 2.4, you need CTypes
+      from http://starship.python.net/crew/theller/ctypes(you must 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.
+
+Warning about a broken readline-like library: several users have
+reported problems stemming from using the pseudo-readline library at
+http://newcenturycomputers.net/projects/readline.html. 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.
+
+
+Installation procedure
+----------------------
+
+Once you have the above installed, from the IPython download directory
+grab the ipython-XXX.win32.exe file, where XXX represents the version
+number. This is a regular windows executable installer, which you can
+simply double-click 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.
+
+IPython tries to install the configuration information in a directory
+named .ipython (_ipython under Windows) located in your 'home'
+directory. IPython sets this directory by looking for a HOME environment
+variable; if such a variable does not exist, it uses HOMEDRIVE\HOMEPATH
+(these are always defined by Windows). This typically gives something
+like C:\Documents and Settings\YourUserName, 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 sys.path, so
+anything you place there can be found by import statements.
+
+
+Upgrading
+---------
+
+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.
+
+
+Manual installation under Win32
+-------------------------------
+
+In case the automatic installer does not work for some reason, you can
+download the ipython-XXX.tar.gz file, which contains the full IPython
+source distribution (the popular WinZip can read .tar.gz files). After
+uncompressing the archive, you can install it at a command terminal just
+like any other Python module, by using 'python setup.py install'.
+
+After the installation, run the supplied win32_manual_post_install.py
+script, which creates the necessary Start Menu shortcuts for you.
+
+
+
+Upgrading from a previous version
+---------------------------------
+
+If you are upgrading from a previous version of IPython, after doing the
+routine installation described above, you should call IPython with the
+-upgrade 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.
+
+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
+C:\Documents and Settings\YourUserName\_ipython, and Win 9x users under
+C:\Program Files\IPython\_ipython.
+
+Initial configuration of your environment
+=========================================
+
+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 $HOME/.ipython. You can change this by
+defining the environment variable IPYTHONDIR, or at runtime with the
+command line option -ipythondir.
+
+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 ipythonrc (with a .ini extension under
+Windows), included for reference in Sec. 7.1
+<node7.html#sec:ipytonrc-sample>. This file is very commented and has
+many variables you can change to suit your taste, you can find more
+details in Sec. 7 <node7.html#sec:customization>. Here we discuss the
+basic things you will want to make sure things are working properly from
+the beginning.
+
+
+
+Access to the Python help system
+--------------------------------
+
+This is true for Python in general (not just for IPython): you should
+have an environment variable called PYTHONDOCS pointing to the directory
+where your HTML Python documentation lives. In my system it's
+/usr/share/doc/python-docs-2.3.4/html, check your local details or ask
+your systems administrator.
+
+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::
+
+    [html]> ls 
+    about.dat acks.html dist/ ext/ index.html lib/ modindex.html
+    stdabout.dat tut/ about.html api/ doc/ icons/ inst/ mac/ ref/ style.css
+
+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.
+
+Under Windows it seems that pydoc finds the documentation automatically,
+so no extra setup appears necessary.
+
+
+Editor
+------
+
+The %edit command (and its alias %ed) will invoke the editor set in your
+environment as EDITOR. If this variable is not set, it will default to
+vi under Linux/Unix and to notepad 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
+Emacs). This way you can edit multi-line code quickly and with the power
+of a real editor right inside IPython.
+
+If you are a dedicated Emacs user, you should set up the Emacs 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 Emacs
+process is already running). For this to work, you need to set your
+EDITOR environment variable to 'emacsclient'. The code below, supplied
+by Francois Pinard, can then be used in your .emacs file to enable the
+server::
+
+    (defvar server-buffer-clients) 
+    (when (and (fboundp 'server-start) (string-equal (getenv "TERM") 'xterm)) 
+      (server-start) 
+      (defun fp-kill-server-with-buffer-routine () 
+        (and server-buffer-clients (server-done))) 
+      (add-hook 'kill-buffer-hook 'fp-kill-server-with-buffer-routine))
+
+You can also set the value of this editor via the commmand-line option
+'-editor' or in your ipythonrc 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).
+
+
+Color
+-----
+
+The default IPython configuration has most bells and whistles turned on
+(they're pretty safe). But there's one that may 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.
+
+The following terminals seem to handle the color sequences fine:
+
+    * Linux main text console, KDE Konsole, Gnome Terminal, E-term,
+      rxvt, xterm.
+    * CDE terminal (tested under Solaris). This one boldfaces light colors.
+    * (X)Emacs buffers. See sec.3.4 <#sec:emacs> for more details on
+      using IPython with (X)Emacs.
+    * A Windows (XP/2k) command prompt with Gary Bishop's support
+      extensions. Gary's extensions are discussed in Sec. 2.3
+      <node2.html#sub:Under-Windows>.
+    * 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.
+
+These have shown problems:
+
+    * Windows command prompt in WinXP/2k logged into a Linux machine via
+      telnet or ssh.
+    * Windows native command prompt in WinXP/2k, without Gary Bishop's
+      extensions. Once Gary's readline library is installed, the normal
+      WinXP/2k command prompt works perfectly.
+
+Currently the following color schemes are available:
+
+    * NoColor: uses no color escapes at all (all escapes are empty '' ''
+      strings). This 'scheme' is thus fully safe to use in any terminal.
+    * Linux: 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.
+    * LightBG: the basic colors are similar to those in the Linux scheme
+      but darker. It is easy to read in terminals with light backgrounds.
+
+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.
+
+
+Input/Output prompts and exception tracebacks
+---------------------------------------------
+
+You can test whether the colored prompts and tracebacks work on your
+system interactively by typing '%colors Linux' at the prompt (use
+'%colors LightBG' if your terminal has a light background). If the input
+prompt shows garbage like:
+[0;32mIn [[1;32m1[0;32m]: [0;00m
+instead of (in color) something like:
+In [1]:
+this means that your terminal doesn't properly handle color escape
+sequences. You can go to a 'no color' mode by typing '%colors NoColor'.
+
+You can try using a different terminal emulator program (Emacs users,
+see below). To permanently set your color preferences, edit the file
+$HOME/.ipython/ipythonrc and set the colors option to the desired value.
+
+
+Object details (types, docstrings, source code, etc.)
+-----------------------------------------------------
+
+IPython has a set of special functions for studying the objects you are
+working with, discussed in detail in Sec. 6.4
+<node6.html#sec:dyn-object-info>. But this system relies on passing
+information which is longer than your screen through a data pager, such
+as the common Unix less and more programs. In order to be able to see
+this information in color, your pager needs to be properly configured. I
+strongly recommend using less instead of more, as it seems that more
+simply can not understand colored text correctly.
+
+In order to configure less as your default pager, do the following:
+
+   1. Set the environment PAGER variable to less.
+   2. Set the environment LESS variable to -r (plus any other options
+      you always want to pass to less by default). This tells less to
+      properly interpret control sequences, which is how color
+      information is given to your terminal.
+
+For the csh or tcsh shells, add to your ~/.cshrc file the lines::
+
+    setenv PAGER less 
+    setenv LESS -r
+
+There is similar syntax for other Unix shells, look at your system
+documentation for details.
+
+If you are on a system which lacks proper data pagers (such as Windows),
+IPython will use a very limited builtin pager.
+
+(X)Emacs configuration
+----------------------
+
+Thanks to the work of Alexander Schmolck and Prabhu Ramachandran,
+currently (X)Emacs and IPython get along very well.
+
+Important note: You will need to use a recent enough version of
+python-mode.el, along with the file ipython.el. You can check that the
+version you have of python-mode.el is new enough by either looking at
+the revision number in the file itself, or asking for it in (X)Emacs via
+M-x py-version. Versions 4.68 and newer contain the necessary fixes for
+proper IPython support.
+
+The file ipython.el is included with the IPython distribution, in the
+documentation directory (where this manual resides in PDF and HTML
+formats).
+
+Once you put these files in your Emacs path, all you need in your .emacs
+file is::
+
+    (require 'ipython) 
+
+This should give you full support for executing code snippets via
+IPython, opening IPython as your Python shell via C-c !, etc.
+
+If you happen to get garbage instead of colored prompts as described in
+the previous section, you may need to set also in your .emacs file::
+
+    (setq ansi-color-for-comint-mode t) 
+
+
+Notes::
+
+    * There is one caveat you should be aware of: you must start the
+      IPython shell before attempting to execute any code regions via
+      C-c |. Simply type C-c ! to start IPython before passing any code
+      regions to the interpreter, and you shouldn't experience any
+      problems.
+      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 ]).
+    * The (X)Emacs support is maintained by Alexander Schmolck, so all
+      comments/requests should be directed to him through the IPython
+      mailing lists.
+    * This code is still somewhat experimental so it's a bit rough
+      around the edges (although in practice, it works quite well).
+    * Be aware that if you customize py-python-command previously, this
+      value will override what ipython.el does (because loading the
+      customization variables comes later).
+
+Quick tips
+==========
+
+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.
+
+The following article by Jeremy Jones provides an introductory tutorial
+about IPython:
+http://www.onlamp.com/pub/a/python/2005/01/27/ipython.html
+
+    * 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 object_name.<TAB> and a list of the
+      object's attributes will be printed (see sec. 6.5
+      <node6.html#sec:readline> 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.
+    * Explore your objects. Typing object_name? 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 %pdoc, %pdef, %psource and %pfile 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 '%' explicitly. See sec. 6.4
+      <node6.html#sec:dyn-object-info> for more.
+    * The %run 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
+      import). I rarely use import for code I am testing, relying on
+      %run instead. See sec. 6.2 <node6.html#sec:magic> 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. 6.9
+      <node6.html#sec:dreload> for a recursive reload command.
+      %run also has special flags for timing the execution of your
+      scripts (-t) and for executing them under the control of either
+      Python's pdb debugger (-d) or profiler (-p). With all of these,
+      %run can be used as the main tool for efficient interactive
+      development of code which you write in your editor of choice.
+    * Use the Python debugger, pdb^2 <footnode.html#foot360>. The %pdb
+      command allows you to toggle on and off the automatic invocation
+      of an IPython-enhanced pdb debugger (with coloring, tab completion
+      and more) at any uncaught exception. The advantage of this is that
+      pdb starts inside 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).
+      Running programs with %run and pdb active can be an efficient to
+      develop and debug code, in many cases eliminating the need for
+      print statements or external debugging tools. I often simply put a
+      1/0 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 1/0.
+      Note also that '%run -d' activates pdb and automatically sets
+      initial breakpoints for you to step through your code, watch
+      variables, etc. See Sec. 6.12 <node6.html#sec:cache_output> for
+      details.
+    * Use the output cache. All output results are automatically stored
+      in a global dictionary named Out and variables named _1, _2, etc.
+      alias them. For example, the result of input line 4 is available
+      either as Out[4] or as _4. Additionally, three variables named _,
+      __ and ___ 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. 6.12
+      <node6.html#sec:cache_output> for more.
+    * Put a ';' 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 _* variables and the Out[]
+      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.
+    * A similar system exists for caching input. All input is stored in
+      a global list called In , so you can re-execute lines 22 through
+      28 plus line 34 by typing 'exec In[22:29]+In[34]' (using Python
+      slicing notation). If you need to execute the same set of lines
+      often, you can assign them to a macro with the %macro function.
+      See sec. 6.11 <node6.html#sec:cache_input> for more.
+    * Use your input history. The %hist command can show you all
+      previous input, without line numbers if desired (option -n) 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 %logstart; these logs can later be either reloaded as
+      IPython sessions or used as code for your programs.
+    * Define your own system aliases. Even though IPython gives you
+      access to your system shell via the ! 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.
+      IPython comes with some pre-defined aliases and a complete system
+      for changing directories, both via a stack (see %pushd, %popd and
+      %dhist) and via direct %cd. The latter keeps a history of visited
+      directories and allows you to go to any previously visited one.
+    * Use Python to manipulate the results of system commands. The '!!'
+      special syntax, and the %sc and %sx magic commands allow you to
+      capture system output into Python variables.
+    * Expand python variables when calling the shell (either via '!' and
+      '!!' or via aliases) by prepending a $ in front of them. You can
+      also expand complete python expressions. See sec. 6.7
+      <node6.html#sub:System-shell-access> for more.
+    * 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. 7.3 <node7.html#sec:profiles> for more.
+    * 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. 9 <node9.html#sec:embed>
+      for more.
+    * Use the Python profiler. When dealing with performance issues, the
+      %run command with a -p option allows you to run complete programs
+      under the control of the Python profiler. The %prun command does a
+      similar job for single Python expressions (like function calls).
+    * 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. 14 <node14.html#sec:interactive-demos> for more.
+    * Run your doctests from within IPython for development and
+      debugging. The special %doctest_mode 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
+      '>>>' prompts, even if they have extra leading whitespace (as is
+      common in doctest files). This combined with the '%history -tn'
+      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.
+
+
+Source code handling tips
+-------------------------
+
+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.
+
+The %edit 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 interactively. Type %edit?
+for the full details on the edit command.
+
+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 %hist
+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::
+
+    %command 10-20 24 28 
+
+where the command given can be:
+
+    * %macro <macroname>: this stores the lines into a variable which,
+      when called at the prompt, re-executes the input. Macros can be
+      edited later using '%edit macroname', and they can be stored
+      persistently across sessions with '%store macroname' (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.
+    * %edit: this will open a text editor with those lines pre-loaded
+      for further modification. It will then execute the resulting
+      file's contents as if you had typed it at the prompt.
+    * %save <filename>: this saves the lines directly to a named file on
+      disk.
+
+While %macro saves input lines into memory for interactive re-execution,
+sometimes you'd like to save your input directly to a file. The %save
+magic does this: its input sytnax is the same as %macro, but it saves
+your input directly to a Python file. Note that the %logstart command
+also saves input, but it logs all input to disk (though you can
+temporarily suspend it and reactivate it with %logoff/%logon); %save
+allows you to select which lines of input you need to save.
+
+
+Lightweight 'version control'
+-----------------------------
+
+When you call %edit 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::
+
+    In [1]: %edit
+
+    IPython will make a temporary file named: /tmp/ipython_edit_yR-HCN.py
+
+    Editing... done. Executing edited code...
+
+    hello - this is a temporary file
+
+    Out[1]: "print 'hello - this is a temporary file'\n"
+
+Now, if you call '%edit -p', IPython tries to open an editor with the
+same data as the last time you used %edit. So if you haven't used %edit
+in the meantime, this same contents will reopen; however, it will be
+done in a new file. 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 '%edit _NN', where NN is the number of the output
+prompt.
+
+Continuing with the example above, this should illustrate this idea::
+
+    In [2]: edit -p
+
+    IPython will make a temporary file named: /tmp/ipython_edit_nA09Qk.py
+
+    Editing... done. Executing edited code...
+
+    hello - now I made some changes
+
+    Out[2]: "print 'hello - now I made some changes'\n"
+
+    In [3]: edit _1
+
+    IPython will make a temporary file named: /tmp/ipython_edit_gy6-zD.py
+
+    Editing... done. Executing edited code...
+
+    hello - this is a temporary file
+
+    IPython version control at work :)
+
+    Out[3]: "print 'hello - this is a temporary file'\nprint 'IPython version control at work :)'\n"
+
+
+This section was written after a contribution by Alexander Belchenko on
+the IPython user list.
+
+
+Effective logging
+-----------------
+
+A very useful suggestion sent in by Robert Kern follows:
+
+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").
+
+    include ipythonrc
+
+    # cancel earlier logfile invocation:
+
+    logfile ''
+
+    execute import time
+
+    execute __cmd = '/Users/kern/research/logfiles/parkfield-%s.log rotate'
+
+    execute __IP.magic_logstart(__cmd % time.strftime('%Y-%m-%d'))
+
+I also added a shell alias for convenience:
+
+    alias parkfield="ipython -pylab -profile parkfield" 
+
+Now I have a nice little directory with everything I ever type in,
+organized by project and date.
+
+Contribute your own: 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!
+
+Command-line use
+================
+
+You start IPython with the command::
+
+    $ ipython [options] files
+
+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 python -i will only execute one
+file and ignore your configuration setup.
+
+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 $HOME/.ipython directory. For Windows users,
+$HOME resolves to C:\\Documents and Settings\\YourUserName in most
+instances. In the rest of this text, we will refer to this directory as
+IPYTHONDIR.
+
+
+Special Threading Options
+
+The following special options are ONLY valid at the beginning of the
+command line, and not later. This is because they control the initial-
+ization of ipython itself, before the normal option-handling mechanism
+is active.
+
+    * [-gthread, -qthread, -q4thread, -wthread, -pylab:] Only one of
+      these can be given, and it can only be given as the first option
+      passed to IPython (it will have no effect in any other position).
+      They provide threading support for the GTK, Qt (versions 3 and 4)
+      and WXPython toolkits, and for the matplotlib library.
+    * [ ] 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).
+    * [ ] Note that with -wthread, you can additionally use the
+      -wxversion option to request a specific version of wx to be used.
+      This requires that you have the wxversion Python module installed,
+      which is part of recent wxPython distributions.
+    * [ ] If -pylab is given, IPython loads special support for the mat
+      plotlib library (http://matplotlib.sourceforge.net), allowing
+      interactive usage of any of its backends as defined in the user's
+      ~/.matplotlib/matplotlibrc file. It automatically activates GTK,
+      Qt or WX threading for IPyhton if the choice of matplotlib backend
+      requires it. It also modifies the %run command to correctly
+      execute (without blocking) any matplotlib-based script which calls
+      show() at the end.
+    * [-tk] The -g/q/q4/wthread options, and -pylab (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, -tk, is available to address this issue. It can
+      only be given as a second option after any of the above (-gthread,
+      -wthread or -pylab).
+    * [ ] If -tk is given, IPython will try to coordinate Tk threading
+      with GTK, Qt or WX. This is however potentially unreliable, and
+      you will have to test on your platform and Python configuration to
+      determine whether it works for you. Debian users have reported
+      success, apparently due to the fact that Debian builds all of Tcl,
+      Tk, Tkinter and Python with pthreads support. Under other Linux
+      environments (such as Fedora Core 2/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.
+    * [ ] There is unfortunately no way for IPython to determine at run
+      time whether -tk will work reliably or not, so you will need to do
+      some experiments before relying on it for regular work.
+
+
+
+Regular Options
+---------------
+
+After the above threading options have been given, regular options can
+follow in any order. All options can be abbreviated to their shortest
+non-ambiguous form and are case-sensitive. One or two dashes can be
+used. Some options have an alternate short form, indicated after a |.
+
+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.
+
+All options with a [no] prepended can be specified in negated form
+(-nooption instead of -option) to turn the feature off.
+
+    * [-help:] print a help message and exit.
+    * [-pylab:] this can only be given as the first option passed to
+      IPython (it will have no effect in any other position). It adds
+      special support for the matplotlib library
+      (http://matplotlib.sourceforge.net
+      http://matplotlib.sourceforge.net), allowing interactive usage of
+      any of its backends as defined in the user's .matplotlibrc file.
+      It automatically activates GTK or WX threading for IPyhton if the
+      choice of matplotlib backend requires it. It also modifies the
+      %run command to correctly execute (without blocking) any
+      matplotlib-based script which calls show() at the end. See Sec. 15
+      <node15.html#sec:matplotlib-support> for more details.
+    * [-autocall] <val>: Make IPython automatically call any callable
+      object even if you didn't type explicit parentheses. For example,
+      'str 43' becomes 'str(43)' automatically. The value can be '0' to
+      disable the feature, '1' for smart autocall, where it is not
+      applied if there are no more arguments on the line, and '2' for
+      full autocall, where all callable objects are automatically called
+      (even if no arguments are present). The default is '1'.
+    * [-[no]autoindent:] Turn automatic indentation on/off.
+    * [-[no]automagic:] make magic commands automatic (without needing
+      their first character to be %). Type %magic at the IPython prompt
+      for more information.
+    * [-[no]autoedit_syntax:] When a syntax error occurs after editing a
+      file, automatically open the file to the trouble causing line for
+      convenient fixing.
+    * [-[no]banner:] Print the initial information banner (default on).
+    * [-c <command>:] execute the given command string, and set sys.argv
+      to ['c']. This is similar to the -c option in the normal Python
+      interpreter.
+    * [-cache_size|cs <n>:] size of the output cache (maximum number of
+      entries to hold in memory). The default is 1000, you can change it
+      permanently in your config file. Setting it to 0 completely
+      disables the caching system, and the minimum value accepted is 20
+      (if you provide a value less than 20, it is reset to 0 and a
+      warning is issued) This limit is defined because otherwise you'll
+      spend more time re-flushing a too small cache than working.
+    * [-classic|cl:] Gives IPython a similar feel to the classic Python
+      prompt.
+    * [-colors <scheme>:] Color scheme for prompts and exception
+      reporting. Currently implemented: NoColor, Linux and LightBG.
+    * [-[no]color_info:] IPython can display information about objects
+      via a set of functions, and optionally can use colors for this,
+      syntax highlighting source code and various other elements.
+      However, because this information is passed through a pager (like
+      'less') and many pagers get confused with color codes, this option
+      is off by default. You can test it and turn it on permanently in
+      your ipythonrc file if it works for you. As a reference, the
+      'less' pager supplied with Mandrake 8.2 works ok, but that in
+      RedHat 7.2 doesn't.
+    * [ ] Test it and turn it on permanently if it works with your
+      system. The magic function %color_info allows you to toggle this
+      interactively for testing.
+    * [-[no]debug:] Show information about the loading process. Very
+      useful to pin down problems with your configuration files or to
+      get details about session restores.
+    * [-[no]deep_reload:] IPython can use the deep_reload module which
+      reloads changes in modules recursively (it replaces the reload()
+      function, so you don't need to change anything to use it).
+      deep_reload() forces a full reload of modules whose code may have
+      changed, which the default reload() function does not.
+    * [ ] When deep_reload is off, IPython will use the normal reload(),
+      but deep_reload will still be available as dreload(). This feature
+      is off by default [which means that you have both normal reload()
+      and dreload()].
+    * [-editor <name>:] Which editor to use with the %edit command. By
+      default, IPython will honor your EDITOR environment variable (if
+      not set, vi is the Unix default and notepad the Windows one).
+      Since this editor is invoked on the fly by IPython and is meant
+      for editing small code snippets, you may want to use a small,
+      lightweight editor here (in case your default EDITOR is something
+      like Emacs).
+    * [-ipythondir <name>:] name of your IPython configuration directory
+      IPYTHONDIR. This can also be specified through the environment
+      variable IPYTHONDIR.
+    * [-log|l:] generate a log file of all input. The file is named
+      ipython_log.py in your current directory (which prevents logs from
+      multiple IPython sessions from trampling each other). You can use
+      this to later restore a session by loading your logfile as a file
+      to be executed with option -logplay (see below).
+    * [-logfile|lf <name>:] specify the name of your logfile.
+    * [-logplay|lp <name>:] 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 -logplay, IPython
+      will try to reconstruct the previous working environment in full,
+      not just execute the commands in the logfile.
+    * [ ] 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.
+    * [ ] Caveats: there are limitations in this option. The history
+      variables _i*,_* and _dh don't get restored properly. In the
+      future we will try to implement full session saving by writing and
+      retrieving a 'snapshot' of the memory state of IPython. But our
+      first attempts failed because of inherent limitations of Python's
+      Pickle module, so this may have to wait.
+    * [-[no]messages:] Print messages which IPython collects about its
+      startup process (default on).
+    * [-[no]pdb:] Automatically call the pdb debugger after every
+      uncaught exception. If you are used to debugging using pdb, this
+      puts you automatically inside of it after any call (either in
+      IPython or in code called by it) which triggers an exception which
+      goes uncaught.
+    * [-[no]pprint:] ipython can optionally use the pprint (pretty
+      printer) module for displaying results. pprint tends to give a
+      nicer display of nested data structures. If you like it, you can
+      turn it on permanently in your config file (default off).
+    * [-profile|p] <name>: assume that your config file is
+      ipythonrc-<name> (looks in current dir first, then in IPYTHONDIR).
+      This is a quick way to keep and load multiple config files for
+      different tasks, especially if you use the include option of
+      config files. You can keep a basic IPYTHONDIR/ipythonrc file and
+      then have other 'profiles' which include this one and load extra
+      things for particular tasks. For example:
+    * [ ] 1. $HOME/.ipython/ipythonrc : load basic things you always want.
+    * [ ] 2. $HOME/.ipython/ipythonrc-math : load (1) and basic
+      math-related modules.
+    * [ ] 3. $HOME/.ipython/ipythonrc-numeric : load (1) and Numeric and
+      plotting modules.
+    * [ ] Since it is possible to create an endless loop by having
+      circular file inclusions, IPython will stop if it reaches 15
+      recursive inclusions.
+    * [-prompt_in1|pi1 <string>:] Specify the string used for input
+      prompts. Note that if you are using numbered prompts, the number
+      is represented with a '\#' in the string. Don't forget to quote
+      strings with spaces embedded in them. Default: 'In [\#]:'.
+      Sec. 7.2 <node7.html#sec:prompts> discusses in detail all the
+      available escapes to customize your prompts.
+    * [-prompt_in2|pi2 <string>:] Similar to the previous option, but
+      used for the continuation prompts. The special sequence '\D' is
+      similar to '\#', but with all digits replaced dots (so you can
+      have your continuation prompt aligned with your input prompt).
+      Default: '   .\D.:' (note three spaces at the start for alignment
+      with 'In [\#]').
+    * [-prompt_out|po <string>:] String used for output prompts, also
+      uses numbers like prompt_in1. Default: 'Out[\#]:'
+    * [-quick:] start in bare bones mode (no config file loaded).
+    * [-rcfile <name>:] name of your IPython resource configuration
+      file. Normally IPython loads ipythonrc (from current directory) or
+      IPYTHONDIR/ipythonrc.
+    * [ ] If the loading of your config file fails, IPython starts with
+      a bare bones configuration (no modules loaded at all).
+    * [-[no]readline:] use the readline library, which is needed to
+      support name completion and command history, among other things.
+      It is enabled by default, but may cause problems for users of
+      X/Emacs in Python comint or shell buffers.
+    * [ ] Note that X/Emacs 'eterm' buffers (opened with M-x term)
+      support IPython's readline and syntax coloring fine, only 'emacs'
+      (M-x shell and C-c !) buffers do not.
+    * [-screen_length|sl <n>:] number of lines of your screen. This is
+      used to control printing of very long strings. Strings longer than
+      this number of lines will be sent through a pager instead of
+      directly printed.
+    * [ ] 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.
+    * [-separate_in|si <string>:] separator before input prompts.
+      Default: '\n'
+    * [-separate_out|so <string>:] separator before output prompts.
+      Default: nothing.
+    * [-separate_out2|so2 <string>:] separator after output prompts.
+      Default: nothing.
+    * [ ] For these three options, use the value 0 to specify no separator.
+    * [-nosep:] shorthand for '-SeparateIn 0 -SeparateOut 0
+      -SeparateOut2 0'. Simply removes all input/output separators.
+    * [-upgrade:] allows you to upgrade your IPYTHONDIR 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 .old
+      extension) all files which it overwrites so that you can merge
+      back any customizations you might have in your personal files.
+    * [-Version:] print version information and exit.
+    * [-wxversion <string>:] Select a specific version of wxPython (used
+      in conjunction with -wthread). Requires the wxversion module, part
+      of recent wxPython distributions
+    * [-xmode <modename>:] Mode for exception reporting.
+    * [ ] Valid modes: Plain, Context and Verbose.
+    * [ ] Plain: similar to python's normal traceback printing.
+    * [ ] Context: prints 5 lines of context source code around each
+      line in the traceback.
+    * [ ] 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).
+
+Interactive use
+===============
+
+Warning: IPython relies on the existence of a global variable called
+__IP which controls the shell itself. If you redefine __IP to anything,
+bizarre behavior will quickly occur.
+
+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.
+
+
+Caution for Windows users
+-------------------------
+
+Windows, unfortunately, uses the '\' character as a path separator. This
+is a terrible choice, because '\' 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 '\' in them will cause strange errors.
+
+A partial solution is to use instead the '/' character as a path
+separator, which Windows recognizes in most situations. However, in
+Windows commands '/' 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:
+%copy \opt/foo/bar.txt \tmp
+
+There is no sensible thing IPython can do to truly work around this flaw
+in Windows^3 <footnode.html#foot878>.
+
+
+
+Magic command system
+--------------------
+
+IPython will treat any line whose first character is a % 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 % character, but parameters are given without
+parentheses or quotes.
+
+Example: typing '%cd mydir' (without the quotes) changes you working
+directory to 'mydir', if it exists.
+
+If you have 'automagic' enabled (in your ipythonrc file, via the command
+line option -automagic or with the %automagic function), you don't need
+to type in the % explicitly. IPython will scan its internal list of
+magic functions and call one if it exists. With automagic on you can
+then just type 'cd mydir' to go to directory 'mydir'. 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 % character at the beginning of the line.
+
+An example (with automagic on) should clarify all this::
+
+    In [1]: cd ipython # %cd is called by automagic
+
+    /home/fperez/ipython
+
+    In [2]: cd=1 # now cd is just a variable
+
+    In [3]: cd .. # and doesn't work as a function anymore
+
+    ------------------------------
+
+        File "<console>", line 1
+
+          cd ..
+
+              ^
+
+    SyntaxError: invalid syntax
+
+    In [4]: %cd .. # but %cd always works
+
+    /home/fperez
+
+    In [5]: del cd # if you remove the cd variable
+
+    In [6]: cd ipython # automagic can work again
+
+    /home/fperez/ipython
+
+You can define your own magic functions to extend the system. The
+following example defines a new magic command, %impall::
+
+    import IPython.ipapi 
+
+    ip = IPython.ipapi.get()
+
+    def doimp(self, arg):
+
+        ip = self.api
+
+        ip.ex("import %s; reload(%s); from %s import *" % (
+
+        arg,arg,arg)
+
+        )
+
+    ip.expose_magic('impall', doimp)
+
+You can also define your own aliased names for magic functions. In your
+ipythonrc file, placing a line like:
+
+execute __IP.magic_cl = __IP.magic_clear
+
+will define %cl as a new name for %clear.
+
+Type %magic for more information, including a list of all available
+magic functions at any time and their docstrings. You can also type
+%magic_function_name? (see sec. 6.4 <#sec:dyn-object-info> for
+information on the '?' system) to get information about any particular
+magic function you are interested in.
+
+
+Magic commands
+--------------
+
+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.
+
+A list of all the magic commands available in IPython's default
+installation follows. This is similar to what you'll see by simply
+typing %magic at the prompt, but that will also give you information
+about magic commands you may have added as part of your personal
+customizations.
+
+
+%Exit: Exit IPython without confirmation.
+
+
+%Pprint: Toggle pretty printing on/off.
+
+
+%alias: Define an alias for a system command.
+
+'%alias alias_name cmd' defines 'alias_name' as an alias for 'cmd'
+
+Then, typing 'alias_name params' will execute the system command 'cmd
+params' (from your underlying operating system).
+
+Aliases have lower precedence than magic functions and Python normal
+variables, so if 'foo' is both a Python variable and an alias, the alias
+can not be executed until 'del foo' removes the Python variable.
+
+You can use the %l specifier in an alias definition to represent the
+whole line when the alias is called. For example:
+
+In [2]: alias all echo "Input in brackets: <%l>"
+In [3]: all hello world
+Input in brackets: <hello world>
+
+You can also define aliases with parameters using %s specifiers (one per
+parameter):
+
+In [1]: alias parts echo first %s second %s
+In [2]: %parts A B
+first A second B
+In [3]: %parts A
+Incorrect number of arguments: 2 expected.
+parts is an alias to: 'echo first %s second %s'
+
+Note that %l and %s are mutually exclusive. You can only use one or the
+other in your aliases.
+
+Aliases expand Python variables just like system calls using ! or !! do:
+all expressions prefixed with '$' get expanded. For details of the
+semantic rules, see PEP-215: http://www.python.org/peps/pep-0215.html.
+This is the library used by IPython for variable expansion. If you want
+to access a true shell variable, an extra $ is necessary to prevent its
+expansion by IPython:
+
+In [6]: alias show echo
+In [7]: PATH='A Python string'
+In [8]: show $PATH
+A Python string
+In [9]: show $$PATH
+/usr/local/lf9560/bin:/usr/local/intel/compiler70/ia32/bin:...
+
+You can use the alias facility to acess all of $PATH. See the %rehash
+and %rehashx functions, which automatically create aliases for the
+contents of your $PATH.
+
+If called with no parameters, %alias prints the current alias table.
+
+
+%autocall: Make functions callable without having to type parentheses.
+
+Usage:
+
+%autocall [mode]
+
+The mode can be one of: 0->Off, 1->Smart, 2->Full. If not given, the
+value is toggled on and off (remembering the previous state).
+
+In more detail, these values mean:
+
+0 -> fully disabled
+
+1 -> active, but do not apply if there are no arguments on the line.
+
+In this mode, you get:
+
+In [1]: callable Out[1]: <built-in function callable>
+
+In [2]: callable 'hello' ---> callable('hello') Out[2]: False
+
+2 -> Active always. Even if no arguments are present, the callable
+object is called:
+
+In [4]: callable ---> callable()
+
+Note that even with autocall off, you can still use '/' at the start of
+a line to treat the first argument on the command line as a function and
+add parentheses to it:
+
+In [8]: /str 43 ---> str(43) Out[8]: '43'
+
+
+%autoindent: Toggle autoindent on/off (if available).
+
+
+%automagic: Make magic functions callable without having to type the
+initial %.
+
+Without argumentsl toggles on/off (when off, you must call it as
+%automagic, of course). With arguments it sets the value, and you can
+use any of (case insensitive):
+
+- on,1,True: to activate
+
+- off,0,False: to deactivate.
+
+Note that magic functions have lowest priority, so if there's a variable
+whose name collides with that of a magic fn, automagic won't work for
+that function (you get the variable instead). However, if you delete the
+variable (del var), the previously shadowed magic function becomes
+visible to automagic again.
+
+
+%bg: Run a job in the background, in a separate thread.
+
+For example,
+
+%bg myfunc(x,y,z=1)
+
+will execute 'myfunc(x,y,z=1)' in a background thread. As soon as the
+execution starts, a message will be printed indicating the job number.
+If your job number is 5, you can use
+
+myvar = jobs.result(5) or myvar = jobs[5].result
+
+to assign this result to variable 'myvar'.
+
+IPython has a job manager, accessible via the 'jobs' object. You can
+type jobs? to get more information about it, and use jobs.<TAB> to see
+its attributes. All attributes not starting with an underscore are meant
+for public use.
+
+In particular, look at the jobs.new() method, which is used to create
+new jobs. This magic %bg function is just a convenience wrapper around
+jobs.new(), for expression-based jobs. If you want to create a new job
+with an explicit function object and arguments, you must call jobs.new()
+directly.
+
+The jobs.new docstring also describes in detail several important
+caveats associated with a thread-based model for background job
+execution. Type jobs.new? for details.
+
+You can check the status of all jobs with jobs.status().
+
+The jobs variable is set by IPython into the Python builtin namespace.
+If you ever declare a variable named 'jobs', you will shadow this name.
+You can either delete your global jobs variable to regain access to the
+job manager, or make a new name and assign it manually to the manager
+(stored in IPython's namespace). For example, to assign the job manager
+to the Jobs name, use:
+
+Jobs = __builtins__.jobs
+
+
+%bookmark: Manage IPython's bookmark system.
+
+%bookmark <name> - set bookmark to current dir %bookmark <name> <dir> -
+set bookmark to <dir> %bookmark -l - list all bookmarks %bookmark -d
+<name> - remove bookmark %bookmark -r - remove all bookmarks
+
+You can later on access a bookmarked folder with: %cd -b <name> or
+simply '%cd <name>' if there is no directory called <name> AND there is
+such a bookmark defined.
+
+Your bookmarks persist through IPython sessions, but they are associated
+with each profile.
+
+
+%cd: Change the current working directory.
+
+This command automatically maintains an internal list of directories you
+visit during your IPython session, in the variable _dh. The command
+%dhist shows this history nicely formatted. You can also do 'cd -<tab>'
+to see directory history conveniently.
+
+Usage:
+
+cd 'dir': changes to directory 'dir'.
+
+cd -: changes to the last visited directory.
+
+cd -<n>: changes to the n-th directory in the directory history.
+
+cd -b <bookmark_name>: jump to a bookmark set by %bookmark (note: cd
+<bookmark_name> is enough if there is no directory <bookmark_name>, but
+a bookmark with the name exists.) 'cd -b <tab>' allows you to
+tab-complete bookmark names.
+
+Options:
+
+-q: quiet. Do not print the working directory after the cd command is
+executed. By default IPython's cd command does print this directory,
+since the default prompts do not display path information.
+
+Note that !cd doesn't work for this purpose because the shell where
+!command runs is immediately discarded after executing 'command'.
+
+
+%color_info: Toggle color_info.
+
+The color_info configuration parameter controls whether colors are used
+for displaying object details (by things like %psource, %pfile or the
+'?' system). This function toggles this value with each call.
+
+Note that unless you have a fairly recent pager (less works better than
+more) in your system, using colored object information displays will not
+work properly. Test it and see.
+
+
+%colors: Switch color scheme for prompts, info system and exception
+handlers.
+
+Currently implemented schemes: NoColor, Linux, LightBG.
+
+Color scheme names are not case-sensitive.
+
+
+%cpaste: Allows you to paste & execute a pre-formatted code block from
+clipboard
+
+You must terminate the block with '-' (two minus-signs) alone on the
+line. You can also provide your own sentinel with '%paste -s %%' ('%%'
+is the new sentinel for this operation)
+
+The block is dedented prior to execution to enable execution of method
+definitions. '>' and '+' characters at the beginning of a line are
+ignored, to allow pasting directly from e-mails or diff files. The
+executed block is also assigned to variable named 'pasted_block' for
+later editing with '%edit pasted_block'.
+
+You can also pass a variable name as an argument, e.g. '%cpaste foo'.
+This assigns the pasted block to variable 'foo' as string, without
+dedenting or executing it.
+
+Do not be alarmed by garbled output on Windows (it's a readline bug).
+Just press enter and type - (and press enter again) and the block will
+be what was just pasted.
+
+IPython statements (magics, shell escapes) are not supported (yet).
+
+
+%debug: Activate the interactive debugger in post-mortem mode.
+
+If an exception has just occurred, this lets you inspect its stack
+frames interactively. Note that this will always work only on the last
+traceback that occurred, so you must call this quickly after an
+exception that you wish to inspect has fired, because if another one
+occurs, it clobbers the previous one.
+
+If you want IPython to automatically do this on every exception, see the
+%pdb magic for more details.
+
+
+%dhist: Print your history of visited directories.
+
+%dhist -> print full history
+%dhist n -> print last n entries only
+%dhist n1 n2 -> print entries between n1 and n2 (n1 not included)
+
+This history is automatically maintained by the %cd command, and always
+available as the global list variable _dh. You can use %cd -<n> to go to
+directory number <n>.
+
+Note that most of time, you should view directory history by entering cd
+-<TAB>.
+
+
+%dirs: Return the current directory stack.
+
+
+%doctest_mode: Toggle doctest mode on and off.
+
+This mode allows you to toggle the prompt behavior between normal
+IPython prompts and ones that are as similar to the default IPython
+interpreter as possible.
+
+It also supports the pasting of code snippets that have leading '»>' and
+'...' prompts in them. This means that you can paste doctests from files
+or docstrings (even if they have leading whitespace), and the code will
+execute correctly. You can then use '%history -tn' to see the translated
+history without line numbers; this will give you the input after removal
+of all the leading prompts and whitespace, which can be pasted back into
+an editor.
+
+With these features, you can switch into this mode easily whenever you
+need to do testing and changes to doctests, without having to leave your
+existing IPython session.
+
+
+%ed: Alias to %edit.
+
+
+%edit: Bring up an editor and execute the resulting code.
+
+Usage: %edit [options] [args]
+
+%edit runs IPython's editor hook. The default version of this hook is
+set to call the __IPYTHON__.rc.editor command. This is read from your
+environment variable $EDITOR. If this isn't found, it will default to vi
+under Linux/Unix and to notepad under Windows. See the end of this
+docstring for how to change the editor hook.
+
+You can also set the value of this editor via the command line option
+'-editor' or in your ipythonrc file. This is useful if you wish to use
+specifically for IPython an editor different from your typical default
+(and for Windows users who typically don't set environment variables).
+
+This command allows you to conveniently edit multi-line code right in
+your IPython session.
+
+If called without arguments, %edit opens up an empty editor with a
+temporary file and will execute the contents of this file when you close
+it (don't forget to save it!).
+
+Options:
+
+-n <number>: open the editor at a specified line number. By default, the
+IPython editor hook uses the unix syntax 'editor +N filename', but you
+can configure this by providing your own modified hook if your favorite
+editor supports line-number specifications with a different syntax.
+
+-p: this will call the editor with the same data as the previous time it
+was used, regardless of how long ago (in your current session) it was.
+
+-r: use 'raw' input. This option only applies to input taken from the
+user's history. By default, the 'processed' history is used, so that
+magics are loaded in their transformed version to valid Python. If this
+option is given, the raw input as typed as the command line is used
+instead. When you exit the editor, it will be executed by IPython's own
+processor.
+
+-x: do not execute the edited code immediately upon exit. This is mainly
+useful if you are editing programs which need to be called with command
+line arguments, which you can then do using %run.
+
+Arguments:
+
+If arguments are given, the following possibilites exist:
+
+    - The arguments are numbers or pairs of colon-separated numbers (like 1
+    4:8 9). These are interpreted as lines of previous input to be loaded
+    into the editor. The syntax is the same of the %macro command.
+
+    - If the argument doesn't start with a number, it is evaluated as a
+    variable and its contents loaded into the editor. You can thus edit any
+    string which contains python code (including the result of previous edits).
+
+    - If the argument is the name of an object (other than a string),
+    IPython will try to locate the file where it was defined and open the
+    editor at the point where it is defined. You can use '%edit function' to
+    load an editor exactly at the point where 'function' is defined, edit it
+    and have the file be executed automatically.
+
+If the object is a macro (see %macro for details), this opens up your
+specified editor with a temporary file containing the macro's data. Upon
+exit, the macro is reloaded with the contents of the file.
+
+Note: opening at an exact line is only supported under Unix, and some
+editors (like kedit and gedit up to Gnome 2.8) do not understand the
+'+NUMBER' parameter necessary for this feature. Good editors like
+(X)Emacs, vi, jed, pico and joe all do.
+
+- If the argument is not found as a variable, IPython will look for a
+file with that name (adding .py if necessary) and load it into the
+editor. It will execute its contents with execfile() when you exit,
+loading any code in the file into your interactive namespace.
+
+After executing your code, %edit will return as output the code you
+typed in the editor (except when it was an existing file). This way you
+can reload the code in further invocations of %edit as a variable, via
+_<NUMBER> or Out[<NUMBER>], where <NUMBER> is the prompt number of the
+output.
+
+Note that %edit is also available through the alias %ed.
+
+This is an example of creating a simple function inside the editor and
+then modifying it. First, start up the editor::
+
+    In [1]: ed
+    Editing... done. Executing edited code...
+    Out[1]: 'def foo():\n print "foo() was defined in an editing session"\n'
+
+    We can then call the function foo():
+
+    In [2]: foo()
+    foo() was defined in an editing session
+
+    Now we edit foo. IPython automatically loads the editor with the
+    (temporary) file where foo() was previously defined:
+
+    In [3]: ed foo
+    Editing... done. Executing edited code...
+
+    And if we call foo() again we get the modified version:
+
+    In [4]: foo()
+    foo() has now been changed!
+
+    Here is an example of how to edit a code snippet successive times. First
+    we call the editor:
+
+    In [8]: ed
+    Editing... done. Executing edited code...
+    hello
+    Out[8]: "print 'hello'\n"
+
+    Now we call it again with the previous output (stored in _):
+
+    In [9]: ed _
+    Editing... done. Executing edited code...
+    hello world
+    Out[9]: "print 'hello world'\n"
+
+    Now we call it with the output #8 (stored in _8, also as Out[8]):
+
+    In [10]: ed _8
+    Editing... done. Executing edited code...
+    hello again
+    Out[10]: "print 'hello again'\n"
+
+Changing the default editor hook:
+
+If you wish to write your own editor hook, you can put it in a
+configuration file which you load at startup time. The default hook is
+defined in the IPython.hooks module, and you can use that as a starting
+example for further modifications. That file also has general
+instructions on how to set a new hook for use once you've defined it.
+
+
+%env: List environment variables.
+
+
+%exit: Exit IPython, confirming if configured to do so.
+
+You can configure whether IPython asks for confirmation upon exit by
+setting the confirm_exit flag in the ipythonrc file.
+
+
+%logoff: Temporarily stop logging.
+
+You must have previously started logging.
+
+
+%logon: Restart logging.
+
+This function is for restarting logging which you've temporarily stopped
+with %logoff. For starting logging for the first time, you must use the
+%logstart function, which allows you to specify an optional log filename.
+
+
+%logstart: Start logging anywhere in a session.
+
+%logstart [-o|-r|-t] [log_name [log_mode]]
+
+If no name is given, it defaults to a file named 'ipython_log.py' in
+your current directory, in 'rotate' mode (see below).
+
+'%logstart name' saves to file 'name' in 'backup' mode. It saves your
+history up to that point and then continues logging.
+
+%logstart takes a second optional parameter: logging mode. This can be
+one of (note that the modes are given unquoted):
+append: well, that says it.
+backup: rename (if exists) to name  and start name.
+global: single logfile in your home dir, appended to.
+over : overwrite existing log.
+rotate: create rotating logs name.1 , name.2 , etc.
+
+Options:
+
+-o: log also IPython's output. In this mode, all commands which generate
+an Out[NN] prompt are recorded to the logfile, right after their
+corresponding input line. The output lines are always prepended with a
+'#[Out]# ' marker, so that the log remains valid Python code.
+
+Since this marker is always the same, filtering only the output from a
+log is very easy, using for example a simple awk call:
+
+awk -F'#
+
+\begin{displaymath}Out\end{displaymath}
+
+# ' 'if($2) print $2' ipython_log.py
+
+-r: log 'raw' input. Normally, IPython's logs contain the processed
+input, so that user lines are logged in their final form, converted into
+valid Python. For example, %Exit is logged as '_ip.magic("Exit"). If the
+-r flag is given, all input is logged exactly as typed, with no
+transformations applied.
+
+-t: put timestamps before each input line logged (these are put in
+comments).
+
+
+%logstate: Print the status of the logging system.
+
+
+%logstop: Fully stop logging and close log file.
+
+In order to start logging again, a new %logstart call needs to be made,
+possibly (though not necessarily) with a new filename, mode and other
+options.
+
+
+%lsmagic: List currently available magic functions.
+
+
+%macro: Define a set of input lines as a macro for future re-execution.
+
+Usage:
+%macro [options] name n1-n2 n3-n4 ... n5 .. n6 ...
+
+Options:
+
+-r: use 'raw' input. By default, the 'processed' history is used, so
+that magics are loaded in their transformed version to valid Python. If
+this option is given, the raw input as typed as the command line is used
+instead.
+
+This will define a global variable called 'name' which is a string made
+of joining the slices and lines you specify (n1,n2,... numbers above)
+from your input history into a single string. This variable acts like an
+automatic function which re-executes those lines as if you had typed
+them. You just type 'name' at the prompt and the code executes.
+
+The notation for indicating number ranges is: n1-n2 means 'use line
+numbers n1,...n2' (the endpoint is included). That is, '5-7' means using
+the lines numbered 5,6 and 7.
+
+Note: as a 'hidden' feature, you can also use traditional python slice
+notation, where N:M means numbers N through M-1.
+
+For example, if your history contains (%hist prints it):
+
+44: x=1
+45: y=3
+46: z=x+y
+47: print x
+48: a=5
+49: print 'x',x,'y',y
+
+you can create a macro with lines 44 through 47 (included) and line 49
+called my_macro with:
+
+In [51]: %macro my_macro 44-47 49
+
+Now, typing 'my_macro' (without quotes) will re-execute all this code in
+one pass.
+
+You don't need to give the line-numbers in order, and any given line
+number can appear multiple times. You can assemble macros with any lines
+from your input history in any order.
+
+The macro is a simple object which holds its value in an attribute, but
+IPython's display system checks for macros and executes them as code
+instead of printing them when you type their name.
+
+You can view a macro's contents by explicitly printing it with:
+
+'print macro_name'.
+
+For one-off cases which DON'T contain magic function calls in them you
+can obtain similar results by explicitly executing slices from your
+input history with:
+
+In [60]: exec In[44:48]+In[49]
+
+
+%magic: Print information about the magic function system.
+
+
+%page: Pretty print the object and display it through a pager.
+
+%page [options] OBJECT
+
+If no object is given, use _ (last output).
+
+Options:
+
+-r: page str(object), don't pretty-print it.
+
+
+%pdb: Control the automatic calling of the pdb interactive debugger.
+
+Call as '%pdb on', '%pdb 1', '%pdb off' or '%pdb 0'. If called without
+argument it works as a toggle.
+
+When an exception is triggered, IPython can optionally call the
+interactive pdb debugger after the traceback printout. %pdb toggles this
+feature on and off.
+
+The initial state of this feature is set in your ipythonrc configuration
+file (the variable is called 'pdb').
+
+If you want to just activate the debugger AFTER an exception has fired,
+without having to type '%pdb on' and rerunning your code, you can use
+the %debug magic.
+
+
+%pdef: Print the definition header for any callable object.
+
+If the object is a class, print the constructor information.
+
+
+%pdoc: Print the docstring for an object.
+
+If the given object is a class, it will print both the class and the
+constructor docstrings.
+
+
+%pfile: Print (or run through pager) the file where an object is defined.
+
+The file opens at the line where the object definition begins. IPython
+will honor the environment variable PAGER if set, and otherwise will do
+its best to print the file in a convenient form.
+
+If the given argument is not an object currently defined, IPython will
+try to interpret it as a filename (automatically adding a .py extension
+if needed). You can thus use %pfile as a syntax highlighting code viewer.
+
+
+%pinfo: Provide detailed information about an object.
+
+'%pinfo object' is just a synonym for object? or ?object.
+
+
+%popd: Change to directory popped off the top of the stack.
+
+
+%profile: Print your currently active IPyhton profile.
+
+
+%prun: Run a statement through the python code profiler.
+
+Usage:
+%prun [options] statement
+
+The given statement (which doesn't require quote marks) is run via the
+python profiler in a manner similar to the profile.run() function.
+Namespaces are internally managed to work correctly; profile.run cannot
+be used in IPython because it makes certain assumptions about namespaces
+which do not hold under IPython.
+
+Options:
+
+-l <limit>: you can place restrictions on what or how much of the
+profile gets printed. The limit value can be:
+
+* A string: only information for function names containing this string
+is printed.
+
+* An integer: only these many lines are printed.
+
+* A float (between 0 and 1): this fraction of the report is printed (for
+example, use a limit of 0.4 to see the topmost 40% only).
+
+You can combine several limits with repeated use of the option. For
+example, '-l __init__ -l 5' will print only the topmost 5 lines of
+information about class constructors.
+
+-r: return the pstats.Stats object generated by the profiling. This
+object has all the information about the profile in it, and you can
+later use it for further analysis or in other functions.
+
+-s <key>: sort profile by given key. You can provide more than one key
+by using the option several times: '-s key1 -s key2 -s key3...'. The
+default sorting key is 'time'.
+
+The following is copied verbatim from the profile documentation
+referenced below:
+
+When more than one key is provided, additional keys are used as
+secondary criteria when the there is equality in all keys selected
+before them.
+
+Abbreviations can be used for any key names, as long as the abbreviation
+is unambiguous. The following are the keys currently defined:
+
+Valid Arg Meaning
+"calls" call count
+"cumulative" cumulative time
+"file" file name
+"module" file name
+"pcalls" primitive call count
+"line" line number
+"name" function name
+"nfl" name/file/line
+"stdname" standard name
+"time" internal time
+
+Note that all sorts on statistics are in descending order (placing most
+time consuming items first), where as name, file, and line number
+searches are in ascending order (i.e., alphabetical). The subtle
+distinction between "nfl" and "stdname" is that the standard name is a
+sort of the name as printed, which means that the embedded line numbers
+get compared in an odd way. For example, lines 3, 20, and 40 would (if
+the file names were the same) appear in the string order "20" "3" and
+"40". In contrast, "nfl" does a numeric compare of the line numbers. In
+fact, sort_stats("nfl") is the same as sort_stats("name", "file", "line").
+
+-T <filename>: save profile results as shown on screen to a text file.
+The profile is still shown on screen.
+
+-D <filename>: save (via dump_stats) profile statistics to given
+filename. This data is in a format understod by the pstats module, and
+is generated by a call to the dump_stats() method of profile objects.
+The profile is still shown on screen.
+
+If you want to run complete programs under the profiler's control, use
+'%run -p [prof_opts] filename.py [args to program]' where prof_opts
+contains profiler specific options as described here.
+
+You can read the complete documentation for the profile module with:
+In [1]: import profile; profile.help()
+
+
+%psearch: Search for object in namespaces by wildcard.
+
+%psearch [options] PATTERN [OBJECT TYPE]
+
+Note: ? can be used as a synonym for %psearch, at the beginning or at
+the end: both a*? and ?a* are equivalent to '%psearch a*'. Still, the
+rest of the command line must be unchanged (options come first), so for
+example the following forms are equivalent
+
+%psearch -i a* function -i a* function? ?-i a* function
+
+Arguments:
+
+PATTERN
+
+where PATTERN is a string containing * as a wildcard similar to its use
+in a shell. The pattern is matched in all namespaces on the search path.
+By default objects starting with a single _ are not matched, many
+IPython generated objects have a single underscore. The default is case
+insensitive matching. Matching is also done on the attributes of objects
+and not only on the objects in a module.
+
+[OBJECT TYPE]
+
+Is the name of a python type from the types module. The name is given in
+lowercase without the ending type, ex. StringType is written string. By
+adding a type here only objects matching the given type are matched.
+Using all here makes the pattern match all types (this is the default).
+
+Options:
+
+-a: makes the pattern match even objects whose names start with a single
+underscore. These names are normally ommitted from the search.
+
+-i/-c: make the pattern case insensitive/sensitive. If neither of these
+options is given, the default is read from your ipythonrc file. The
+option name which sets this value is 'wildcards_case_sensitive'. If this
+option is not specified in your ipythonrc file, IPython's internal
+default is to do a case sensitive search.
+
+-e/-s NAMESPACE: exclude/search a given namespace. The pattern you
+specifiy can be searched in any of the following namespaces: 'builtin',
+'user', 'user_global','internal', 'alias', where 'builtin' and 'user'
+are the search defaults. Note that you should not use quotes when
+specifying namespaces.
+
+'Builtin' contains the python module builtin, 'user' contains all user
+data, 'alias' only contain the shell aliases and no python objects,
+'internal' contains objects used by IPython. The 'user_global' namespace
+is only used by embedded IPython instances, and it contains module-level
+globals. You can add namespaces to the search with -s or exclude them
+with -e (these options can be given more than once).
+
+Examples:
+
+%psearch a* -> objects beginning with an a %psearch -e builtin a* ->
+objects NOT in the builtin space starting in a %psearch a* function ->
+all functions beginning with an a %psearch re.e* -> objects beginning
+with an e in module re %psearch r*.e* -> objects that start with e in
+modules starting in r %psearch r*.* string -> all strings in modules
+beginning with r
+
+Case sensitve search:
+
+%psearch -c a* list all object beginning with lower case a
+
+Show objects beginning with a single _:
+
+%psearch -a _* list objects beginning with a single underscore
+
+
+%psource: Print (or run through pager) the source code for an object.
+
+
+%pushd: Place the current dir on stack and change directory.
+
+Usage:
+%pushd ['dirname']
+
+
+%pwd: Return the current working directory path.
+
+
+%pycat: Show a syntax-highlighted file through a pager.
+
+This magic is similar to the cat utility, but it will assume the file to
+be Python source and will show it with syntax highlighting.
+
+
+%quickref: Show a quick reference sheet
+
+
+%quit: Exit IPython, confirming if configured to do so (like %exit)
+
+
+%r: Repeat previous input.
+
+Note: Consider using the more powerfull %rep instead!
+
+If given an argument, repeats the previous command which starts with the
+same string, otherwise it just repeats the previous input.
+
+Shell escaped commands (with ! as first character) are not recognized by
+this system, only pure python code and magic commands.
+
+
+%rehashx: Update the alias table with all executable files in $PATH.
+
+This version explicitly checks that every entry in $PATH is a file with
+execute access (os.X_OK), so it is much slower than %rehash.
+
+Under Windows, it checks executability as a match agains a '|'-separated
+string of extensions, stored in the IPython config variable
+win_exec_ext. This defaults to 'exe|com|bat'.
+
+This function also resets the root module cache of module completer,
+used on slow filesystems.
+
+
+%reset: Resets the namespace by removing all names defined by the user.
+
+Input/Output history are left around in case you need them.
+
+
+%run: Run the named file inside IPython as a program.
+
+Usage:
+%run [-n -i -t [-N<N>] -d [-b<N>] -p [profile options]] file [args]
+
+Parameters after the filename are passed as command-line arguments to
+the program (put in sys.argv). Then, control returns to IPython's prompt.
+
+This is similar to running at a system prompt:
+$ python file args
+but with the advantage of giving you IPython's tracebacks, and of
+loading all variables into your interactive namespace for further use
+(unless -p is used, see below).
+
+The file is executed in a namespace initially consisting only of
+__name__=='__main__' and sys.argv constructed as indicated. It thus sees
+its environment as if it were being run as a stand-alone program (except
+for sharing global objects such as previously imported modules). But
+after execution, the IPython interactive namespace gets updated with all
+variables defined in the program (except for __name__ and sys.argv).
+This allows for very convenient loading of code for interactive work,
+while giving each program a 'clean sheet' to run in.
+
+Options:
+
+-n: __name__ is NOT set to '__main__', but to the running file's name
+without extension (as python does under import). This allows running
+scripts and reloading the definitions in them without calling code
+protected by an ' if __name__ == "__main__" ' clause.
+
+-i: run the file in IPython's namespace instead of an empty one. This is
+useful if you are experimenting with code written in a text editor which
+depends on variables defined interactively.
+
+-e: ignore sys.exit() calls or SystemExit exceptions in the script being
+run. This is particularly useful if IPython is being used to run
+unittests, which always exit with a sys.exit() call. In such cases you
+are interested in the output of the test results, not in seeing a
+traceback of the unittest module.
+
+-t: print timing information at the end of the run. IPython will give
+you an estimated CPU time consumption for your script, which under Unix
+uses the resource module to avoid the wraparound problems of
+time.clock(). Under Unix, an estimate of time spent on system tasks is
+also given (for Windows platforms this is reported as 0.0).
+
+If -t is given, an additional -N<N> option can be given, where <N> must
+be an integer indicating how many times you want the script to run. The
+final timing report will include total and per run results.
+
+For example (testing the script uniq_stable.py):
+
+In [1]: run -t uniq_stable
+
+IPython CPU timings (estimated):
+User : 0.19597 s.
+System: 0.0 s.
+
+In [2]: run -t -N5 uniq_stable
+
+IPython CPU timings (estimated):
+Total runs performed: 5
+Times : Total Per run
+User : 0.910862 s, 0.1821724 s.
+System: 0.0 s, 0.0 s.
+
+-d: run your program under the control of pdb, the Python debugger. This
+allows you to execute your program step by step, watch variables, etc.
+Internally, what IPython does is similar to calling:
+
+pdb.run('execfile("YOURFILENAME")')
+
+with a breakpoint set on line 1 of your file. You can change the line
+number for this automatic breakpoint to be <N> by using the -bN option
+(where N must be an integer). For example:
+
+%run -d -b40 myscript
+
+will set the first breakpoint at line 40 in myscript.py. Note that the
+first breakpoint must be set on a line which actually does something
+(not a comment or docstring) for it to stop execution.
+
+When the pdb debugger starts, you will see a (Pdb) prompt. You must
+first enter 'c' (without qoutes) to start execution up to the first
+breakpoint.
+
+Entering 'help' gives information about the use of the debugger. You can
+easily see pdb's full documentation with "import pdb;pdb.help()" at a
+prompt.
+
+-p: run program under the control of the Python profiler module (which
+prints a detailed report of execution times, function calls, etc).
+
+You can pass other options after -p which affect the behavior of the
+profiler itself. See the docs for %prun for details.
+
+In this mode, the program's variables do NOT propagate back to the
+IPython interactive namespace (because they remain in the namespace
+where the profiler executes them).
+
+Internally this triggers a call to %prun, see its documentation for
+details on the options available specifically for profiling.
+
+There is one special usage for which the text above doesn't apply: if
+the filename ends with .ipy, the file is run as ipython script, just as
+if the commands were written on IPython prompt.
+
+
+%runlog: Run files as logs.
+
+Usage:
+%runlog file1 file2 ...
+
+Run the named files (treating them as log files) in sequence inside the
+interpreter, and return to the prompt. This is much slower than %run
+because each line is executed in a try/except block, but it allows
+running files with syntax errors in them.
+
+Normally IPython will guess when a file is one of its own logfiles, so
+you can typically use %run even for logs. This shorthand allows you to
+force any file to be treated as a log file.
+
+
+%save: Save a set of lines to a given filename.
+
+Usage:
+%save [options] filename n1-n2 n3-n4 ... n5 .. n6 ...
+
+Options:
+
+-r: use 'raw' input. By default, the 'processed' history is used, so
+that magics are loaded in their transformed version to valid Python. If
+this option is given, the raw input as typed as the command line is used
+instead.
+
+This function uses the same syntax as %macro for line extraction, but
+instead of creating a macro it saves the resulting string to the
+filename you specify.
+
+It adds a '.py' extension to the file if you don't do so yourself, and
+it asks for confirmation before overwriting existing files.
+
+
+%sc: Shell capture - execute a shell command and capture its output.
+
+DEPRECATED. Suboptimal, retained for backwards compatibility.
+
+You should use the form 'var = !command' instead. Example:
+
+"%sc -l myfiles = ls " should now be written as
+
+"myfiles = !ls "
+
+myfiles.s, myfiles.l and myfiles.n still apply as documented below.
+
+- %sc [options] varname=command
+
+IPython will run the given command using commands.getoutput(), and will
+then update the user's interactive namespace with a variable called
+varname, containing the value of the call. Your command can contain
+shell wildcards, pipes, etc.
+
+The '=' sign in the syntax is mandatory, and the variable name you
+supply must follow Python's standard conventions for valid names.
+
+(A special format without variable name exists for internal use)
+
+Options:
+
+-l: list output. Split the output on newlines into a list before
+assigning it to the given variable. By default the output is stored as a
+single string.
+
+-v: verbose. Print the contents of the variable.
+
+In most cases you should not need to split as a list, because the
+returned value is a special type of string which can automatically
+provide its contents either as a list (split on newlines) or as a
+space-separated string. These are convenient, respectively, either for
+sequential processing or to be passed to a shell command.
+
+For example:
+
+# Capture into variable a In [9]: sc a=ls *py
+
+# a is a string with embedded newlines In [10]: a Out[10]: 'setup.py
+win32_manual_post_install.py'
+
+# which can be seen as a list: In [11]: a.l Out[11]: ['setup.py',
+'win32_manual_post_install.py']
+
+# or as a whitespace-separated string: In [12]: a.s Out[12]: 'setup.py
+win32_manual_post_install.py'
+
+# a.s is useful to pass as a single command line: In [13]: !wc -l $a.s
+146 setup.py 130 win32_manual_post_install.py 276 total
+
+# while the list form is useful to loop over: In [14]: for f in a.l:
+....: !wc -l $f ....: 146 setup.py 130 win32_manual_post_install.py
+
+Similiarly, the lists returned by the -l option are also special, in the
+sense that you can equally invoke the .s attribute on them to
+automatically get a whitespace-separated string from their contents:
+
+In [1]: sc -l b=ls *py
+
+In [2]: b Out[2]: ['setup.py', 'win32_manual_post_install.py']
+
+In [3]: b.s Out[3]: 'setup.py win32_manual_post_install.py'
+
+In summary, both the lists and strings used for ouptut capture have the
+following special attributes:
+
+.l (or .list) : value as list. .n (or .nlstr): value as
+newline-separated string. .s (or .spstr): value as space-separated string.
+
+
+%sx: Shell execute - run a shell command and capture its output.
+
+%sx command
+
+IPython will run the given command using commands.getoutput(), and
+return the result formatted as a list (split on '\n'). Since the output
+is _returned_, it will be stored in ipython's regular output cache
+Out[N] and in the '_N' automatic variables.
+
+Notes:
+
+1) If an input line begins with '!!', then %sx is automatically invoked.
+That is, while: !ls causes ipython to simply issue system('ls'), typing
+!!ls is a shorthand equivalent to: %sx ls
+
+2) %sx differs from %sc in that %sx automatically splits into a list,
+like '%sc -l'. The reason for this is to make it as easy as possible to
+process line-oriented shell output via further python commands. %sc is
+meant to provide much finer control, but requires more typing.
+
+3) Just like %sc -l, this is a list with special attributes:
+
+.l (or .list) : value as list. .n (or .nlstr): value as
+newline-separated string. .s (or .spstr): value as whitespace-separated
+string.
+
+This is very useful when trying to use such lists as arguments to system
+commands.
+
+
+%system_verbose: Set verbose printing of system calls.
+
+If called without an argument, act as a toggle
+
+
+%time: Time execution of a Python statement or expression.
+
+The CPU and wall clock times are printed, and the value of the
+expression (if any) is returned. Note that under Win32, system time is
+always reported as 0, since it can not be measured.
+
+This function provides very basic timing functionality. In Python 2.3,
+the timeit module offers more control and sophistication, so this could
+be rewritten to use it (patches welcome).
+
+Some examples:
+
+In [1]: time 2**128 CPU times: user 0.00 s, sys: 0.00 s, total: 0.00 s
+Wall time: 0.00 Out[1]: 340282366920938463463374607431768211456L
+
+In [2]: n = 1000000
+
+In [3]: time sum(range(n)) CPU times: user 1.20 s, sys: 0.05 s, total:
+1.25 s Wall time: 1.37 Out[3]: 499999500000L
+
+In [4]: time print 'hello world' hello world CPU times: user 0.00 s,
+sys: 0.00 s, total: 0.00 s Wall time: 0.00
+
+Note that the time needed by Python to compile the given expression will
+be reported if it is more than 0.1s. In this example, the actual
+exponentiation is done by Python at compilation time, so while the
+expression can take a noticeable amount of time to compute, that time is
+purely due to the compilation:
+
+In [5]: time 3**9999; CPU times: user 0.00 s, sys: 0.00 s, total: 0.00 s
+Wall time: 0.00 s
+
+In [6]: time 3**999999; CPU times: user 0.00 s, sys: 0.00 s, total: 0.00
+s Wall time: 0.00 s Compiler : 0.78 s
+
+
+%timeit: Time execution of a Python statement or expression
+
+Usage:
+%timeit [-n<N> -r<R> [-t|-c]] statement
+
+Time execution of a Python statement or expression using the timeit module.
+
+Options: -n<N>: execute the given statement <N> times in a loop. If this
+value is not given, a fitting value is chosen.
+
+-r<R>: repeat the loop iteration <R> times and take the best result.
+Default: 3
+
+-t: use time.time to measure the time, which is the default on Unix.
+This function measures wall time.
+
+-c: use time.clock to measure the time, which is the default on Windows
+and measures wall time. On Unix, resource.getrusage is used instead and
+returns the CPU user time.
+
+-p<P>: use a precision of <P> digits to display the timing result.
+Default: 3
+
+Examples:
+In [1]: %timeit pass 10000000 loops, best of 3: 53.3 ns per loop
+
+In [2]: u = None
+
+In [3]: %timeit u is None 10000000 loops, best of 3: 184 ns per loop
+
+In [4]: %timeit -r 4 u == None 1000000 loops, best of 4: 242 ns per loop
+
+In [5]: import time
+
+In [6]: %timeit -n1 time.sleep(2) 1 loops, best of 3: 2 s per loop
+
+The times reported by %timeit will be slightly higher than those
+reported by the timeit.py script when variables are accessed. This is
+due to the fact that %timeit executes the statement in the namespace of
+the shell, compared with timeit.py, which uses a single setup statement
+to import function or create variables. Generally, the bias does not
+matter as long as results from timeit.py are not mixed with those from
+%timeit.
+
+
+%unalias: Remove an alias
+
+
+%upgrade: Upgrade your IPython installation
+
+This will copy the config files that don't yet exist in your ipython dir
+from the system config dir. Use this after upgrading IPython if you
+don't wish to delete your .ipython dir.
+
+Call with -nolegacy to get rid of ipythonrc* files (recommended for new
+users)
+
+
+%who: Print all interactive variables, with some minimal formatting.
+
+If any arguments are given, only variables whose type matches one of
+these are printed. For example:
+
+%who function str
+
+will only list functions and strings, excluding all other types of
+variables. To find the proper type names, simply use type(var) at a
+command line to see how python prints type names. For example:
+
+In [1]: type('hello')
+Out[1]: <type 'str'>
+
+indicates that the type name for strings is 'str'.
+
+%who always excludes executed names loaded through your configuration
+file and things which are internal to IPython.
+
+This is deliberate, as typically you may load many modules and the
+purpose of %who is to show you only what you've manually defined.
+
+
+%who_ls: Return a sorted list of all interactive variables.
+
+If arguments are given, only variables of types matching these arguments
+are returned.
+
+
+%whos: Like %who, but gives some extra information about each variable.
+
+The same type filtering of %who can be applied here.
+
+For all variables, the type is printed. Additionally it prints:
+
+- For ,[],(): their length.
+
+- For numpy and Numeric arrays, a summary with shape, number of
+elements, typecode and size in memory.
+
+- Everything else: a string representation, snipping their middle if too
+long.
+
+
+%xmode: Switch modes for the exception handlers.
+
+Valid modes: Plain, Context and Verbose.
+
+If called without arguments, acts as a toggle.
+
+
+    Access to the standard Python help
+
+As of Python 2.1, a help system is available with access to object
+docstrings and the Python manuals. Simply type 'help' (no quotes) to
+access it. You can also type help(object) to obtain information about a
+given object, and help('keyword') for information on a keyword. As noted
+in sec. 3.1 <node3.html#sec:help-access>, you need to properly configure
+your environment variable PYTHONDOCS for this feature to work correctly.
+
+
+
+    Dynamic object information
+
+Typing ?word or word? 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.
+
+Typing ??word or word?? gives access to the full information without
+snipping long strings. Long strings are sent to the screen through the
+less pager if longer than the screen and printed otherwise. On systems
+lacking the less command, IPython uses a very basic internal pager.
+
+The following magic functions are particularly useful for gathering
+information about your working environment. You can get more details by
+typing %magic or querying them individually (use %function_name? with or
+without the %), this is just a summary:
+
+    * [%pdoc <object>:] 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 constructor docstrings.
+    * [%pdef <object>:] Print the definition header for any callable
+      object. If the object is a class, print the constructor information.
+    * [%psource <object>:] Print (or run through a pager if too long)
+      the source code for an object.
+    * [%pfile <object>:] Show the entire source file where an object was
+      defined via a pager, opening it at the line where the object
+      definition begins.
+    * [%who/%whos:] These functions give information about identifiers
+      you have defined interactively (not things you loaded or defined
+      in your configuration files). %who just prints a list of
+      identifiers and %whos prints a table with some basic details about
+      each identifier.
+
+Note that the dynamic object information functions (?/??, %pdoc, %pfile,
+%pdef, %psource) give you access to documentation even on things which
+are not really defined as separate identifiers. Try for example typing
+{}.get? or after doing import os, type os.path.abspath??.
+
+
+
+    Readline-based features
+
+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.
+
+
+Command line completion
+-----------------------
+
+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.
+
+
+Search command history
+----------------------
+
+IPython provides two ways for searching through previous input and thus
+reduce the need for repetitive typing:
+
+   1. Start typing, and then use Ctrl-p (previous,up) and Ctrl-n
+      (next,down) to search through only the history items that match
+      what you've typed so far. If you use Ctrl-p/Ctrl-n at a blank
+      prompt, they just behave like normal arrow keys.
+   2. Hit Ctrl-r: 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.
+
+
+Persistent command history across sessions
+------------------------------------------
+
+IPython will save your input history when it leaves and reload it next
+time you restart it. By default, the history file is named
+$IPYTHONDIR/history, but if you've loaded a named profile,
+'-PROFILE_NAME' 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.
+
+
+Autoindent
+----------
+
+IPython can recognize lines ending in ':' and indent the next line,
+while also un-indenting automatically after 'raise' or 'return'.
+
+This feature uses the readline library, so it will honor your ~/.inputrc
+configuration (or whatever file your INPUTRC variable points to). Adding
+the following lines to your .inputrc file can make indenting/unindenting
+more convenient (M-i indents, M-u unindents)::
+
+    $if Python 
+    "\M-i": "    "  
+    "\M-u": "\d\d\d\d"  
+    $endif
+
+Note that there are 4 spaces between the quote marks after "M-i" above.
+
+Warning: 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 %autoindent allows you to
+toggle it on/off at runtime. You can also disable it permanently on in
+your ipythonrc file (set autoindent 0).
+
+
+Customizing readline behavior
+-----------------------------
+
+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 ipythonrc configuration file (note
+that these options can not be specified at the command line):
+
+    * [readline_parse_and_bind:] this option can appear as many times as
+      you want, each time defining a string to be executed via a
+      readline.parse_and_bind() 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.
+    * [readline_remove_delims:] 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.
+    * [readline_omit__names:] when tab-completion is enabled, hitting
+      <tab> after a '.' in a name will complete all attributes of an
+      object, including all the special methods whose names include
+      double underscores (like __getitem__ or __class__). 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 _ after the period and hitting <tab>:
+      'name._<tab>' will always complete attribute names starting with '_'.
+    * [ ] This option is off by default so that new users see all
+      attributes of any objects they are dealing with.
+
+You will find the default values along with a corresponding detailed
+explanation in your ipythonrc file.
+
+
+Session logging and restoring
+-----------------------------
+
+You can log all input from a session either by starting IPython with the
+command line switches -log or -logfile (see sec. 5.2
+<node5.html#sec:cmd-line-opts>)or by activating the logging at any
+moment with the magic function %logstart.
+
+Log files can later be reloaded with the -logplay 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.
+
+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.
+
+The %logstart function for activating logging in mid-session is used as
+follows:
+
+%logstart [log_name [log_mode]]
+
+If no name is given, it defaults to a file named 'log' in your
+IPYTHONDIR directory, in 'rotate' mode (see below).
+
+'%logstart name' saves to file 'name' in 'backup' mode. It saves your
+history up to that point and then continues logging.
+
+%logstart takes a second optional parameter: logging mode. This can be
+one of (note that the modes are given unquoted):
+
+    * [over:] overwrite existing log_name.
+    * [backup:] rename (if exists) to log_name~ and start log_name.
+    * [append:] well, that says it.
+    * [rotate:] create rotating logs log_name.1~, log_name.2~, etc.
+
+The %logoff and %logon functions allow you to temporarily stop and
+resume logging to a file which had previously been started with
+%logstart. They will fail (with an explanation) if you try to use them
+before logging has been started.
+
+
+
+System shell access
+-------------------
+
+Any input line beginning with a ! character is passed verbatim (minus
+the !, of course) to the underlying operating system. For example,
+typing !ls will run 'ls' in the current directory.
+
+
+Manual capture of command output
+--------------------------------
+
+If the input line begins with two exclamation marks, !!, 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 !! syntax is a shorthand for the %sx magic command.
+
+Finally, the %sc magic (short for 'shell capture') is similar to %sx,
+but allowing more fine-grained control of the capture details, and
+storing the result directly into a named variable.
+
+See Sec. 6.2 <#sec:magic> for details on the magics %sc and %sx, or use
+IPython's own help (sc? and sx?) for further details.
+
+IPython also allows you to expand the value of python variables when
+making system calls. Any python variable or expression which you prepend
+with $ will get expanded before the system call is made::
+
+    In [1]: pyvar='Hello world' 
+    In [2]: !echo "A python variable: $pyvar"  
+    A python variable: Hello world
+
+If you want the shell to actually see a literal $, you need to type it
+twice::
+
+    In [3]: !echo "A system variable: $$HOME"  
+    A system variable: /home/fperez
+
+You can pass arbitrary expressions, though you'll need to delimit them
+with {} if there is ambiguity as to the extent of the expression::
+
+    In [5]: x=10 
+    In [6]: y=20 
+    In [13]: !echo $x+y  
+    10+y  
+    In [7]: !echo ${x+y}  
+    30
+
+Even object attributes can be expanded::
+
+    In [12]: !echo $sys.argv  
+    [/home/fperez/usr/bin/ipython]
+
+
+System command aliases
+----------------------
+
+The %alias magic function and the alias option in the ipythonrc
+configuration file allow you to define magic functions which are in fact
+system shell commands. These aliases can have parameters.
+
+'%alias alias_name cmd' defines 'alias_name' as an alias for 'cmd'
+
+Then, typing '%alias_name params' will execute the system command 'cmd
+params' (from your underlying operating system).
+
+You can also define aliases with parameters using %s specifiers (one per
+parameter). The following example defines the %parts function as an
+alias to the command 'echo first %s second %s' where each %s will be
+replaced by a positional parameter to the call to %parts::
+
+    In [1]: alias parts echo first %s second %s 
+    In [2]: %parts A B 
+    first A second B  
+    In [3]: %parts A  
+    Incorrect number of arguments: 2 expected.  
+    parts is an alias to: 'echo first %s second %s'
+
+If called with no parameters, %alias prints the table of currently
+defined aliases.
+
+The %rehash/rehashx magics allow you to load your entire $PATH as
+ipython aliases. See their respective docstrings (or sec. 6.2
+<#sec:magic> for further details).
+
+
+
+Recursive reload
+----------------
+
+The dreload function does a recursive reload of a module: changes made
+to the module since you imported will actually be available without
+having to exit.
+
+
+Verbose and colored exception traceback printouts
+-------------------------------------------------
+
+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 %run 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.
+
+See the magic xmode and colors functions for details (just type %magic).
+
+These features are basically a terminal version of Ka-Ping Yee's cgitb
+module, now part of the standard Python library.
+
+
+
+Input caching system
+--------------------
+
+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).
+
+The following GLOBAL variables always exist (so don't overwrite them!):
+_i: stores previous input. _ii: next previous. _iii: next-next previous.
+_ih : a list of all input _ih[n] is the input from line n and this list
+is aliased to the global variable In. If you overwrite In with a
+variable of your own, you can remake the assignment to the internal list
+with a simple 'In=_ih'.
+
+Additionally, global variables named _i<n> are dynamically created (<n>
+being the prompt counter), such that
+_i<n> == _ih[<n>] == In[<n>].
+
+For example, what you typed at prompt 14 is available as _i14, _ih[14]
+and In[14].
+
+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 'exec _i9' will re-execute the
+contents of input prompt 9, 'exec In[9:14]+In[18]' will re-execute lines
+9 through 13 and line 18).
+
+You can also re-execute multiple lines of input easily by using the
+magic %macro function (which automates the process and allows
+re-execution without having to type 'exec' every time). The macro system
+also allows you to re-execute previous lines which include magic
+function calls (which require special processing). Type %macro? or see
+sec. 6.2 <#sec:magic> for more details on the macro system.
+
+A history function %hist allows you to see any part of your input
+history by printing a range of the _i variables.
+
+Output caching system
+---------------------
+
+For output that is returned from actions, a system similar to the input
+cache exists but using _ instead of _i. Only actions that produce a
+result (NOT assignments, for example) are cached. If you are familiar
+with Mathematica, IPython's _ variables behave exactly like
+Mathematica's % variables.
+
+The following GLOBAL variables always exist (so don't overwrite them!):
+
+    * [_] (a single underscore) : stores previous output, like Python's
+      default interpreter.
+    * [__] (two underscores): next previous.
+    * [___] (three underscores): next-next previous.
+
+Additionally, global variables named _<n> are dynamically created (<n>
+being the prompt counter), such that the result of output <n> is always
+available as _<n> (don't use the angle brackets, just the number, e.g.
+_21).
+
+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 _oh and Out (similar to _ih and In). So the
+output from line 12 can be obtained as _12, Out[12] or _oh[12]. If you
+accidentally overwrite the Out variable you can recover it by typing
+'Out=_oh' at the prompt.
+
+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 ipythonrc
+file) cache_size. If you set it to 0, the whole system is completely
+disabled and the prompts revert to the classic '>>>' of normal Python.
+
+
+Directory history
+-----------------
+
+Your history of visited directories is kept in the global list _dh, and
+the magic %cd command can be used to go to any entry in that list. The
+%dhist command allows you to view this history.
+
+
+Automatic parentheses and quotes
+--------------------------------
+
+These features were adapted from Nathan Gray's LazyPython. They are
+meant to allow less typing for common situations.
+
+
+Automatic parentheses
+---------------------
+
+Callable objects (i.e. functions, methods, etc) can be invoked like this
+(notice the commas between the arguments)::
+
+    >>> callable_ob arg1, arg2, arg3
+
+and the input will be translated to this::
+
+    -> callable_ob(arg1, arg2, arg3)
+
+You can force automatic parentheses by using '/' as the first character
+of a line. For example::
+
+    >>> /globals # becomes 'globals()'
+
+Note that the '/' MUST be the first character on the line! This won't work::
+
+    >>> print /globals # syntax error
+
+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)::
+
+    In [1]: zip (1,2,3),(4,5,6) # won't work
+
+but this will work::
+
+    In [2]: /zip (1,2,3),(4,5,6) 
+    ---> zip ((1,2,3),(4,5,6))  
+    Out[2]= [(1, 4), (2, 5), (3, 6)]
+
+IPython tells you that it has altered your command line by displaying
+the new command line preceded by ->. e.g.::
+
+    In [18]: callable list 
+    ----> callable (list)
+
+
+Automatic quoting
+-----------------
+
+You can force automatic quoting of a function's arguments by using ','
+or ';' as the first character of a line. For example::
+
+    >>> ,my_function /home/me # becomes my_function("/home/me")
+
+If you use ';' instead, the whole argument is quoted as a single string
+(while ',' splits on whitespace)::
+
+    >>> ,my_function a b c # becomes my_function("a","b","c")
+
+    >>> ;my_function a b c # becomes my_function("a b c")
+
+Note that the ',' or ';' MUST be the first character on the line! This
+won't work::
+
+    >>> x = ,my_function /home/me # syntax error
+
+Customization
+=============
+
+As we've already mentioned, IPython reads a configuration file which can
+be specified at the command line (-rcfile) or which by default is
+assumed to be called ipythonrc. Such a file is looked for in the current
+directory where IPython is started and then in your IPYTHONDIR, 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).
+
+The syntax of an rcfile is one of key-value pairs separated by
+whitespace, one per line. Lines beginning with a # are ignored as
+comments, but comments can not 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.
+
+First, an rcfile can contain permanent default values for almost all
+command line options (except things like -help or -Version). Sec 5.2
+<node5.html#sec:cmd-line-opts> contains a description of all
+command-line options. However, values you explicitly specify at the
+command line override the values defined in the rcfile.
+
+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.
+
+Each of these options may appear as many times as you need it in the file.
+
+    * [include <file1> <file2> ...:] you can name other rcfiles you want
+      to recursively load up to 15 levels (don't use the <> 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 -profile <name> option
+      (abbreviates to -p <name>) which tells it to look for an rcfile
+      named ipythonrc-<name>.
+    * [import_mod <mod1> <mod2> ...:] import modules with 'import
+      <mod1>,<mod2>,...'
+    * [import_some <mod> <f1> <f2> ...:] import functions with 'from
+      <mod> import <f1>,<f2>,...'
+    * [import_all <mod1> <mod2> ...:] for each module listed import
+      functions with 'from <mod> import *'
+    * [execute <python code>:] give any single-line python code to be
+      executed.
+    * [execfile <filename>:] execute the python file given with an
+      'execfile(filename)' 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.
+    * [alias <alias_def>:] this is equivalent to calling
+      '%alias <alias_def>' at the IPython command line. This way, from
+      within IPython you can do common system tasks without having to
+      exit it or use the ! 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.
+
+
+
+Sample ipythonrc file
+---------------------
+
+The default rcfile, called ipythonrc and supplied in your IPYTHONDIR
+directory contains lots of comments on all of these options. We
+reproduce it here for reference::
+
+
+    # -*- Mode: Shell-Script -*-  Not really, but shows comments correctly
+    # $Id: ipythonrc 2156 2007-03-19 02:32:19Z fperez $
+
+    #***************************************************************************
+    #
+    # Configuration file for IPython -- ipythonrc format
+    #
+    # ===========================================================
+    # Deprecation note: you should look into modifying ipy_user_conf.py (located 
+    # in ~/.ipython or ~/_ipython, depending on your platform) instead, it's a 
+    # more flexible and robust (and better supported!) configuration
+    # method.
+    # ===========================================================
+    #
+    # The format of this file is simply one of 'key value' lines.
+    # Lines containing only whitespace at the beginning and then a # are ignored
+    # as comments. But comments can NOT be put on lines with data.
+
+    # The meaning and use of each key are explained below.
+
+    #---------------------------------------------------------------------------
+    # Section: included files
+
+    # Put one or more *config* files (with the syntax of this file) you want to
+    # include. For keys with a unique value the outermost file has precedence. For
+    # keys with multiple values, they all get assembled into a list which then
+    # gets loaded by IPython.
+
+    # In this file, all lists of things should simply be space-separated.
+
+    # This allows you to build hierarchies of files which recursively load
+    # lower-level services. If this is your main ~/.ipython/ipythonrc file, you
+    # should only keep here basic things you always want available. Then you can
+    # include it in every other special-purpose config file you create.
+    include 
+
+    #---------------------------------------------------------------------------
+    # Section: startup setup
+
+    # These are mostly things which parallel a command line option of the same
+    # name.
+
+    # Keys in this section should only appear once. If any key from this section
+    # is encountered more than once, the last value remains, all earlier ones get
+    # discarded.
+
+
+    # Automatic calling of callable objects.  If set to 1 or 2, callable objects
+    # are automatically called when invoked at the command line, even if you don't
+    # type parentheses.  IPython adds the parentheses for you.  For example:
+
+    #In [1]: str 45
+    #------> str(45)
+    #Out[1]: '45'
+
+    # IPython reprints your line with '---->' indicating that it added
+    # parentheses.  While this option is very convenient for interactive use, it
+    # may occasionally cause problems with objects which have side-effects if
+    # called unexpectedly.
+
+    # The valid values for autocall are:
+
+    # autocall 0 -> disabled (you can toggle it at runtime with the %autocall magic)
+
+    # autocall 1 -> active, but do not apply if there are no arguments on the line.
+
+    # In this mode, you get:
+
+    #In [1]: callable
+    #Out[1]: <built-in function callable>
+
+    #In [2]: callable 'hello'
+    #------> callable('hello')
+    #Out[2]: False
+
+    # 2 -> Active always.  Even if no arguments are present, the callable object
+    # is called:
+
+    #In [4]: callable
+    #------> callable()
+
+    # Note that even with autocall off, you can still use '/' at the start of a
+    # line to treat the first argument on the command line as a function and add
+    # parentheses to it:
+
+    #In [8]: /str 43
+    #------> str(43)
+    #Out[8]: '43'
+
+    autocall 1
+
+    # Auto-edit syntax errors.  When you use the %edit magic in ipython to edit
+    # source code (see the 'editor' variable below), it is possible that you save
+    # a file with syntax errors in it.  If this variable is true, IPython will ask
+    # you whether to re-open the editor immediately to correct such an error.
+
+    autoedit_syntax 0
+
+    # Auto-indent. IPython can recognize lines ending in ':' and indent the next
+    # line, while also un-indenting automatically after 'raise' or 'return'.  
+
+    # This feature uses the readline library, so it will honor your ~/.inputrc
+    # configuration (or whatever file your INPUTRC variable points to).  Adding
+    # the following lines to your .inputrc file can make indent/unindenting more
+    # convenient (M-i indents, M-u unindents):
+
+    #  $if Python
+    #  "\M-i": "    "
+    #  "\M-u": "\d\d\d\d"
+    #  $endif
+
+    # The feature is potentially a bit dangerous, because it can cause problems
+    # with pasting of indented code (the pasted code gets re-indented on each
+    # line).  But it's a huge time-saver when working interactively.  The magic
+    # function %autoindent allows you to toggle it on/off at runtime.
+
+    autoindent 1
+
+    # Auto-magic. This gives you access to all the magic functions without having
+    # to prepend them with an % sign. If you define a variable with the same name
+    # as a magic function (say who=1), you will need to access the magic function
+    # with % (%who in this example). However, if later you delete your variable
+    # (del who), you'll recover the automagic calling form.
+
+    # Considering that many magic functions provide a lot of shell-like
+    # functionality, automagic gives you something close to a full Python+system
+    # shell environment (and you can extend it further if you want).
+
+    automagic 1
+
+    # Size of the output cache. After this many entries are stored, the cache will
+    # get flushed. Depending on the size of your intermediate calculations, you
+    # may have memory problems if you make it too big, since keeping things in the
+    # cache prevents Python from reclaiming the memory for old results. Experiment
+    # with a value that works well for you.
+
+    # If you choose cache_size 0 IPython will revert to python's regular >>>
+    # unnumbered prompt. You will still have _, __ and ___ for your last three
+    # results, but that will be it.  No dynamic _1, _2, etc. will be created. If
+    # you are running on a slow machine or with very limited memory, this may
+    # help.
+
+    cache_size 1000
+
+    # Classic mode: Setting 'classic 1' you lose many of IPython niceties,
+    # but that's your choice! Classic 1 -> same as IPython -classic.
+    # Note that this is _not_ the normal python interpreter, it's simply
+    # IPython emulating most of the classic interpreter's behavior.
+    classic 0
+
+    # colors - Coloring option for prompts and traceback printouts.
+
+    # Currently available schemes: NoColor, Linux, LightBG.
+
+    # This option allows coloring the prompts and traceback printouts. This
+    # requires a terminal which can properly handle color escape sequences. If you
+    # are having problems with this, use the NoColor scheme (uses no color escapes
+    # at all).
+
+    # The Linux option works well in linux console type environments: dark
+    # background with light fonts.
+
+    # LightBG is similar to Linux but swaps dark/light colors to be more readable
+    # in light background terminals.
+
+    # keep uncommented only the one you want:
+    colors Linux
+    #colors LightBG
+    #colors NoColor
+
+    ########################
+    # Note to Windows users
+    #
+    # Color and readline support is avaialble to Windows users via Gary Bishop's
+    # readline library.  You can find Gary's tools at
+    # http://sourceforge.net/projects/uncpythontools.
+    # Note that his readline module requires in turn the ctypes library, available
+    # at http://starship.python.net/crew/theller/ctypes.
+    ########################
+
+    # color_info: IPython can display information about objects via a set of
+    # functions, and optionally can use colors for this, syntax highlighting
+    # source code and various other elements. This information is passed through a
+    # pager (it defaults to 'less' if $PAGER is not set). 
+
+    # If your pager has problems, try to setting it to properly handle escapes
+    # (see the less manpage for detail), or disable this option.  The magic
+    # function %color_info allows you to toggle this interactively for testing.
+
+    color_info 1
+
+    # confirm_exit: set to 1 if you want IPython to confirm when you try to exit
+    # with an EOF (Control-d in Unix, Control-Z/Enter in Windows). Note that using
+    # the magic functions %Exit or %Quit you can force a direct exit, bypassing
+    # any confirmation.
+
+    confirm_exit 1
+
+    # Use deep_reload() as a substitute for reload() by default. deep_reload() is
+    # still available as dreload() and appears as a builtin.
+
+    deep_reload 0
+
+    # Which editor to use with the %edit command. If you leave this at 0, IPython
+    # will honor your EDITOR environment variable. 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.
+
+    # For Emacs users, setting up your Emacs server properly as described in the
+    # manual is a good idea. An alternative is to use jed, a very light editor
+    # with much of the feel of Emacs (though not as powerful for heavy-duty work).
+
+    editor 0
+
+    # log 1 -> same as ipython -log. This automatically logs to ./ipython.log
+    log 0
+
+    # Same as ipython -Logfile YourLogfileName. 
+    # Don't use with log 1 (use one or the other)
+    logfile ''
+
+    # banner 0 -> same as ipython -nobanner
+    banner 1
+
+    # messages 0 -> same as ipython -nomessages
+    messages 1
+
+    # 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.
+    pdb 0
+
+    # Enable the pprint module for printing. pprint tends to give a more readable
+    # display (than print) for complex nested data structures.
+    pprint 1
+
+    # Prompt strings
+
+    # Most bash-like escapes can be used to customize IPython's prompts, as well as
+    # a few additional ones which are IPython-specific.  All valid prompt escapes
+    # are described in detail in the Customization section of the IPython HTML/PDF
+    # manual.
+
+    # Use \# to represent the current prompt number, and quote them to protect
+    # spaces.
+    prompt_in1 'In [\#]: '
+
+    # \D is replaced by as many dots as there are digits in the
+    # current value of \#.
+    prompt_in2 '   .\D.: '
+
+    prompt_out 'Out[\#]: '
+
+    # Select whether to left-pad the output prompts to match the length of the
+    # input ones.  This allows you for example to use a simple '>' as an output
+    # prompt, and yet have the output line up with the input.  If set to false,
+    # the output prompts will be unpadded (flush left).
+    prompts_pad_left 1
+
+    # Pylab support: when ipython is started with the -pylab switch, by default it
+    # executes 'from matplotlib.pylab import *'.  Set this variable to false if you
+    # want to disable this behavior.
+
+    # For details on pylab, see the matplotlib website:
+    # http://matplotlib.sf.net
+    pylab_import_all 1
+
+
+    # quick 1 -> same as ipython -quick
+    quick 0
+
+    # Use the readline library (1) or not (0). Most users will want this on, but
+    # if you experience strange problems with line management (mainly when using
+    # IPython inside Emacs buffers) you may try disabling it. Not having it on
+    # prevents you from getting command history with the arrow keys, searching and
+    # name completion using TAB.
+
+    readline 1
+
+    # Screen Length: 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 paged with the less command instead of directly printed.
+
+    # The default value for this is 0, which means IPython will auto-detect your
+    # screen size every time it needs to print. If for some reason this isn't
+    # working well (it needs curses support), specify it yourself. Otherwise don't
+    # change the default.
+
+    screen_length 0
+
+    # Prompt separators for input and output.
+    # Use \n for newline explicitly, without quotes.
+    # Use 0 (like at the cmd line) to turn off a given separator.
+
+    # The structure of prompt printing is:
+    # (SeparateIn)Input....
+    # (SeparateOut)Output...
+    # (SeparateOut2),   # that is, no newline is printed after Out2
+    # By choosing these you can organize your output any way you want.
+
+    separate_in \n
+    separate_out 0
+    separate_out2 0
+
+    # 'nosep 1' is a shorthand for '-SeparateIn 0 -SeparateOut 0 -SeparateOut2 0'.
+    # Simply removes all input/output separators, overriding the choices above.
+    nosep 0
+
+    # Wildcard searches - IPython has a system for searching names using
+    # shell-like wildcards; type %psearch? for details.  This variables sets
+    # whether by default such searches should be case sensitive or not.  You can
+    # always override the default at the system command line or the IPython
+    # prompt.
+
+    wildcards_case_sensitive 1
+
+    # Object information: at what level of detail to display the string form of an
+    # object.  If set to 0, ipython will compute the string form of any object X,
+    # by calling str(X), when X? is typed.  If set to 1, str(X) will only be
+    # computed when X?? is given, and if set to 2 or higher, it will never be
+    # computed (there is no X??? level of detail).  This is mostly of use to
+    # people who frequently manipulate objects whose string representation is
+    # extremely expensive to compute.
+
+    object_info_string_level 0
+
+    # xmode - Exception reporting mode. 
+
+    # Valid modes: Plain, Context and Verbose.
+
+    # Plain: similar to python's normal traceback printing.
+
+    # Context: prints 5 lines of context source code around each line in the
+    # traceback.
+
+    # 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).
+
+    #xmode Plain
+    xmode Context
+    #xmode Verbose
+
+    # multi_line_specials: if true, allow magics, aliases and shell escapes (via
+    # !cmd) to be used in multi-line input (like for loops).  For example, if you
+    # have this active, the following is valid in IPython:
+    #
+    #In [17]: for i in range(3):
+    #   ....:     mkdir $i
+    #   ....:     !touch $i/hello
+    #   ....:     ls -l $i
+
+    multi_line_specials 1
+
+
+    # System calls: When IPython makes system calls (e.g. via special syntax like
+    # !cmd or !!cmd, or magics like %sc or %sx), it can print the command it is
+    # executing to standard output, prefixed by a header string.
+
+    system_header "IPython system call: "
+
+    system_verbose 1
+
+    # wxversion: request a specific wxPython version (used for -wthread)
+
+    # Set this to the value of wxPython you want to use, but note that this
+    # feature requires you to have the wxversion Python module to work.  If you
+    # don't have the wxversion module (try 'import wxversion' at the prompt to
+    # check) or simply want to leave the system to pick up the default, leave this
+    # variable at 0.
+
+    wxversion 0
+
+    #---------------------------------------------------------------------------
+    # Section: Readline configuration (readline is not available for MS-Windows)
+
+    # This is done via the following options:
+
+    # (i) readline_parse_and_bind: this option can appear as many times as you
+    # want, each time defining a string to be executed via a
+    # readline.parse_and_bind() 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.
+
+    # The TAB key can be used to complete names at the command line in one of two
+    # ways: 'complete' and 'menu-complete'. The difference is that 'complete' only
+    # completes as much as possible while 'menu-complete' cycles through all
+    # possible completions. Leave the one you prefer uncommented.
+
+    readline_parse_and_bind tab: complete
+    #readline_parse_and_bind tab: menu-complete
+
+    # This binds Control-l to printing the list of all possible completions when
+    # there is more than one (what 'complete' does when hitting TAB twice, or at
+    # the first TAB if show-all-if-ambiguous is on)
+    readline_parse_and_bind "\C-l": possible-completions
+
+    # This forces readline to automatically print the above list when tab
+    # completion is set to 'complete'. You can still get this list manually by
+    # using the key bound to 'possible-completions' (Control-l by default) or by
+    # hitting TAB twice. Turning this on makes the printing happen at the first
+    # TAB.
+    readline_parse_and_bind set show-all-if-ambiguous on
+
+    # If you have TAB set to complete names, you can rebind any key (Control-o by
+    # default) to insert a true TAB character.
+    readline_parse_and_bind "\C-o": tab-insert
+
+    # These commands allow you to indent/unindent easily, with the 4-space
+    # convention of the Python coding standards.  Since IPython's internal
+    # auto-indent system also uses 4 spaces, you should not change the number of
+    # spaces in the code below.
+    readline_parse_and_bind "\M-i": "    "
+    readline_parse_and_bind "\M-o": "\d\d\d\d"
+    readline_parse_and_bind "\M-I": "\d\d\d\d"
+
+    # Bindings for incremental searches in the history. These searches use the
+    # string typed so far on the command line and search anything in the previous
+    # input history containing them.
+    readline_parse_and_bind "\C-r": reverse-search-history
+    readline_parse_and_bind "\C-s": forward-search-history
+
+    # Bindings for completing the current line in the history of previous
+    # commands. This allows you to recall any previous command by typing its first
+    # few letters and hitting Control-p, bypassing all intermediate commands which
+    # may be in the history (much faster than hitting up-arrow 50 times!)
+    readline_parse_and_bind "\C-p": history-search-backward
+    readline_parse_and_bind "\C-n": history-search-forward
+
+    # I also like to have the same functionality on the plain arrow keys. If you'd
+    # rather have the arrows use all the history (and not just match what you've
+    # typed so far), comment out or delete the next two lines.
+    readline_parse_and_bind "\e[A": history-search-backward
+    readline_parse_and_bind "\e[B": history-search-forward
+
+    # These are typically on by default under *nix, but not win32.
+    readline_parse_and_bind "\C-k": kill-line
+    readline_parse_and_bind "\C-u": unix-line-discard
+
+    # (ii) readline_remove_delims: 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.
+
+    readline_remove_delims -/~
+
+    # (iii) readline_merge_completions: whether to merge the result of all
+    # possible completions or not.  If true, IPython will complete filenames,
+    # python names and aliases and return all possible completions.  If you set it
+    # to false, each completer is used at a time, and only if it doesn't return
+    # any completions is the next one used.
+
+    # The default order is: [python_matches, file_matches, alias_matches]
+
+    readline_merge_completions 1
+
+    # (iv) readline_omit__names: normally hitting <tab> after a '.' in a name
+    # will complete all attributes of an object, including all the special methods
+    # whose names start with single or double underscores (like __getitem__ or
+    # __class__).
+
+    # This variable allows you to control this completion behavior:
+
+    # readline_omit__names 1 -> completion will omit showing any names starting
+    # with two __, but it will still show names starting with one _.
+
+    # readline_omit__names 2 -> completion will omit all names beginning with one
+    # _ (which obviously means filtering out the double __ ones).
+
+    # Even when this option is set, you can still see those names by explicitly
+    # typing a _ after the period and hitting <tab>: 'name._<tab>' will always
+    # complete attribute names starting with '_'.
+
+    # This option is off by default so that new users see all attributes of any
+    # objects they are dealing with.
+
+    readline_omit__names 0
+
+    #---------------------------------------------------------------------------
+    # Section: modules to be loaded with 'import ...'
+
+    # List, separated by spaces, the names of the modules you want to import
+
+    # Example:
+    # import_mod sys os
+    # will produce internally the statements
+    # import sys
+    # import os
+
+    # Each import is executed in its own try/except block, so if one module
+    # fails to load the others will still be ok.
+
+    import_mod 
+
+    #---------------------------------------------------------------------------
+    # Section: modules to import some functions from: 'from ... import ...'
+
+    # List, one per line, the modules for which you want only to import some
+    # functions. Give the module name first and then the name of functions to be
+    # imported from that module.
+
+    # Example:
+
+    # import_some IPython.genutils timing timings
+    # will produce internally the statement
+    # from IPython.genutils import timing, timings
+
+    # timing() and timings() are two IPython utilities for timing the execution of
+    # your own functions, which you may find useful.  Just commment out the above
+    # line if you want to test them.
+
+    # If you have more than one modules_some line, each gets its own try/except
+    # block (like modules, see above).
+
+    import_some 
+
+    #---------------------------------------------------------------------------
+    # Section: modules to import all from : 'from ... import *'
+
+    # List (same syntax as import_mod above) those modules for which you want to
+    # import all functions. Remember, this is a potentially dangerous thing to do,
+    # since it is very easy to overwrite names of things you need. Use with
+    # caution.
+
+    # Example:
+    # import_all sys os
+    # will produce internally the statements
+    # from sys import *
+    # from os import *
+
+    # As before, each will be called in a separate try/except block.
+
+    import_all 
+
+    #---------------------------------------------------------------------------
+    # Section: Python code to execute.
+
+    # Put here code to be explicitly executed (keep it simple!)
+    # Put one line of python code per line. All whitespace is removed (this is a
+    # feature, not a bug), so don't get fancy building loops here.
+    # This is just for quick convenient creation of things you want available.
+
+    # Example:
+    # execute x = 1
+    # execute print 'hello world'; y = z = 'a'
+    # will produce internally
+    # x = 1
+    # print 'hello world'; y = z = 'a'
+    # and each *line* (not each statement, we don't do python syntax parsing) is
+    # executed in its own try/except block.
+
+    execute 
+
+    # Note for the adventurous: you can use this to define your own names for the
+    # magic functions, by playing some namespace tricks:
+
+    # execute __IPYTHON__.magic_pf = __IPYTHON__.magic_profile
+
+    # defines %pf as a new name for %profile.
+
+    #---------------------------------------------------------------------------
+    # Section: Pyhton files to load and execute.
+
+    # Put here the full names of files you want executed with execfile(file).  If
+    # you want complicated initialization, just write whatever you want in a
+    # regular python file and load it from here.
+
+    # Filenames defined here (which *must* include the extension) are searched for
+    # through all of sys.path. Since IPython adds your .ipython directory to
+    # sys.path, they can also be placed in your .ipython dir and will be
+    # found. Otherwise (if you want to execute things not in .ipyton nor in
+    # sys.path) give a full path (you can use ~, it gets expanded)
+
+    # Example:
+    # execfile file1.py ~/file2.py
+    # will generate
+    # execfile('file1.py')
+    # execfile('_path_to_your_home/file2.py')
+
+    # As before, each file gets its own try/except block.
+
+    execfile
+
+    # If you are feeling adventurous, you can even add functionality to IPython
+    # through here. IPython works through a global variable called __ip which
+    # exists at the time when these files are read. If you know what you are doing
+    # (read the source) you can add functions to __ip in files loaded here. 
+
+    # The file example-magic.py contains a simple but correct example. Try it:
+
+    # execfile example-magic.py
+
+    # Look at the examples in IPython/iplib.py for more details on how these magic
+    # functions need to process their arguments.
+
+    #---------------------------------------------------------------------------
+    # Section: aliases for system shell commands
+
+    # Here you can define your own names for system commands. The syntax is
+    # similar to that of the builtin %alias function:
+
+    # alias alias_name command_string
+
+    # The resulting aliases are auto-generated magic functions (hence usable as
+    # %alias_name)
+
+    # For example:
+
+    # alias myls ls -la
+
+    # will define 'myls' as an alias for executing the system command 'ls -la'.
+    # This allows you to customize IPython's environment to have the same aliases
+    # you are accustomed to from your own shell.
+
+    # You can also define aliases with parameters using %s specifiers (one per
+    # parameter):
+
+    # alias parts echo first %s second %s
+
+    # will give you in IPython:
+    # >>> %parts A B
+    # first A second B
+
+    # Use one 'alias' statement per alias you wish to define.
+
+    # alias 
+
+    #************************* end of file <ipythonrc> ************************
+    
+
+
+Fine-tuning your prompt
+-----------------------
+
+IPython's prompts can be customized using a syntax similar to that of
+the bash shell. Many of bash's escapes are supported, as well as a few
+additional ones. We list them below:
+
+*\#*
+    the prompt/history count number. This escape is automatically
+    wrapped in the coloring codes for the currently active color scheme. 
+*\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. 
+*\D*
+    the prompt/history count, with the actual digits replaced by dots.
+    Used mainly in continuation prompts (prompt_in2) 
+*\w*
+    the current working directory 
+*\W*
+    the basename of current working directory 
+*\Xn*
+    where $n=0\ldots5.$ The current working directory, with $HOME
+    replaced by ~, and filtered out to contain only $n$ path elements 
+*\Yn*
+    Similar to \Xn, but with the $n+1$ element included if it is ~ (this
+    is similar to the behavior of the %cn escapes in tcsh) 
+*\u*
+    the username of the current user 
+*\$*
+    if the effective UID is 0, a #, otherwise a $ 
+*\h*
+    the hostname up to the first '.' 
+*\H*
+    the hostname 
+*\n*
+    a newline 
+*\r*
+    a carriage return 
+*\v*
+    IPython version string 
+
+In addition to these, ANSI color escapes can be insterted into the
+prompts, as \C_ColorName. 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.
+
+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 $x.y to expand the value of x.y,
+and for more complicated expressions you can use braces: ${foo()+x} will
+call function foo and add to it the value of x, before putting the
+result into your prompt. For example, using
+prompt_in1 '${commands.getoutput("uptime")}\nIn [\#]: ' 
+will print the result of the uptime command on each prompt (assuming the
+commands module has been imported in your ipythonrc file).
+
+
+      Prompt examples
+
+The following options in an ipythonrc file will give you IPython's
+default prompts::
+
+    prompt_in1 'In [\#]:' 
+    prompt_in2 '   .\D.:' 
+    prompt_out 'Out[\#]:'
+
+which look like this:
+
+    In [1]: 1+2 
+    Out[1]: 3
+
+    In [2]: for i in (1,2,3): 
+       ...:    print i, 
+       ...: 
+    1 2 3
+
+These will give you a very colorful prompt with path information::
+
+    #prompt_in1 '\C_Red\u\C_Blue[\C_Cyan\Y1\C_Blue]\C_LightGreen\#>' 
+    prompt_in2 ' ..\D>' 
+    prompt_out '<\#>'
+
+which look like this::
+
+    fperez[~/ipython]1> 1+2 
+                    <1> 3 
+    fperez[~/ipython]2> for i in (1,2,3): 
+                   ...>     print i, 
+                   ...> 
+    1 2 3
+
+
+
+IPython profiles
+----------------
+
+As we already mentioned, IPython supports the -profile command-line
+option (see sec. 5.2 <node5.html#sec:cmd-line-opts>). A profile is
+nothing more than a particular configuration file like your basic
+ipythonrc one, but with particular customizations for a specific
+purpose. When you start IPython with 'ipython -profile <name>', it
+assumes that in your IPYTHONDIR there is a file called ipythonrc-<name>,
+and loads it instead of the normal ipythonrc.
+
+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 ipythonrc file as a starting
+point, and then add further customizations.
+
+In sections 11 <node11.html#sec:syntax-extensions> and 16
+<node16.html#sec:Gnuplot> we discuss some particular profiles which come
+as part of the standard IPython distribution. You may also look in your
+IPYTHONDIR directory, any file whose name begins with ipythonrc- is a
+profile. You can use those as examples for further customizations to
+suit your own needs.
+
+IPython as your default Python environment
+==========================================
+
+Python honors the environment variable PYTHONSTARTUP 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::
+
+    import IPython 
+    IPython.Shell.IPShell().mainloop(sys_exit=1)
+
+then IPython will be your working environment anytime you start Python.
+The sys_exit=1 is needed to have IPython issue a call to sys.exit() when
+it finishes, otherwise you'll be back at the normal Python '>>>'
+prompt^4 <footnode.html#foot2368>.
+
+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.
+
+Embedding IPython
+=================
+
+It is possible to start an IPython instance inside 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 not propagate back
+to the running code, so it is safe to modify your values because you
+won't break your code in bizarre ways by doing so.
+
+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.
+
+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^5 <footnode.html#foot3206>.
+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).
+
+The following code snippet is the bare minimum you need to include in
+your Python programs for this to work (detailed examples follow later)::
+
+    from IPython.Shell import IPShellEmbed
+
+    ipshell = IPShellEmbed()
+
+    ipshell() # this call anywhere in your program will start IPython
+
+You can run embedded instances even in code which is itself being run at
+the IPython interactive prompt with '%run <filename>'. 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.
+
+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.
+
+Please look at the docstrings in the Shell.py module for more details on
+the use of this system.
+
+The following sample file illustrating how to use the embedding
+functionality is provided in the examples directory as example-embed.py.
+It should be fairly self-explanatory::
+
+
+    #!/usr/bin/env python
+
+    """An example of how to embed an IPython shell into a running program.
+
+    Please see the documentation in the IPython.Shell module for more details.
+
+    The accompanying file example-embed-short.py has quick code fragments for
+    embedding which you can cut and paste in your code once you understand how
+    things work.
+
+    The code in this file is deliberately extra-verbose, meant for learning."""
+
+    # The basics to get you going:
+
+    # IPython sets the __IPYTHON__ variable so you can know if you have nested
+    # copies running.
+
+    # Try running this code both at the command line and from inside IPython (with
+    # %run example-embed.py)
+    try:
+        __IPYTHON__
+    except NameError:
+        nested = 0
+        args = ['']
+    else:
+        print "Running nested copies of IPython."
+        print "The prompts for the nested copy have been modified"
+        nested = 1
+        # what the embedded instance will see as sys.argv:
+        args = ['-pi1','In <\\#>: ','-pi2','   .\\D.: ',
+                '-po','Out<\\#>: ','-nosep']
+
+    # First import the embeddable shell class
+    from IPython.Shell import IPShellEmbed
+
+    # Now create an instance of the embeddable shell. The first argument is a
+    # string with options exactly as you would type them if you were starting
+    # IPython at the system command line. Any parameters you want to define for
+    # configuration can thus be specified here.
+    ipshell = IPShellEmbed(args,
+                           banner = 'Dropping into IPython',
+                           exit_msg = 'Leaving Interpreter, back to program.')
+
+    # Make a second instance, you can have as many as you want.
+    if nested:
+        args[1] = 'In2<\\#>'
+    else:
+        args = ['-pi1','In2<\\#>: ','-pi2','   .\\D.: ',
+                '-po','Out<\\#>: ','-nosep']
+    ipshell2 = IPShellEmbed(args,banner = 'Second IPython instance.')
+
+    print '\nHello. This is printed from the main controller program.\n'
+
+    # You can then call ipshell() anywhere you need it (with an optional
+    # message):
+    ipshell('***Called from top level. '
+            'Hit Ctrl-D to exit interpreter and continue program.\n'
+            'Note that if you use %kill_embedded, you can fully deactivate\n'
+            'This embedded instance so it will never turn on again')
+
+    print '\nBack in caller program, moving along...\n'
+
+    #---------------------------------------------------------------------------
+    # More details:
+
+    # IPShellEmbed instances don't print the standard system banner and
+    # messages. The IPython banner (which actually may contain initialization
+    # messages) is available as <instance>.IP.BANNER in case you want it.
+
+    # IPShellEmbed instances print the following information everytime they
+    # start:
+
+    # - A global startup banner.
+
+    # - A call-specific header string, which you can use to indicate where in the
+    # execution flow the shell is starting.
+
+    # They also print an exit message every time they exit.
+
+    # Both the startup banner and the exit message default to None, and can be set
+    # either at the instance constructor or at any other time with the
+    # set_banner() and set_exit_msg() methods.
+
+    # The shell instance can be also put in 'dummy' mode globally or on a per-call
+    # basis. This gives you fine control for debugging without having to change
+    # code all over the place.
+
+    # The code below illustrates all this.
+
+
+    # This is how the global banner and exit_msg can be reset at any point
+    ipshell.set_banner('Entering interpreter - New Banner')
+    ipshell.set_exit_msg('Leaving interpreter - New exit_msg')
+
+    def foo(m):
+        s = 'spam'
+        ipshell('***In foo(). Try @whos, or print s or m:')
+        print 'foo says m = ',m
+
+    def bar(n):
+        s = 'eggs'
+        ipshell('***In bar(). Try @whos, or print s or n:')
+        print 'bar says n = ',n
+
+    # Some calls to the above functions which will trigger IPython:
+    print 'Main program calling foo("eggs")\n'
+    foo('eggs')
+
+    # The shell can be put in 'dummy' mode where calls to it silently return. This
+    # allows you, for example, to globally turn off debugging for a program with a
+    # single call.
+    ipshell.set_dummy_mode(1)
+    print '\nTrying to call IPython which is now "dummy":'
+    ipshell()
+    print 'Nothing happened...'
+    # The global 'dummy' mode can still be overridden for a single call
+    print '\nOverriding dummy mode manually:'
+    ipshell(dummy=0)
+
+    # Reactivate the IPython shell
+    ipshell.set_dummy_mode(0)
+
+    print 'You can even have multiple embedded instances:'
+    ipshell2()
+
+    print '\nMain program calling bar("spam")\n'
+    bar('spam')
+
+    print 'Main program finished. Bye!'
+
+    #********************** End of file <example-embed.py> ***********************
+
+Once you understand how the system functions, you can use the following
+code fragments in your programs which are ready for cut and paste::
+
+
+    """Quick code snippets for embedding IPython into other programs.
+
+    See example-embed.py for full details, this file has the bare minimum code for
+    cut and paste use once you understand how to use the system."""
+
+    #---------------------------------------------------------------------------
+    # This code loads IPython but modifies a few things if it detects it's running
+    # embedded in another IPython session (helps avoid confusion)
+
+    try:
+        __IPYTHON__
+    except NameError:
+        argv = ['']
+        banner = exit_msg = ''
+    else:
+        # Command-line options for IPython (a list like sys.argv)
+        argv = ['-pi1','In <\\#>:','-pi2','   .\\D.:','-po','Out<\\#>:']
+        banner = '*** Nested interpreter ***'
+        exit_msg = '*** Back in main IPython ***'
+
+    # First import the embeddable shell class
+    from IPython.Shell import IPShellEmbed
+    # Now create the IPython shell instance. Put ipshell() anywhere in your code
+    # where you want it to open.
+    ipshell = IPShellEmbed(argv,banner=banner,exit_msg=exit_msg)
+
+    #---------------------------------------------------------------------------
+    # This code will load an embeddable IPython shell always with no changes for
+    # nested embededings.
+
+    from IPython.Shell import IPShellEmbed
+    ipshell = IPShellEmbed()
+    # Now ipshell() will open IPython anywhere in the code.
+
+    #---------------------------------------------------------------------------
+    # This code loads an embeddable shell only if NOT running inside
+    # IPython. Inside IPython, the embeddable shell variable ipshell is just a
+    # dummy function.
+
+    try:
+        __IPYTHON__
+    except NameError:
+        from IPython.Shell import IPShellEmbed
+        ipshell = IPShellEmbed()
+        # Now ipshell() will open IPython anywhere in the code
+    else:
+        # Define a dummy ipshell() so the same code doesn't crash inside an
+        # interactive IPython
+        def ipshell(): pass
+
+    #******************* End of file <example-embed-short.py> ********************
+
+Using the Python debugger (pdb)
+===============================
+
+
+Running entire programs via pdb
+-------------------------------
+
+pdb, 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 pdb,
+regardless of whether you have wrapped it into a 'main()' function or
+not. For this, simply type '%run -d myscript' at an IPython prompt. See
+the %run command's documentation (via '%run?' or in Sec. 6.2
+<node6.html#sec:magic>) for more details, including how to control where
+pdb will stop execution first.
+
+For more information on the use of the pdb debugger, read the included
+pdb.doc file (part of the standard Python distribution). On a stock
+Linux system it is located at /usr/lib/python2.3/pdb.doc, but the
+easiest way to read it is by using the help() function of the pdb module
+as follows (in an IPython prompt):
+
+In [1]: import pdb 
+In [2]: pdb.help()
+
+This will load the pdb.doc document in a file viewer for you automatically.
+
+
+Automatic invocation of pdb on exceptions
+-----------------------------------------
+
+IPython, if started with the -pdb option (or if the option is set in
+your rc file) can call the Python pdb debugger every time your code
+triggers an uncaught exception^6 <footnode.html#foot2403>. This feature
+can also be toggled at any time with the %pdb magic command. This can be
+extremely useful in order to find the origin of subtle bugs, because pdb
+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.
+
+Furthermore, you can use these debugging facilities both with the
+embedded IPython mode and without IPython at all. For an embedded shell
+(see sec. 9 <node9.html#sec:embed>), simply call the constructor with
+'-pdb' in the argument string and automatically pdb will be called if an
+uncaught exception is triggered by your code.
+
+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:
+
+import sys,IPython.ultraTB  
+sys.excepthook = IPython.ultraTB.FormattedTB(mode='Verbose',
+color_scheme='Linux', call_pdb=1)
+
+The mode keyword can be either 'Verbose' or 'Plain', giving either very
+detailed or normal tracebacks respectively. The color_scheme keyword can
+be one of 'NoColor', 'Linux' (default) or 'LightBG'. These are the same
+options which can be set in IPython with -colors and -xmode.
+
+This will give any of your programs detailed, colored tracebacks with
+automatic invocation of pdb.
+
+
+Extensions for syntax processing
+================================
+
+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.
+
+In the IPython/Extensions 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.
+
+
+Pasting of code starting with '»> ' or '... '
+----------------------------------------------
+
+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 '>>> ' or '... ', 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.
+
+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
+InterpreterPasteInput.py in the IPython/Extensions directory for details
+on how this is done.
+
+IPython comes with a special profile enabling this feature, called
+tutorial. Simply start IPython via 'ipython -p tutorial' and the feature
+will be available. In a normal IPython session you can activate the
+feature by importing the corresponding module with:
+In [1]: import IPython.Extensions.InterpreterPasteInput
+
+The following is a 'screenshot' of how things work when this extension
+is on, copying an example from the standard tutorial::
+
+    IPython profile: tutorial 
+
+    *** Pasting of code with ">>>" or "..." has been enabled. 
+
+    In [1]: >>> def fib2(n): # return Fibonacci series up to n 
+       ...: ...     """Return a list containing the Fibonacci series up to
+    n.""" 
+       ...: ...     result = [] 
+       ...: ...     a, b = 0, 1 
+       ...: ...     while b < n: 
+       ...: ...         result.append(b)    # see below 
+       ...: ...         a, b = b, a+b 
+       ...: ...     return result 
+       ...: 
+
+    In [2]: fib2(10) 
+    Out[2]: [1, 1, 2, 3, 5, 8]
+
+Note that as currently written, this extension does not 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.
+
+
+Input of physical quantities with units
+---------------------------------------
+
+The module PhysicalQInput allows a simplified form of input for physical
+quantities with units. This file is meant to be used in conjunction with
+the PhysicalQInteractive module (in the same directory) and
+Physics.PhysicalQuantities from Konrad Hinsen's ScientificPython
+(http://dirac.cnrs-orleans.fr/ScientificPython/).
+
+The Physics.PhysicalQuantities module defines PhysicalQuantity objects,
+but these must be declared as instances of a class. For example, to
+define v as a velocity of 3 m/s, normally you would write::
+    In [1]: v = PhysicalQuantity(3,'m/s')
+
+Using the PhysicalQ_Input extension this can be input instead as: 
+In [1]: v = 3 m/s
+which is much more convenient for interactive use (even though it is
+blatantly invalid Python syntax).
+
+The physics profile supplied with IPython (enabled via 'ipython -p
+physics') uses these extensions, which you can also activate with:
+
+from math import * # math MUST be imported BEFORE PhysicalQInteractive 
+from IPython.Extensions.PhysicalQInteractive import * 
+import IPython.Extensions.PhysicalQInput
+
+IPython as a system shell
+=========================
+
+IPython ships with a special profile called pysh, which you can activate
+at the command line as 'ipython -p pysh'. This loads InterpreterExec,
+along with some additional facilities and a prompt customized for
+filesystem navigation.
+
+Note that this does not 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.
+
+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.
+
+
+Aliases
+-------
+
+All of your $PATH has been loaded as IPython aliases, so you should be
+able to type any normal system command and have it executed. See %alias?
+and %unalias? for details on the alias facilities. See also %rehash? and
+%rehashx? for details on the mechanism used to load $PATH.
+
+
+Special syntax
+--------------
+
+Any lines which begin with '~', '/' and '.' will be executed as shell
+commands instead of as Python code. The special escapes below are also
+recognized. !cmd is valid in single or multi-line input, all others are
+only valid in single-line input::
+
+*!cmd*
+    pass 'cmd' directly to the shell 
+*!!cmd*
+    execute 'cmd' and return output as a list (split on '\n') 
+*var=!cmd
+    capture output of cmd into var, as a string list
+
+The $/$$ 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 !/!!, you can expand any
+python variable or expression by prepending it with $. Full details of
+the allowed syntax can be found in Python's PEP 215.
+
+A few brief examples will illustrate these (note that the indentation
+below may be incorrectly displayed)::
+
+    fperez[~/test]|3> !ls *s.py  
+    scopes.py strings.py
+
+ls is an internal alias, so there's no need to use !::
+
+    fperez[~/test]|4> ls *s.py  
+    scopes.py* strings.py
+
+!!ls will return the output into a Python variable FIXME!!!::
+
+    fperez[~/test]|5> !!ls *s.py  
+                  <5> ['scopes.py', 'strings.py']  
+    fperez[~/test]|6> print _5  
+    ['scopes.py', 'strings.py']
+
+$ and $$ allow direct capture to named variables:
+
+fperez[~/test]|7> $astr = ls *s.py  
+fperez[~/test]|8> astr  
+              <8> 'scopes.py\nstrings.py'
+
+fperez[~/test]|9> $$alist = ls *s.py  
+fperez[~/test]|10> alist  
+              <10> ['scopes.py', 'strings.py']
+
+alist is now a normal python list you can loop over. Using $ will expand
+back the python values when alias calls are made:
+
+fperez[~/test]|11> for f in alist:  
+              |..>    print 'file',f,  
+              |..>    wc -l $f  
+              |..>  
+file scopes.py 13 scopes.py  
+file strings.py 4 strings.py
+
+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 .bak
+extensions, you must use::
+
+    fperez[~/test]|12> for f in alist:  
+                  |..>    cp $f ${f}.bak
+
+If you try using $f.bak, you'll get an AttributeError exception saying
+that your string object doesn't have a .bak attribute. This is because
+the $ expansion mechanism allows you to expand full Python expressions::
+
+    fperez[~/test]|13> echo "sys.platform is: $sys.platform"  
+    sys.platform is: linux2
+
+IPython's input history handling is still active, which allows you to
+rerun a single block of multi-line input by simply using exec::
+
+    fperez[~/test]|14> $$alist = ls *.eps  
+    fperez[~/test]|15> exec _i11  
+    file image2.eps 921 image2.eps  
+    file image.eps 921 image.eps
+
+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.
+
+
+Useful functions and modules
+----------------------------
+
+The os, sys and shutil modules from the Python standard library are
+automatically loaded. Some additional functions, useful for shell usage,
+are listed below. You can request more help about them with '?'.
+
+*shell*
+    - execute a command in the underlying system shell 
+*system*
+    - like shell(), but return the exit status of the command 
+*sout*
+    - capture the output of a command as a string 
+*lout*
+    - capture the output of a command as a list (split on '\n') 
+*getoutputerror*
+    - capture (output,error) of a shell commandss 
+
+sout/lout are the functional equivalents of $/$$. They are provided to
+allow you to capture system output in the middle of true python code,
+function definitions, etc (where $ and $$ are invalid).
+
+
+Directory management
+--------------------
+
+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.
+
+Pysh provides its own builtin '%cd' magic command to move in the
+filesystem (the % is not required with automagic on). It also maintains
+a list of visited directories (use %dhist to see it) and allows direct
+switching to any of them. Type 'cd?' for more details.
+
+%pushd, %popd and %dirs are provided for directory stack handling.
+
+
+    Prompt customization
+
+The supplied ipythonrc-pysh 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:
+
+*\#*
+    - Prompt number, wrapped in the color escapes for the input prompt
+    (determined by the current color scheme). 
+*\N*
+    - Just the prompt counter number, without any coloring wrappers. You
+    can thus customize the actual prompt colors manually. 
+*\D*
+    - Dots, as many as there are digits in \# (so they align). 
+*\w*
+    - Current working directory (cwd). 
+*\W*
+    - Basename of current working directory. 
+*\XN*
+    - Where N=0..5. N terms of the cwd, with $HOME written as ~. 
+*\YN*
+    - Where N=0..5. Like XN, but if ~ is term N+1 it's also shown. 
+*\u*
+    - Username. 
+*\H*
+    - Full hostname. 
+*\h*
+    - Hostname up to first '.' 
+*\$*
+    - Root symbol ($ or #). 
+*\t*
+    - Current time, in H:M:S format. 
+*\v*
+    - IPython release version. 
+*\n*
+    - Newline. 
+*\r*
+    - Carriage return. 
+*\\*
+    - An explicitly escaped '\'. 
+
+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:
+
+*\C_Black*
+
+*\C_Blue*
+
+*\C_Brown*
+
+*\C_Cyan*
+
+*\C_DarkGray*
+
+*\C_Green*
+
+*\C_LightBlue*
+
+*\C_LightCyan*
+
+*\C_LightGray*
+
+*\C_LightGreen*
+
+*\C_LightPurple*
+
+*\C_LightRed*
+
+*\C_Purple*
+
+*\C_Red*
+
+*\C_White*
+
+*\C_Yellow*
+
+*\C_Normal*
+    Stop coloring, defaults to your terminal settings. 
+
+Threading support
+=================
+
+WARNING: 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.
+
+IPython, via the -gthread , -qthread, -q4thread and -wthread options
+(described in Sec. 5.1 <node5.html#sec:threading-opts>), 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.
+
+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 %run, for
+example) your GUI code without blocking.
+
+A nice mini-tutorial on using IPython along with the Qt Designer
+application is available at the SciPy wiki:
+http://www.scipy.org/Cookbook/Matplotlib/Qt_with_IPython_and_Designer.
+
+
+Tk issues
+---------
+
+As indicated in Sec. 5.1 <node5.html#sec:threading-opts>, a special -tk
+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.
+
+
+I/O pitfalls
+------------
+
+Be mindful that the Python interpreter switches between threads every
+$N$ bytecodes, where the default value as of Python 2.3 is $N=100.$ This
+value can be read by using the sys.getcheckinterval() function, and it
+can be reset via sys.setcheckinterval(N). 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
+'\n'. An instruction as simple as 
+  print >> filehandle, ''hello world''
+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.
+
+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 file/open
+function is the buffering value)::
+  filehandle = open(filename,mode,0)
+
+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.
+
+Interactive demos with IPython
+==============================
+
+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.
+
+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::
+
+
+    """A simple interactive demo to illustrate the use of IPython's Demo class.
+
+    Any python script can be run as a demo, but that does little more than showing
+    it on-screen, syntax-highlighted in one shot.  If you add a little simple
+    markup, you can stop at specified intervals and return to the ipython prompt,
+    resuming execution later.
+    """
+
+    print 'Hello, welcome to an interactive IPython demo.'
+    print 'Executing this block should require confirmation before proceeding,'
+    print 'unless auto_all has been set to true in the demo object'
+
+    # The mark below defines a block boundary, which is a point where IPython will
+    # stop execution and return to the interactive prompt.
+    # Note that in actual interactive execution, 
+    # <demo> --- stop ---
+
+    x = 1
+    y = 2
+
+    # <demo> --- stop ---
+
+    # the mark below makes this block as silent
+    # <demo> silent
+
+    print 'This is a silent block, which gets executed but not printed.'
+
+    # <demo> --- stop ---
+    # <demo> auto
+    print 'This is an automatic block.'
+    print 'It is executed without asking for confirmation, but printed.'
+    z = x+y
+
+    print 'z=',x
+
+    # <demo> --- stop ---
+    # This is just another normal block.
+    print 'z is now:', z
+
+    print 'bye!'
+
+In order to run a file as a demo, you must first make a Demo object out
+of it. If the file is named myscript.py, the following code will make a
+demo::
+
+    from IPython.demo import Demo
+
+    mydemo = Demo('myscript.py')
+
+This creates the mydemo 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::
+
+    mydemo 
+
+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 '?' on them to see their docstrings for more usage
+details. In addition, the demo module itself contains a comprehensive
+docstring, which you can access via::
+
+    from IPython import demo
+
+    demo?
+
+Limitations: It is important to note that these demos are limited to
+fairly simple uses. In particular, you can not 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. 9
+
+
+Plotting with matplotlib
+========================
+
+The matplotlib library (http://matplotlib.sourceforge.net
+http://matplotlib.sourceforge.net) 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.
+
+IPython accepts the special option -pylab (Sec. 5.2
+<node5.html#sec:cmd-line-opts>). This configures it to support
+matplotlib, honoring the settings in the .matplotlibrc file. IPython
+will detect the user's choice of matplotlib GUI backend, and
+automatically select the proper threading model to prevent blocking. It
+also sets matplotlib in interactive mode and modifies %run slightly, so
+that any matplotlib-based script can be executed using %run and the
+final show() command does not block the interactive shell.
+
+The -pylab 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. 7.3 <node7.html#sec:profiles>): ''ipython -pylab -p
+myprofile'' will load the profile defined in ipythonrc-myprofile after
+configuring matplotlib.
+
+Reporting bugs
+==============
+
+Automatic crash reports
+-----------------------
+
+Ideally, IPython itself shouldn't crash. It will catch exceptions
+produced by you, but bugs in its internals will still crash it.
+
+In such a situation, IPython will leave a file named
+IPython_crash_report.txt 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. 20 <node20.html#sec:credits> for names and
+addresses), it will help us a lot in understanding the cause of the
+problem and fixing it sooner.
+
+
+The bug tracker
+---------------
+
+IPython also has an online bug-tracker, located at
+http://projects.scipy.org/ipython/ipython/report/1. 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.
+
+You can also use this bug tracker to file feature requests.
+
+Brief history
+=============
+
+
+    Origins
+
+The current IPython system grew out of the following three projects:
+
+    * [ipython] by Fernando Pérez. I was working on adding
+      Mathematica-type prompts and a flexible configuration system
+      (something better than $PYTHONSTARTUP) to the standard Python
+      interactive interpreter.
+    * [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.
+    * [LazyPython] by Nathan Gray. Simple but very powerful. The quick
+      syntax (auto parens, auto quotes) and verbose/colored tracebacks
+      were all taken from here.
+
+When I found out (see sec. 20 <node20.html#figgins>) 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.
+
+
+Current status
+--------------
+
+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).
+
+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.
+
+
+Future
+------
+
+See the separate new_design 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 interactive
+interpreter. But that will never happen with the current state of the
+code, so all contributions are welcome.
+
+License
+=======
+
+IPython is released under the terms of the BSD license, whose general
+form can be found at:
+http://www.opensource.org/licenses/bsd-license.php. The full text of the
+IPython license is reproduced below::
+
+    IPython is released under a BSD-type license.
+
+    Copyright (c) 2001, 2002, 2003, 2004 Fernando Perez
+    <[e-mail]>.
+
+    Copyright (c) 2001 Janko Hauser <[e-mail]> and  
+    Nathaniel Gray <[e-mail]>.
+
+    All rights reserved.
+
+    Redistribution and use in source and binary forms, with or without
+    modification, are permitted provided that the following conditions
+    are met:
+
+    a. Redistributions of source code must retain the above copyright
+    notice, this list of conditions and the following disclaimer.
+
+    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.
+
+    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.
+
+    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. 
+
+Individual authors are the holders of the copyright for their code and
+are listed in each file.
+
+Some files (DPyGetOpt.py, for example) may be licensed under different
+conditions. Ultimately each file indicates clearly the conditions under
+which its author/authors have decided to publish the code.
+
+Versions of IPython up to and including 0.6.3 were released under the
+GNU Lesser General Public License (LGPL), available at
+http://www.gnu.org/copyleft/lesser.html.
+
+Credits
+=======
+
+IPython is mainly developed by Fernando Pérez
+<[e-mail]>, but the project was born from mixing in
+Fernando's code with the IPP project by Janko Hauser
+<jhauser-AT-zscout.de> and LazyPython by Nathan Gray
+<n8gray-AT-caltech.edu>. For all IPython-related requests, please
+contact Fernando.
+
+As of early 2006, the following developers have joined the core team:
+
+    * [Robert Kern] <rkern-AT-enthought.com>: co-mentored the 2005
+      Google Summer of Code project to develop python interactive
+      notebooks (XML documents) and graphical interface. This project
+      was awarded to the students Tzanko Matev <tsanko-AT-gmail.com> and
+      Toni Alatalo <antont-AT-an.org>
+    * [Brian Granger] <bgranger-AT-scu.edu>: extending IPython to allow
+      support for interactive parallel computing.
+    * [Ville Vainio] <vivainio-AT-gmail.com>: Ville is the new
+      maintainer for the main trunk of IPython after version 0.7.1.
+
+User or development help should be requested via the IPython mailing lists:
+
+*User list:*
+    http://scipy.net/mailman/listinfo/ipython-user 
+*Developer's list:*
+    http://scipy.net/mailman/listinfo/ipython-dev 
+
+The IPython project is also very grateful to^7 <footnode.html#foot2913>:
+
+Bill Bumgarner <bbum-AT-friday.com>: 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).
+
+Ka-Ping Yee <ping-AT-lfw.org>: for providing the Itpl module for
+convenient and powerful string interpolation with a much nicer syntax
+than formatting through the '%' operator.
+
+Arnd Baecker <baecker-AT-physik.tu-dresden.de>: 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).
+
+Obviously Guido van Rossum and the whole Python development team, that
+goes without saying.
+
+IPython's website is generously hosted at http://ipython.scipy.orgby
+Enthought (http://www.enthought.com). I am very grateful to them and all
+of the SciPy team for their contribution.
+
+Fernando would also like to thank Stephen Figgins <fig-AT-monitor.net>,
+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:
+http://www.onlamp.com/pub/a/python/2001/10/11/pythonnews.html.
+
+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:
+
+    * [Jack Moffit] <jack-AT-xiph.org> 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.
+      Jack is also contributing with Debian packaging and many other
+      things.
+    * [Alexander Schmolck] <a.schmolck-AT-gmx.net> 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.
+    * [Andrea Riciputi] <andrea.riciputi-AT-libero.it> Mac OSX
+      information, Fink package management.
+    * [Gary Bishop] <gb-AT-cs.unc.edu> Bug reports, and patches to work
+      around the exception handling idiosyncracies of WxPython. Readline
+      and color support for Windows.
+    * [Jeffrey Collins] <Jeff.Collins-AT-vexcel.com> Bug reports. Much
+      improved readline support, including fixes for Python 2.3.
+    * [Dryice Liu] <dryice-AT-liu.com.cn> FreeBSD port.
+    * [Mike Heeter] <korora-AT-SDF.LONESTAR.ORG>
+    * [Christopher Hart] <hart-AT-caltech.edu> PDB integration.
+    * [Milan Zamazal] <pdm-AT-zamazal.org> Emacs info.
+    * [Philip Hisley] <compsys-AT-starpower.net>
+    * [Holger Krekel] <pyth-AT-devel.trillke.net> Tab completion, lots
+      more.
+    * [Robin Siebler] <robinsiebler-AT-starband.net>
+    * [Ralf Ahlbrink] <ralf_ahlbrink-AT-web.de>
+    * [Thorsten Kampe] <thorsten-AT-thorstenkampe.de>
+    * [Fredrik Kant] <fredrik.kant-AT-front.com> Windows setup.
+    * [Syver Enstad] <syver-en-AT-online.no> Windows setup.
+    * [Richard] <rxe-AT-renre-europe.com> Global embedding.
+    * [Hayden Callow] <h.callow-AT-elec.canterbury.ac.nz> Gnuplot.py 1.6
+      compatibility.
+    * [Leonardo Santagada] <retype-AT-terra.com.br> Fixes for Windows
+      installation.
+    * [Christopher Armstrong] <radix-AT-twistedmatrix.com> Bugfixes.
+    * [Francois Pinard] <pinard-AT-iro.umontreal.ca> Code and
+      documentation fixes.
+    * [Cory Dodt] <cdodt-AT-fcoe.k12.ca.us> Bug reports and Windows
+      ideas. Patches for Windows installer.
+    * [Olivier Aubert] <oaubert-AT-bat710.univ-lyon1.fr> New magics.
+    * [King C. Shu] <kingshu-AT-myrealbox.com> Autoindent patch.
+    * [Chris Drexler] <chris-AT-ac-drexler.de> Readline packages for
+      Win32/CygWin.
+    * [Gustavo Cordova Avila] <gcordova-AT-sismex.com> EvalDict code for
+      nice, lightweight string interpolation.
+    * [Kasper Souren] <Kasper.Souren-AT-ircam.fr> Bug reports, ideas.
+    * [Gever Tulley] <gever-AT-helium.com> Code contributions.
+    * [Ralf Schmitt] <ralf-AT-brainbot.com> Bug reports & fixes.
+    * [Oliver Sander] <osander-AT-gmx.de> Bug reports.
+    * [Rod Holland] <rhh-AT-structurelabs.com> Bug reports and fixes to
+      logging module.
+    * [Daniel 'Dang' Griffith] <pythondev-dang-AT-lazytwinacres.net>
+      Fixes, enhancement suggestions for system shell use.
+    * [Viktor Ransmayr] <viktor.ransmayr-AT-t-online.de> Tests and
+      reports on Windows installation issues. Contributed a true Windows
+      binary installer.
+    * [Mike Salib] <msalib-AT-mit.edu> Help fixing a subtle bug related
+      to traceback printing.
+    * [W.J. van der Laan] <gnufnork-AT-hetdigitalegat.nl> Bash-like
+      prompt specials.
+    * [Antoon Pardon] <Antoon.Pardon-AT-rece.vub.ac.be> Critical fix for
+      the multithreaded IPython.
+    * [John Hunter] <jdhunter-AT-nitace.bsd.uchicago.edu> Matplotlib
+      author, helped with all the development of support for matplotlib
+      in IPyhton, including making necessary changes to matplotlib itself.
+    * [Matthew Arnison] <maffew-AT-cat.org.au> Bug reports, '%run -d' idea.
+    * [Prabhu Ramachandran] <prabhu_r-AT-users.sourceforge.net> Help
+      with (X)Emacs support, threading patches, ideas...
+    * [Norbert Tretkowski] <tretkowski-AT-inittab.de> help with Debian
+      packaging and distribution.
+    * [George Sakkis] <gsakkis-AT-eden.rutgers.edu> New matcher for
+      tab-completing named arguments of user-defined functions.
+    * [Jörgen Stenarson] <jorgen.stenarson-AT-bostream.nu> Wildcard
+      support implementation for searching namespaces.
+    * [Vivian De Smedt] <vivian-AT-vdesmedt.com> Debugger enhancements,
+      so that when pdb is activated from within IPython, coloring, tab
+      completion and other features continue to work seamlessly.
+    * [Scott Tsai] <scottt958-AT-yahoo.com.tw> Support for automatic
+      editor invocation on syntax errors (see
+      http://www.scipy.net/roundup/ipython/issue36).
+    * [Alexander Belchenko] <bialix-AT-ukr.net> Improvements for win32
+      paging system.
+    * [Will Maier] <willmaier-AT-ml1.net> Official OpenBSD port.
+