Deprecate UNSPECIFIED for simple enums (#221)

Deprecate `EnergyMarketCodeType.UNSPECIFIED`, `Metric.UNSPECIFIED` and
`MetricConnectionCategory.UNSPECIFIED` and add new safe accessor methods
to retrieve the valid enum values or raise an exception:

- `DeliveryArea.get_code_type()`
- `MetricConnection.get_category()`
- `MetricSample.get_metric()`

The `UNSPECIFIED` value is now stored as a low-level `0` integer, so
users can still access it directly if needed, but regular use will raise
an exception if trying to use an unspecified or unrecognized value. This
should lead to much simpler happy path, while still allowing for the
possibility of handling unspecified values in a controlled manner and
making rare and error conditions more explicit.

The `ElectricalComponentCategory` and `XxxType` enums are not affected
by this change, as they do not have an `UNSPECIFIED` value, but will be
completely removed in the future.

Part of #223.

Author: llucax

RELEASE_NOTES.md

@@ -6,14 +6,38 @@
 
 ## Upgrading
 
-<!-- Here goes notes on how to upgrade from previous versions, including deprecations and what they should be replaced with -->
+* The `UNSPECIFIED` members in the following enums are now deprecated:
+
+    * `frequenz.client.common.grid.EnergyMarketCodeType`
+    * `frequenz.client.common.metrics.Metric`
+    * `frequenz.client.common.metrics.MetricConnectionCategory`
+
+    When loading these types from protobuf using dataclass-level converters (e.g., `delivery_area_from_proto`, `metric_sample_from_proto`), the low-level fields (`code_type`, `category`, `metric`) now store the raw integer `0` for unspecified values instead of the deprecated member. Unspecified values should be rare errors, so it is better to expose them only via the low-level interface.
+
+    Lower-level enum-level converters still return the deprecated member.
+
+    Users are encouraged to switch from direct field access to the new `get_*()` methods (see New Features), which provide a safer way to handle unspecified or unrecognized values.
 
 ## New Features
 
+* Added new exceptions:
+
+    * `frequenz.client.common.ClientCommonError` as a base exception for the package.
+    * `frequenz.client.common.UnspecifiedValueError` for unspecified values (raw `0` or the deprecated member).
+    * `frequenz.client.common.UnrecognizedValueError` for enum members not yet recognized by the library. Carries the raw integer value in its `value` attribute.
+
+* Added safe convenience getters that raise the new exceptions for unspecified or unrecognized values:
+
+    * `frequenz.client.common.grid.DeliveryArea.get_code_type()`
+    * `frequenz.client.common.metrics.MetricConnection.get_category()`
+    * `frequenz.client.common.metrics.MetricSample.get_metric()`
+
 * Added a new `frequenz.client.common.types.Lifetime` type together with the `frequenz.client.common.types.proto.v1alpha8.lifetime_from_proto` conversion function.
+
 * Added a new `frequenz.client.common.types.Location` type together with the `frequenz.client.common.types.proto.v1alpha8.location_from_proto` conversion function.
+
 * Added a new `frequenz.client.common.microgrid.Microgrid` type, together with the `frequenz.client.common.microgrid.proto.v1alpha8.microgrid_from_proto` conversion function.
-* Added a new `frequenz.client.common.ClientCommonError` base exception and `UnspecifiedValueError` at the package root.
+
 * Added a new `frequenz.client.common.microgrid.electrical_components` package, featuring a `ElectricalComponent` class hierarchy and its families (battery, inverter, EV charger, etc.), and `ElectricalComponentConnection`, including `v1alpha8` proto conversion functions.
 * Added a new `frequenz.client.common.microgrid.Microgrid` type with a raising `is_active()` method, together with the `frequenz.client.common.microgrid.proto.v1alpha8.microgrid_from_proto` conversion function.
 

pyproject.toml

@@ -28,7 +28,7 @@ requires-python = ">= 3.11, < 4"
 dependencies = [
   "typing-extensions >= 4.13.0, < 5",
   "frequenz-api-common >= 0.8.4, < 1",
-  "frequenz-core >= 1.0.2, < 2",
+  "frequenz-core >= 1.3.0, < 2",
   "protobuf >= 6.33.6, < 8",
 ]
 dynamic = ["version"]

src/frequenz/client/common/__init__.py

@@ -3,9 +3,14 @@
 
 """Common code and utilities for Frequenz API clients."""
 
-from ._exception import ClientCommonError, UnspecifiedValueError
+from ._exception import (
+    ClientCommonError,
+    UnrecognizedValueError,
+    UnspecifiedValueError,
+)
 
 __all__ = [
     "ClientCommonError",
+    "UnrecognizedValueError",
     "UnspecifiedValueError",
 ]

src/frequenz/client/common/_exception.py

@@ -8,8 +8,36 @@ class ClientCommonError(Exception):
     """Base class for all errors raised by frequenz-client-common."""
 
 
+class UnrecognizedValueError(ClientCommonError, ValueError):
+    """Raised when a semantic accessor sees an unrecognized protobuf value.
+
+    This happens when the server sets an enum value that this version of the
+    client does not recognize, as opposed to an unspecified value (see
+    [`UnspecifiedValueError`][..UnspecifiedValueError]). The raw
+    unrecognized value is available as `value`.
+
+    This is also a ``ValueError`` for convenience.
+    """
+
+    def __init__(self, value: int, message: str | None = None) -> None:
+        """Initialize this error.
+
+        Args:
+            value: The raw protobuf value that was not recognized.
+            message: A custom error message. If `None`, a default message
+                mentioning the unrecognized value is used.
+        """
+        self.value: int = value
+        super().__init__(
+            message if message is not None else f"unrecognized enum value: {value!r}"
+        )
+
+
 class UnspecifiedValueError(ClientCommonError, ValueError):
-    """Raised when a semantic accessor sees an unspecified or unknown protobuf value.
+    """Raised when a semantic accessor sees an unspecified protobuf value.
+
+    For a value that is set but not recognized by this client, see
+    [`UnrecognizedValueError`][..UnrecognizedValueError].
 
     This is also a [`ValueError`][] for convenience.
     """

src/frequenz/client/common/grid/_delivery_area.py

@@ -3,12 +3,17 @@
 
 """Delivery area information for the energy market."""
 
-import enum
+import warnings
 from dataclasses import dataclass
+from typing import assert_never
 
+from frequenz.core.enum import Enum, deprecated_member, unique
 
-@enum.unique
-class EnergyMarketCodeType(enum.Enum):
+from .._exception import UnrecognizedValueError, UnspecifiedValueError
+
+
+@unique
+class EnergyMarketCodeType(Enum):
     """The identification code types used in the energy market.
 
     CodeType specifies the type of identification code used for uniquely
@@ -35,7 +40,11 @@ class EnergyMarketCodeType(enum.Enum):
         processing errors.
     """
 
-    UNSPECIFIED = 0
+    UNSPECIFIED = deprecated_member(
+        0,
+        "EnergyMarketCodeType.UNSPECIFIED is deprecated; use the `int` value `0` "
+        "instead if you really need to check for this low-level value.",
+    )
     """Unspecified type. This value is a placeholder and should not be used."""
 
     EUROPE_EIC = 1
@@ -74,6 +83,9 @@ class DeliveryArea:
 
     This code could be extended in the future, in case an unknown code type is
     encountered, a plain integer value is used to represent it.
+
+    This is the lower-level, forward-compatible accessor; prefer
+    `DeliveryArea.get_code_type()` to obtain a known member or a clear error.
     """
 
     def __str__(self) -> str:
@@ -85,3 +97,36 @@ def __str__(self) -> str:
             else self.code_type.name
         )
         return f"{code}[{code_type}]"
+
+    def get_code_type(self) -> EnergyMarketCodeType:
+        """Return the code type as a known enum member.
+
+        This is the higher-level accessor for the `code_type` attribute: it
+        resolves the value to a known `EnergyMarketCodeType` member or raises a
+        clear, catchable error.
+
+        Returns:
+            The code type, when it is a known `EnergyMarketCodeType` member.
+
+        Raises:
+            UnspecifiedValueError: If the code type is unspecified.
+            UnrecognizedValueError: If the code type is a value not recognized by
+                this version of the client. The raw value is available on the
+                exception's `value` attribute.
+        """
+        # Suppressing the deprecation warning can be removed when UNSPECIFIED is removed
+        with warnings.catch_warnings():
+            warnings.filterwarnings("ignore", category=DeprecationWarning)
+            match self.code_type:
+                case 0 | EnergyMarketCodeType.UNSPECIFIED:
+                    raise UnspecifiedValueError(f"code type of {self} is unspecified")
+                case EnergyMarketCodeType() as code_type:
+                    return code_type
+                case int() as code_type:
+                    raise UnrecognizedValueError(
+                        code_type,
+                        f"code type {code_type!r} of {self} is not a recognized "
+                        "EnergyMarketCodeType",
+                    )
+                case unknown:
+                    assert_never(unknown)

