Add metrics package compatible with v1alpha8 (#128)

This PR introduces a new `metrics` package compatible with the v1alpha8
API version, along with a new `proto` package for common protobuf
conversion utilities. The changes deprecate the old `enum_proto` module
in favor of the new `proto.enum_from_proto` function and improve
deprecation messages across the codebase to include full module paths.

**Key changes:**
- Adds new `frequenz.client.common.proto` package with
`enum_from_proto`, `datetime_from_proto`, and `datetime_to_proto`
utilities
- Introduces `frequenz.client.common.metrics` package with comprehensive
metric types (`Metric`, `MetricSample`, `AggregatedMetricValue`,
`Bounds`, etc.) compatible with v1alpha8
- Deprecates `frequenz.client.common.enum_proto` module with improved
deprecation messages that include full module paths
- Updates all existing deprecation messages to include full module paths
for better clarity

Author: llucax

RELEASE_NOTES.md

@@ -2,20 +2,21 @@
 
 ## Summary
 
-This is the same release as v0.3.5 but with prefixes in `Event` enum values removed. The v0.3.5 release will be yanked from PyPI and it should not be used.
+This release main change is the introduction of a new `metrics` package compatible with the common API v0.8 (`v1alpha8`) (the old `metric` package, in singular, still works with the old v0.5/`v1` version).
 
-## Upgrading
+## Deprecations
 
-- The `pagination.Params` class is deprecated; use the protobuf message directly.
-- The `pagination.Info` class is deprecated in favor of the new `pagination.PaginationInfo` class.
+- The old `frequenz.client.common.enum_proto` module is now deprecated, please use `frequenz.client.common.proto.enum_from_proto` instead.
 
 ## New Features
 
-- Mapping for the new `Event` message has been added.
-- Add new common API enums for `ElectricalComponent` (previously `Components`).
-
-- Added `v1alpha8` variants of the pagination data structures.
-
-## Bug Fixes
-
-- Updated display of protobuf version warnings
+- New `frequenz.client.common.common.proto` module with conversion utilities for protobuf types:
+  - `enum_from_proto()` (moved from `enum_proto).
+  - `datetime_to_proto()` and `datetime_from_proto()` functions to convert between Python `datetime` and protobuf `Timestamp` (imported from `frequenz-client-base`.
+- New `metrics` package compatible with API v0.8, which includes:
+  - `Metric` enum with all supported metrics.
+  - `MetricSample` dataclass to represent metric samples.
+  - `AggregatedMetricValue` dataclass to represent derived statistical summaries.
+  - `Bounds` dataclass to represent bounds for metrics.
+  - `MetricConnection` and `MetricConnectionCategory` to represent connections from which metrics are obtained.
+  - `proto` submodule with conversion functions to/from protobuf types.

pyproject.toml

@@ -29,6 +29,7 @@ dependencies = [
   "typing-extensions >= 4.13.0, < 5",
   "frequenz-api-common >= 0.8.0, < 1",
   "frequenz-core >= 1.0.2, < 2",
+  "protobuf >= 6.33.1, < 7",
 ]
 dynamic = ["version"]
 
@@ -60,6 +61,7 @@ dev-mkdocs = [
 dev-mypy = [
   "mypy == 1.18.2",
   "types-Markdown == 3.9.0.20250906",
+  "types-protobuf == 6.32.1.20251105",
   # For checking the noxfile, docs/ script, and tests
   "frequenz-client-common[dev-mkdocs,dev-noxfile,dev-pytest]",
 ]
@@ -72,6 +74,7 @@ dev-pylint = [
 dev-pytest = [
   "pytest == 8.4.2",
   "frequenz-repo-config[extra-lint-examples] == 0.13.6",
+  "hypothesis == 6.140.3",
   "pytest-mock == 3.15.1",
   "pytest-asyncio == 1.2.0",
   "async-solipsism == 0.8",

src/frequenz/client/common/enum_proto.py

@@ -6,6 +6,8 @@
 import enum
 from typing import Literal, TypeVar, overload
 
+from typing_extensions import deprecated
+
 EnumT = TypeVar("EnumT", bound=enum.Enum)
 """A type variable that is bound to an enum."""
 
@@ -22,6 +24,10 @@ def enum_from_proto(
 ) -> EnumT | int: ...
 
 
+@deprecated(
+    "frequenz.client.common.enum_proto.enum_from_proto is deprecated. "
+    "Please use frequenz.client.common.proto.enum_from_proto instead."
+)
 def enum_from_proto(
     value: int, enum_type: type[EnumT], *, allow_invalid: bool = True
 ) -> EnumT | int:

src/frequenz/client/common/metric/__init__.py

@@ -142,7 +142,10 @@ class Metric(enum.Enum):
     SENSOR_IRRADIANCE = PBMetric.METRIC_SENSOR_IRRADIANCE
 
     @classmethod
-    @deprecated("Use `frequenz.client.common.enum_proto.enum_from_proto` instead.")
+    @deprecated(
+        "frequenz.client.common.metric.Metric.from_proto() is deprecated. "
+        "Use frequenz.client.common.proto.enum_from_proto instead."
+    )
     def from_proto(cls, metric: PBMetric.ValueType) -> Self:
         """Convert a protobuf Metric value to Metric enum.
 

src/frequenz/client/common/metrics/__init__.py

@@ -0,0 +1,24 @@
+# License: MIT
+# Copyright © 2025 Frequenz Energy-as-a-Service GmbH
+
+"""Metrics definitions."""
+
+from ._bounds import Bounds
+from ._metric import Metric
+from ._sample import (
+    AggregatedMetricValue,
+    AggregationMethod,
+    MetricConnection,
+    MetricConnectionCategory,
+    MetricSample,
+)
+
+__all__ = [
+    "AggregatedMetricValue",
+    "AggregationMethod",
+    "Bounds",
+    "Metric",
+    "MetricConnection",
+    "MetricConnectionCategory",
+    "MetricSample",
+]

src/frequenz/client/common/metrics/_bounds.py

@@ -0,0 +1,45 @@
+# License: MIT
+# Copyright © 2024 Frequenz Energy-as-a-Service GmbH
+
+
+"""Definitions for bounds."""
+
+import dataclasses
+
+
+@dataclasses.dataclass(frozen=True, kw_only=True)
+class Bounds:
+    """A set of lower and upper bounds for any metric.
+
+    The lower bound must be less than or equal to the upper bound.
+
+    The units of the bounds are always the same as the related metric.
+    """
+
+    lower: float | None = None
+    """The lower bound.
+
+    If `None`, there is no lower bound.
+    """
+
+    upper: float | None = None
+    """The upper bound.
+
+    If `None`, there is no upper bound.
+    """
+
+    def __post_init__(self) -> None:
+        """Validate these bounds."""
+        if self.lower is None:
+            return
+        if self.upper is None:
+            return
+        if self.lower > self.upper:
+            raise ValueError(
+                f"Lower bound ({self.lower}) must be less than or equal to upper "
+                f"bound ({self.upper})"
+            )
+
+    def __str__(self) -> str:
+        """Return a string representation of these bounds."""
+        return f"[{self.lower}, {self.upper}]"