From 4879f402503168cdb3b434af07b1c16102174a8f 2008-03-29 13:46:11 From: Ville M. Vainio Date: 2008-03-29 13:46:11 Subject: [PATCH] add ipython.rst to sphinx source --- diff --git a/doc/source/conf.py b/doc/source/conf.py new file mode 100644 index 0000000..7e4a70c --- /dev/null +++ b/doc/source/conf.py @@ -0,0 +1,132 @@ +# -*- coding: utf-8 -*- +# +# IPython documentation build configuration file, created by +# sphinx-quickstart.py on Sat Mar 29 15:36:13 2008. +# +# This file is execfile()d with the current directory set to its containing dir. +# +# The contents of this file are pickled, so don't put values in the namespace +# that aren't pickleable (module imports are okay, they're removed automatically). +# +# All configuration values have a default value; values that are commented out +# serve to show the default value. + +import sys + +# If your extensions are in another directory, add it here. +#sys.path.append('some/directory') + +# General configuration +# --------------------- + +# Add any Sphinx extension module names here, as strings. They can be extensions +# coming with Sphinx (named 'sphinx.addons.*') or your custom ones. +#extensions = [] + +# Add any paths that contain templates here, relative to this directory. +templates_path = ['_templates'] + +# The suffix of source filenames. +source_suffix = '.rst' + +# The master toctree document. +master_doc = 'ipython' + +# General substitutions. +project = 'IPython' +copyright = '2008, IPython team' + +# The default replacements for |version| and |release|, also used in various +# other places throughout the built documents. +# +# The short X.Y version. +version = '0.8.3' +# The full version, including alpha/beta/rc tags. +release = '0.8.3' + +# There are two options for replacing |today|: either, you set today to some +# non-false value, then it is used: +#today = '' +# Else, today_fmt is used as the format for a strftime call. +today_fmt = '%B %d, %Y' + +# List of documents that shouldn't be included in the build. +#unused_docs = [] + +# If true, '()' will be appended to :func: etc. cross-reference text. +#add_function_parentheses = True + +# If true, the current module name will be prepended to all description +# unit titles (such as .. function::). +#add_module_names = True + +# If true, sectionauthor and moduleauthor directives will be shown in the +# output. They are ignored by default. +#show_authors = False + +# The name of the Pygments (syntax highlighting) style to use. +pygments_style = 'sphinx' + + +# Options for HTML output +# ----------------------- + +# The style sheet to use for HTML and HTML Help pages. A file of that name +# must exist either in Sphinx' static/ path, or in one of the custom paths +# given in html_static_path. +html_style = 'default.css' + +# Add any paths that contain custom static files (such as style sheets) here, +# relative to this directory. They are copied after the builtin static files, +# so a file named "default.css" will overwrite the builtin "default.css". +html_static_path = ['_static'] + +# If not '', a 'Last updated on:' timestamp is inserted at every page bottom, +# using the given strftime format. +html_last_updated_fmt = '%b %d, %Y' + +# If true, SmartyPants will be used to convert quotes and dashes to +# typographically correct entities. +#html_use_smartypants = True + +# Content template for the index page. +#html_index = '' + +# Custom sidebar templates, maps document names to template names. +#html_sidebars = {} + +# Additional templates that should be rendered to pages, maps page names to +# template names. +#html_additional_pages = {} + +# If false, no module index is generated. +#html_use_modindex = True + +# If true, the reST sources are included in the HTML build as _sources/. +#html_copy_source = True + +# Output file base name for HTML help builder. +htmlhelp_basename = 'IPythondoc' + + +# Options for LaTeX output +# ------------------------ + +# The paper size ('letter' or 'a4'). +#latex_paper_size = 'letter' + +# The font size ('10pt', '11pt' or '12pt'). +#latex_font_size = '10pt' + +# Grouping the document tree into LaTeX files. List of tuples +# (source start file, target name, title, author, document class [howto/manual]). +#latex_documents = [] + +# Additional stuff for the LaTeX preamble. +#latex_preamble = '' + +# Documents to append as an appendix to all manuals. +#latex_appendices = [] + +# If false, no module index is generated. +#latex_use_modindex = True diff --git a/doc/source/ipython.rst b/doc/source/ipython.rst new file mode 100644 index 0000000..92aa987 --- /dev/null +++ b/doc/source/ipython.rst @@ -0,0 +1,5026 @@ +.. 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 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 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 for +configuring things optimally and 4 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- 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 + + 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 +. This file is very commented and has +many variables you can change to suit your taste, you can find more +details in Sec. 7 . 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 + . + * 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 +. 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. and a list of the + object's attributes will be printed (see sec. 6.5 + 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 + 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 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 + 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 . 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 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 + 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 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 + 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 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 + 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 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 : 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 : 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 + for more details. + * [-autocall] : 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 :] 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 :] 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 :] 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 :] 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 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 :] specify the name of your logfile. + * [-logplay|lp :] 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] : assume that your config file is + ipythonrc- (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 :] 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 discusses in detail all the + available escapes to customize your prompts. + * [-prompt_in2|pi2 :] 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 used for output prompts, also + uses numbers like prompt_in1. Default: 'Out[\#]:' + * [-quick:] start in bare bones mode (no config file loaded). + * [-rcfile :] 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 :] 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 :] separator before input prompts. + Default: '\n' + * [-separate_out|so :] separator before output prompts. + Default: nothing. + * [-separate_out2|so2 :] 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 :] Select a specific version of wxPython (used + in conjunction with -wthread). Requires the wxversion module, part + of recent wxPython distributions + * [-xmode :] 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 . + + + +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 "", 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: + +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]: + +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. 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 - set bookmark to current dir %bookmark - +set bookmark to %bookmark -l - list all bookmarks %bookmark -d + - remove bookmark %bookmark -r - remove all bookmarks + +You can later on access a bookmarked folder with: %cd -b or +simply '%cd ' if there is no directory called 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 -' +to see directory history conveniently. + +Usage: + +cd 'dir': changes to directory 'dir'. + +cd -: changes to the last visited directory. + +cd -: changes to the n-th directory in the directory history. + +cd -b : jump to a bookmark set by %bookmark (note: cd + is enough if there is no directory , but +a bookmark with the name exists.) 'cd -b ' 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 - to go to +directory number . + +Note that most of time, you should view directory history by entering cd +-. + + +%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 : 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 +_ or Out[], where 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 : 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 : 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 : save profile results as shown on screen to a text file. +The profile is still shown on screen. + +-D : 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] -d [-b] -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 option can be given, where 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 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 -r [-t|-c]] statement + +Time execution of a Python statement or expression using the timeit module. + +Options: -n: execute the given statement times in a loop. If this +value is not given, a fitting value is chosen. + +-r: repeat the loop iteration 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

