evol4

utils/parsers/data_preparation.py

@@ -6,7 +6,22 @@ import re
 
 logger = logging.getLogger(__name__)
 
-def get_data(cfg, id):
+def get_data(cfg: object, id: int) -> tuple:
+    """
+    Retrieves data for a specific tool from the database.
+
+    This function connects to the database using the provided configuration,
+    executes a query to retrieve the unit name, tool name ID, and tool data
+    associated with the given ID from the raw data table, and returns the results.
+
+    Args:
+        cfg: A configuration object containing database connection parameters
+             and table names (cfg.dbname, cfg.dbrectable).
+        id: The ID of the tool record to retrieve.
+
+    Returns:
+        A tuple containing the unit name, tool name ID, and tool data.
+    """
     with connetti_db(cfg) as conn:
         cur = conn.cursor()
         cur.execute(f'select unit_name, tool_name, tool_data from {cfg.dbname}.{cfg.dbrectable} where id = {id}')
@@ -15,7 +30,28 @@ def get_data(cfg, id):
         conn.close()
         return unit_name, tool_name, tool_data
 
-def make_matrix(cfg, id):
+def make_matrix(cfg: object, id: int) -> list:
+    """
+    Processes raw tool data and transforms it into a matrix format for database insertion.
+
+    This function retrieves raw tool data using `get_data`, splits it into individual
+    readings (rows), and further parses each reading into individual values.  It
+    handles data where multiple nodes might be reporting values within a single
+    reading.  The resulting matrix is a list of lists, where each inner list
+    represents a row of data ready for insertion into the database.  Missing
+    values are padded with `None` to ensure consistent row length.
+
+    Args:
+        cfg: A configuration object containing database connection parameters
+             and table names.
+        id: The ID of the tool record to process.
+
+    Returns:
+        A list of lists (matrix) representing the processed data.  Each inner list
+        contains the following elements: UnitName, ToolNameID, NodeNum, EventDate,
+        EventTime, BatLevel, Temperature, followed by up to 16 additional
+        measurement values (Val0 to ValF), padded with None if necessary.
+    """
     UnitName, ToolNameID, ToolData = get_data(cfg, id)
     righe = ToolData.splitlines()
     matrice_valori = []
@@ -29,7 +65,28 @@ def make_matrix(cfg, id):
 
     return matrice_valori
 
-def make_loc_matrix(cfg, id):
+def make_loc_matrix(cfg: object, id: int) -> list:
+    """
+    Processes raw location (LOC) tool data and transforms it into a matrix format for database insertion.
+
+    This function retrieves raw LOC tool data using `get_data`, splits it into
+    individual readings (rows), and parses each reading into individual values
+    specific to the LOC data format (timestamp, battery level, temperature, and
+    four additional values: ain1, ain2, din1, din2).  The resulting matrix is a list
+    of lists, where each inner list represents a row of data ready for insertion
+    into the database.  Missing values are padded with `None` to ensure consistent
+    row length.  It uses a regular expression to filter lines that match the
+    expected LOC data format.
+
+    Args:
+        cfg: A configuration object containing database connection parameters
+             and table names.
+        id: The ID of the tool record to process.
+
+    Returns:
+        A list of lists (matrix) representing the processed LOC data.  Each inner
+        list contains data fields similar to `make_matrix`, adjusted for LOC data.
+    """
     UnitName, ToolNameID, ToolData = get_data(cfg, id)
     righe = ToolData.splitlines()
     matrice_valori = []