This plugin adds a summary command, which prints a brief summary of a branch and its files. For example:

$ bzr summary -r15 --group-by-ext /sandbox/plugins/summary
# Branch URL: file:///sandbox/plugins/summary/
# Branch nick: summary
# Revisions: 23
# Selected revno: 15
# Files: 5
#   ---: 1
#   py : 4
# Directories: 1
# Others: 0

In addition to the basic information we can get with bzr info, the command counts the number of files and directories, optionally grouped by the file type. The -r option can be used to select a revision; it is implemented by re-using Bazaar's built-in revision selector you have seen in all bzr commands. As with all bzr commands, the -h and --help flags can be used to print detailed help with all the options of the command.

This plugin adds custom log formats that can be used with the bzr log command. For example:

$ bzr log /sandbox/plugins/summary/ --git --limit 1
commit janos@axiom-20130114172512-vkaw1yzw1aodr8a7
Bazaar revno: 23
Author: Janos Gyerik <janos@axiom>
Date:   Mon Jan 14 18:25:12 2013 +0100

    changed "pivot revno" to "selected revno" in output

The --git flag is not a standard parameter of the bzr log command; it is added by the plugin. The output mimics the format used by Git. Bazaar's log formats hide merged revisions by default. In order to mimic Git's behavior, this plugin will always show merged revisions.

The plugin is written in a way to make it easy to add other custom log formats. After reading this section about creating a plugin, it should be straightforward to duplicate an existing log format to create a new one.

The appendlog plugin contains a hook that can be used to automatically append commit logs to a file configured in a branch. To enable the logging, the path to the log file must be specified in the post_config_log variable in the configuration file .bzr/branch/branch.conf inside a branch. Let's create a dummy branch to test this:

$ bzr init /tmp/dummy
Created a standalone tree (format: 2a)

And let's enable the hook in the branch configuration file by using the bzr config command. For example:

$ cd /tmp/dummy
$ bzr config post_commit_log=/tmp/changes.log

If you commit a couple of revisions in this dummy branch, they will be logged in the file /tmp/changes.log, using the long log format.

The first statement in the file must be a string literal, commonly named the docstring in Python. The first line of docstring is used as the description of the plugin when listing plugins with bzr plugins. The full docstring is used when viewing the detailed help of the plugin with bzr help plugins/NAME. For example, the docstring in the example customlog plugin is as follows:

"""Custom log formats to use with ``bzr log --CUSTOMNAME``

TODO: more explanation..."""

The first line of this text will appear in the output of bzr plugins:

$ bzr plugins | grep customlog -A1
customlog 1.0.0dev
  Custom log formats to use with ``bzr log --CUSTOMNAME``

The full docstring text will appear in bzr help plugins/customlog:

$ bzr help plugins/customlog
Custom log formats to use with ``bzr log --CUSTOMNAME``

TODO: more explanation...

The plugin should declare the bzrlib API version it depends on, as follows:

import bzrlib
from bzrlib.api import require_api
require_api(bzrlib, (2, 5, 0))

Bazaar will load the plugin only if the bzrlib API version is equal to or higher than the specified version. If a plugin cannot be loaded because it requires a newer API than the current Bazaar installation, the bzr plugins command will show that as an error. For example:

$ bzr plugins | grep customlog -A1
customlog (failed to load)
  ** Unable to load plugin u'customlog'. It requested API version (3, 5, 0) of module <module 'bzrlib' from '/Library/Python/2.6/site-packages/bzrlib/__init__.pyc'> but the minimum exported version is (2, 4, 0), and the maximum is (2, 5, 0)

In this case, the plugin will not be loaded, and the bzr help plugins/NAME command will not work either.

The right value to use for these settings is the lowest API version with which the plugin was confirmed to work well. The version of bzrlib corresponds to the version of Bazaar. Strictly speaking, you can find this version in the output of the bzr version command, or programmatically with:

$ python -c 'import bzrlib; print bzrlib.version_info[0:3]'
(2, 5, 0)

The plugin should expose its own version by using the version_info variable. For example:

version_info = (1, 0, 0, 'dev', 0)

Although it's not a requirement, it's probably a good idea to adopt the same convention for setting the version, as explained in the __init__.py file of bzrlib itself:

# same format as sys.version_info: "A tuple containing the five components of
# the version number: major, minor, micro, releaselevel, and serial. All
# values except releaselevel are integers; the release level is 'alpha',
# 'beta', 'candidate', or 'final'. The version_info value corresponding to the
# Python version 2.0 is (2, 0, 0, 'final', 0)."  Additionally we use a
# releaselevel of 'dev' for unreleased under-development code.

The value of this variable is used, for example, in the output of the bzr plugins command.