src/frequenz/client/common/grid/proto/v1alpha8/_delivery_area.py

@@ -57,8 +57,13 @@ def delivery_area_from_proto(message: delivery_area_pb2.DeliveryArea) -> Deliver
     if code is None:
         issues.append("code is empty")
 
-    code_type = energy_market_code_type_from_proto(message.code_type)
-    if code_type is EnergyMarketCodeType.UNSPECIFIED:
+    raw_code_type = message.code_type
+    code_type: EnergyMarketCodeType | int = (
+        raw_code_type
+        if raw_code_type == 0
+        else energy_market_code_type_from_proto(raw_code_type)
+    )
+    if raw_code_type == 0:
         issues.append("code_type is unspecified")
     elif isinstance(code_type, int):
         issues.append("code_type is unrecognized")

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

@@ -3,11 +3,11 @@
 
 """Supported metrics for microgrid components."""
 
-import enum
+from frequenz.core import enum as core_enum
 
 
-@enum.unique
-class Metric(enum.Enum):
+@core_enum.unique
+class Metric(core_enum.Enum):
     """List of supported metrics.
 
     Metric units are as follows:
@@ -39,7 +39,11 @@ class Metric(enum.Enum):
           period, and therefore can be inconsistent.
     """
 
-    UNSPECIFIED = 0
+    UNSPECIFIED = core_enum.deprecated_member(
+        0,
+        "Metric.UNSPECIFIED is deprecated; use the `int` value `0` "
+        "instead if you really need to check for this low-level value.",
+    )
     """The metric is unspecified (this should not be used)."""
 
     DC_VOLTAGE = 1

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

@@ -4,11 +4,15 @@
 """Definition to work with metric sample values."""
 
 import enum
+import warnings
 from collections.abc import Sequence
 from dataclasses import dataclass
 from datetime import datetime
 from typing import assert_never
 
+from frequenz.core import enum as core_enum
+
+from .._exception import UnrecognizedValueError, UnspecifiedValueError
 from ._bounds import Bounds
 from ._metric import Metric
 
@@ -66,11 +70,15 @@ def __str__(self) -> str:
         return f"avg:{self.avg}{extra_str}"
 
 
-@enum.unique
-class MetricConnectionCategory(enum.Enum):
+@core_enum.unique
+class MetricConnectionCategory(core_enum.Enum):
     """The categories of connections from which metrics can be obtained."""
 
-    UNSPECIFIED = 0
+    UNSPECIFIED = core_enum.deprecated_member(
+        0,
+        "MetricConnectionCategory.UNSPECIFIED is deprecated; use the `int` value `0` "
+        "instead if you really need to check for this low-level value.",
+    )
     """The connection category was not specified (do not use)."""
 
     OTHER = 1
