Extension Files/Package Layout¶

Required Files¶

At minimum, an extension requires the following files:

• pyproject.toml

• extensiondir/__init__.py

• extensiondir/extension.py

Let’s go into each of these files and show some examples.

pyproject.toml

This file defines your Python package, its metadata, and the Entry Point used to allow Review Board to find the extension. This is covered in detail in Extension Distribution.

You can learn more about pyproject.toml by reading:

• Writing your pyproject.toml

• Configuring setuptools using pyproject.toml files

Here’s an example pyproject.toml:

[build-system]
requires = [
    # Update this for the target version of Review Board.
    'reviewboard~=7.1',

    'reviewboard[extension-packaging]',
]
build-backend = 'reviewboard.extensions.packaging.backend'


[project]
name = 'sample_extension'
version = '1.0'
description = 'Description of your extension package.'
authors = [
    {name = 'Your Name', email = 'your-email@example.com'}
]

dependencies = [
    # Your package dependencies go here.
    # Don't include "ReviewBoard" in this list.
]

classifiers = [
    # For a full list of package classifiers, see
    # https://pypi.python.org/pypi?%3Aaction=list_classifiers

    'Development Status :: 3 - Alpha',
    'Environment :: Web Framework',
    'Framework :: Review Board',
    'Operating System :: OS Independent',
    'Programming Language :: Python',
]


[project.entry-points."reviewboard.extensions"]
sample_extension = 'sample_extension.extension:SampleExtension'


[tool.setuptools.packages.find]
where = ['.']
namespaces = false

Important

Prior to Review Board 7.1, new extensions would provide a setup.py file instead, and may have only included some basic information in pyproject.toml.

Modern Python packaging requires pyproject.toml. You can keep your existing setup.py or fully convert to pyproject.toml. If you keep your setup.py, make sure to at least add the [build-system] section from above in your pyproject.toml.

sample_extension/__init__.py

This file is needed in order for sample_extension to be a proper Python module. You will generally leave this blank.

sample_extension/extension.py

This is the main module containing your extension, where the bulk of your work will go (at least initially). In here, you’ll define a subclass of Extension, add any metadata, and handle any initialization of extension hooks.

This will look something like:

from reviewboard.extensions.base import Extension


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

Throughout the Extending Review Board guide, we’ll cover the various things you may place in this file.

Optional Files¶

You can put anything you want in your extension’s top-level module directory (and even create nested subdirectories of modules). There’s a few filenames that are special, though.

models.py

An extension can provide custom Django models (which become tables in the database) in this file. The corresponding tables will be created in the database when the extension is loaded. See Database Models for more information.

admin_urls.py

This file is used to define custom URLs in the administration UI. These are often used to create configuration pages for your extension, but they can really be used for any purpose.

This file is only used when is_configurable is set to True.

For more information, see Configuration URLs.

admin.py

This file allows an extension to register its models (from models.py) in its own section of the administration UI. This allows administrators to browse through the content of the models owned by your extension.

This file is only used when has_admin_site is set to True.

For more information, see Adding Models to the Admin Database Browser.