mqtt_gateways.utils package

Module contents

Utilities.

Submodules

mqtt_gateways.utils.throttled_exception module

An exception class that throttles events in case an error is triggered too often.

This exception can be used as a base class instead of Exception. It adds a counter and a timer that allow to silence the error for a while if desired. Only after a given period a trigger is set to indicate that a number of errors have happened and it is time to report them. It creates 2 members:

  • trigger is a boolean set to True after the requested lag;
  • report is a string giving some more information on top of the latest message.

The code using these exceptions can test the member trigger and decide to silence the error until it is True. At any point one can still decide to use these exceptions as normal ones and ignore the trigger and report members.

Usage:

try:
    some statements that might raise your own exception derived from ThrottledException
except YourExceptionError as err:
    if err.trigger:
        log(err.report)
exception mqtt_gateways.utils.throttled_exception.ThrottledException(msg=None, throttlelag=10, module_name=None)

Bases: exceptions.Exception

Exception class base to throttle events

Parameters:
  • msg (string) – the error message, as for usual exceptions, optional
  • throttlelag (int) – the lag time in seconds while errors should be throttled, optional
  • module_name (string) – the calling module to give extra information, optional

mqtt_gateways.utils.init_logger module

Function to initialise a logger with pre-defined handlers.

mqtt_gateways.utils.init_logger.initlogger(logger, logfiledata, emaildata)

The logger passed as parameter should be sent by the ‘root’ module if hierarchical logging is the objective. The logger is then initialised with the following handlers:

  • the standard ‘Stream’ handler will always log level WARN and above;
  • a rotating file handler, with fixed parameters (max 50kB, 3 rollover files); the level for this handler is DEBUG if the parameter ‘log_debug’ is True, INFO otherwise; the file name for this log is given by the log_filepath parameter which is used as is; an error message is logged in the standard handler if there was a problem creating the file;
  • an email handler with the level set to CRITICAL;
Parameters:
  • logger – the actual logger object to be initialised;
  • logfiledata (tuple) –
    [0] = logfilepath (string): the log file path,
    if None, file logging is disabled;
    [1] = log_debug (boolean): a flag to indicate
    if DEBUG logging is required, or only INFO;
    [2] = consolelevel (string): the level of log to be sent
    to the console (stdout), or NONE.
  • emaildata (tuple) –

    [0] = host (string), [1] = port (int), [2] = address (string),

    if either of those 3 values are None or empty, no email logging is enabled;

    [3] = app_name (string).
Returns:

Nothing
Raises:

any IOErrors thrown by file handling methods are caught.

mqtt_gateways.utils.load_config module

Function to facilitate the loading of configuration parameters. Based on ConfigParser.

mqtt_gateways.utils.load_config.loadconfig(cfg_dflt_string, cfg_filepath)

The configuration is loaded with the help of the python library ConfigParser and the following convention.

The default configuration is represented by the string passed as argument cfg_dflt_string. This string is expected to have all the necessary sections and options that the application will need, with their default values. All options need to be listed there, even the ones that HAVE to be updated and have no default value. This default configuration will be usually declared in the caller module as a constant string, and will be used as a template for the actual configuration file.

The function ‘loads’ this default configuration, then checks if the configuration file is available, and if found it grabs only the values from the file that are also present in the default configuration. Anything else in the file is not considered, except for the [INTERFACE] section (see below). The result is a configuration object with all the necessary fields, updated by the file values if present, or with the default values if not. The application can therefore call all fields without index errors.

The exception to the above process in the [INTERFACE] section. The options of this section will be loaded ‘as is’ in the Config object. This section can be used to define ad-hoc options that are not in the default configuration.

Finally, the function updates the option ‘location’ in the section [CONFIG] with the full path of the configuration file used, just in case it is needed later. However it only updates it if it was present in the default configuration string, in the spirit of the above convention. It also ‘logs’ the error in the ‘error’ option of the same section, if any OS exception occurred while opening or reading the configuration file.

Parameters:
  • cfg_dflt_string (string) – represents the default configuration.
  • cfg_filepath (string) – the path of the configuration file; it is used ‘as is’ and if it is relative there is no guarantee of where it will actually point.
Returns:

object loaded with the parameters.
Return type:

ConfigParser.RawConfigParser object