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
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)
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 220.127.116.11 Downloading http://pypi.python.org/packages/2.7/r/readline/readline-18.104.22.168-py2.7-macosx.. Processing readline-22.214.171.124-py2.7-macosx-10.7-intel.egg creating /Library/Python/2.7/site-packages/readline-126.96.36.199-py2.7-macosx-10.7-intel.egg Extracting readline-188.8.131.52-py2.7-macosx-10.7-intel.egg to /Library/Python/2.7/site-packages Adding readline 184.108.40.206 to easy-install.pth file Installed /Library/Python/2.7/site-packages/readline-220.127.116.11-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 :
IPython is now installed on your system.
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, 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 : from sys import std stderr stdin stdout In : 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 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
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.
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 : %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 : 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.
%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: 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.
%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 : 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. source %who This function list objects, functions, etc. that have been added in the current namespace, as well as modules that have been imported. In : who Interactive namespace is empty.
In : import sys In : import os In : 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 : !ping www.google.com PING www.google.com (18.104.22.168): 56 data bytes 64 bytes from 22.214.171.124: icmp_seq=0 ttl=49 time=6.096 ms 64 bytes from 126.96.36.199: icmp_seq=1 ttl=49 time=5.963 ms ^C
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 : %alias Total number of aliases: 16 Out: ('lk', 'ls -F -l %l | grep ^l'), ('ll', 'ls -F -l'), ('ls', 'ls -F'), ...
A more comprhensive documentation can be found here: http://ipython.org/ipython-doc/stable/interactive/tutorial.html http://wiki.ipython.org/index.php?title=Cookbook
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.
Read more about: