7.2.4. mqttgateway.utils package¶

7.2.4.1. Submodules¶

7.2.4.2. mqttgateway.utils.app_properties module¶

Application wide properties.

This module is an alternative to a singleton. It keeps some application variables in the module namespace making them effectively global. At startup, the module should be imported straight away so that it creates an AppProperties object called Properties that is global, and initialised with mostly empty values, except the init attribute which is essentially the constructor.

class mqttgateway.utils.app_properties.AppProperties(name, directories, config_file_path, root_logger, init, get_path, get_logger)¶

Bases: tuple

config_file_path¶: Alias for field number 2

directories¶: Alias for field number 1

get_logger¶: Alias for field number 6

get_path¶: Alias for field number 5

init¶: Alias for field number 4

name¶: Alias for field number 0

root_logger¶: Alias for field number 3

7.2.4.3. mqttgateway.utils.init_logger module¶

Function to initialise a logger with pre-defined handlers.

mqttgateway.utils.init_logger.initlogger(logger, logfiledata, emaildata)¶

Initialise the logging environment for the application. from cgi import logfile

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;

Args:

logger: the actual logger object to be initialised; logfiledata (tuple): 3 elements tuple made of

[0] = logfilepath (string): the log file path, if None, file logging is disabled; [1] = filelevel (string): the level of log to be sent to the file, or NONE; [2] = consolelevel (string): the level of log to be sent to the console (stdout), or NONE.

emaildata (tuple): 4 elements tuple; no email logging if either of first 3 values invalid

[0] = host (string), [1] = port (int), [2] = address (string), ,is enabled; [3] = app_name (string).

Returns:

Nothing

Raises:

any IOErrors thrown by file handling methods are caught.

7.2.4.4. mqttgateway.utils.load_config module¶

Function to facilitate the loading of configuration parameters.

Based on ConfigParser.

mqttgateway.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 is declared as a constant string, and is also the 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. 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… Better send an absolute path then.
Returns:	object loaded with the parameters.
Return type:	ConfigParser.RawConfigParser object

7.2.4.5. mqttgateway.utils.throttled_exception module¶

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

exception mqttgateway.utils.throttled_exception.ThrottledException(msg=None, throttlelag=10, module_name=None)¶

Bases: exceptions.Exception

Exception class base to throttle events

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 True 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)

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

7.2.4.6. Module contents¶

Utilities package