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.
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.
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.
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
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()')
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
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()
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')
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
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.
[~]|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.
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