Application Plugins

Introduction to the Plugin Interface

Cement defines a Plugin Interface, as well as the default CementPluginHandler that implements the interface.

Cement often includes multiple handler implementations of an interface that may or may not have additional features or functionality than the interface requires. The documentation below only references usage based on the interface and default handler (not the full capabilities of an implementation).

Cement Extensions that Provide Plugin Handlers:

• Plugin

API References:

• Cement Core Plugin Module

Configuration

Application Configuration Settings

The following settings under the application's primary configuration section modify plugin handling:

Setting	Description
plugin_dir	A directory path where plugin code can be found. Will be prepended to App.Meta.plugin_dirs

Application Meta Options:

The following options under App.Meta modify plugin handling:

Option	Description
plugins	A hardcoded list of plugins to load. In general, application plugins should be dynamically enabled/disabled via the application's configuration files. However, some application designs may prefer to always load specific builtin plugins. Default: []
config_dirs	Plugin configuration files are loaded from any discovered application configuration directories.
plugin_module	A python module (dotted import path) where plugin code can be loaded from instead of external directories (builtin plugins shipped with the application code). Default: myapp.plugins
plugin_dirs	A list of directory paths where plugin code (modules) can be loaded from (external to the application). Will be merged with App.Meta.core_system_plugin_dirs and App.Meta.core_user_plugin_dirs. Default: []

Working with Plugins

The plugin handler can be used to access information about loaded plugins, as well as manually loading plugins if necessary.

Example: Working with Extensions

from cement import App

with App('myapp') as app:
    # list loaded plugins
    app.plugin.get_loaded_plugins()

    # list enabled plugins
    app.plugin.get_enabled_plugins()

    # list disabled plugins
    app.plugin.get_disabled_plugins()

    # load a plugin
    app.plugin.load_plugin('myplugin')

    # load a list of plugins
    app.plugin.load_plugins(['myplugin1',
                             'myplugin2'])

Creating a Plugin

The plugin system is a mechanism for dynamically loading code to extend the functionality of a specific application. In general, this includes the registration of interfaces, handlers, and/or hooks but can include controllers, command-line options, or anything else.

The preferred method of creating a plugin would be via the included developer tools:

$ cement generate plugin /path/to/myapp/plugins

This will produce an example plugin directory like the following:

├── __init__.py
├── controllers
│   ├── __init__.py
│   └── myplugin.py
└── templates
    ├── __init__.py
    └── plugins
        └── myplugin
            └── command1.jinja2

The example plugin includes a controller, sub-command, and output generated via Jinja2 template. That said, the only thing Cement needs is a load() function.... everything else is arbitrary. In the generated plugin, we find this in myplugin/__init__.py:

import os
from .controllers.myplugin import MyPlugin

def add_template_dir(app):
    path = os.path.join(os.path.dirname(__file__), 'templates')
    app.add_template_dir(path)

def load(app):
    app.handler.register(MyPlugin)
    app.hook.register('post_setup', add_template_dir)

Plugins can provide anything from defining interfaces, registering hooks, or even adding command line sub-commands and arguments. The only thing required to make up a plugin is a load() function in myplugin.py or myplugin/__init__.py files.

You will notice that plugins are essentially the same as framework extensions. The difference is found both in when/how the code is loaded, as well as the purpose of that code.

Framework extensions add functionality to the framework for the application to utilize, whereas application plugins extend the functionality of the application itself.

Loading a Plugin

Plugin modules are discovered and loaded in the following order:

• From directories listed in App.Meta.plugin_dirs

• From the python path defined in App.Meta.plugin_module

In order for the framework to know about a plugin, it must be defined in the application's configuration settings under its designated section of plugin.myplugin. This configuration block can live in any application configuration file, including files loaded from configuration dirs (ex: /etc/myapp/plugin.d/myplugin.conf).

Example: Loading a Plugin

myapp.py

from cement import App

class MyApp(App):
    class Meta:
        label = 'myapp'
        plugin_dirs = ['./plugins']

with MyApp() as app:
    app.run()

plugins/myplugin.py

def load(app):
    print('Inside MyPlugin!')

cli

$ python myapp.py
Inside MyPlugin!
...

If a plugin configuration is found, its settings will be loaded into the app. However, the plugin will only be loaded if it is enabled:

[myapp]
# ...

[plugin.myplugin]
enabled: true

Single File Plugins vs. Plugin Directories

As of Cement 2.9.x, plugins can be either a single file (i.e myplugin.py) or a python module directory (i.e. myplugin/__init__.py). Both will be loaded and executed the exact same way.

One caveat, however, is that the submodules referenced from within a plugin directory must be relative paths. For example:

Example: Loading Submodules in a Plugin

myplugin/__init__.py

from .controllers import MyPluginController

def load(app):
    app.handler.register(MyPluginController)

This will ensure that Python will properly load the sub-modules regardless of where they live on the filesystem (or within a project's own modules, etc).

Loading Templates From Plugin Directories

In order for a plugin to use its own template files, its templates directory first needs to be registered with the app. We accomplish this with a post_setup hook:

Example: Registering Plugin Template Directories

myplugin/__init__.py

import os

def add_template_dir(app):
    path = os.path.join(os.path.basename(self.__file__, 'templates')
    app.add_template_dir(path)

​def load(app):
    app.hook.register('post_setup', add_template_dir)

Creating a Plugin Handler

All interfaces in Cement can be overridden with your own implementation. This can be done either by sub-classing PluginHandler itself, or by sub-classing an existing extension's handlers in order to alter their functionality.

Example: Creating a Plugin Handler

myapp.py

from cement import App
from cement.core.plugin import PluginHandler

class MyPluginHandler(PluginHandler):
    class Meta:
        label = 'my_plugin_handler'

    # do something to implement the interface

class MyApp(App):
    class Meta:
        label = 'myapp'
        plugin_handler = 'my_plugin_handler'
        handlers = [
            MyPluginHandler,
        ]