QuLab 2.11.7__py3-none-any.whl → 2.11.9__py3-none-any.whl

qulab/monitor/dataset.py

@@ -1,77 +1,184 @@
+"""
+QuLab Monitor Dataset Module
+
+This module provides data management functionality for the QuLab monitor application.
+It handles storage and retrieval of time-series data with support for both point-by-point
+and trace-based data collection.
+
+The Dataset class maintains a rolling buffer of data frames, where each frame can
+contain multiple named columns of numerical data.
+"""
+
 from collections import defaultdict, deque
+from typing import Union, Sequence
 
-from .config import Nroll
+from .config import ROLL_BUFFER_SIZE
 
 PAUSE_TIME = 1
 
-Number = int | float | complex
+Number = Union[int, float, complex]
+DataPoint = Union[Number, Sequence[Number]]
+DataFrame = Union[Sequence[Number], Sequence[Sequence[Number]]]
 
 
 def remove_duplicates(input_list: list[str]) -> list[str]:
     """
-    Remove duplicates from a list of strings, keeping the order of the elements.
+    Remove duplicates from a list of strings while preserving order.
+
+    Args:
+        input_list: List of strings that may contain duplicates
+
+    Returns:
+        List of unique strings in their original order
     """
     return list(dict.fromkeys(input_list))
 
 
-class Dataset():
+class Dataset:
+    """
+    A data management class for storing and retrieving time-series data.
 
-    def __init__(self):
-        self.column_names = []
-        self.box = deque(maxlen=Nroll)
-        self.dirty = True
+    This class maintains a rolling buffer of data frames, where each frame
+    contains multiple columns of numerical data. It supports both point-by-point
+    data collection and trace-based data collection.
 
-    def clear(self):
-        self.box.clear()
+    Attributes:
+        column_names: List of column names for the dataset
+        box: Rolling buffer containing data frames
+        dirty: Flag indicating if data has been modified since last read
+    """
 
-    def clear_history(self):
-        o = self.box.popleft()
+    def __init__(self):
+        """Initialize an empty dataset with a rolling buffer."""
+        self.column_names: list[str] = []
+        self.box: deque[dict] = deque(maxlen=ROLL_BUFFER_SIZE)
+        self.dirty: bool = True
+
+    def clear(self) -> None:
+        """Clear all data from the dataset."""
         self.box.clear()
-        self.box.appendleft(o)
 
-    def set_column_names(self, column_names: list[str]):
+    def clear_history(self) -> None:
+        """
+        Clear historical data while preserving the most recent frame.
+        
+        This is useful for maintaining the current state while discarding
+        historical data that is no longer needed.
+        """
+        if self.box:
+            current_frame = self.box.popleft()
+            self.box.clear()
+            self.box.appendleft(current_frame)
+
+    def set_column_names(self, column_names: list[str]) -> None:
+        """
+        Set or update the column names for the dataset.
+
+        If the new column names differ from the current ones, all existing
+        data will be cleared to maintain consistency.
+
+        Args:
+            column_names: List of unique column names
+        """
         column_names = remove_duplicates(column_names)
         if column_names != self.column_names:
             self.clear()
         self.column_names = column_names
 
-    def get_data(self, step: int, xname: str,
-                 yname: str) -> tuple[list[Number], list[Number]]:
+    def get_data(self, step: int, x_name: str,
+                 y_name: str) -> tuple[list[Number], list[Number]]:
+        """
+        Retrieve X-Y data pairs from a specific step in the dataset.
+
+        Args:
+            step: Index of the data frame to retrieve
+            x_name: Name of the column to use for X values
+            y_name: Name of the column to use for Y values
+
+        Returns:
+            Tuple containing lists of X and Y values. Returns empty lists if
+            the requested step is not available.
+        """
         try:
-            b = self.box[step]
+            frame = self.box[step]
+            return frame[x_name], frame[y_name]
         except IndexError:
             return [], []
-        return b[xname], b[yname]
 
