IPython Extension Api

IPython api (defined in IPython/ipapi.py) is the public api that should be used for

Configuration of user preferences (.ipython/ipy_user_conf.py)
Creating new profiles (.ipython/ipy_profile_PROFILENAME.py)
Writing extensions

This page will contain official, stable api documentation, for now it's a work in progress.

For an example extension (the 'sh' profile), see ipy_profile_sh.py

For the last word on how things work, see the source of ipapi.py

Getting started

If you want to define an extension, create a normal python module that can be imported. The module will access IPython functionality through the 'ip' object defined below.

If you are creating a new profile (e.g. foobar), name the module as 'ipy_profile_foobar.py' and put it in your ~/.ipython directory. Then, when you start ipython with the '-p foobar' argument, the module is automatically imported on ipython startup.

If you are just doing some per-user configuration, you can either

Put the commands directly into ipy_user_conf.py.
Create a new module with your customization code and import that module in ipy_user_conf.py. This is preferable to the first approach, because now you can reuse and distribute your customization code.

Getting a handle to the api

Put this in the start of your module:

   1 import IPython.ipapi
   2 ip = IPython.ipapi.get()

The 'ip' object will then be used for accessing IPython functionality. 'ip' will mean this api object in all the following code snippets. The same 'ip' that we just acquired is always accessible in interactive IPython sessions by the name _ip - play with it like this:

[~\_ipython]|81> a = 10
[~\_ipython]|82> _ip.e
_ip.ev           _ip.ex           _ip.expose_magic
[~\_ipython]|82> _ip.ev('a+13')
            <82> 23

The _ip object is also used in some examples in this document - it can be substituted by 'ip' in non-interactive use.

Changing options

The ip object has 'options' attribute that can be used te get/set configuration options (just as in the ipythonrc file).

   1 o = ip.options
   2 o.autocall = 2
   3 o.automagic = 1

Executing statements in IPython namespace with 'ex' and 'ev'

Often, you want to e.g. import some module or define something that should be visible in IPython namespace. Use ip.ev to evaluate (calculate the value of) expression and ip.ex to execute a statement.

   1 # path module will be visible to the interactive session
   2 ip.ex("from path import path" )
   3 
   4 # define a handy function 'up' that changes the working directory
   5 
   6 ip.ex('import os')
   7 ip.ex("def up(): os.chdir('..')")
   8 
   9 
  10 # _i2 has the input history entry #2, print its value in uppercase.
  11 print ip.ev('_i2.upper()')

Accessing the IPython namespace

ip.user_ns attribute has a dictionary containing the IPython global namespace (the namespace visible in the interactive session).

[~\_ipython]|84> tauno = 555
[~\_ipython]|85> _ip.user_ns['tauno']
            <85> 555

Defining new magic commands

The following example defines a new magic command, %impall. What the command does should be obvious.

   1 def doimp(self, arg):
   2     ip = self.api
   3     ip.ex("import %s; reload(%s); from %s import *" % (
   4     arg,arg,arg)
   5     )
   6 
   7 ip.expose_magic('impall', doimp)

Things to observe in this example:

Define a function that implements the magic command using the ipapi methods defined in this document
The first argument of the function is 'self', i.e. the interpreter object. It shouldn't be used directly. however. The interpreter object is probably not going to remain stable through IPython versions.
Access the ipapi through 'self.api' instead of the global 'ip' object.
All the text following the magic command on the command line is contained in the second argument
Expose the magic by ip.expose_magic()

Calling magic functions and system commands

Use ip.magic() to execute a magic function, and ip.system() to execute a system command.

   1 # go to a bookmark
   2 ip.magic('%cd -b relfiles')
   3 
   4 # execute 'ls -F' system command. Interchangeable with os.system('ls'), really.
   5 ip.system('ls -F')

Launching IPython instance from normal python code

Use ipapi.launch_new_instance() with an argument that specifies the namespace to use. This can be useful for trivially embedding IPython into your program. Here's an example of normal python program test.py (without an existing IPython session) that launches an IPython interpreter and regains control when the interpreter is exited:

   1 [ipython]|1> cat test.py
   2 my_ns = dict(
   3     kissa = 15,
   4     koira = 16)
   5 import IPython.ipapi
   6 print "launching IPython instance"
   7 IPython.ipapi.launch_new_instance(my_ns)
   8 print "Exited IPython instance!"
   9 print "New vals:",my_ns['kissa'], my_ns['koira']

And here's what it looks like when run (note how we don't start it from an ipython session):

Q:\ipython>python test.py
launching IPython instance
Py 2.5 (r25:51908, Sep 19 2006, 09:52:17) [MSC v.1310 32 bit (Intel)] IPy 0.7.3b3.r1975
[ipython]|1> kissa = 444
[ipython]|2> koira = 555
[ipython]|3> Exit
Exited IPython instance!
New vals: 444 555

Accessing unexposed functionality

There are still many features that are not exposed via the ipapi. If you can't avoid using them, you can use the functionality in InteractiveShell object (central IPython session class, defined in iplib.py) through ip.IP.

For example:

[~]|7> _ip.IP.expand_aliases('np','myfile.py')
   <7> 'c:/opt/Notepad++/notepad++.exe myfile.py'
[~]|8>

Still, it's preferable that if you encounter such a feature, contact the IPython team and request that the functionality be exposed in a future version of IPython. Things not in ipapi are more likely to change over time.

Wiki

Page