Application Plugins

Cement defines a plugin interface called IPlugin, as well as the default CementPluginHandler that implements the interface.

Please note that there may be other handlers that implement the IPlugin interface. The documentation below only references usage based on the interface and not the full capabilities of the implementation.

The following plugin handlers are included and maintained with Cement:

• CementPluginHandler

Please reference the IPlugin interface documentation for writing your own plugin handler.

Plugin Configuration Settings

There are a few settings related to how plugins are loaded under an applications meta options. These are:

plugins = []

A list of plugins to load. This is generally considered bad practice since plugins should be dynamically enabled/disabled via a plugin config file.

plugin_config_dirs = None

A list of directory paths where plugin config files can be found. Files must end in .conf (or the extension defined by CementApp.Meta.config_extension), or they will be ignored.

Note: Though CementApp.Meta.plugin_config_dirs is None, Cement will set this to a default list based on CementApp.Meta.label. This will equate to:

['/etc/<app_label>/plugins.d', '~/.<app_label>/plugin.d']

Files are loaded in order, and have precedence in that order. Therefore, the last configuration loaded has precedence (and overwrites settings loaded from previous configuration files).

plugin_config_dir = None

A directory path where plugin config files can be found. Files must end in .conf (or the extension defined by CementApp.Meta.config_extension), or they will be ignored. By default, this setting is also overridden by the [<app_label>] -> plugin_config_dir config setting parsed in any of the application configuration files.

If set, this item will be appended to CementApp.Meta.plugin_config_dirs so that it’s settings will have presedence over other configuration files.

In general, this setting should not be defined by the developer, as it is primarily used to allow the end-user to define a plugin_config_dir without completely trumping the hard-coded list of default plugin_config_dirs defined by the app/developer.

plugin_bootstrap = None

A python package (dotted import path) where plugin code can be loaded from. This is generally something like myapp.plugins where a plugin file would live at myapp/plugins/myplugin.py or myapp/plugins/myplugin/__init__.py. This provides a facility for applications that have builtin plugins that ship with the applications source code and live in the same Python module.

Note: Though the meta default is None, Cement will set this to <app_label>.plugins if not set.

plugin_dirs = None

A list of directory paths where plugin code (modules) can be loaded from.

Note: Though CementApp.Meta.plugin_dirs is None, Cement will set this to a default list based on CementApp.Meta.label if not set. This will equate to:

['~/.<app_label>/plugins', '/usr/lib/<app_label>/plugins']

Modules are attempted to be loaded in order, and will stop loading once a plugin is successfully loaded from a directory. Therefore this is the oposite of configuration file loading, in that here the first has precedence.

plugin_dir = None

A directory path where plugin code (modules) can be loaded from. By default, this setting is also overridden by the [<app_label>] -> plugin_dir config setting parsed in any of the application configuration files.

If set, this item will be prepended to Meta.plugin_dirs so that a users defined plugin_dir has precedence over others.

In general, this setting should not be defined by the developer, as it is primarily used to allow the end-user to define a plugin_dir without completely trumping the hard-coded list of default plugin_dirs defined by the app/developer.

Creating a Plugin

A plugin is essentially an extension of a Cement application, that is loaded from an internal or external source location. It is a mechanism for dynamically loading code (whether the plugin is enabled or not). It can contain any code that would normally be part of your application, but should be thought of as optional features, where the core application does not rely on that code to operate.

The following is an example plugin (single file) that provides a number of options and commands via an application controller:

myplugin.py

from cement.core.controller import CementBaseController, expose

class MyPluginController(CementBaseController):
    class Meta:
        label = 'myplugin'
        description = 'this is my controller description'
        stacked_on = 'base'

        config_defaults = dict(
            foo='bar',
            )

        arguments = [
            (['--foo'],
             dict(action='store', help='the infamous foo option')),
            ]

    @expose(help="this is my command description")
    def mycommand(self):
        print 'in MyPlugin.mycommand()'

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

As you can see, this is very similar to an application that has a base controller, however as you’ll note we do not create an application object via foundation.CementApp() like we do in our application. This code/file would then be saved to a location defined by your applications configuration that determines where plugins are loaded from (see the next section).

Notice that all ‘bootstrapping’ code goes in a load() function. This is where registration of handlers/hooks should happen. For convenience, and certain edge cases, the app object is passed here in its current state at the time that load() is called. You do not need to do anything with the app object, but you can.

A plugin also has a configuration file that will be Cement will attempt to find in one of the directories listed in CementApp.Meta.plugin_config_dirs as defined by your application’s configuration. The following is an example plugin configuration file:

myplugin.conf

[myplugin]
enable_plugin = true
foo = bar

