<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<title>IPython extension API — IPython 0.10.2 documentation</title>
<link rel="stylesheet" href="../_static/default.css" type="text/css" />
<link rel="stylesheet" href="../_static/pygments.css" type="text/css" />
<script type="text/javascript">
var DOCUMENTATION_OPTIONS = {
URL_ROOT: '../',
VERSION: '0.10.2',
COLLAPSE_INDEX: false,
FILE_SUFFIX: '.html',
HAS_SOURCE: true
};
</script>
<script type="text/javascript" src="../_static/jquery.js"></script>
<script type="text/javascript" src="../_static/underscore.js"></script>
<script type="text/javascript" src="../_static/doctools.js"></script>
<link rel="top" title="IPython 0.10.2 documentation" href="../index.html" />
<link rel="up" title="Using IPython for interactive work" href="index.html" />
<link rel="next" title="Using IPython for parallel computing" href="../parallel/index.html" />
<link rel="prev" title="IPython as a system shell" href="shell.html" />
</head>
<body>
<div class="related">
<h3>Navigation</h3>
<ul>
<li class="right" style="margin-right: 10px">
<a href="../genindex.html" title="General Index"
accesskey="I">index</a></li>
<li class="right" >
<a href="../py-modindex.html" title="Python Module Index"
>modules</a> |</li>
<li class="right" >
<a href="../parallel/index.html" title="Using IPython for parallel computing"
accesskey="N">next</a> |</li>
<li class="right" >
<a href="shell.html" title="IPython as a system shell"
accesskey="P">previous</a> |</li>
<li><a href="../index.html">IPython 0.10.2 documentation</a> »</li>
<li><a href="index.html" accesskey="U">Using IPython for interactive work</a> »</li>
</ul>
</div>
<div class="document">
<div class="documentwrapper">
<div class="bodywrapper">
<div class="body">
<div class="section" id="ipython-extension-api">
<h1>IPython extension API<a class="headerlink" href="#ipython-extension-api" title="Permalink to this headline">¶</a></h1>
<p>IPython api (defined in IPython/ipapi.py) is the public api that
should be used for</p>
<blockquote>
<div><ul class="simple">
<li>Configuration of user preferences (.ipython/ipy_user_conf.py)</li>
<li>Creating new profiles (.ipython/ipy_profile_PROFILENAME.py)</li>
<li>Writing extensions</li>
</ul>
</div></blockquote>
<p>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.</p>
<p>For an example extension (the ‘sh’ profile), see
IPython/Extensions/ipy_profile_sh.py.</p>
<p>For the last word on what’s available, see the source code of
IPython/ipapi.py.</p>
<div class="section" id="getting-started">
<h2>Getting started<a class="headerlink" href="#getting-started" title="Permalink to this headline">¶</a></h2>
<p>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.</p>
<p>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.</p>
<p>If you are just doing some per-user configuration, you can either</p>
<blockquote>
<div><ul class="simple">
<li>Put the commands directly into ipy_user_conf.py.</li>
<li>Create a new module with your customization code and import <em>that</em>
module in ipy_user_conf.py. This is preferable to the first approach,
because now you can reuse and distribute your customization code.</li>
</ul>
</div></blockquote>
</div>
<div class="section" id="getting-a-handle-to-the-api">
<h2>Getting a handle to the api<a class="headerlink" href="#getting-a-handle-to-the-api" title="Permalink to this headline">¶</a></h2>
<p>Put this in the start of your module:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="c">#!python</span>
<span class="kn">import</span> <span class="nn">IPython.ipapi</span>
<span class="n">ip</span> <span class="o">=</span> <span class="n">IPython</span><span class="o">.</span><span class="n">ipapi</span><span class="o">.</span><span class="n">get</span><span class="p">()</span>
</pre></div>
</div>
<p>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:</p>
<div class="highlight-python"><pre>[~\_ipython]|81> a = 10
[~\_ipython]|82> _ip.e
_ip.ev _ip.ex _ip.expose_magic
[~\_ipython]|82> _ip.ev('a+13')
<82> 23</pre>
</div>
<p>The _ip object is also used in some examples in this document - it can
be substituted by ‘ip’ in non-interactive use.</p>
</div>
<div class="section" id="changing-options">
<h2>Changing options<a class="headerlink" href="#changing-options" title="Permalink to this headline">¶</a></h2>
<p>The ip object has ‘options’ attribute that can be used te get/set
configuration options (just as in the ipythonrc file):</p>
<div class="highlight-python"><div class="highlight"><pre><span class="n">o</span> <span class="o">=</span> <span class="n">ip</span><span class="o">.</span><span class="n">options</span>
<span class="n">o</span><span class="o">.</span><span class="n">autocall</span> <span class="o">=</span> <span class="mi">2</span>
<span class="n">o</span><span class="o">.</span><span class="n">automagic</span> <span class="o">=</span> <span class="mi">1</span>
</pre></div>
</div>
</div>
<div class="section" id="executing-statements-in-ipython-namespace-with-ex-and-ev">
<h2>Executing statements in IPython namespace with ‘ex’ and ‘ev’<a class="headerlink" href="#executing-statements-in-ipython-namespace-with-ex-and-ev" title="Permalink to this headline">¶</a></h2>
<p>Often, you want to e.g. import some module or define something that
should be visible in IPython namespace. Use <tt class="docutils literal"><span class="pre">ip.ev</span></tt> to
<em>evaluate</em> (calculate the value of) expression and <tt class="docutils literal"><span class="pre">ip.ex</span></tt> to
‘’‘execute’‘’ a statement:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="c"># path module will be visible to the interactive session</span>
<span class="n">ip</span><span class="o">.</span><span class="n">ex</span><span class="p">(</span><span class="s">"from path import path"</span> <span class="p">)</span>
<span class="c"># define a handy function 'up' that changes the working directory</span>
<span class="n">ip</span><span class="o">.</span><span class="n">ex</span><span class="p">(</span><span class="s">'import os'</span><span class="p">)</span>
<span class="n">ip</span><span class="o">.</span><span class="n">ex</span><span class="p">(</span><span class="s">"def up(): os.chdir('..')"</span><span class="p">)</span>
<span class="c"># _i2 has the input history entry #2, print its value in uppercase.</span>
<span class="k">print</span> <span class="n">ip</span><span class="o">.</span><span class="n">ev</span><span class="p">(</span><span class="s">'_i2.upper()'</span><span class="p">)</span>
</pre></div>
</div>
</div>
<div class="section" id="accessing-the-ipython-namespace">
<h2>Accessing the IPython namespace<a class="headerlink" href="#accessing-the-ipython-namespace" title="Permalink to this headline">¶</a></h2>
<p>ip.user_ns attribute has a dictionary containing the IPython global
namespace (the namespace visible in the interactive session).</p>
<div class="highlight-python"><pre>[~\_ipython]|84> tauno = 555
[~\_ipython]|85> _ip.user_ns['tauno']
<85> 555</pre>
</div>
</div>
<div class="section" id="defining-new-magic-commands">
<h2>Defining new magic commands<a class="headerlink" href="#defining-new-magic-commands" title="Permalink to this headline">¶</a></h2>
<p>The following example defines a new magic command, %impall. What the
command does should be obvious:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="k">def</span> <span class="nf">doimp</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">arg</span><span class="p">):</span>
<span class="n">ip</span> <span class="o">=</span> <span class="bp">self</span><span class="o">.</span><span class="n">api</span>
<span class="n">ip</span><span class="o">.</span><span class="n">ex</span><span class="p">(</span><span class="s">"import </span><span class="si">%s</span><span class="s">; reload(</span><span class="si">%s</span><span class="s">); from </span><span class="si">%s</span><span class="s"> import *"</span> <span class="o">%</span> <span class="p">(</span>
<span class="n">arg</span><span class="p">,</span><span class="n">arg</span><span class="p">,</span><span class="n">arg</span><span class="p">)</span>
<span class="p">)</span>
<span class="n">ip</span><span class="o">.</span><span class="n">expose_magic</span><span class="p">(</span><span class="s">'impall'</span><span class="p">,</span> <span class="n">doimp</span><span class="p">)</span>
</pre></div>
</div>
<p>Things to observe in this example:</p>
<blockquote>
<div><ul class="simple">
<li>Define a function that implements the magic command using the
ipapi methods defined in this document</li>
<li>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 <em>not</em> going to remain stable
through IPython versions.</li>
<li>Access the ipapi through ‘self.api’ instead of the global ‘ip’ object.</li>
<li>All the text following the magic command on the command line is
contained in the second argument</li>
<li>Expose the magic by ip.expose_magic()</li>
</ul>
</div></blockquote>
</div>
<div class="section" id="calling-magic-functions-and-system-commands">
<h2>Calling magic functions and system commands<a class="headerlink" href="#calling-magic-functions-and-system-commands" title="Permalink to this headline">¶</a></h2>
<p>Use ip.magic() to execute a magic function, and ip.system() to execute
a system command:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="c"># go to a bookmark</span>
<span class="n">ip</span><span class="o">.</span><span class="n">magic</span><span class="p">(</span><span class="s">'</span><span class="si">%c</span><span class="s">d -b relfiles'</span><span class="p">)</span>
<span class="c"># execute 'ls -F' system command. Interchangeable with os.system('ls'), really.</span>
<span class="n">ip</span><span class="o">.</span><span class="n">system</span><span class="p">(</span><span class="s">'ls -F'</span><span class="p">)</span>
</pre></div>
</div>
</div>
<div class="section" id="launching-ipython-instance-from-normal-python-code">
<h2>Launching IPython instance from normal python code<a class="headerlink" href="#launching-ipython-instance-from-normal-python-code" title="Permalink to this headline">¶</a></h2>
<p>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:</p>
<div class="highlight-python"><pre>[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']</pre>
</div>
<p>And here’s what it looks like when run (note how we don’t start it
from an ipython session):</p>
<div class="highlight-python"><pre>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</pre>
</div>
</div>
<div class="section" id="accessing-unexposed-functionality">
<h2>Accessing unexposed functionality<a class="headerlink" href="#accessing-unexposed-functionality" title="Permalink to this headline">¶</a></h2>
<p>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.</p>
<p>For example:</p>
<div class="highlight-python"><pre>[~]|7> _ip.IP.expand_aliases('np','myfile.py')
<7> 'c:/opt/Notepad++/notepad++.exe myfile.py'
[~]|8></pre>
</div>
<p>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.</p>
</div>
<div class="section" id="provided-extensions">
<h2>Provided extensions<a class="headerlink" href="#provided-extensions" title="Permalink to this headline">¶</a></h2>
<p>You can see the list of available extensions (and profiles) by doing
<tt class="docutils literal"><span class="pre">import</span> <span class="pre">ipy_<TAB></span></tt>. Some extensions don’t have the <tt class="docutils literal"><span class="pre">ipy_</span></tt> prefix in
module name, so you may need to see the contents of IPython/Extensions
folder to see what’s available.</p>
<p>You can see a brief documentation of an extension by looking at the
module docstring:</p>
<div class="highlight-python"><pre>[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).</pre>
</div>
<p>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:</p>
<div class="highlight-python"><pre>[c:p]|192> import ipy_traits_completer
[c:p]|193> ipy_traits_completer.activate()</pre>
</div>
<p>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).</p>
<p>Just for reference, the list of bundled extensions at the time of
writing is below:</p>
<p>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</p>
</div>
</div>
</div>
</div>
</div>
<div class="sphinxsidebar">
<div class="sphinxsidebarwrapper">
<h3><a href="../index.html">Table Of Contents</a></h3>
<ul>
<li><a class="reference internal" href="#">IPython extension API</a><ul>
<li><a class="reference internal" href="#getting-started">Getting started</a></li>
<li><a class="reference internal" href="#getting-a-handle-to-the-api">Getting a handle to the api</a></li>
<li><a class="reference internal" href="#changing-options">Changing options</a></li>
<li><a class="reference internal" href="#executing-statements-in-ipython-namespace-with-ex-and-ev">Executing statements in IPython namespace with ‘ex’ and ‘ev’</a></li>
<li><a class="reference internal" href="#accessing-the-ipython-namespace">Accessing the IPython namespace</a></li>
<li><a class="reference internal" href="#defining-new-magic-commands">Defining new magic commands</a></li>
<li><a class="reference internal" href="#calling-magic-functions-and-system-commands">Calling magic functions and system commands</a></li>
<li><a class="reference internal" href="#launching-ipython-instance-from-normal-python-code">Launching IPython instance from normal python code</a></li>
<li><a class="reference internal" href="#accessing-unexposed-functionality">Accessing unexposed functionality</a></li>
<li><a class="reference internal" href="#provided-extensions">Provided extensions</a></li>
</ul>
</li>
</ul>
<h4>Previous topic</h4>
<p class="topless"><a href="shell.html"
title="previous chapter">IPython as a system shell</a></p>
<h4>Next topic</h4>
<p class="topless"><a href="../parallel/index.html"
title="next chapter">Using IPython for parallel computing</a></p>
<h3>This Page</h3>
<ul class="this-page-menu">
<li><a href="../_sources/interactive/extension_api.txt"
rel="nofollow">Show Source</a></li>
</ul>
<div id="searchbox" style="display: none">
<h3>Quick search</h3>
<form class="search" action="../search.html" method="get">
<input type="text" name="q" size="18" />
<input type="submit" value="Go" />
<input type="hidden" name="check_keywords" value="yes" />
<input type="hidden" name="area" value="default" />
</form>
<p class="searchtip" style="font-size: 90%">
Enter search terms or a module, class or function name.
</p>
</div>
<script type="text/javascript">$('#searchbox').show(0);</script>
</div>
</div>
<div class="clearer"></div>
</div>
<div class="related">
<h3>Navigation</h3>
<ul>
<li class="right" style="margin-right: 10px">
<a href="../genindex.html" title="General Index"
>index</a></li>
<li class="right" >
<a href="../py-modindex.html" title="Python Module Index"
>modules</a> |</li>
<li class="right" >
<a href="../parallel/index.html" title="Using IPython for parallel computing"
>next</a> |</li>
<li class="right" >
<a href="shell.html" title="IPython as a system shell"
>previous</a> |</li>
<li><a href="../index.html">IPython 0.10.2 documentation</a> »</li>
<li><a href="index.html" >Using IPython for interactive work</a> »</li>
</ul>
</div>
<div class="footer">
© Copyright 2008, The IPython Development Team.
Last updated on Apr 09, 2011.
Created using <a href="http://sphinx.pocoo.org/">Sphinx</a> 1.1pre.
</div>
</body>
</html>