-    def append(self, dataframe: list[Number] | list[list[Number]]):
+    def append(self, dataframe: DataFrame) -> None:
+        """
+        Append new data to the dataset.
+
+        This method automatically determines whether the input is point data
+        or trace data based on its structure.
+
+        Args:
+            dataframe: Either a list of values for point data or a list of
+                      lists for trace data. The length must match the number
+                      of columns.
+
+        Raises:
+            AssertionError: If the input data length doesn't match the number
+                           of columns.
+            TypeError: If the input data format is invalid.
+        """
         if not dataframe:
             return
         try:
-            iter(dataframe[0])  # test if dataframe is a list of list
+            # Test if dataframe is a list of lists (trace data)
+            iter(dataframe[0])
             self._append_traces(dataframe)
         except TypeError:
             self._append_points(dataframe)
 
-    def roll(self):
+    def roll(self) -> None:
+        """
+        Add a new empty frame to the dataset.
+        
+        This creates a new defaultdict that will automatically create empty
+        lists for any new column names accessed.
+        """
         self.box.appendleft(defaultdict(list))
 
-    def _append_points(self, points: list[Number]):
+    def _append_points(self, points: Sequence[Number]) -> None:
+        """
+        Append point data to the current frame.
+
+        Args:
+            points: List of values, one for each column
+
+        Raises:
+            AssertionError: If the number of points doesn't match the number
+                           of columns
+        """
         self.dirty = True
-        assert (len(points) == len(
-            self.column_names)), (f"-PointDataBox\n"
-                                  f"-ap\n"
-                                  f"-Length Must be same\n"
-                                  f"the column_names : {self.column_names}\n"
-                                  f"given data : {points}")
-        for name, p in zip(self.column_names, points):
-            self.box[0][name].append(p)
-
-    def _append_traces(self, traces: list[list[Number]]):
+        if len(points) != len(self.column_names):
+            raise AssertionError(
+                "Point data length mismatch\n"
+                f"Expected {len(self.column_names)} values for columns: {self.column_names}\n"
+                f"Received {len(points)} values: {points}"
+            )
+        
+        for name, value in zip(self.column_names, points):
+            self.box[0][name].append(value)
+
+    def _append_traces(self, traces: Sequence[Sequence[Number]]) -> None:
+        """
+        Append trace data as a new frame.
+
+        Args:
+            traces: List of data sequences, one for each column
+
+        Raises:
+            AssertionError: If the number of traces doesn't match the number
+                           of columns
+        """
         self.dirty = True
-        assert (len(traces) == len(
-            self.column_names)), (f"-TraceDataBox\n"
-                                  f"-at\n"
-                                  f"-Length Must be same\n"
-                                  f"the column_names : {self.column_names}\n"
-                                  f"given data : {traces}")
+        if len(traces) != len(self.column_names):
+            raise AssertionError(
+                "Trace data length mismatch\n"
+                f"Expected {len(self.column_names)} sequences for columns: {self.column_names}\n"
+                f"Received {len(traces)} sequences"
+            )
+        
         self.box.appendleft(dict(zip(self.column_names, traces)))

qulab/monitor/event_queue.py

@@ -1,54 +1,127 @@
+"""
+QuLab Monitor Event Queue Module
+
+This module implements an event handling system for the QuLab monitor application.
+It processes commands and data received through a multiprocessing queue to update
+the monitor's display and datasets.
+
+The event queue handles various types of commands:
+- PN/TN: Set column names for point/trace data
+- PD/TD: Append point/trace data
+- ROLL: Create new data frame
+- PXY/TXY: Update plot configurations
+"""
+
 import warnings
 from multiprocessing import Queue
+from typing import Any, Literal, Tuple, Union
 
 from .dataset import Dataset
 from .toolbar import ToolBar
 
