cement.core.handler
Cement core handler module.
- class cement.core.handler.Handler(**kw)[source]
-
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 toNone
, 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).
- 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:
- Keyword Arguments:
setup (bool) – Whether or not to call
setup()
on the handler before returning. This will not be called on thefallback
if no the handler given does not exist.- Returns:
An uninstantiated handler object
- Return type:
- 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:
- 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:
- Raises:
cement.core.exc.InterfaceError – If the
handler_class
does not implementHandler
, or ifhandler_class
does not properly sub-class it’s interface.cement.core.exc.InterfaceError – If the
handler_class.Meta.interface
does not exist
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:
- Returns:
True
if the handler is registered,False
otherwise- Return type:
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:
- 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())