Feb. 26, 2013

IPython a short introduction


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

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
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
$ ipython
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
Downloading http://pypi.python.org/packages/2.7/r/readline/readline-
Processing readline-
creating /Library/Python/2.7/site-packages/readline-
Extracting readline- to /Library/Python/2.7/site-packages
Adding readline to easy-install.pth file

Installed /Library/Python/2.7/site-packages/readline-
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


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

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.


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

Files will be run in lexicographical order, so you can control the execution
order of files with a prefix, e.g.::

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.

>>> 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.
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

Automagic is ON, % prefix IS NOT needed for line magics.
Help Commands
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,

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

Return the number of items of a sequence or mapping.


Type:       type
String Form:
Namespace:  Python builtin
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
resets the interactive environment

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

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. 

The %edit command (and its alias %ed) will invoke the editor set in your
environment as EDITOR. source

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 ( 56 data bytes
64 bytes from icmp_seq=0 ttl=49 time=6.096 ms
64 bytes from icmp_seq=1 ttl=49 time=5.963 ms
You can capture the output into a Python list, e.g.: files = !ls. 


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
 ('lk', 'ls -F -l %l | grep ^l'),
 ('ll', 'ls -F -l'),
 ('ls', 'ls -F'),
A more comprhensive documentation can be found here:

Share this article

Recommended Python Training – DataCamp

For Python training, our top recommendation is DataCamp.

Datacamp provides online interactive courses that combine interactive coding challenges with videos from top instructors in the field.

Datacamp has beginner to advanced Python training that programmers of all levels benefit from.


Download Our Free Guide To Learning Python

* indicates required

Read more about:
Disclosure of Material Connection: Some of the links in the post above are “affiliate links.” This means if you click on the link and purchase the item, I will receive an affiliate commission. Regardless, PythonForBeginners.com only recommend products or services that we try personally and believe will add value to our readers.