docs/source/interactive/extension_api.txt

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