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

Note that by using the extension api for configuration (editing ipy_user_conf.py instead of ipythonrc), you get better validity checks and get richer functionality - for example, you can import an extension and call functions in it to configure it for your purposes.

For an example extension (the ‘sh’ profile), see IPython/Extensions/ipy_profile_sh.py.

For the last word on what’s available, see the source code of IPython/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:

#!python
import IPython.ipapi
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):

o = ip.options
o.autocall = 2
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:

# path module will be visible to the interactive session
ip.ex("from path import path" )

# define a handy function 'up' that changes the working directory

ip.ex('import os')
ip.ex("def up(): os.chdir('..')")


# _i2 has the input history entry #2, print its value in uppercase.
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:

def doimp(self, arg):
    ip = self.api
    ip.ex("import %s; reload(%s); from %s import *" % (
    arg,arg,arg)
    )

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:

# go to a bookmark
ip.magic('%cd -b relfiles')

# execute 'ls -F' system command. Interchangeable with os.system('ls'), really.
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:

[ipython]|1> cat test.py
my_ns = dict(
    kissa = 15,
    koira = 16)
import IPython.ipapi
print "launching IPython instance"
IPython.ipapi.launch_new_instance(my_ns)
print "Exited IPython instance!"
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.

Provided extensions

You can see the list of available extensions (and profiles) by doing import ipy_<TAB>. Some extensions don’t have the ipy_ prefix in module name, so you may need to see the contents of IPython/Extensions folder to see what’s available.

You can see a brief documentation of an extension by looking at the module docstring:

[c:p/ipython_main]|190> import ipy_fsops
[c:p/ipython_main]|191> ipy_fsops?

...

Docstring:
    File system operations

Contains: Simple variants of normal unix shell commands (icp, imv, irm,
imkdir, igrep).

You can also install your own extensions - the recommended way is to just copy the module to ~/.ipython. Extensions are typically enabled by just importing them (e.g. in ipy_user_conf.py), but some extensions require additional steps, for example:

[c:p]|192> import ipy_traits_completer
[c:p]|193> ipy_traits_completer.activate()

Note that extensions, even if provided in the stock IPython installation, are not guaranteed to have the same requirements as the rest of IPython - an extension may require external libraries or a newer version of Python than what IPython officially requires. An extension may also be under a more restrictive license than IPython (e.g. ipy_bzr is under GPL).

Just for reference, the list of bundled extensions at the time of writing is below:

astyle.py clearcmd.py envpersist.py ext_rescapture.py ibrowse.py igrid.py InterpreterExec.py InterpreterPasteInput.py ipipe.py ipy_app_completers.py ipy_autoreload.py ipy_bzr.py ipy_completers.py ipy_constants.py ipy_defaults.py ipy_editors.py ipy_exportdb.py ipy_extutil.py ipy_fsops.py ipy_gnuglobal.py ipy_kitcfg.py ipy_legacy.py ipy_leo.py ipy_p4.py ipy_profile_doctest.py ipy_profile_none.py ipy_profile_scipy.py ipy_profile_sh.py ipy_profile_zope.py ipy_pydb.py ipy_rehashdir.py ipy_render.py ipy_server.py ipy_signals.py ipy_stock_completers.py ipy_system_conf.py ipy_traits_completer.py ipy_vimserver.py ipy_which.py ipy_workdir.py jobctrl.py ledit.py numeric_formats.py PhysicalQInput.py PhysicalQInteractive.py pickleshare.py pspersistence.py win32clip.py __init__.py