[MERGE] Add a plugin-api.txt developer document starting to description services for/from plugins.

Martin Pool mbp at canonical.com
Fri Feb 29 12:27:43 GMT 2008


Martin Pool has voted resubmit.
Status is now: Resubmit
Comment:
> +==========
> +Plugin API
> +==========
> +
> +Status
> +======
> +
> +:Date: 2008-02-29
> +
 > +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.
> +

The "Status" heading is strange (orphaned?), so I suggest you just
remove it and put this text as introductory matter before the contents.
Also, delete the "motivation" section and just add

   This document provides an overview of the API and conventions for 
plugin authors.

Please delete the date; this always either goes out of date or causes
confusion about whether it should be updated by minor changes.

> +
> +.. contents::
> +
> +
> +Motivation
> +==========
> +
> +To provide a pithy central document for plugin authors to refer to.


> +
> +
> +Plugin metadata before installation
> +===================================
> +
 > +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.

This needs an earlier section to establish context.

   Structure of a plugin
   =====================

   Plugins are Python modules under ``bzrlib.plugins``.  They can be
   installed either into the PYTHONPATH in that location, or in
   ~/.bazaar/plugins.

   Plugins should typically have a setup.py.

   As for other Python modules, the name of the directory must match the
   expected name of the plugin.

I guess they normally do have a setup.py, though it's unclear to me that
will interact well with people just putting a checkout under
~/.bazaar/plugins.

> +
> +Design
> +------
> +
> +Because loading a plugin is all that is required to activate it, and
 > +because plugins may require external dependencies to load properly 
(such
 > +as being specific to the Windows platform), we use a separate 
interface to
> +obtain plugin metadata from the setup.py script which plugins will
> +typically have.

Delete heading, rephrase to

   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.

> +
> +Metadata protocol
> +-----------------
> +
> +A plugin that supports the bzr plugin metadata protocol will do two
 > +things. Firstly, the ``setup.py`` for the plugin will guard the call 
to
> +``setup()``::
> +
> +  if __name__ == 'main':
> +      setup(...)
> +
 > +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.

It seems like we are basically overriding setup.py here.  Why not have a
separate file, say bzr_plugin_meta.py, with these variables.  It can
then be loaded from setup.py if desired.

After all it is quite possible that loading setup.py may have side
effects or raise errors.



> +
 > 
++------------------------+---------+----------------------------------------+
 > +| Variable               | Default | Definition 
|
 > 
++========================+=========+========================================+
 > +| bzr_plugin_name        | None    | The name the plugin package 
should be  |
 > +|                        |         | given on disk. The plugin is 
then      |
 > +|                        |         | available to python at 
|
 > +|                        |         | bzrlib.plugins.NAME 
|
 > 
++------------------------+---------+----------------------------------------+
 > +| bzr_commands           | []      | 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). 
|

Probably we should list the commands that are overridden.

 > 
++------------------------+---------+----------------------------------------+
 > +| bzr_plugin_version     | None    | A version_info 5-tuple with the 
plugins|
 > +|                        |         | version. 
|

   plugin's

and give an example (1, 1, 0, 'final', 0)

 > 
++------------------------+---------+----------------------------------------+
 > +| bzr_minimum_version    | None    | A version_info 3-tuple for 
comparison  |
 > +|                        |         | with the bzrlib minimum and 
current    |
 > +|                        |         | version, for determining likely 
|
 > +|                        |         | compatibility. 
|

e.g. (1, 1, 0)

 > 
++------------------------+---------+----------------------------------------+
 > +| bzr_maximum_version    | None    | A version_info 3-tuple like 
|
 > +|                        |         | bzr_minimum_version but checking 
the   |
 > +|                        |         | upper limits supported. 
|
 > 
++------------------------+---------+----------------------------------------+
 > +| bzr_control_formats    | {}      | A dictionary of descriptions of 
version|
 > +|                        |         | control directories. See 
|
 > +|                        |         | `Control Formats` below. 
|
 > 
++------------------------+---------+----------------------------------------+
 > +| bzr_checkout_formats   | {}      | A dictionary of 
tree_format_string ->  |
 > +|                        |         | human description strings, for 
tree    |
 > +|                        |         | formats that drop into the 
|
 > +|                        |         | ``.bzr/checkout`` metadir 
system.      |
 > 
++------------------------+---------+----------------------------------------+
 > +| bzr_branch_formats     | {}  As bzr_checkout_formats but for 
branches.    |
 > 
++------------------------+---------+----------------------------------------+
 > +| bzr_repository_formats | {} As bzr_checkout_formats but for 
repositories. |
 > 
++------------------------+---------+----------------------------------------+

Broken ReST here.

> +
> +Control Formats
> +---------------
> +
 > +Because disk format detection for formats that bzr does not 
understand at
 > +all can be useful, we allow a declaritive description of the shape of 
a

declarative



For details, see: 
http://bundlebuggy.aaronbentley.com/request/%3C1204283630.28682.40.camel%40lifeless-64%3E



More information about the bazaar mailing list