Add a metric aggregation wrapper

These wrappers are also not present in 0.15, but are added so users can
already start writing code that supports aggregates to ease the
migration to 0.17.

Because of this, no protobuf parsing code is added yet.

Signed-off-by: Leandro Lucarella <[email protected]>

Author: llucax

src/frequenz/client/microgrid/metrics.py

@@ -0,0 +1,61 @@
+# License: MIT
+# Copyright © 2025 Frequenz Energy-as-a-Service GmbH
+
+"""Definition to work with metric sample values."""
+
+import enum
+from collections.abc import Sequence
+from dataclasses import dataclass
+
+
+@enum.unique
+class AggregationMethod(enum.Enum):
+    """The type of the aggregated value."""
+
+    AVG = "avg"
+    """The average value of the metric."""
+
+    MIN = "min"
+    """The minimum value of the metric."""
+
+    MAX = "max"
+    """The maximum value of the metric."""
+
+
+@dataclass(frozen=True, kw_only=True)
+class AggregatedMetricValue:
+    """Encapsulates derived statistical summaries of a single metric.
+
+    The message allows for the reporting of statistical summaries — minimum,
+    maximum, and average values - as well as the complete list of individual
+    samples if available.
+
+    This message represents derived metrics and contains fields for statistical
+    summaries—minimum, maximum, and average values. Individual measurements are
+    are optional, accommodating scenarios where only subsets of this information
+    are available.
+    """
+
+    avg: float
+    """The derived average value of the metric."""
+
+    min: float | None
+    """The minimum measured value of the metric."""
+
+    max: float | None
+    """The maximum measured value of the metric."""
+
+    raw_values: Sequence[float]
+    """All the raw individual values (it might be empty if not provided by the component)."""
+
+    def __str__(self) -> str:
+        """Return the short string representation of this instance."""
+        extra: list[str] = []
+        if self.min is not None:
+            extra.append(f"min:{self.min}")
+        if self.max is not None:
+            extra.append(f"max:{self.max}")
+        if len(self.raw_values) > 0:
+            extra.append(f"num_raw:{len(self.raw_values)}")
+        extra_str = f"<{' '.join(extra)}>" if extra else ""
+        return f"avg:{self.avg}{extra_str}"

tests/test_metrics.py

@@ -0,0 +1,42 @@
+# License: MIT
+# Copyright © 2025 Frequenz Energy-as-a-Service GmbH
+
+"""Tests for the Sample class and related classes."""
+
+from frequenz.client.microgrid.metrics import AggregatedMetricValue, AggregationMethod
+
+
+def test_aggregation_method_values() -> None:
+    """Test that AggregationMethod enum has the expected values."""
+    assert AggregationMethod.AVG.value == "avg"
+    assert AggregationMethod.MIN.value == "min"
+    assert AggregationMethod.MAX.value == "max"
+
+
+def test_aggregated_metric_value() -> None:
+    """Test AggregatedMetricValue creation and string representation."""
+    # Test with full data
+    value = AggregatedMetricValue(
+        avg=5.0,
+        min=1.0,
+        max=10.0,
+        raw_values=[1.0, 5.0, 10.0],
+    )
+    assert value.avg == 5.0
+    assert value.min == 1.0
+    assert value.max == 10.0
+    assert list(value.raw_values) == [1.0, 5.0, 10.0]
+    assert str(value) == "avg:5.0<min:1.0 max:10.0 num_raw:3>"
+
+    # Test with minimal data (only avg required)
+    value = AggregatedMetricValue(
+        avg=5.0,
+        min=None,
+        max=None,
+        raw_values=[],
+    )
+    assert value.avg == 5.0
+    assert value.min is None
+    assert value.max is None
+    assert not value.raw_values
+    assert str(value) == "avg:5.0"