@@ -100,7 +108,13 @@ class MetricConnection:
     """A connection from which a metric was obtained."""
 
     category: MetricConnectionCategory | int
-    """The category of the connection from which the metric was obtained."""
+    """The category of the connection from which the metric was obtained.
+
+    This is the lower-level, forward-compatible accessor: it may hold a known
+    `MetricConnectionCategory` member, the raw `int` `0` when the category is
+    unspecified, or any other raw `int` not yet known to this client. Prefer
+    `MetricConnection.get_category()` to obtain a known member or a clear error.
+    """
 
     name: str | None = None
     """The name of the specific connection from which the metric was obtained.
@@ -122,6 +136,40 @@ def __str__(self) -> str:
             return f"{category_name}({self.name})"
         return category_name
 
+    def get_category(self) -> MetricConnectionCategory:
+        """Return the connection category as a known enum member.
+
+        This is the higher-level accessor for the lower-level
+        [`category`][frequenz.client.common.metrics.MetricConnection.category]
+        field: it returns a known member or raises instead of exposing the raw
+        sentinel `0` or an unknown `int`.
+
+        Returns:
+            The category when it is a known `MetricConnectionCategory` member.
+
+        Raises:
+            UnspecifiedValueError: If the category is unspecified (the raw value
+                `0` or a member whose value is `0`).
+            UnrecognizedValueError: If the category is an `int` this client does
+                not recognize. The raw value is available on the error's `value`
+                attribute.
+        """
+        with warnings.catch_warnings():
+            warnings.filterwarnings("ignore", category=DeprecationWarning)
+            match self.category:
+                case 0 | MetricConnectionCategory.UNSPECIFIED:
+                    raise UnspecifiedValueError("connection category is unspecified")
+                case MetricConnectionCategory():
+                    return self.category
+                case int():
+                    raise UnrecognizedValueError(
+                        self.category,
+                        f"connection category {self.category!r} is not a recognized "
+                        "MetricConnectionCategory",
+                    )
+                case unexpected:
+                    assert_never(unexpected)
+
 
 @dataclass(frozen=True, kw_only=True)
 class MetricSample:
@@ -141,7 +189,13 @@ class MetricSample:
     """The moment when the metric was sampled."""
 
     metric: Metric | int
-    """The metric that was sampled."""
+    """The metric that was sampled.
+
+    This is the lower-level, forward-compatible accessor: it may hold a known
+    `Metric` member, the raw `int` `0` when the metric is unspecified, or any
+    other raw `int` not yet known to this client. Prefer
+    `MetricSample.get_metric()` to obtain a known member or a clear error.
+    """
 
     value: float | AggregatedMetricValue | None
     """The value of the sampled metric."""
@@ -227,3 +281,36 @@ def as_single_value(
                 return None
             case unexpected:
                 assert_never(unexpected)
+
+    def get_metric(self) -> Metric:
+        """Return the sampled metric as a known enum member.
+
+        This is the higher-level accessor for the lower-level
+        [`metric`][frequenz.client.common.metrics.MetricSample.metric] field: it
+        returns a known member or raises instead of exposing the raw sentinel
+        `0` or an unknown `int`.
+
+        Returns:
+            The metric when it is a known `Metric` member.
+
+        Raises:
+            UnspecifiedValueError: If the metric is unspecified (the raw value
+                `0` or a member whose value is `0`).
+            UnrecognizedValueError: If the metric is an `int` this client does
+                not recognize. The raw value is available on the error's `value`
+                attribute.
+        """
+        with warnings.catch_warnings():
+            warnings.filterwarnings("ignore", category=DeprecationWarning)
+            match self.metric:
+                case 0 | Metric.UNSPECIFIED:
+                    raise UnspecifiedValueError("sampled metric is unspecified")
+                case Metric():
+                    return self.metric
+                case int():
+                    raise UnrecognizedValueError(
+                        self.metric,
+                        f"sampled metric {self.metric!r} is not a recognized Metric",
+                    )
+                case unexpected:
+                    assert_never(unexpected)