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