Interfaces and Handlers

Cement has a unique interface and handler system that is used to break up pieces of the framework and allow customization of how Cement handles everything from logging to config file parsing, and almost every action in between.

The Cement Interface code is loosely modeled after Zope Interface which allows a developer to define an interface that other developers can then create implementations for. For example, an interface might define that a class have a function called _setup(). Any implementation of that interface must provide a function called _setup(), and perform the expected actions when called.

In Cement, we call the implementation of interfaces handlers and provide the ability to easily register, and retrieve them via the app.

API References:

• Cement Interface Module
• Cement Handler Module

Defining an Interface

Cement uses interfaces and handlers extensively to manage the framework, however developers can also make use of this system to provide a clean, and standardized way of allowing other developers to customize their application.

The following defines a basic interface:

from cement.core.foundation import CementApp
from cement.core.interface import Interface, Attribute

class MyInterface(Interface):
    class IMeta:
        label = 'myinterface'

    # Must be provided by the implementation
    Meta = Attribute('Handler Meta-data')
    my_var = Attribute('A variable of epic proportions.')

    def _setup(app_obj):
        """
        The setup function is called during application initialization and
        must 'setup' the handler object making it ready for the framework
        or the application to make further calls to it.

        Required Arguments:

            app_obj
                The application object.

        Returns: n/a

        """

    def do_something():
        """
        This function does something.

        """

class MyApp(CementApp):
    class Meta:
        label = 'myapp'
        define_handlers = [MyInterface]

Alternatively, if you need more control you might define a handler this way:

from cement.core.foundation import CementApp

with CementApp('myapp') as app:
    # define interfaces after app is created
    app.handler.define(MyInterface)

    app.run()

The above simply defines the interface. It does not implement any functionality, and can’t be used directly. This is why the class functions do not have an argument of self, nor do they contain any code other than comments.

That said, what is required is an IMeta class that is used to interact with the interface. At the very least, this must include a unique label to identify the interface. This can also be considered the ‘handler type’. For example, the ILog interface has a label of log and any handlers registered to that interface are stored in HandlerManager.__handlers__['log'].

Notice that we defined Meta and my_var as Interface Attributes. This is a simple identifier that describes an attribute that an implementation is expected to provide.

Validating Interfaces

A validator call back function can be defined in the interfaces IMeta class like this:

from cement.core import interface

def my_validator(klass, obj):
    members = [
        '_setup',
        'do_something',
        'my_var',
        ]
    interface.validate(MyInterface, obj, members)

class MyInterface(interface.Interface):
    class IMeta:
        label = 'myinterface'
        validator = my_validator
    ...

When CementApp.handler.register() is called to register a handler to an interface, the validator is called and the handler object is passed to the validator. In the above example, we simply define what members we want to validate for and then call interface.validate() which will raise cement.core.exc.InterfaceError if validation fails. It is not necessary to use interface.validate() but it is useful and recommended. In general, the key thing to note is that a validator either raises InterfaceError or does nothing if validation passes.

Registering Handlers to an Interface

An interface simply defines what an implementation is expected to provide, where a handler actually implements the interface. The following example is a handler that implements the MyInterface above:

from cement.core.foundation import CementApp
from cement.core.handler import CementBaseHandler
from myapp.interfaces import MyInterface

class MyHandler(CementBaseHandler):
    class Meta:
        interface = MyInterface
        label = 'my_handler'
        description = 'This handler implements MyInterface'
        config_defaults = dict(
            foo='bar'
            )

    my_var = 'This is my var'

    def __init__(self):
        self.app = None

    def _setup(self, app_obj):
        self.app = app_obj

    def do_something(self):
        print "Doing work!"

class MyApp(CementApp):
    class Meta:
        label = 'myapp'
        handlers = [MyHandler]

Alternatively, if you need more control you might use this approach:

from cement.core.foundation import CementApp

with CementApp('myapp') as app:
    # register handler after the app is created
    app.handler.register(MyHandler)

    app.run()

The above is a simple class that meets all the expectations of the interface. When calling CementApp.handler.register(), MyHandler is passed to the validator (if defined in the interface) and if it passes validation will be registered into HandlerManager.__handlers__.

Using Handlers

The following are a few examples of working with handlers:

from cement.core.foundation import CementApp

with CementApp('myapp') as app:
    # Get a log handler called 'logging'
    lh = app.handler.get('log', 'logging')

    # Instantiate the handler class, passing any keyword arguments that
    # the handler supports.
    log = log_handler()

    # Setup the handler, passing it the app object.
    log._setup(app)

    # List all handlers of type 'config'
    app.handler.list('config')

    # Check if an interface called 'output' is defined
    app.handler.defined('output')

    # Check if the handler 'argparse' is registered to the 'argument'
    # interface
    app.handler.registered('argument', 'argparse')

It is important to note that handlers are stored with the app as uninstantiated objects. Meaning you must instantiate them after retrieval, and call _setup(app) when using handlers directly (as in the above example).

Overriding Default Handlers

Cement sets up a number of default handlers for logging, config parsing, etc. These can be overridden in a number of ways. The first way is by passing them as keyword arguments to CementApp:

from cement.core.foundation import CementApp
from myapp.log import MyLogHandler

# Create the application
app = CementApp('myapp', log_handler=MyLogHandler)
app.setup()
app.run()
app.close()

The second way to override a handler is by setting it directly in the CementApp meta data:

from cement.core.foundation import CementApp
from myapp.log import MyLogHandler

class MyApp(CementApp):
    class Meta:
        label = 'myapp'
        log_handler = MyLogHandler

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

There are times that you may want to pre-instantiate handlers before passing them to CementApp(). The following works just the same:

from cement.core.foundation import CementApp
from myapp.log import MyLogHandler

my_log = MyLogHandler(some_param='some_value')

class MyApp(CementApp):
    class Meta:
        label = 'myapp'
        log_handler = my_log

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

To see what default handlers can be overridden, see the cement.core.foundation documentation.

Multiple Registered Handlers

All handlers and interfaces are unique. In most cases, where the framework is concerned, only one handler is used. For example, whatever is configured for the log_handler will be used and setup as app.log. However, take for example an Output Handler. You might have a default output_handler of mustache’ (a text templating language) but may also want to override that handler with the json output handler when -o json is passed at command line. In order to allow this functionality, both the mustache and json output handlers must be registered.

Any number of handlers can be registered to an interface. You might have a use case for an Interface/Handler that may provide different compatibility base on the operating system, or perhaps based on simply how the application is called. A good example would be an application that automates building packages for Linux distributions. An interface would define what a build handler needs to provide, but the build handler would be different based on the OS. The application might have an rpm build handler, or a dpkg build handler to perform the build process differently.

Customizing Handlers

The most common way to customize a handler is to subclass it, and then pass it to CementApp:

from cement.core.foundation import CementApp
from cement.lib.ext_logging import LoggingLogHandler

class MyLogHandler(LoggingLogHandler):
    class Meta:
        label = 'mylog'

    def info(self, msg):
        # do something to customize this function, here...
        super(MyLogHandler, self).info(msg)

app = CementApp('myapp', log_handler=MyLogHandler)

Handler Default Configuration Settings

All handlers can define default config file settings via their config_defaults meta option. These will be merged into the app.config under the [handler_interface].[handler_label] section. These settings are overridden in the following order.

• The config_defaults dictionary passed to CementApp
• Via any application config files with a [handler_interface].[handler_type] block (i.e. cache.memcached)

The following shows how to override defaults by passing them with the defaults dictionary to CementApp:

from cement.core import foundation
from cement.utils.misc import init_defaults

defaults = init_defaults('myinterface.myhandler')
defaults['myinterface.myhandler'] = dict(foo='bar')
app = foundation.CementApp('myapp', config_defaults=defaults)

Cement will use all defaults set via MyHandler.Meta.config_defaults (for this example), and then override just what is passed via config_defaults['myinterface.myhandler']. You should use this approach only to modify the global defaults for your application. The second way is to then set configuration file defaults under the [myinterface.myhandler] section. For example:

my.config

[myinterface.myhandler]
foo = bar

In the real world this may look like [cache.memcached], or [database.mysql] depending on what the interface label, and handler label’s are. Additionally, individual handlers can override their config section by setting Meta.config_section.

Overriding Handlers Via Command Line

In some use cases, you will want the end user to have access to override the default handler of a particular interface. For example, Cement ships with multiple Output Handlers including json, yaml, and mustache. A typical application might default to using mustache to render console output from text templates. That said, without changing any code in the application, the end user can simply pass the -o json command line option and output the same data that is rendered to template, out in pure JSON.

The only built-in handler override that Cement includes is for the above mentioned example, but you can add any that your application requires.

The following example shows this in action… note that the following is already setup by Cement, but we’re putting it here for clarity:

from cement.core.foundation import CementApp

class MyApp(CementApp):
    class Meta:
        label = 'myapp'

        # define what extensions we want to load
        extensions = ['mustache', 'json', 'yaml']

        # define our default output handler
        output_handler = 'mustache'

        # define our handler override options
        handler_override_options = dict(
            output = (['-o'], dict(help='output format')),
            )


with MyApp() as app:
    # run the application
    app.run()

    # define some data for the output handler
    data = dict(foo='bar')

    # render something using out output handlers, using mustache by
    # default which will use the default.m templae
    app.render(data, 'default.m')

Note what we see at command line:

$ python myapp.py --help
usage: myapp.py [-h] [--debug] [--quiet] [-o {yaml,json}]

optional arguments:
  -h, --help      show this help message and exit
  --debug         toggle debug output
  --quiet         suppress all output
  -o {yaml,json}  output format

Notice the -o command line option, that includes the choices: yaml and json. This feature will include all Output Handlers that have the overridable meta-data option set to True. The MustacheOutputHandler does not set this option, therefore it does not show up as a valid choice.

Now what happens when we run it?

$ python myapp.py

This text is being rendered via Mustache.
The value of the 'foo' variable is => 'bar'

The above is the default output, using mustache as our output_handler, and rendering the output text from a template called default.m. We can now override the output handler using the -o option and modify the output format:

$ python myapp.py -o json
{"foo": "bar"}

Again, any handler can be overridden in this fashion.