# `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.