# This Source Code Form is subject to the terms of the Mozilla Public
# License, v. 2.0. If a copy of the MPL was not distributed with this
# file, You can obtain one at http://mozilla.org/MPL/2.0/.

from __future__ import absolute_import, unicode_literals

import logging


class LoggingMixin(object):
    """Provides functionality to control logging."""

    def populate_logger(self, name=None):
        """Ensure this class instance has a logger associated with it.

        Users of this mixin that call log() will need to ensure self._logger is
        a logging.Logger instance before they call log(). This function ensures
        self._logger is defined by populating it if it isn't.
        """
        if hasattr(self, '_logger'):
            return

        if name is None:
            name = '.'.join([self.__module__, self.__class__.__name__])

        self._logger = logging.getLogger(name)

    def log(self, level, action, params, format_str):
        """Log a structured log event.

        A structured log event consists of a logging level, a string action, a
        dictionary of attributes, and a formatting string.

        The logging level is one of the logging.* constants, such as
        logging.INFO.

        The action string is essentially the enumeration of the event. Each
        different type of logged event should have a different action.

        The params dict is the metadata constituting the logged event.

        The formatting string is used to convert the structured message back to
        human-readable format. Conversion back to human-readable form is
        performed by calling format() on this string, feeding into it the dict
        of attributes constituting the event.

        Example Usage
        -------------

        self.log(logging.DEBUG, 'login', {'username': 'johndoe'},
            'User login: {username}')
        """
        self._logger.log(level, format_str,
            extra={'action': action, 'params': params})