+# Type definitions
+CommandType = Literal["PN", "TN", "PD", "TD", "ROLL", "PXY", "TXY"]
+DataType = Union[list[str], list[float], str, None]
+EventType = Tuple[CommandType, DataType]
+
+
+class EventQueue:
+    """
+    Event handler for processing monitor commands and data.
 
-class EventQueue():
+    This class manages the communication between the data collection process
+    and the monitor display. It receives commands and data through a queue
+    and updates the appropriate components of the monitor.
+
+    Attributes:
+        toolbar: The monitor's toolbar for UI controls
+        queue: Multiprocessing queue for receiving commands and data
+        point_dataset: Dataset for point-by-point data collection
+        trace_dataset: Dataset for trace-based data collection
+    """
 
     def __init__(self, queue: Queue, toolbar: ToolBar, point_dataset: Dataset,
                  trace_dataset: Dataset):
+        """
+        Initialize the event queue.
+
+        Args:
+            queue: Multiprocessing queue for receiving commands
+            toolbar: Monitor's toolbar instance
+            point_dataset: Dataset for point data
+            trace_dataset: Dataset for trace data
+        """
         self.toolbar = toolbar
         self.queue = queue
         self.point_dataset = point_dataset
         self.trace_dataset = trace_dataset
 
-    def flush(self):
-        while (not self.queue.empty()):
-            words = self.queue.get()
+    def flush(self) -> None:
+        """
+        Process all pending events in the queue.
+
+        This method retrieves and processes all available events from the queue.
+        Each event should be a tuple containing a command string and associated data.
+        Invalid events are logged as warnings and skipped.
+        """
+        while not self.queue.empty():
             try:
-                assert (isinstance(
-                    words, tuple)), "QueueHandler - fifo Content must be tuple"
-                assert (
-                    len(words) == 2
-                ), "QueueHandler -the tuple must be like (\"command_type\" , \"DATA\")"
-                cmd, data = words
-                assert (isinstance(
-                    cmd, str)), "QueueHandler - the command should be a string"
-            except AssertionError as e:
-                warnings.warn(e.args[0])
+                event = self.queue.get()
+                if not isinstance(event, tuple):
+                    raise ValueError("Queue event must be a tuple")
+                if len(event) != 2:
+                    raise ValueError("Queue event must contain exactly two elements (command, data)")
+                
+                command, data = event
+                if not isinstance(command, str):
+                    raise ValueError("Command must be a string")
+                
+                self.handle(command, data)
+                
+            except (ValueError, AssertionError) as error:
+                warnings.warn(f"Invalid event format: {error}")
                 continue
 
-            self.handle(cmd, data)
+    def handle(self, command: str, data: Any) -> None:
+        """
+        Process a single event based on its command type.
+
+        Args:
+            command: String identifying the type of event
+            data: Data associated with the event
 
-    def handle(self, cmd, data):
-        match cmd:
-            case "PN":
+        The following commands are supported:
+            PN: Set point data column names
+            TN: Set trace data column names
+            PD: Append point data
+            TD: Append trace data
+            ROLL: Create new data frame
+            PXY: Update point plot configuration
+            TXY: Update trace plot configuration
+        """
+        match command:
+            case "PN":  # Set point data column names
                 self.point_dataset.set_column_names(data)
                 self.toolbar.refresh_comb()
-            case "TN":
+                
+            case "TN":  # Set trace data column names
                 self.trace_dataset.set_column_names(data)
                 self.toolbar.refresh_comb()
-            case "PD":
+                
+            case "PD":  # Append point data
                 self.point_dataset.append(data)
-            case "TD":
+                
+            case "TD":  # Append trace data
                 self.trace_dataset.append(data)
-            case "ROLL":
+                
+            case "ROLL":  # Create new data frame
                 self.point_dataset.roll()
-            case "PXY":
+                
+            case "PXY":  # Update point plot configuration
                 self.toolbar.set_point_text(data)
-            case "TXY":
+                
+            case "TXY":  # Update trace plot configuration
                 self.toolbar.set_trace_text(data)
+                
             case _:
-                warnings.warn(f"QueueHandler - unknown command : {cmd}")
+                warnings.warn(f"Unknown command: {command}")