September 12, 2005

Introducing IPython

Author: Conrad Koziol

Python, an interpretive programming language that combines elegant code with a powerful object-oriented approach and many modules, has been around since the early 1990s. To make Python more productive, Fernando Perez in 2001 began working on IPython, an enhanced interactive Python shell with improvements such as history caching, profiles, object information, and session logging, as a replacement for the default interpreter.

IPython is an evolutionary step for interactive Python. Some features are small timesavers and ease-of-use techniques, like automatic parenthesizing and tab completion. Others add capabilities beyond the default interpreter, such as profiles and editor use from within.

For instance, one nuisance of the standard Python interpreter is that in order to enjoy tab completion, you must import a few modules. IPython offers tab completion by default. To use it, begin typing in the interpreter, and then press Tab. If you've typed enough letters to uniquely identify a match, then the command will be completed; if not, the shell will show a list of possible matches. You can use Ctrl-N and Ctrl-P to cycle through them.


If you type lsmagic at the IPython interpreter, you'll see something like this:

In [1]: lsmagic
Available magic functions:
%Exit %Pprint %Quit %alias %autocall %autoindent %automagic %bg %bookmark %cd %color_info %colors %config
%dhist %dirs %ed %edit %env %hist %history %logoff %logon %logstart %logstate %lsmagic %macro %magic %p
%page %pdb %pdef %pdoc %pfile %pinfo %popd %profile %prun %prun %psource %pushd %pwd %r %rehash %rehashx

%reset %run %runlog %save %sc %sx %system_verbose %time %unalias %who %who_ls %whos %xmode

Automagic is ON, % prefix NOT needed for magic functions.

These "magic" keywords are specific to IPython. IPython automatically identifies them once you enter them. If automagic is off (which is not the default), you will need to prepend them with %.


To find out which commands you've run in the past, enter the keyword hist. The output will look like this:

1: ipmagic("lsmagic ")
2: x = 1 + 2
3: y = 2**3
4: print x, y
5: x = 5
6: 4 + 4

To remove the numbers, add the -n option. This makes copying and pasting multiple lines possible.

The program includes a number of features that make it easier to execute previous commands. Past commands are stored as strings in the In[] list. Since they are strings, you can modify them, or run them with exec. The latest three are stored in the variables _i, _ii, _iii. Here we concatenate two previous commands and execute the result:

In[8]: exec In[4:5] + In[3]
5 8

To access a single line in your history, you can use _i notation:

In[9]: _i3
'y = 2**3\n'

Not only is the prompt input cached, but so is the output. Similar to the way _i, _ii, and _iii access the last three inputs, _, __, and ___ access the last three outputs. The output of line x is stored in _x, which is created from the list of outputs, Out.

In[10]: 2**3 + 3
Out[10]: 11

In[11]: _
Out[11]: 11

In[12]: Out[11]
Out[12]: 11


Entering complex code or nested structures into the interpreter is difficult with only single-line editing. The edit keyword is an attempt to implement multiline editing. It opens the editor defined by the environment variable $EDITOR. Saving and exiting the editor causes the code written inside it to run.

Session logging and restoring

You can log your IPython session by using the command-line option -log, which creates the file ipython.log in the current directory. Or you can type -logfile and specify your own filename. Later when you want to resume the session, enter IPython -logplay [file]. The logoff and logon keywords allow you to temporarily stop and start logging.

IPython can automatically add parentheses to functions and methods:

In [13]: pow 2, 3
------- pow(2,3)
Out[13]: 8

Notice that it needs the commas between the arguments.

This is just a brief rundown on some of the niftier features of IPython. The IPython Web site has a tips section that contains a comprehensive list of the most used commands. You can also check out the hefty 68-page manual or the extensive documentation accessible within the interpreter itself. For instance, magic displays a reference list of magic keywords and their meaning.

While this article discusses IPython as a replacement for the default interpreter, its functionality extends beyond that. IPython can be embedded in other programs and offers flexible framework which can be used as the base environment for other systems.


  • Python