Cement core handler module.

class cement.core.handler.Handler(**kw)[source]

Bases: abc.ABC, cement.core.meta.MetaMixin

Base handler class that all Cement Handlers should subclass from.

class Meta[source]

Bases: object

Handler meta-data (can also be passed as keyword arguments to the parent class).

config_defaults = None

A config dictionary that is merged into the applications config in the [<config_section>] block. These are defaults and do not override any existing defaults under that section.

config_section = None

A config section to merge config_defaults with.

Note: Though App.Meta.config_section defaults to None, Cement will set this to the value of <interface_label>.<handler_label> if no section is set by the user/developer.

interface = NotImplemented

The interface that this class implements.

label = NotImplemented

The string identifier of this handler.

overridable = False

Whether or not handler can be overridden by App.Meta.handler_override_options. Will be listed as an available choice to override the specific handler (i.e. App.Meta.output_handler, etc).


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.

Parameters:app (instance) – The application object.

Perform any validation to ensure proper data, meta-data, etc.

class cement.core.handler.HandlerManager(app)[source]

Bases: object

Manages the handler system to define, get, resolve, etc handlers with the Cement Framework.

get(interface, handler_label, fallback=None, **kwargs)[source]

Get a handler object.

  • interface (str) – The interface of the handler (i.e. output)
  • handler_label (str) – The label of the handler (i.e. json)
  • fallback (Handler) – A fallback value to return if handler_label doesn’t exist.
Keyword Arguments:

setup (bool) – Whether or not to call setup() on the handler before returning. This will not be called on the fallback if no the handler given does not exist.


An uninstantiated handler object

Return type:



cement.core.exc.InterfaceError – If the interface does not exist, or if the handler itself does not exist.


_handler = app.handler.get('output', 'json')
output = _handler()

Return a list of handlers for a given interface.

Parameters:interface (str) – The interface of the handler (i.e. output)
Returns:Handler labels (str) that match interface.
Return type:list
Raises:cement.core.exc.InterfaceError – If the interface does not exist.


register(handler_class, force=False)[source]

Register a handler class to an interface. If the same object is already registered then no exception is raised, however if a different object attempts to be registered to the same name a InterfaceError is raised.


handler_class (Handler) – The uninstantiated handler class to register.

Keyword Arguments:
  • force (bool) – Whether to allow replacement if an existing
  • of the same label is already registered. (handler) –


class MyDatabaseHandler(object):
    class Meta:
        interface = IDatabase
        label = 'mysql'

    def connect(self):
        # ...

registered(interface, handler_label)[source]

Check if a handler is registered.

  • interface (str) – The interface of the handler (interface label)
  • handler_label (str) – The label of the handler

True if the handler is registered, False otherwise

Return type:



app.handler.registered('log', 'colorlog')
resolve(interface, handler_def, **kwargs)[source]

Resolves the actual handler, as it can be either a string identifying the handler to load from self.__handlers__, or it can be an instantiated or non-instantiated handler class.

  • interface (str) – The interface of the handler (ex: output)
  • handler_def (str,instance,Handler) – The loose references of the handler, by label, instantiated object, or non-instantiated class.
Keyword Arguments:
  • raise_error (bool) – Whether or not to raise an exception if unable to resolve the handler.
  • meta_defaults (dict) – Optional meta-data dictionary used as defaults to pass when instantiating uninstantiated handlers. Use App.Meta.meta_defaults by default.
  • setup (bool) – Whether or not to call .setup() before return. Default: False

The instantiated handler object.

Return type:



# via label (str)
log = app.handler.resolve('log', 'colorlog')

# via uninstantiated handler class
log = app.handler.resolve('log', ColorLogHanddler)

# via instantiated handler instance
log = app.handler.resolve('log', ColorLogHandler())

Setup a handler class so that it can be used.

Parameters:handler_class (class) – An uninstantiated handler class.

Returns: None


for controller in app.handler.list('controller'):
    ch = app.handler.setup(controller)