File Layout¶

Required Files¶

At minimum, an extension requires the following files:

• setup.py
• extensiondir/__init__.py
• extensiondir/extension.py

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).