Framework Extensions

Introduction to the Extension Interface

Cement defines an Extension Interface, as well as the default CementExtensionHandler that implements the interface. Its purpose is to manage loading framework extensions and making them usable by the application. Extensions are similar to Application Plugins, but at the framework level (application agnostic).

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

As of Cement 2.1.3, optional extensions with external dependencies are now being shipped along with mainline sources. This means that although Cement Core continues to maintain a 100% zero dependency policy, Framework Extensions can rely on external deps. It is the responsibility of the application developer to include these dependencies in their application (as the Cement package does not include these dependencies).

API References:

• Cement Core Extension Module

Configuration

Application Meta Options

The following options under App.Meta modify extension handling:

Option	Description
extension_handler	A handler class that implements the Extension Interface. This can be a string (label of a registered handler), an uninstantiated class, or an instantiated class object. Default: ExtensionHandler
extensions	A list of additional framework extensions to load. Will be merged together with App.Meta.core_extensions.

Working with Extensions

In general, extensions are only loaded and accessed by the framework. That said the extension handler can be used to access information about loaded extensions, as well as manually load extensions if necessary.

Example: Working with Extensions

from cement import App

with App('myapp') as app:
    # list loaded extensions
    app.ext.list()

    # load an extension
    app.ext.load_extension('myapp.ext.myextension')

    # load a list of extensions
    app.ext.load_extensions(['myapp.ext.ext1',
                             'myapp.ext.ext2'])

Creating an Extension

The extension system is a mechanism for dynamically loading code to extend the functionality of the framework. 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 an extension would be via the included developer tools:

$ cement generate extension /path/to/myapp/ext

This would produce something like the following:

Example: Creating an Extension

myapp/ext/ext_myextension.py

from cement import minimal_logger

LOG = minimal_logger(__name__)

def myextension_pre_run_hook(app):
    # do something with app
    LOG.debug('Inside myextension_pre_run_hook!')

def load(app):
    # do something to extend cement
    app.hook.register('pre_run', myextension_pre_run_hook)

Extensions can provide anything from defining interfaces, registering hooks, or even adding command line arguments. The only thing required to make up an extension is the load() function.

You will notice that extensions are essentially the same as application plugins. 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 Extensions

Extensions are loaded when App.setup() is called on an application. Cement automatically loads all extensions listed under the application's App.Meta.core_extensions and App.Meta.extensions meta options.

To load the above example into our application, we just add it to the list of App.Meta.extensions. Let's assume the extension code lives in myapp/ext/ext_myextension.py:

Example: Loading Extensions

from cement import App

class MyApp(App):
    class Meta:
        label = 'myapp'
        extensions = 'myapp.ext.ext_myextension'

Note that Cement provides a shortcut for its own builtin extensions so that you can refer to extensions via their short name (ex: json instead of cement.ext.ext_json). All other extensions must be referenced by their full dotted Python module name.

Loading Extensions via a Configuration File

Some use cases may require that end-users be able to modify what framework extensions are loaded depending on the needs of the application, while most extensions are defined by the developer to support key features.

The following example demonstrates an application loading extensions defined via the extensions setting under the application's configuration settings.

Example: Loading Extensions via Configuration File

myapp.py

from cement import App

with App('myapp') as app:
    app.run()

    for e in app.extension.list():
        print(e)

~/.myapp.conf

[myapp]
exensions = json, yaml, myapp.ext.ext_myextension

cli

$ python myapp.py
cement.ext.ext_dummy
cement.ext.ext_smtp
cement.ext.ext_plugin
cement.ext.ext_configparser
cement.ext.ext_logging
cement.ext.ext_argparse
cement.ext.ext_json
cement.ext.ext_yaml
myapp.ext.ext_myextension

Note that extensions loaded in this way will happen after the config handler is setup. Normally, extensions are loaded just before the configuration files are read. Therefore, some extensions may not be compatible with this method if they attempt to perform any actions before app.setup() completes (such as in early framework hooks before configuration files are loaded).