`cement.core.handler`

Cement core handler module.

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

Bases: ABC, 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: Dict[str, Any] | None = 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: str = 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: str = NotImplemented: The interface that this class implements.

label: str = NotImplemented: The string identifier of this handler.

overridable: bool = 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: App) → None[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() → None[source]: Perform any validation to ensure proper data, meta-data, etc.

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

Bases: object

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

get(interface: str, handler_label: str, fallback: Type[Handler] | None = None, **kwargs: Any) → Handler | Type[Handler][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: str) → List[Type[Handler]][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: Type[Handler], force: bool = False) → None[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
registered. (handler of the same label is already)

Raises:

cement.core.exc.InterfaceError – If the handler_class does not implement Handler, or if handler_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: str, handler_label: str) → bool[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: str, handler_def: str | Handler | Type[Handler], **kwargs: Any) → Handler | None[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: Type[Handler]) → Handler[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)

cement.core.handler

`cement.core.handler`