IPython a short introduction

Overview

The goal of this article is to write a short introduction to IPython. While IPython has two main components (an interactive Python Shell and an architecture for interactive parallel computing), this post will be about the Python shell. I will leave the parallel computing part for another time. In the future I’ll also write about “The IPython Notebook“, which is a web-based interactive environment where you can combine code execution, text, mathematics, plots and rich media into a single document. IPython is known to work on the following operating systems Linux Most other Unix-like OSs (AIX, Solaris, BSD, etc.) Mac OS X Windows (CygWin, XP, Vista, etc.)

What is IPython?

IPython is an interactive shell for the Python programming language that offers enhanced introspection, additional shell syntax, tab completion and rich history. source

Why IPython?

The default interactive Python shell can sometimes feel to basic. There is an alternative called “IPython” which you can install by typing apt-get install IPython (see the install section below) When its installed you can just start it by typing IPython in the terminal IPython gives you all that you get in the basic interpreter but with a lot extra (line numbers, advanced editing, more functions, help functions etc)

Install IPython?

As I wrote above, if you are on a Ubuntu system, you can install IPython by typing apt-get install IPython in your terminal. If you are on another system, please take a look here Let’s go ahead and see how an installation can look like on a system running Mac.

# To see if I've ipython installed, I simply type "ipython" in my terminal. 

$ ipython
-bash: ipython: command not found

So IPython is not installed on my system. Let’s install it

$ sudo easy_install ipython
Password:
Searching for ipython
Reading http://pypi.python.org/simple/ipython/
Reading http://ipython.scipy.org
Reading http://ipython.scipy.org/dist
Reading http://ipython.org
Reading https://github.com/ipython/ipython/downloads
Reading http://ipython.scipy.org/dist/0.8.4
Reading http://ipython.scipy.org/dist/0.9.1
Reading http://archive.ipython.org/release/0.12.1
Reading http://ipython.scipy.org/dist/old/0.9
Reading http://ipython.scipy.org/dist/0.10
Reading http://archive.ipython.org/release/0.11/
Reading http://archive.ipython.org/release/0.12
Best match: ipython 0.13.1
Downloading http://pypi.python.org/packages/2.7/i/ipython/ipython-0.13.1-py2.7.egg#md5..
Processing ipython-0.13.1-py2.7.egg
creating /Library/Python/2.7/site-packages/ipython-0.13.1-py2.7.egg
Extracting ipython-0.13.1-py2.7.egg to /Library/Python/2.7/site-packages
Adding ipython 0.13.1 to easy-install.pth file
Installing ipcontroller script to /usr/local/bin
Installing iptest script to /usr/local/bin
Installing ipcluster script to /usr/local/bin
Installing ipython script to /usr/local/bin
Installing pycolor script to /usr/local/bin
Installing iplogger script to /usr/local/bin
Installing irunner script to /usr/local/bin
Installing ipengine script to /usr/local/bin
Installed /Library/Python/2.7/site-packages/ipython-0.13.1-py2.7.egg
Processing dependencies for ipython
Finished processing dependencies for ipython

When I this time type IPython in my terminal, it starts, but I get an error message:

$ ipython
/Library/Python/2.7/site-packages/ipython-0.13.1-py2.7.egg/IPython/utils/rlineimpl.py:111: 
RuntimeWarning:
libedit detected - readline will not be well behaved, including but not limited to:
   * crashes on tab completion
   * incorrect history navigation
   * corrupting long-lines
   * failure to wrap or indent lines properly
It is highly recommended that you install readline, which is easy_installable:
     easy_install readline
Note that `pip install readline` generally DOES NOT WORK, because
it installs to site-packages, which come *after* lib-dynload in sys.path,
where readline is located.  It must be `easy_install readline`, or to a custom
location on your PYTHONPATH (even --user comes after lib-dyload).

To solve that, simply type easy_install readline (as it also state above)

$sudo easy_install readline

Searching for readline
Reading http://pypi.python.org/simple/readline/
Reading http://github.com/ludwigschwardt/python-readline
Reading http://www.python.org/
Best match: readline 6.2.4.1
Downloading http://pypi.python.org/packages/2.7/r/readline/readline-6.2.4.1-py2.7-macosx..
Processing readline-6.2.4.1-py2.7-macosx-10.7-intel.egg
creating /Library/Python/2.7/site-packages/readline-6.2.4.1-py2.7-macosx-10.7-intel.egg
Extracting readline-6.2.4.1-py2.7-macosx-10.7-intel.egg to /Library/Python/2.7/site-packages
Adding readline 6.2.4.1 to easy-install.pth file

