cement.core.handler

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

_setup(app)[source]

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.
_validate()[source]

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.

Parameters:
  • 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.

Returns:

An uninstantiated handler object

Return type:

Handler

Raises:

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

Example

_handler = app.handler.get('output', 'json')
output = _handler()
output._setup(app)
output.render(dict(foo='bar'))
list(interface)[source]

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.

Example

app.handler.list('log')
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.

Parameters:

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) –
Raises:

Usage:

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

    def connect(self):
        # ...

app.handler.register(MyDatabaseHandler)
registered(interface, handler_label)[source]

Check if a handler is registered.

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

True if the handler is registered, False otherwise

Return type:

bool

Example

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.

Parameters:
  • 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
Returns:

The instantiated handler object.

Return type:

instance

Example

# 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(handler_class)[source]

Setup a handler class so that it can be used.

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

Returns: None

Example

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