Jump to >

File Layout

Extensions must follow a certain file structure in order to be recognized and loaded by Review Board. They are distributed inside Python Egg packages, which must follow a few conventions. See Python Egg for more information.

Note

The Review Board extension system has been designed to follow many of Django‘s conventions. The structure of an extension package tries to mirror that of Django apps.

The main constituent of an extension is a class which inherits from the Extension base class reviewboard.extensions.base.Extension.

The Review Board repository contains a script for generating the initial code an extension requires. See Extension Boilerplate Generator for more information.

Required Files

At minimum, an extension requires the following files:

The following are a description and example of each file. In each example extensiondir has been replaced with the extension’s package, ‘sample_extension’:

setup.py

This is the file used to create the Python Egg. It defines the Entry Point along with other meta-data. See Extension Distribution for a description of features relevant to Review Board extensions. For example:

from reviewboard.extensions.packaging import setup


PACKAGE = "sample_extension"
VERSION = "0.1"


setup(
    name=PACKAGE,
    version=VERSION,
    description='Description of extension package.',
    author='Your Name',
    packages=['sample_extension'],
    entry_points={
        'reviewboard.extensions':
            '%s = sample_extension.extension:SampleExtension' % PACKAGE,
    },
)

See Extension Distribution and the setuptools documentation for more information.

sample_extension/__init__.py
This file indicates the sample_extension is a Python package. It is generally left blank.
sample_extension/extension.py

This is the main module of the extension. The Extension subclass should be defined here. For example:

from reviewboard.extensions.base import Extension


class SampleExtension(Extension):
    def initialize(self):
        # Your extension initialization code belongs here.

This file will often be where you’ll define any hooks, utility functions, and extension metadata you may need. Throughout this guide, we’ll cover the various things you may place in this file.

Optional Files

Review Board also expects extensions to follow a few other conventions when naming files. The following files serve a special purpose:

models.py
An extension may define Django models in this file. The corresponding tables will be created in the database when the extension is loaded. See Database Models for more information.
models/
As an alternative to using models.py, a Python package may be created in a models/ directory, which may contain files with other models. Like any Python module directory, it must also contain an __init__.py.
admin_urls.py

An extension may define URLs for configuration in the administration UI.

This file is only used when is_configurable is set True. For more information, see Configuration URLs.

admin.py

This file allows an extension to register its models in its own section of the administration UI, allowing administrators to browse the content in the database.

This file is only used when has_admin_site is set True. For more information, see Admin Site (Database Browser).