<!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="X-UA-Compatible" content="IE=Edge" />
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<title>Plugin API — Bazaar 2.7.0 documentation</title>
<link rel="stylesheet" href="_static/classic.css" type="text/css" />
<link rel="stylesheet" href="_static/pygments.css" type="text/css" />
<script type="text/javascript" id="documentation_options" data-url_root="./" src="_static/documentation_options.js"></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>
<script type="text/javascript" src="_static/language_data.js"></script>
<link rel="shortcut icon" href="_static/bzr.ico"/>
<link rel="search" title="Search" href="search.html" />
<link rel="next" title="Repositories" href="repository.html" />
<link rel="prev" title="Network Protocol" href="network-protocol.html" />
<link rel="stylesheet" href="_static/bzr-doc.css" type="text/css" />
</head><body>
<div class="related" role="navigation" aria-label="related navigation">
<h3>Navigation</h3>
<ul>
<li class="right" style="margin-right: 10px">
<a href="repository.html" title="Repositories"
accesskey="N">next</a></li>
<li class="right" >
<a href="network-protocol.html" title="Network Protocol"
accesskey="P">previous</a> |</li>
<li><a href="http://bazaar.canonical.com/">
<img src="_static/bzr icon 16.png" /> Home</a> | </li>
<a href="http://doc.bazaar.canonical.com/en/">Documentation</a> | </li>
<li class="nav-item nav-item-0"><a href="index.html">Developer Document Catalog (2.7.0)</a> »</li>
<li class="nav-item nav-item-1"><a href="specifications.html" accesskey="U">Specifications</a> »</li>
</ul>
</div>
<div class="document">
<div class="documentwrapper">
<div class="bodywrapper">
<div class="body" role="main">
<div class="section" id="plugin-api">
<h1><a class="toc-backref" href="#id2">Plugin API</a><a class="headerlink" href="#plugin-api" title="Permalink to this headline">¶</a></h1>
<table class="docutils field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field-odd field"><th class="field-name">Date:</th><td class="field-body">2009-01-23</td>
</tr>
</tbody>
</table>
<div class="contents topic" id="contents">
<p class="topic-title first">Contents</p>
<ul class="simple">
<li><a class="reference internal" href="#plugin-api" id="id2">Plugin API</a><ul>
<li><a class="reference internal" href="#introduction" id="id3">Introduction</a><ul>
<li><a class="reference internal" href="#see-also" id="id4">See also</a></li>
</ul>
</li>
<li><a class="reference internal" href="#structure-of-a-plugin" id="id5">Structure of a plugin</a></li>
<li><a class="reference internal" href="#plugin-metadata-before-installation" id="id6">Plugin metadata before installation</a><ul>
<li><a class="reference internal" href="#metadata-protocol" id="id7">Metadata protocol</a></li>
<li><a class="reference internal" href="#control-formats" id="id8">Control Formats</a></li>
<li><a class="reference internal" href="#example" id="id9">Example</a></li>
</ul>
</li>
<li><a class="reference internal" href="#plugin-metadata-after-installation" id="id10">Plugin metadata after installation</a><ul>
<li><a class="reference internal" href="#help-and-documentation" id="id11">Help and documentation</a></li>
<li><a class="reference internal" href="#api-version" id="id12">API version</a></li>
<li><a class="reference internal" href="#plugin-version" id="id13">Plugin version</a></li>
<li><a class="reference internal" href="#detecting-whether-code-s-being-loaded-as-a-plugin" id="id14">Detecting whether code’s being loaded as a plugin</a></li>
</ul>
</li>
<li><a class="reference internal" href="#plugin-performance" id="id15">Plugin performance</a></li>
<li><a class="reference internal" href="#plugin-registrations" id="id16">Plugin registrations</a></li>
<li><a class="reference internal" href="#publishing-your-plugin" id="id17">Publishing your plugin</a></li>
</ul>
</li>
</ul>
</div>
<div class="section" id="introduction">
<h2><a class="toc-backref" href="#id3">Introduction</a><a class="headerlink" href="#introduction" title="Permalink to this headline">¶</a></h2>
<p>bzrlib has a very flexible internal structure allowing plugins for many
operations. Plugins can add commands, new storage formats, diff and merge
features and more. This document provides an overview of the API and
conventions for plugin authors.</p>
<p>If you’re writing a plugin and have questions not addressed by this
document, please ask us.</p>
<div class="section" id="see-also">
<h3><a class="toc-backref" href="#id4">See also</a><a class="headerlink" href="#see-also" title="Permalink to this headline">¶</a></h3>
<blockquote>
<div><ul class="simple">
<li><a class="reference external" href="../index.html">Bazaar Developer Documentation Catalog</a>.</li>
<li><a class="reference external" href="http://doc.bazaar.canonical.com/plugins/en/plugin-development.html">Bazaar Plugins Guide</a> for
more suggestions about particular APIs.</li>
</ul>
</div></blockquote>
</div>
</div>
<div class="section" id="structure-of-a-plugin">
<h2><a class="toc-backref" href="#id5">Structure of a plugin</a><a class="headerlink" href="#structure-of-a-plugin" title="Permalink to this headline">¶</a></h2>
<p>Plugins are Python modules under <code class="docutils literal notranslate"><span class="pre">bzrlib.plugins</span></code>. They can be installed
either into the PYTHONPATH in that location, or in ~/.bazaar/plugins.</p>
<p>Plugins should have a setup.py.</p>
<p>As for other Python modules, the name of the directory must match the
expected name of the plugin.</p>
</div>
<div class="section" id="plugin-metadata-before-installation">
<h2><a class="toc-backref" href="#id6">Plugin metadata before installation</a><a class="headerlink" href="#plugin-metadata-before-installation" title="Permalink to this headline">¶</a></h2>
<p>Plugins can export a summary of what they provide, and what versions of bzrlib
they are compatible with. This allows tools to be written to work with plugins,
such as to generate a directory of plugins, or install them via a
symlink/checkout to ~/.bazaar/plugins.</p>
<p>This interface allows bzr to interrogate a plugin without actually loading
it. This is useful because loading a plugin may have side effects such
as registering or overriding commands, or the plugin may raise an error,
if for example a prerequisite is not present.</p>
<div class="section" id="metadata-protocol">
<h3><a class="toc-backref" href="#id7">Metadata protocol</a><a class="headerlink" href="#metadata-protocol" title="Permalink to this headline">¶</a></h3>
<p>A plugin that supports the bzr plugin metadata protocol will do two
things. Firstly, the <code class="docutils literal notranslate"><span class="pre">setup.py</span></code> for the plugin will guard the call to
<code class="docutils literal notranslate"><span class="pre">setup()</span></code>:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="k">if</span> <span class="vm">__name__</span> <span class="o">==</span> <span class="s1">'main'</span><span class="p">:</span>
<span class="n">setup</span><span class="p">(</span><span class="o">...</span><span class="p">)</span>
</pre></div>
</div>
<p>Secondly, the setup module will have one or more of the following variables
present at module scope. Any variables that are missing will be given the
defaults from the table. An example of every variable is provided after
the full list.</p>
<table border="1" class="docutils">
<colgroup>
<col width="33%" />
<col width="12%" />
<col width="55%" />
</colgroup>
<thead valign="bottom">
<tr class="row-odd"><th class="head">Variable</th>
<th class="head">Default</th>
<th class="head">Definition</th>
</tr>
</thead>
<tbody valign="top">
<tr class="row-even"><td>bzr_plugin_name</td>
<td>None</td>
<td>The name the plugin package should be
given on disk. The plugin is then
available to python at
bzrlib.plugins.NAME</td>
</tr>
<tr class="row-odd"><td>bzr_commands</td>
<td>[]</td>
<td>A list of the commands that the plugin
provides. Commands that already exist
in bzr and are decorated by the plugin
do not need to be listed (but it is not
harmful if you do list them).</td>
</tr>
<tr class="row-even"><td>bzr_plugin_version</td>
<td>None</td>
<td>A version_info 5-tuple with the plugins
version.</td>
</tr>
<tr class="row-odd"><td>bzr_minimum_version</td>
<td>None</td>
<td>A version_info 3-tuple for comparison
with the bzrlib minimum and current
version, for determining likely
compatibility.</td>
</tr>
<tr class="row-even"><td>bzr_maximum_version</td>
<td>None</td>
<td>A version_info 3-tuple like
bzr_minimum_version but checking the
upper limits supported.</td>
</tr>
<tr class="row-odd"><td>bzr_control_formats</td>
<td>{}</td>
<td>A dictionary of descriptions of version
control directories. See
<cite>Control Formats</cite> below.</td>
</tr>
<tr class="row-even"><td>bzr_checkout_formats</td>
<td>{}</td>
<td>A dictionary of tree_format_string ->
human description strings, for tree
formats that drop into the
<code class="docutils literal notranslate"><span class="pre">.bzr/checkout</span></code> metadir system.</td>
</tr>
<tr class="row-odd"><td>bzr_branch_formats</td>
<td>{}</td>
<td>As bzr_checkout_formats but for
branches.</td>
</tr>
<tr class="row-even"><td>bzr_repository_formats</td>
<td>{}</td>
<td>As bzr_checkout_formats but for
repositories.</td>
</tr>
<tr class="row-odd"><td>bzr_transports</td>
<td>[]</td>
<td>URL prefixes for which this plugin
will register transports.</td>
</tr>
</tbody>
</table>
</div>
<div class="section" id="control-formats">
<h3><a class="toc-backref" href="#id8">Control Formats</a><a class="headerlink" href="#control-formats" title="Permalink to this headline">¶</a></h3>
<p>Because disk format detection for formats that bzr does not understand at
all can be useful, we allow a declarative description of the shape of a
control directory. Each description has a name for showing to users, and a
dictonary of relative paths, and the content needed at each path. Paths
that end in ‘/’ are required to be directories and the value for that key
is ignored. Other paths are required to be regular files, and the value
for that key is either None, in which case the file is statted but the
content is ignored, or a literal string which is compared against for
the content of the file. Thus:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="c1"># (look for a .hg directory)</span>
<span class="n">bzr_control_formats</span> <span class="o">=</span> <span class="p">{</span><span class="s2">"Mercurial"</span><span class="p">:{</span><span class="s1">'.hg/'</span><span class="p">:</span> <span class="kc">None</span><span class="p">}}</span>
<span class="c1"># (look for a file called .svn/format with contents 4\n).</span>
<span class="n">bzr_control_formats</span> <span class="o">=</span> <span class="p">{</span><span class="s2">"Subversion"</span><span class="p">:{</span><span class="s1">'.svn/format'</span><span class="p">:</span> <span class="s1">'4</span><span class="se">\n</span><span class="s1">'</span><span class="p">}}</span>
</pre></div>
</div>
</div>
<div class="section" id="example">
<h3><a class="toc-backref" href="#id9">Example</a><a class="headerlink" href="#example" title="Permalink to this headline">¶</a></h3>
<p>An example setup.py follows:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="ch">#!/usr/bin/env python2.4</span>
<span class="kn">from</span> <span class="nn">distutils.core</span> <span class="k">import</span> <span class="n">setup</span>
<span class="n">bzr_plugin_name</span> <span class="o">=</span> <span class="s1">'demo'</span>
<span class="n">bzr_commands</span> <span class="o">=</span> <span class="p">[</span>
<span class="s1">'new-command'</span><span class="p">,</span>
<span class="p">]</span>
<span class="n">bzr_branch_formats</span> <span class="o">=</span> <span class="p">{</span>
<span class="s2">"Branch label on disk</span><span class="se">\n</span><span class="s2">"</span><span class="p">:</span><span class="s2">"demo branch"</span><span class="p">,</span>
<span class="p">}</span>
<span class="n">bzr_control_formats</span> <span class="o">=</span> <span class="p">{</span><span class="s2">"Subversion"</span><span class="p">:{</span><span class="s1">'.svn/format'</span><span class="p">:</span> <span class="s1">'4</span><span class="se">\n</span><span class="s1">'</span><span class="p">}}</span>
<span class="n">bzr_transports</span> <span class="o">=</span> <span class="p">[</span><span class="s2">"hg+ssh://"</span><span class="p">]</span>
<span class="n">bzr_plugin_version</span> <span class="o">=</span> <span class="p">(</span><span class="mi">1</span><span class="p">,</span> <span class="mi">3</span><span class="p">,</span> <span class="mi">0</span><span class="p">,</span> <span class="s1">'dev'</span><span class="p">,</span> <span class="mi">0</span><span class="p">)</span>
<span class="n">bzr_minimum_version</span> <span class="o">=</span> <span class="p">(</span><span class="mi">1</span><span class="p">,</span> <span class="mi">0</span><span class="p">,</span> <span class="mi">0</span><span class="p">)</span>
<span class="k">if</span> <span class="vm">__name__</span> <span class="o">==</span> <span class="s1">'main'</span><span class="p">:</span>
<span class="n">setup</span><span class="p">(</span><span class="n">name</span><span class="o">=</span><span class="s2">"Demo"</span><span class="p">,</span>
<span class="n">version</span><span class="o">=</span><span class="s2">"1.3.0dev0"</span><span class="p">,</span>
<span class="n">description</span><span class="o">=</span><span class="s2">"Demo plugin for plugin metadata."</span><span class="p">,</span>
<span class="n">author</span><span class="o">=</span><span class="s2">"Canonical Ltd"</span><span class="p">,</span>
<span class="n">author_email</span><span class="o">=</span><span class="s2">"bazaar@lists.canonical.com"</span><span class="p">,</span>
<span class="n">license</span> <span class="o">=</span> <span class="s2">"GNU GPL v2"</span><span class="p">,</span>
<span class="n">url</span><span class="o">=</span><span class="s2">"https://launchpad.net/bzr-demo"</span><span class="p">,</span>
<span class="n">packages</span><span class="o">=</span><span class="p">[</span><span class="s1">'bzrlib.plugins.demo'</span><span class="p">,</span>
<span class="s1">'bzrlib.plugins.demo.tests'</span><span class="p">,</span>
<span class="p">],</span>
<span class="n">package_dir</span><span class="o">=</span><span class="p">{</span><span class="s1">'bzrlib.plugins.demo'</span><span class="p">:</span> <span class="s1">'.'</span><span class="p">})</span>
</pre></div>
</div>
</div>
</div>
<div class="section" id="plugin-metadata-after-installation">
<h2><a class="toc-backref" href="#id10">Plugin metadata after installation</a><a class="headerlink" href="#plugin-metadata-after-installation" title="Permalink to this headline">¶</a></h2>
<p>After a plugin has been installed, metadata can be more easily obtained by
looking inside the module object – in other words, for variables defined
in the plugin’s <code class="docutils literal notranslate"><span class="pre">__init__.py</span></code>.</p>
<div class="section" id="help-and-documentation">
<h3><a class="toc-backref" href="#id11">Help and documentation</a><a class="headerlink" href="#help-and-documentation" title="Permalink to this headline">¶</a></h3>
<p>The module docstring is used as the plugin description shown by <code class="docutils literal notranslate"><span class="pre">bzr</span>
<span class="pre">plugins</span></code>. As with all Python docstrings, the first line should be a
short complete sentence summarizing the plugin. The full docstring is
shown by <code class="docutils literal notranslate"><span class="pre">bzr</span> <span class="pre">help</span> <span class="pre">PLUGIN_NAME</span></code>.</p>
<p>This is a user-visible docstring so should be prefixed with <code class="docutils literal notranslate"><span class="pre">__doc__</span> <span class="pre">=</span></code>
to ensure help works under <code class="docutils literal notranslate"><span class="pre">python</span> <span class="pre">-OO</span></code> with docstrings stripped.</p>
</div>
<div class="section" id="api-version">
<h3><a class="toc-backref" href="#id12">API version</a><a class="headerlink" href="#api-version" title="Permalink to this headline">¶</a></h3>
<p>Plugins can and should declare that they depend on a particular version of
bzrlib like so:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="kn">from</span> <span class="nn">bzrlib.api</span> <span class="k">import</span> <span class="n">require_api</span>
<span class="n">require_api</span><span class="p">(</span><span class="n">bzrlib</span><span class="p">,</span> <span class="p">(</span><span class="mi">1</span><span class="p">,</span> <span class="mi">11</span><span class="p">,</span> <span class="mi">0</span><span class="p">))</span>
</pre></div>
</div>
<p>Please see <a class="reference external" href="api-versioning.html">API versioning</a> for more details on the API
metadata protocol used by bzrlib.</p>
</div>
<div class="section" id="plugin-version">
<h3><a class="toc-backref" href="#id13">Plugin version</a><a class="headerlink" href="#plugin-version" title="Permalink to this headline">¶</a></h3>
<p>The plugin should expose a version tuple to describe its own version.
Some plugins use a version number that corresponds to the version of bzr
they’re released against, but you can use whatever you want. For example:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">version_info</span> <span class="o">=</span> <span class="p">(</span><span class="mi">1</span><span class="p">,</span> <span class="mi">10</span><span class="p">,</span> <span class="mi">0</span><span class="p">)</span>
</pre></div>
</div>
</div>
<div class="section" id="detecting-whether-code-s-being-loaded-as-a-plugin">
<h3><a class="toc-backref" href="#id14">Detecting whether code’s being loaded as a plugin</a><a class="headerlink" href="#detecting-whether-code-s-being-loaded-as-a-plugin" title="Permalink to this headline">¶</a></h3>
<p>You may have a Python module that can be used as a bzr plugin and also in
other places. To detect whether the module is being loaded by bzr, use
something like this:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="k">if</span> <span class="vm">__name__</span> <span class="o">==</span> <span class="s1">'bzrlib.plugins.loggerhead'</span><span class="p">:</span>
<span class="c1"># register with bzrlib...</span>
</pre></div>
</div>
</div>
</div>
<div class="section" id="plugin-performance">
<h2><a class="toc-backref" href="#id15">Plugin performance</a><a class="headerlink" href="#plugin-performance" title="Permalink to this headline">¶</a></h2>
<p>Plugins should avoid doing work or loading code from the plugin or
external libraries, if they’re just installed but not actually active,
because this slows down every invocation of bzr. The bzrlib APIs
generally allow the plugin to ‘lazily’ register methods to invoke if a
particular disk format or seen or a particular command is run.</p>
</div>
<div class="section" id="plugin-registrations">
<h2><a class="toc-backref" href="#id16">Plugin registrations</a><a class="headerlink" href="#plugin-registrations" title="Permalink to this headline">¶</a></h2>
<p>The plugin <code class="docutils literal notranslate"><span class="pre">__init__.py</span></code> runs when the plugin is loaded during bzr
startup. Generally the plugin won’t want to actually do anything at this
time other than register or override functions to be called later.</p>
<p>The plugin can import bzrlib and call any function.
Some interesting APIs are described in <a class="reference external" href="http://doc.bazaar.canonical.com/plugins/en/plugin-development.html">Bazaar Plugins Guide</a>.</p>
</div>
<div class="section" id="publishing-your-plugin">
<h2><a class="toc-backref" href="#id17">Publishing your plugin</a><a class="headerlink" href="#publishing-your-plugin" title="Permalink to this headline">¶</a></h2>
<p>When your plugin is basically working you might like to share it with
other people. Here are some steps to consider:</p>
<blockquote>
<div><ul class="simple">
<li>make a project on Launchpad.net like
<<a class="reference external" href="https://launchpad.net/bzr-fastimport">https://launchpad.net/bzr-fastimport</a>>
and publish the branches or tarballs there</li>
<li>include the plugin in <<a class="reference external" href="http://wiki.bazaar.canonical.com/BzrPlugins">http://wiki.bazaar.canonical.com/BzrPlugins</a>></li>
<li>post about it to the <code class="docutils literal notranslate"><span class="pre">bazaar-announce</span></code> list at <code class="docutils literal notranslate"><span class="pre">lists.canonical.com</span></code></li>
</ul>
</div></blockquote>
</div>
</div>
</div>
</div>
</div>
<div class="sphinxsidebar" role="navigation" aria-label="main navigation">
<div class="sphinxsidebarwrapper">
<h3><a href="index.html">Table of Contents</a></h3>
<ul>
<li><a class="reference internal" href="#">Plugin API</a><ul>
<li><a class="reference internal" href="#introduction">Introduction</a><ul>
<li><a class="reference internal" href="#see-also">See also</a></li>
</ul>
</li>
<li><a class="reference internal" href="#structure-of-a-plugin">Structure of a plugin</a></li>
<li><a class="reference internal" href="#plugin-metadata-before-installation">Plugin metadata before installation</a><ul>
<li><a class="reference internal" href="#metadata-protocol">Metadata protocol</a></li>
<li><a class="reference internal" href="#control-formats">Control Formats</a></li>
<li><a class="reference internal" href="#example">Example</a></li>
</ul>
</li>
<li><a class="reference internal" href="#plugin-metadata-after-installation">Plugin metadata after installation</a><ul>
<li><a class="reference internal" href="#help-and-documentation">Help and documentation</a></li>
<li><a class="reference internal" href="#api-version">API version</a></li>
<li><a class="reference internal" href="#plugin-version">Plugin version</a></li>
<li><a class="reference internal" href="#detecting-whether-code-s-being-loaded-as-a-plugin">Detecting whether code’s being loaded as a plugin</a></li>
</ul>
</li>
<li><a class="reference internal" href="#plugin-performance">Plugin performance</a></li>
<li><a class="reference internal" href="#plugin-registrations">Plugin registrations</a></li>
<li><a class="reference internal" href="#publishing-your-plugin">Publishing your plugin</a></li>
</ul>
</li>
</ul>
<h4>Previous topic</h4>
<p class="topless"><a href="network-protocol.html"
title="previous chapter">Network Protocol</a></p>
<h4>Next topic</h4>
<p class="topless"><a href="repository.html"
title="next chapter">Repositories</a></p>
<div role="note" aria-label="source link">
<h3>This Page</h3>
<ul class="this-page-menu">
<li><a href="_sources/plugin-api.txt"
rel="nofollow">Show Source</a></li>
</ul>
</div>
<div id="searchbox" style="display: none" role="search">
<h3>Quick search</h3>
<div class="searchformwrapper">
<form class="search" action="search.html" method="get">
<input type="text" name="q" />
<input type="submit" value="Go" />
<input type="hidden" name="check_keywords" value="yes" />
<input type="hidden" name="area" value="default" />
</form>
</div>
</div>
<script type="text/javascript">$('#searchbox').show(0);</script>
</div>
</div>
<div class="clearer"></div>
</div>
<div class="related" role="navigation" aria-label="related navigation">
<h3>Navigation</h3>
<ul>
<li class="right" style="margin-right: 10px">
<a href="repository.html" title="Repositories"
>next</a></li>
<li class="right" >
<a href="network-protocol.html" title="Network Protocol"
>previous</a> |</li>
<li><a href="http://bazaar.canonical.com/">
<img src="_static/bzr icon 16.png" /> Home</a> | </li>
<a href="http://doc.bazaar.canonical.com/en/">Documentation</a> | </li>
<li class="nav-item nav-item-0"><a href="index.html">Developer Document Catalog (2.7.0)</a> »</li>
<li class="nav-item nav-item-1"><a href="specifications.html" >Specifications</a> »</li>
</ul>
</div>
<div class="footer" role="contentinfo">
© Copyright 2009-2011 Canonical Ltd.
Created using <a href="http://sphinx-doc.org/">Sphinx</a> 1.8.4.
</div>
</body>
</html>
