juham.database¶
Description¶
Classes implementing MQTT pub-sub networks used for data transmission between IoT nodes. These classes must be derived trom base.MQtt base class.
- class juham.database.JConsole(name='jconsole')[source]¶
Bases:
JDatabase
Database interface that simply dumps the written records to stdout solely for testing and debugging purposes.
- classmethod app_name(name)¶
Set application name
- Parameters:
name (str) – application name
- classmethod classattrs_from_dict(attributes)¶
Set class attributes from a dictionary.
- classmethod classattrs_to_dict()¶
Convert class attributes to a dictionary.
- classmethod configure_args(args)¶
Register startup arguments to be parsed.
- Parameters:
parser (argparse.ArgumentParser) – parser to add the startup arguments.
- Return type:
None
- copy()¶
Create and return a copy of the current object.
This method serializes the current object to a dictionary using the to_dict method, creates a new instance of the object’s class, and populates it with the serialized data using the from_dict method.
This method uses class identifier based instantiation (see factory method pattern) to create a new instance of the object, and ‘to_dict’ and ‘from_dict’ methods to initialize object’s state.
- Return type:
MasterPiece
- Returns:
A new instance of the object’s class with the same state as the original object.
Example:
clone_of_john = john.copy()
- database = 'home'¶
- debug(msg, details='')¶
Logs the given debug message to the application log.
- Parameters:
msg (str) – The information message to be logged.
details (str) – Additional detailed information for the message to be logged
- Return type:
None
- deserialize_from_json(f)¶
Load attributes from the given JSON file.
- elapsed_seconds_in_day(ts_utc)¶
Fetch the elapsed seconds since the be given time stamp ‘ts_utc’.
- Returns:
elapsed second today
- Return type:
float
- elapsed_seconds_in_hour(ts_utc)¶
Given timestamp in UTC, Compute elapsed seconds within an hour
- Parameters:
ts (float) – seconds since UTC epoch
- Returns:
_description_
- Return type:
float
- epoc2utc(epoch)¶
Converts the given epoch time to UTC time string. All time coordinates are represented in UTC time. This allows the time coordinate to be mapped to any local time representation without ambiguity.
- Parameters:
epoch (float) – timestamp in UTC time
rc (str) – time string describing date, time and time zone e.g 2024-07-08T12:10:22Z
- Returns:
UTC time
- error(msg, details='')¶
Logs the given error message to the application log.
- Parameters:
msg (str) – The message to be logged.
details (str) – Additional detailed information for the message to be logged
- Return type:
None
- classmethod find_class(class_id)¶
Given class identifier find the registered class. If no class with the give identifier exists return None.
- Parameters:
class_id (int) – class identifier
- Returns:
class or null if not registered
- Return type:
obj (obj)
- from_dict(data_dict)¶
Update instance attributes from a dictionary.
- classmethod get_app_name()¶
Get application name
- Returns:
application name
- Return type:
name (str)
- classmethod get_class_id()¶
Return the class id of the class. Each class has an unique identifier that can be used for instantiating the class via
Object.instantiate()
method.- Parameters:
cls (class) – class
- Return type:
str
- Returns:
id (int) unique class identifier through which the class can be instantiated by factory method pattern.
- classmethod get_json_file()¶
Generate the JSON file name based on the class name.
The file is created into users home folder.
- classmethod get_registered_classes()¶
Get the dictionary holding the registered class identifiers and the corresponding classes.
- Returns:
dictionary of class identifier - class pairs
- Return type:
dict
- classmethod has_class_method_directly(method_name)¶
Check if the method is in the class’s own dictionary
- Return type:
bool
- host: str = ''¶
- info(msg, details='')¶
Logs the given information message to the application log.
- Parameters:
msg (str) – The information message to be logged.
details (str) – Additional detailed information for the message to be logged
- Return type:
None
- classmethod initialize_class(load_class_attrs=True)¶
Initialize the class for instantiation. Initializes the class identifier. Initialize public class attributes from the class-specific configuration files, unless disabled with the load_class_attrs parameter. Call the register() method of the class to let each class do custom initializations. Set up atexit callback to generate class-specific initialization files if they don’t exist already.
- Parameters:
load_class_attrs (bool, optional) – If true, then attempts to initialize class attributes from the class-specific configuration files. Defaults to True.
- Returns:
Returns true if the class was initialized. False implies the class is already initialized, in which case the method call has no effect.
- Return type:
bool
- classmethod instantiate(class_id)¶
Create an instance of the class corresponding to the given class identifier. This method implements the factory method pattern, which is essential for a plugin architecture.
- Parameters:
class_id (int) – Identifier of the class to instantiate.
- Returns:
An instance of the class corresponding to the given class identifier.
- Return type:
obj
- classmethod instantiate_with_param(class_id, param)¶
Given class identifier and one constructor argument create the corresponding object.
- Parameters:
class_id (
str
) – class identifierparam (
Any
) – class specific constructor parameter
- Returns:
instance of the given class.
- Return type:
obj
- classmethod is_abstract()¶
Check whether the class is abstract or real. Override in the derived sub-classes. The default is False.
- Return type:
bool
- Returns:
True (bool) if abstract
- is_time_between(begin_time, end_time, check_time=None)¶
Check if the given time is within the given time line. All timestamps must be in UTC time.
- Parameters:
begin_time (timestamp) – beginning of the timeline
end_time (timestamp) – end of the timeline
check_time (timestamp) – time to be checked
- Returns:
True if within the timeline
- Return type:
rc (bool)
- classmethod load_from_json()¶
Load class attributes from a JSON file.
- org: str = 'juham'¶
- classmethod parse_args()¶
Parse registered startup arguments.
- Parameters:
parser (argparse.ArgumentParser) – parser to add the startup arguments.
- Return type:
None
- classmethod parse_initial_args()¶
Parse application name and configuration name arguments. Note that argument parsing is two stage process. This method must be called at very early on to know where to load class initialization files. See register_args() method.
- print(prefix='', is_last=True)¶
Print the name of the object, decorated with prefix consisting of ├─, └─, and │.
- quantize(quanta, value)¶
Quantize the given value.
- Parameters:
quanta (float) – resolution for quantization
value (float) – value to be quantized
- Returns:
quantized value
- Return type:
(float)
Example:
hour_of_a_day = self.quantize(3600, epoch_seconds)
- classmethod register()¶
Register the class.
Called immediately upon class initialization, right before the class attributes are loaded from the class specific configuration files.
Subclasses can extend this with custom register functionality:
class MyMasterPiece(MasterPiece): @classmethod def register(cls): super().register() # Don't forget cls._custom_field = True
- Return type:
None
- classmethod register_args(parser)¶
Register startup arguments to be parsed.
- Parameters:
parser (argparse.ArgumentParser) – parser to add the startup arguments.
- Return type:
None
- classmethod register_class(class_id, ctor)¶
Register the given class identifier for identifier based instantiation . This, factory method pattern, as it is called, decouples the actual implementation from the interface. For more information see
instantiate()
method.- Parameters:
class_id (str) – class identifier
ctor (function) – constructor
- run()¶
Run the masterpiece. Dispatches the call to payload object and returns the control to the caller.
- Return type:
None
- run_forever()¶
Run the masterpiece forever. This method will return only when violently terminated.
- Return type:
None
- classmethod save_to_json()¶
Create class configuration file, if the file does not exist yet.
- serialize_to_json(f)¶
Serialize the object to given JSON file
- classmethod set_log(l)¶
Set logger.
- Parameters:
l (logger) – logger object
- Return type:
None
- shutdown()¶
Shutdown the masterpiece. It is up to the sub classes to implement this method. Dispatches the call to payload object.
- Return type:
None
- timestamp()¶
Returns the current date-time in UTC.
- Returns:
datetime in UTC.
- Return type:
rc (datetime)
- timestamp_hour(ts)¶
Returns the hour in 24h format in UTC.
- Parameters:
ts (float) – timestamp
- Returns:
current hour in UTC 0 …23
- Return type:
rc (int)
- timestampstr(ts)¶
Converts the given timestamp to human readable string of format ‘Y-m-d H:M:S’.
- Parameters:
ts (timestamp) – time stamp to be converted
- Returns:
human readable date-time string
- Return type:
rc (string)
- to_dict()¶
Convert instance attributes to a dictionary.
- token: str = ''¶
- warning(msg, details='')¶
Logs the given warning message to the application log.
- Parameters:
msg (str) – The message to be logged.
details (str) – Additional detailed information for the message to be logged
- Return type:
None
- class juham.database.JInflux(name='influx')[source]¶
Bases:
JDatabase
Influx time series database version 3.
- classmethod app_name(name)¶
Set application name
- Parameters:
name (str) – application name
- classmethod classattrs_from_dict(attributes)¶
Set class attributes from a dictionary.
- classmethod classattrs_to_dict()¶
Convert class attributes to a dictionary.
- classmethod configure_args(args)¶
Register startup arguments to be parsed.
- Parameters:
parser (argparse.ArgumentParser) – parser to add the startup arguments.
- Return type:
None
- copy()¶
Create and return a copy of the current object.
This method serializes the current object to a dictionary using the to_dict method, creates a new instance of the object’s class, and populates it with the serialized data using the from_dict method.
This method uses class identifier based instantiation (see factory method pattern) to create a new instance of the object, and ‘to_dict’ and ‘from_dict’ methods to initialize object’s state.
- Return type:
MasterPiece
- Returns:
A new instance of the object’s class with the same state as the original object.
Example:
clone_of_john = john.copy()
- database = 'home'¶
- debug(msg, details='')¶
Logs the given debug message to the application log.
- Parameters:
msg (str) – The information message to be logged.
details (str) – Additional detailed information for the message to be logged
- Return type:
None
- deserialize_from_json(f)¶
Load attributes from the given JSON file.
- elapsed_seconds_in_day(ts_utc)¶
Fetch the elapsed seconds since the be given time stamp ‘ts_utc’.
- Returns:
elapsed second today
- Return type:
float
- elapsed_seconds_in_hour(ts_utc)¶
Given timestamp in UTC, Compute elapsed seconds within an hour
- Parameters:
ts (float) – seconds since UTC epoch
- Returns:
_description_
- Return type:
float
- epoc2utc(epoch)¶
Converts the given epoch time to UTC time string. All time coordinates are represented in UTC time. This allows the time coordinate to be mapped to any local time representation without ambiguity.
- Parameters:
epoch (float) – timestamp in UTC time
rc (str) – time string describing date, time and time zone e.g 2024-07-08T12:10:22Z
- Returns:
UTC time
- error(msg, details='')¶
Logs the given error message to the application log.
- Parameters:
msg (str) – The message to be logged.
details (str) – Additional detailed information for the message to be logged
- Return type:
None
- classmethod find_class(class_id)¶
Given class identifier find the registered class. If no class with the give identifier exists return None.
- Parameters:
class_id (int) – class identifier
- Returns:
class or null if not registered
- Return type:
obj (obj)
- from_dict(data_dict)¶
Update instance attributes from a dictionary.
- classmethod get_app_name()¶
Get application name
- Returns:
application name
- Return type:
name (str)
- classmethod get_class_id()¶
Return the class id of the class. Each class has an unique identifier that can be used for instantiating the class via
Object.instantiate()
method.- Parameters:
cls (class) – class
- Return type:
str
- Returns:
id (int) unique class identifier through which the class can be instantiated by factory method pattern.
- classmethod get_json_file()¶
Generate the JSON file name based on the class name.
The file is created into users home folder.
- classmethod get_registered_classes()¶
Get the dictionary holding the registered class identifiers and the corresponding classes.
- Returns:
dictionary of class identifier - class pairs
- Return type:
dict
- classmethod has_class_method_directly(method_name)¶
Check if the method is in the class’s own dictionary
- Return type:
bool
- host: str = ''¶
- info(msg, details='')¶
Logs the given information message to the application log.
- Parameters:
msg (str) – The information message to be logged.
details (str) – Additional detailed information for the message to be logged
- Return type:
None
- classmethod initialize_class(load_class_attrs=True)¶
Initialize the class for instantiation. Initializes the class identifier. Initialize public class attributes from the class-specific configuration files, unless disabled with the load_class_attrs parameter. Call the register() method of the class to let each class do custom initializations. Set up atexit callback to generate class-specific initialization files if they don’t exist already.
- Parameters:
load_class_attrs (bool, optional) – If true, then attempts to initialize class attributes from the class-specific configuration files. Defaults to True.
- Returns:
Returns true if the class was initialized. False implies the class is already initialized, in which case the method call has no effect.
- Return type:
bool
- classmethod instantiate(class_id)¶
Create an instance of the class corresponding to the given class identifier. This method implements the factory method pattern, which is essential for a plugin architecture.
- Parameters:
class_id (int) – Identifier of the class to instantiate.
- Returns:
An instance of the class corresponding to the given class identifier.
- Return type:
obj
- classmethod instantiate_with_param(class_id, param)¶
Given class identifier and one constructor argument create the corresponding object.
- Parameters:
class_id (
str
) – class identifierparam (
Any
) – class specific constructor parameter
- Returns:
instance of the given class.
- Return type:
obj
- classmethod is_abstract()¶
Check whether the class is abstract or real. Override in the derived sub-classes. The default is False.
- Return type:
bool
- Returns:
True (bool) if abstract
- is_time_between(begin_time, end_time, check_time=None)¶
Check if the given time is within the given time line. All timestamps must be in UTC time.
- Parameters:
begin_time (timestamp) – beginning of the timeline
end_time (timestamp) – end of the timeline
check_time (timestamp) – time to be checked
- Returns:
True if within the timeline
- Return type:
rc (bool)
- classmethod load_from_json()¶
Load class attributes from a JSON file.
- org: str = 'juham'¶
- classmethod parse_args()¶
Parse registered startup arguments.
- Parameters:
parser (argparse.ArgumentParser) – parser to add the startup arguments.
- Return type:
None
- classmethod parse_initial_args()¶
Parse application name and configuration name arguments. Note that argument parsing is two stage process. This method must be called at very early on to know where to load class initialization files. See register_args() method.
- print(prefix='', is_last=True)¶
Print the name of the object, decorated with prefix consisting of ├─, └─, and │.
- quantize(quanta, value)¶
Quantize the given value.
- Parameters:
quanta (float) – resolution for quantization
value (float) – value to be quantized
- Returns:
quantized value
- Return type:
(float)
Example:
hour_of_a_day = self.quantize(3600, epoch_seconds)
- classmethod register()¶
Register the class.
Called immediately upon class initialization, right before the class attributes are loaded from the class specific configuration files.
Subclasses can extend this with custom register functionality:
class MyMasterPiece(MasterPiece): @classmethod def register(cls): super().register() # Don't forget cls._custom_field = True
- Return type:
None
- classmethod register_args(parser)¶
Register startup arguments to be parsed.
- Parameters:
parser (argparse.ArgumentParser) – parser to add the startup arguments.
- Return type:
None
- classmethod register_class(class_id, ctor)¶
Register the given class identifier for identifier based instantiation . This, factory method pattern, as it is called, decouples the actual implementation from the interface. For more information see
instantiate()
method.- Parameters:
class_id (str) – class identifier
ctor (function) – constructor
- run()¶
Run the masterpiece. Dispatches the call to payload object and returns the control to the caller.
- Return type:
None
- run_forever()¶
Run the masterpiece forever. This method will return only when violently terminated.
- Return type:
None
- classmethod save_to_json()¶
Create class configuration file, if the file does not exist yet.
- serialize_to_json(f)¶
Serialize the object to given JSON file
- classmethod set_log(l)¶
Set logger.
- Parameters:
l (logger) – logger object
- Return type:
None
- shutdown()¶
Shutdown the masterpiece. It is up to the sub classes to implement this method. Dispatches the call to payload object.
- Return type:
None
- timestamp()¶
Returns the current date-time in UTC.
- Returns:
datetime in UTC.
- Return type:
rc (datetime)
- timestamp_hour(ts)¶
Returns the hour in 24h format in UTC.
- Parameters:
ts (float) – timestamp
- Returns:
current hour in UTC 0 …23
- Return type:
rc (int)
- timestampstr(ts)¶
Converts the given timestamp to human readable string of format ‘Y-m-d H:M:S’.
- Parameters:
ts (timestamp) – time stamp to be converted
- Returns:
human readable date-time string
- Return type:
rc (string)
- to_dict()¶
Convert instance attributes to a dictionary.
- token: str = ''¶
- warning(msg, details='')¶
Logs the given warning message to the application log.
- Parameters:
msg (str) – The message to be logged.
details (str) – Additional detailed information for the message to be logged
- Return type:
None