Although some plugins may have their entire code in the __init__.py file itself, it is more common and often more optimal that the main code is separated into other *.py files. In this case, when loading the modules with the main functionality, we must use the absolute import path. For example:

def test_suite():
    from bzrlib.plugins.customlog import tests
    return tests.test_suite()

To make sure that Bazaar can resolve the absolute import path bzrlib.plugins.customlog, it is a common practice to add this simple check:

if __name__ != 'bzrlib.plugins.customlog':
    raise ImportError(
        'The customlog plugin must be installed as'
        ' bzrlib.plugins.customlog not %s'
        % __name__)

In this way, the plugin will work only if installed in the directory customlog, otherwise Bazaar will raise an exception and abort loading the plugin. The exception raised is visible in all the Bazaar commands, as the __init__.py file is always loaded for all plugins.

In order to hook into Bazaar's architecture, the plugin must register its methods appropriately so that Bazaar can discover them. In the following sections, we will show, with examples, how to register the following types of functionality:

from bzrlib.commands import plugin_cmds
plugin_cmds.register_lazy(
    'cmd_summary', [], 'bzrlib.plugins.summary.cmd_summary')

$ python
>>> import bzrlib.commands
>>> help(bzrlib.commands.plugin_cmds.register_lazy)

from bzrlib.log import log_formatter_registry
log_formatter_registry.register_lazy(
    'custom1', 'bzrlib.plugins.customlog.custom1',
    'Custom1LogFormatter',
    'Custom1 log format'
)

$ python
>>> import bzrlib.log
>>> help(bzrlib.log.log_formatter_registry.register_lazy)

yyy.hooks.install_named_hook_lazy("xxx", …)

from bzrlib.branch import Branch
Branch.hooks.install_named_hook_lazy(
    'post_commit', 'bzrlib.plugins.appendlog.main',
    'appendlog',
    'Append commit log to a configured file'
)

$ python
>>> import bzrlib.branch
>>> help(bzrlib.branch.Branch.hooks)

Bazaar has a framework to perform self-tests of plugins. In order to enable self-tests for the plugin, you must define a test_suite method in __init__.py. For example:

def test_suite():
    from bzrlib.plugins.customlog import tests
    return tests.test_suite()

The method must return an instance of the unittest.TestSuite class, and should include all the unit test cases and test suites to run for the plugin. As usual, in order to keep __init__.py as fast as possible, the test_suite method body should be as short as possible, and should only do minimal initialization.

Although we violate the general Python best practice of placing imports near the top of the file, we have a good reason to do so. Defining the test_suite method is important to let Bazaar know of the test suites, and the implementation should only be loaded when we actually want to perform the self-tests.

Throughout this section, we used the lazy registration methods in all the examples. The reason is that every time you run a bzr command, Bazaar will load the __init__.py file of all the Python packages it finds on the plugin path, even if some plugins might not be used. This is the price of the great flexibility—plugins can extend and modify all the aspects of Bazaar, and since there is no way to know in advance what a plugin might do, Bazaar has to load the __init__.py files in order to let the plugins register their functions and hook into Bazaar's architecture.

By using the lazy registration methods, we make sure that if a plugin is not used during a given bzr operation, then __init__.py is the only file that gets loaded and nothing else. When writing __init__.py, you should always be careful to only load what is essential for the registration of the plugin, and leave the main implementation in the other files that are only loaded when the plugin is actually used. Otherwise, the plugin will cause slowness in all bzr commands, even the ones that don't use the functionality of that plugin.

Following the implementation guidelines, you can implement and organize the main functionality of the plugin more or less freely within the plugin directory. However, in terms of coding style and certain aspects of programming in Python, there is a relatively long list of guidelines, strongly recommended by the documentation at http://doc.bazaar.canonical.com/developers/code-style.html.

As this document contains many specificities, which might change over time, it is best to find the latest version and read it carefully before you begin to work on a plugin. Here, we will add only a few tips not mentioned in the documentation.

In terms of coding style, PEP8 is the baseline, with a few additional rules explained in the guidelines. An easy way to create a PEP8-compliant code is by using the pep8 utility. This tool checks all the Python files in the specified directories and their subdirectories, and warns of all PEP8 violations. It is also a good idea to review and adjust the settings in your Python IDE, as it may have options to make it easier to create PEP8-compliant code in the first place, rather than fixing violations later.

Another useful tool to validate the Python code and catch common mistakes is pyflakes, typically in a package with the same name. It checks all the Python files in the specified directories and their subdirectories, and warns of the various types of common Python programming errors and best practice violations.

These are only additional tips. For a detailed list of guidelines, always read the up-to-date version of the Bazaar coding style guide.