: use a precision of

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]: + +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 , 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 :] 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 :] Print the definition header for any callable + object. If the object is a class, print the constructor information. + * [%psource :] Print (or run through a pager if too long) + the source code for an object. + * [%pfile :] 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 + 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 : + 'name._' 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 +)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 are dynamically created ( +being the prompt counter), such that +_i == _ih[] == In[]. + +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 _ are dynamically created ( +being the prompt counter), such that the result of output is always +available as _ (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 + 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 ...:] 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 option + (abbreviates to -p ) which tells it to look for an rcfile + named ipythonrc-. + * [import_mod ...:] import modules with 'import + ,,...' + * [import_some ...:] import functions with 'from + import ,,...' + * [import_all ...:] for each module listed import + functions with 'from import *' + * [execute :] give any single-line python code to be + executed. + * [execfile :] 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 :] this is equivalent to calling + '%alias ' 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]: + + #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 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 : 'name._' 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 ************************ + + + +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 ). 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 ', it +assumes that in your IPYTHONDIR there is a file called ipythonrc-, +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 and 16 + 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 . + +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 . +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 '. 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 .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 *********************** + +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 ******************** + +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 +) 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 . 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 ), 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 ), 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 , 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, + # --- stop --- + + x = 1 + y = 2 + + # --- stop --- + + # the mark below makes this block as silent + # silent + + print 'This is a silent block, which gets executed but not printed.' + + # --- stop --- + # auto + print 'This is an automatic block.' + print 'It is executed without asking for confirmation, but printed.' + z = x+y + + print 'z=',x + + # --- 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 +). 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 ): ''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 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 ) 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 + . + + Copyright (c) 2001 Janko Hauser and + Nathaniel Gray . + + 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 +, but the project was born from mixing in +Fernando's code with the IPP project by Janko Hauser + and LazyPython by Nathan Gray +. For all IPython-related requests, please +contact Fernando. + +As of early 2006, the following developers have joined the core team: + + * [Robert Kern] : 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 and + Toni Alatalo + * [Brian Granger] : extending IPython to allow + support for interactive parallel computing. + * [Ville Vainio] : 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 : + +Bill Bumgarner : 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 : for providing the Itpl module for +convenient and powerful string interpolation with a much nicer syntax +than formatting through the '%' operator. + +Arnd Baecker : 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 , +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] 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] 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] Mac OSX + information, Fink package management. + * [Gary Bishop] Bug reports, and patches to work + around the exception handling idiosyncracies of WxPython. Readline + and color support for Windows. + * [Jeffrey Collins] Bug reports. Much + improved readline support, including fixes for Python 2.3. + * [Dryice Liu] FreeBSD port. + * [Mike Heeter] + * [Christopher Hart] PDB integration. + * [Milan Zamazal] Emacs info. + * [Philip Hisley] + * [Holger Krekel] Tab completion, lots + more. + * [Robin Siebler] + * [Ralf Ahlbrink] + * [Thorsten Kampe] + * [Fredrik Kant] Windows setup. + * [Syver Enstad] Windows setup. + * [Richard] Global embedding. + * [Hayden Callow] Gnuplot.py 1.6 + compatibility. + * [Leonardo Santagada] Fixes for Windows + installation. + * [Christopher Armstrong] Bugfixes. + * [Francois Pinard] Code and + documentation fixes. + * [Cory Dodt] Bug reports and Windows + ideas. Patches for Windows installer. + * [Olivier Aubert] New magics. + * [King C. Shu] Autoindent patch. + * [Chris Drexler] Readline packages for + Win32/CygWin. + * [Gustavo Cordova Avila] EvalDict code for + nice, lightweight string interpolation. + * [Kasper Souren] Bug reports, ideas. + * [Gever Tulley] Code contributions. + * [Ralf Schmitt] Bug reports & fixes. + * [Oliver Sander] Bug reports. + * [Rod Holland] Bug reports and fixes to + logging module. + * [Daniel 'Dang' Griffith] + Fixes, enhancement suggestions for system shell use. + * [Viktor Ransmayr] Tests and + reports on Windows installation issues. Contributed a true Windows + binary installer. + * [Mike Salib] Help fixing a subtle bug related + to traceback printing. + * [W.J. van der Laan] Bash-like + prompt specials. + * [Antoon Pardon] Critical fix for + the multithreaded IPython. + * [John Hunter] Matplotlib + author, helped with all the development of support for matplotlib + in IPyhton, including making necessary changes to matplotlib itself. + * [Matthew Arnison] Bug reports, '%run -d' idea. + * [Prabhu Ramachandran] Help + with (X)Emacs support, threading patches, ideas... + * [Norbert Tretkowski] help with Debian + packaging and distribution. + * [George Sakkis] New matcher for + tab-completing named arguments of user-defined functions. + * [Jörgen Stenarson] Wildcard + support implementation for searching namespaces. + * [Vivian De Smedt] Debugger enhancements, + so that when pdb is activated from within IPython, coloring, tab + completion and other features continue to work seamlessly. + * [Scott Tsai] Support for automatic + editor invocation on syntax errors (see + http://www.scipy.net/roundup/ipython/issue36). + * [Alexander Belchenko] Improvements for win32 + paging system. + * [Will Maier] Official OpenBSD port. +