cement.core.handler

Cement core handler module.

class cement.core.handler.CementBaseHandler(**kw)

Bases: cement.core.meta.MetaMixin

Base handler class that all Cement Handlers should subclass from.

class Meta

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 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 = None

The interface that this class implements.

label = None

The string identifier of this handler.

overridable = False

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

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

Parameters:app_obj – The application object.
Returns:None
class cement.core.handler.HandlerManager(use_backend_globals=False)

Bases: object

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

Parameters:use_backend_globals – Whether to use backend globals (backward compatibility and deprecated).
define(interface)

Define a handler based on the provided interface. Defines a handler type based on <interface>.IMeta.label.

Parameters:interface – The interface class that defines the interface to be implemented by handlers.
Raises:cement.core.exc.InterfaceError
Raises:cement.core.exc.FrameworkError

Usage:

app.handler.define(IDatabaseHandler)
defined(handler_type)

Test whether handler_type is defined.

Parameters:handler_type – The name or handler_type of the handler (I.e. log, config, output, etc).
Returns:True if the handler type is defined, False otherwise.
Return type:boolean

Usage:

app.handler.defined('log')
get(handler_type, handler_label, *args)

Get a handler object.

Parameters:
  • handler_type (str) – The type of handler (i.e. output)
  • handler_label (str) – The label of the handler (i.e. json)
  • fallback – A fallback value to return if handler_label doesn’t exist.
Returns:

An uninstantiated handler object

Raises:

cement.core.exc.FrameworkError

Usage:

output = app.handler.get('output', 'json')
output.render(dict(foo='bar'))
list(handler_type)

Return a list of handlers for a given handler_type.

Parameters:handler_type – The type of handler (i.e. output)
Returns:List of handlers that match hander_type.
Return type:list
Raises:cement.core.exc.FrameworkError

Usage:

app.handler.list('log')
list_types()

Return a list of handler types (interface labels).

Returns:List of handlers types (interface labels).
Return type:list
Raises:cement.core.exc.FrameworkError

Usage:

app.handler.list_types()
register(handler_obj, force=False)

Register a handler object to a handler. 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 FrameworkError is raised.

Parameters:
  • handler_obj – The uninstantiated handler object to register.
  • force – Whether to allow replacement if an existing handler of the same label is already registered.
Raises:

cement.core.exc.InterfaceError

Raises:

cement.core.exc.FrameworkError

Usage:

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

    def connect(self):
        # ...

app.handler.register(MyDatabaseHandler)
registered(handler_type, handler_label)

Check if a handler is registered.

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

True if the handler is registered, False otherwise

Return type:

boolean

Usage:

app.handler.registered('log', 'colorlog')
resolve(handler_type, handler_def, **kwargs)

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:
  • handler_type – The type of handler (aka the interface label)
  • handler_def (str, uninstantiated object, or instantiated object) – The handler as defined in CementApp.Meta.
  • raise_error (boolean) – Whether or not to raise an exception if unable to resolve the handler.
Keywork meta_defaults:
 

Optional meta-data dictionary used as defaults to pass when instantiating uninstantiated handlers. See CementApp.Meta.meta_defaults.

Returns:

The instantiated handler object.

Usage:

# 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())
cement.core.handler.define(interface)

DEPRECATION WARNING: This function is deprecated as of Cement 2.7.x and will be removed in future versions of Cement. Use CementApp.handler.define() instead.

Define a handler based on the provided interface. Defines a handler type based on <interface>.IMeta.label.

Parameters:interface – The interface class that defines the interface to be implemented by handlers.
Raises:cement.core.exc.InterfaceError
Raises:cement.core.exc.FrameworkError

Usage:

from cement.core import handler

handler.define(IDatabaseHandler)
cement.core.handler.defined(handler_type)

DEPRECATION WARNING: This function is deprecated as of Cement 2.7.x and will be removed in future versions of Cement. Use CementApp.handler.defined() instead.

Test whether a handler type is defined.

Parameters:handler_type – The name or ‘type’ of the handler (I.e. ‘logging’).
Returns:True if the handler type is defined, False otherwise.
Return type:boolean
cement.core.handler.get(handler_type, handler_label, *args)

DEPRECATION WARNING: This function is deprecated as of Cement 2.7.x and will be removed in future versions of Cement. Use CementApp.handler.get() instead.

Get a handler object.

Required Arguments:

Parameters:
  • handler_type (str) – The type of handler (i.e. ‘output’)
  • handler_label (str) – The label of the handler (i.e. ‘json’)
  • fallback – A fallback value to return if handler_label doesn’t exist.
Returns:

An uninstantiated handler object

Raises:

cement.core.exc.FrameworkError

Usage:

from cement.core import handler output = handler.get(‘output’, ‘json’) output.render(dict(foo=’bar’))
cement.core.handler.list(handler_type)

DEPRECATION WARNING: This function is deprecated as of Cement 2.7.x and will be removed in future versions of Cement. Use CementApp.handler.list() instead.

Return a list of handlers for a given type.

Parameters:handler_type – The type of handler (i.e. ‘output’)
Returns:List of handlers that match type.
Return type:list
Raises:cement.core.exc.FrameworkError
cement.core.handler.register(handler_obj, force=False)

DEPRECATION WARNING: This function is deprecated as of Cement 2.7.x and will be removed in future versions of Cement. Use CementApp.handler.register() instead.

Register a handler object to a handler. 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 FrameworkError is raised.

Parameters:
  • handler_obj – The uninstantiated handler object to register.
  • force – Whether to allow replacement if an existing handler of the same label is already registered.
Raises:

cement.core.exc.InterfaceError

Raises:

cement.core.exc.FrameworkError

Usage:

from cement.core import handler

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

    def connect(self):
    ...

handler.register(MyDatabaseHandler)
cement.core.handler.registered(handler_type, handler_label)

DEPRECATION WARNING: This function is deprecated as of Cement 2.7.x and will be removed in future versions of Cement. Use CementApp.handler.registered() instead.

Check if a handler is registered.

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

True if the handler is registered, False otherwise

Return type:

boolean

cement.core.handler.resolve(handler_type, handler_def, raise_error=True)

DEPRECATION WARNING: This function is deprecated as of Cement 2.7.x and will be removed in future versions of Cement. Use CementApp.handler.resolve() instead.

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

Parameters:
  • handler_type – The type of handler (aka the interface label)
  • hander_def – The handler as defined in CementApp.Meta.
  • raise_error (boolean) – Whether or not to raise an exception if unable to resolve the handler.
Returns:

The instantiated handler object.