Installed /Library/Python/2.7/site-packages/readline-6.2.4.1-py2.7-macosx-10.7-intel.egg
Processing dependencies for readline
Finished processing dependencies for readline

With readline installed, everything should be fine.

$ ipython
Python 2.7.2 (default, Jun 20 2012, 16:23:33)
Type "copyright", "credits" or "license" for more information.

IPython 0.13.1 -- An enhanced Interactive Python.
?         -> Introduction and overview of IPython's features.
%quickref -> Quick reference.
help      -> Python's own help system.
object?   -> Details about 'object', use 'object??' for extra details.

In [1]:

IPython is now installed on your system.

Start IPython

You start IPython by typing “ipython” in your terminal.

$ ipython
Python 2.7.2 (default, Jun 20 2012, 16:23:33) 
Type "copyright", "credits" or "license" for more information.

IPython 0.13.1 -- An enhanced Interactive Python.
?         -> Introduction and overview of IPython's features.
%quickref -> Quick reference.
help      -> Python's own help system.
object?   -> Details about 'object', use 'object??' for extra details.

Run Python code from a file

The basic workflow in IPython is that you use the text editor to edit your code. You save the file and load it into IPython. If you want to test the code interactive, use the %run -i, otherwise, you can just use %run. If something goes wrong, just go back to the text editor, fix the error, save and exit. Then go back to IPython and run the file again. To run python code that you have saved to a file (example hello.py), you use the command %run (in our case %run hello.py). IPython will look for that file in the current folder. You can list the content of the files in your current folder with the ls command The code in hello.py will run, but the functions in it will not be available for interactive calls. If you want to test the code interactive, you will have to add the -i switch when you use %run. The command for running it interactive is %run -i hello.py

Tab completion

Tab completion, especially for attributes, is a convenient way to explore the structure of any object you’re dealing with. source To use completion, type a pattern you would like the shell to match, followed by the Tab key. Simply type object_name. to view the object’s attributes Besides Python objects and keywords, tab completion also works on file and directory names.

In [1]: from sys import std
stderr  stdin   stdout

In [1]: from urllib2 import url
url2pathname  urlopen       urlparse

Macros

IPython macros are great for executing the same code over and over. Macros allow a user to associate a name with a section of Python code so the code can be run later by referring to the name. They are editable via the ‘%edit’ magic command

Using the Python debugger (pdb)

The Python debugger (pdb) is a powerful interactive debugger which allows you to step through code, set breakpoints, watch variables, etc. With automatic pdb calling enabled, the Python debugger will start automatically when Python encounters an unhandled exception. The current line in the debugger will be the line of code on which the exception occurred. If you start IPython with the –pdb option then you can call the Python pdb debugger every time your code triggers an uncaught exception. This feature can also be toggled at any time with the %pdb magic command. source

Profiles

A profile is a directory containing configuration and runtime files, such as logs, connection info for the parallel apps, and your IPython command history. Profiles make it easy to keep a separate configuration files, logs, and histories for specific projects. Profiles can easily be created by the following command. $ ipython profile create profile_name This adds a directory called profile_name to your IPython directory. Then you can load this profile by adding –profile= to your command line options. Profiles are supported by all IPython applications. This command should create and print the path where the profile is setup at. To use the profile just specify the profile as an argument for ipython. $ ipython –profile=profile_name IPython ships with some sample profiles in IPython/config/profile.

Startup Files

In the profile_/startup directory you can put any python (.py) or IPython (.ipy) files that you want to run as soon as IPython start. The only thing that is currently in my profile_default/startup directory is a README file. The contents of that file, should look something similar to this ” This is the IPython startup directory .py and .ipy files in this directory will be run *prior* to any code or files specified via the exec_lines or exec_files configurables whenever you load this profile. Files will be run in lexicographical order, so you can control the execution order of files with a prefix, e.g.:: 00-first.py 50-middle.py 99-last.ipy ” OK. Great, let’s try this out. Create a new file in your editor:

$ vim calc.py

# This is a small python script calculating numbers

a = 1 + 1

b = 2 * 2

c = 10 / 2

d = 10 - 5

print a,b,c,d

Exit the editor and start IPython

$ ipython 
Python 2.7.2 (default, Jun 20 2012, 16:23:33) 
Type "copyright", "credits" or "license" for more information.

