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

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