Plugins

Using abc and stevedore to write plugins

Introduction

e3-core is designed to be small and to be easy to configure and extend by loading external code dynamically. In order to discover and load the plugins at runtime e3-core uses setuptools entry points. To ease the management of the plugins and avoid hard to detect errors, the e3 project uses stevedore and abc.

An entry point is a way to reference an object defined in another Python package. In e3 these objects are classes derived from an abstract base class (using abc) defining the plugin interface.

Namespaces

The namespace for e3 entry point are all prefixed with e3. in order to avoid polluting the namespace.

e3-core plugins

e3-core defines and uses the following plugins interface:

e3-sandbox

The command line actions for e3-sandbox can be provided by external plugins registered in the e3.anod.sandbox.sandbox_action namespace. To add another action subclass :class::e3.anod.sandbox.SandBoxAction and reference your new class in the e3.anod.sandbox.sandbox_action entry points namespace.

Example

In a package e3-contrib, define a new class:

class SandBoxActionExample(e3.anod.sandbox.SandBoxAction):

    name = 'example'
    help = 'An example of e3-sandbox action'

    def add_parser(self):
        self.parser.add_argument(
            '--another-command-line')

    def run(self.args):
        sandbox = e3.anod.sandbox.SandBox()
        sandbox.root_dir = args.sandbox

        # Run any action on the sandbox
        # ...

Then register it in e3-contrib/setup.py:

entry_points={
    'e3.anod.sandbox.sandbox_action': [
        'example = e3.contrib.sandbox.SandBoxActionExample',
]}