SIENTIAPDE-1084

Enhance documentation and improve shutdown methods for DataManager and IngestorManager

- Updated README.md to clarify persistent storage capabilities.
- Enhanced docstrings in DataManager and IngestorManager for shutdown processes, detailing resource cleanup and error handling.
- Improved comments in various methods to provide clearer explanations of functionality and side effects.

ingestor/managers/opc_manager.py

@@ -194,16 +194,22 @@ class OpcManager(BaseActivity):
     async def create_subscription(self, name: str, period: int = 500):
         """
         Creates a subscription with the specified monitoring period.
+
         This method establishes a subscription to monitor data changes or events
         from the OPC UA server. If the client is not connected, an exception is raised.
+
         Args:
+            name (str): The name identifier for the subscription
             period (int, optional): The monitoring period in milliseconds. Defaults to 500 ms.
+
         Raises:
             ValueError: If the client is not connected.
+
         Side Effects:
             - Sets the `self.period` attribute to the specified or default period.
-            - Creates a subscription and assigns it to `self.subscription`.
+            - Creates a subscription and assigns it to `self.subscriptions[name]`.
             - Logs the creation of the subscription.
+            - Increments subscription creation metrics.
         """
 
         if not self.client:
@@ -222,18 +228,26 @@ class OpcManager(BaseActivity):
     async def subscribe(self, subscription: str, nodes: dict, collect_period: int):
         """
         Subscribes to a set of OPC UA nodes for data change notifications.
+
         This method adds the specified nodes to the subscription and configures
         their data collection rules based on the provided collection period and
         node-specific frequency.
+
         Args:
-            nodes (dict): A dictionary where keys are node identifiers (e.g., node
-                IDs or paths) and values are configurations for each node. Each
-                configuration must include a 'frequency' key indicating the
-                frequency of data collection in Hz.
+            subscription (str): The name of the subscription to use
+            nodes (dict): A dictionary where keys are node identifiers and values are
+                configurations for each node. Each configuration must include a 'frequency'
+                key indicating the frequency of data collection in Hz.
             collect_period (int): The data collection period in seconds.
+
         Raises:
             ValueError: If the subscription has not been created by calling
                 `create_subscription` prior to this method.
+
+        Side Effects:
+            - Updates internal node tracking and cycle rules
+            - Establishes data change monitoring for specified nodes
+            - Updates metrics for subscribed tags count
         """
 
         if not self.subscriptions.get(subscription):
@@ -261,11 +275,17 @@ class OpcManager(BaseActivity):
     async def unsubscribe(self, subscription: str):
         """
         Unsubscribes from a given subscription.
+
+        This method removes the specified subscription and cleans up associated
+        resources. It handles cases where the subscription doesn't exist gracefully.
+
         Args:
             subscription (str): The name of the subscription to unsubscribe from.
+
         Logs:
             - A warning if the specified subscription does not exist.
             - An info message upon successful unsubscription.
+
         Behavior:
             - If the subscription exists, it is deleted and removed from the 
               subscriptions dictionary.
@@ -283,12 +303,20 @@ class OpcManager(BaseActivity):
     async def disconnect(self):
         """
         Disconnects from the OPC UA server.
-        This method handles the disconnection process by deleting the subscription
+
+        This method handles the disconnection process by deleting all subscriptions
         and disconnecting the client from the OPC UA server. It logs the disconnection
         process and handles any exceptions that may occur during cleanup.
+
         Raises:
             Exception: If an error occurs while deleting the subscription or disconnecting
                        from the OPC UA server, it logs the error details.
+
+        Side Effects:
+            - Deletes all active subscriptions
+            - Disconnects the OPC client
+            - Updates connection status metrics
+            - Clears internal client reference
         """
 
         self.logger.warning('Disconnecting from OPC server')
@@ -319,14 +347,17 @@ class OpcManager(BaseActivity):
     async def datachange_notification(self, node, _val, data):
         """
         Handles data change notifications for monitored OPC UA nodes.
+
         This method is triggered when a monitored node's value changes. It processes
         the notification, updates internal state, and publishes the data to the
         appropriate topics.
+
         Args:
             node (NodeId): The OPC UA node that triggered the data change notification.
             _val (Any): The new value of the node (unused in this implementation).
             data (DataChangeNotification): The data change notification object containing
                 details about the change.
+
         Behavior:
             - Extracts the value and source timestamp from the monitored item.
             - Resets the cycle count for the node's cycle rule.
@@ -365,12 +396,15 @@ class OpcManager(BaseActivity):
     def check_cycles(self):
         """
         Checks the cycle counts for all monitored nodes and sends
-            notifications if thresholds are exceeded.
+        notifications if thresholds are exceeded.
 
         This method iterates through all monitored nodes and updates their cycle counts based on 
         configured increments. If a node's cycle count exceeds a threshold (5 cycles), it triggers
         a warning notification.
 
+        Side Effects:
+            - Updates cycle counts for all monitored nodes
+            - Sends warning notifications for nodes exceeding cycle thresholds
         """
         for node, config in self.nodes.items():
             self.nodes[node]['cycle_rule']['cycle_count'] += config[
@@ -389,8 +423,20 @@ class OpcManager(BaseActivity):
     def check_opc_listenning(self) -> bool:
         """
         Checks the OPC connection and triggers notifications if the connection is lost.
+
+        This method monitors the data reception health by tracking cycles without
+        data. It sends notifications at different thresholds and can trigger
+        reconnection attempts.
+
         Returns:
-            bool: True if the connection is lost, False otherwise.
+            bool: True if the connection is lost and reconnection should be attempted,
+                  False otherwise.
+
+        Side Effects:
+            - Increments non-receive count
+            - Updates metrics for cycles without data
+            - Sends warning notifications at 5 cycles
+            - Sends error notifications and triggers reconnection at 15 cycles
         """
 
         self.non_receive_count += 1