Loading a Plugin

Plugin modules are looked for first in one of the defined plugin_dirs, and if not found then Cement attempts to load them from the plugin_bootstrap. The following application shows how to configure an application to load plugins. Take note that these are the default settings and will work the same if not defined:

from cement.core.foundation import CementApp
from cement.core.controller import CementBaseController, expose

class MyBaseController(CementBaseController):
    class Meta:
        label = 'base'
        description = 'MyApp Does Amazing Things'

class MyApp(CementApp):
    class Meta:
        label = 'myapp'
        base_controller = MyBaseController
        plugin_bootstrap='myapp.bootstrap',
        plugin_config_dirs=[
            '/etc/myapp/plugins.d',
            '~/.myapp/plugins.d',
            ]
        plugin_dirs=[
            '/usr/lib/myapp/plugins',
            '~/.myapp/plugins',
            ]


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

if __name__ == '__main__':
    main()

We modified the default settings for plugin_config_dirs and plugin_dirs. These are the default settings under Cementapp, however we have put them here for clarity.

Running this application will do nothing particularly special, however the following demonstrates what happens when we add a simple plugin that provides an application controller:

/etc/myapp/plugins.d/myplugin.conf

[myplugin]
enable_plugin = true
some_option = some value

/usr/lib/myapp/plugins/myplugin.py

from cement.core.controller import CementBaseController, expose
from cement.utils.misc import init_defaults

defaults = init_defaults('myplugin')

class MyPluginController(CementBaseController):
    class Meta:
        label = 'myplugin'
        description = 'this is my plugin description'
        stacked_on = 'base'
        config_defaults = defaults
        arguments = [
            (['--some-option'], dict(action='store')),
            ]

    @expose(help="this is my command description")
    def my_plugin_command(self):
        print 'In MyPlugin.my_plugin_command()'

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

Running our application with the plugin disabled, we see:

$ python myapp.py --help
usage: myapp.py (sub-commands ...) [options ...] {arguments ...}

MyApp Does Amazing Things

optional arguments:
  -h, --help  show this help message and exit
  --debug     toggle debug output
  --quiet     suppress all output

But if we enable the plugin, we get something a little different:

$ python myapp.py --help
usage: myapp.py (sub-commands ...) [options ...] {arguments ...}

MyApp Does Amazing Things

commands:

  my-plugin-command
    this is my command description

optional arguments:
  -h, --help            show this help message and exit
  --debug               toggle debug output
  --quiet               suppress all output
  --some-option SOME_OPTION

We can see that the my-plugin-command and the --some-option option were provided by our plugin, which has been ‘stacked’ on top of the base controller.

User Defined Plugin Configuration and Module Directories

Most applications will want to provide the ability for the end-user to define where plugin configurations and modules live. This is possible by setting the plugin_config_dir and plugin_dir settings in any of the applications configuration files. Note that these paths will be added to the built-in plugin_config_dirs and plugin_dirs settings respectively, rather than completely overwriting them. Therefore, your application can maintain it’s default list of plugin configuration and module paths while also allowing users to define their own.

/etc/myapp/myapp.conf

[myapp]
plugin_dir = /usr/lib/myapp/plugins
plugin_config_dir = /etc/myapp/plugins.d

The plugin_bootstrap setting is however only configurable within the application itself.

What Can Go Into a Plugin?

The above example shows how to add an optional application controller via a plugin, however a plugin can contain anything you want. This could be as simple as adding a hook that does something magical. For example:

from cement.core import hook

def my_magical_hook(app):
    # do something magical
    print('Something Magical is Happening!')

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

And with the plugin enabled, we get this when we run the same app defined above:

$ python myapp.py
Something Magical is Happening!

The primary detail is that Cement calls the load() function of a plugin… after that, you can do anything you like.

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 path. For example:

myplugin/__init__.py

from .controllers import MyPluginController

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

myplugin/controllers.py

from cement.core.controller import CementBaseController, expose

class MyPluginController(CementBaseController):
    class Meta:
        label = 'myplugin'
        stacked_on = 'base'
        stacked_type = 'embedded'

    @expose()
    def my_command(self):
        print('Inside MyPluginController.my_command()')

Loading Templates From Plugin Directories

A common use case for complex applications is to use an output handler the uses templates, such as Mustache, Genshi, Jinja2, etc. In order for a plugin to use it’s own template files it’s templates directory first needs to be added to the list of template directories to be parsed. In the future, this will be more streamlined however currently the following is the recommeded way:

myplugin/__init__.py

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)

The above will append the directory /path/to/myplugin/templates to the list of template directories that the applications output handler with search for template files.