IPython 0.13.1 -- An enhanced Interactive Python.
?         -> Introduction and overview of IPython's features.
%quickref -> Quick reference.
help      -> Python's own help system.
object?   -> Details about 'object', use 'object??' for extra details.
3

>>> 2 4 5 5

In [1]: %run calc.py
2 4 5 5

Everything in the startup files can then be used without retyping them each time you re-enter IPython.

Commands in IPython

IPython “magic” commands are conventionally prefaced by %, but if the flag %automagic is set to on (which is default), then one can call magic commands without the preceding %. IPython checks if the command that you typed against its list of magic keywords. If the command is a magic keyword, IPython knows what to do with it. If it’s not a magic keyword, it lets Python figure out to do with it.

lsmagic

list all built in commands, called magic commands. These are prefixed with % to differentiate between variables if they have the same name.

#In [57]: lsmagic

Available line magics:
%alias  %alias_magic  %autocall  %autoindent  %automagic  %bookmark  %cd  %colors  %config
%cpaste  %debug  %dhist  %dirs  %doctest_mode  %ed  %edit  %env  %gui  %hist  %history
%install_default_config  %install_ext  %install_profiles  %killbgscripts  %load  %load_ext
%loadpy  %logoff  %logon  %logstart  %logstate  %logstop  %lsmagic  %macro  %magic
%notebook  %page  %paste  %pastebin  %pdb  %pdef  %pdoc  %pfile  %pinfo  %pinfo2  %popd
%pprint  %precision %profile  %prun  %psearch  %psource  %pushd  %pwd  %pycat  %pylab
%quickref  %recall  %rehashx %reload_ext  %rep  %rerun  %reset  %reset_selective  %run
%save  %sc  %store  %sx  %system  %tb %time  %timeit  %unalias  %unload_ext  %who  %who_ls 
%whos  %xdel  %xmode

Available cell magics:
%%!  %%bash  %%capture  %%file  %%perl  %%prun  %%ruby  %%script  %%sh  %%sx  %%system
%%timeit

Automagic is ON, % prefix IS NOT needed for line magics.

Help Commands

%quickref shows wich “magic” commands that are availble in IPython. If you type %quickref inside IPython, you will see the Quick Reference Card, containing a lot of useful help. IPython — An enhanced Interactive Python – Quick Reference Card ================================================================ The “?” is very useful. If you type in ? after a len?, you will see the documentation about the function len. Typing ? after a name will give you information about the object attached to that name,

>>>len?

Type:       builtin_function_or_method
String Form:
Namespace:  Python builtin
Docstring:
len(object) -> integer

Return the number of items of a sequence or mapping.

>>>str?

Type:       type
String Form:<type 'str'="">
Namespace:  Python builtin
Docstring:
str(object) -> string

Return a nice string representation of the object.

If the argument is a string, the return value is the same object.

More Commands

%reset resets the interactive environment %hist allows you to see any part of your input history %hist -g somestring Search (‘grep’) through your history by typing In [55]: hist -g math 19: import math 55: hist -g math %paste use text that you have in the clipboard, for example if you have copied code with Ctrl+C. The command cleans up certain characters and tries to find out how the code should be formatted. %edit The %edit command (and its alias %ed) will invoke the editor set in your environment as EDITOR. %who This function list objects, functions, etc. that have been added in the current namespace, as well as modules that have been imported. In [50]: who Interactive namespace is empty.

In [51]: import sys

In [52]: import os

In [53]: who
os  sys 

System shell access

Any input line beginning with a ! character is passed verbatim (minus the !) to the underlying operating system. For example, typing !ls will run ‘ls’ in the current directory. To run any command at the system shell:

In [2]: !ping www.google.com

PING www.google.com (173.194.67.104): 56 data bytes
64 bytes from 173.194.67.104: icmp_seq=0 ttl=49 time=6.096 ms
64 bytes from 173.194.67.104: icmp_seq=1 ttl=49 time=5.963 ms
^C

You can capture the output into a Python list, e.g.: files = !ls.

Aliases

IPython comes with some pre-defined 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. In [1]: %alias Total number of aliases: 16 Out[1]: (‘lk’, ‘ls -F -l %l | grep ^l’), (‘ll’, ‘ls -F -l’), (‘ls’, ‘ls -F’), … A more comprehensive documentation can be found here: http://ipython.org/ipython-doc/stable/interactive/tutorial.html http://wiki.ipython.org/index.php?title=Cookbook