Rename *ValueError to *EnumValueError (#234)

Both custom exceptions raised by the semantic accessors are specifically
about protobuf enum values: an UNSPECIFIED proto enum reaching a `get_*`
accessor, or an integer the client does not recognize as a member of the
wrapper enum. The current names suggest a generic value error and leave
the enum-value origin implicit.

Rename `UnspecifiedValueError` to `UnspecifiedEnumValueError` and
`UnrecognizedValueError` to `UnrecognizedEnumValueError`, putting that
origin in the type name.

Part of #223.

Author: llucax

RELEASE_NOTES.md

@@ -63,8 +63,8 @@
 * 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.
+    * `frequenz.client.common.UnspecifiedEnumValueError` for unspecified enum values (raw `0` or the deprecated member).
+    * `frequenz.client.common.UnrecognizedEnumValueError` 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:
 

src/frequenz/client/common/__init__.py

@@ -5,12 +5,12 @@
 
 from ._exception import (
     ClientCommonError,
-    UnrecognizedValueError,
-    UnspecifiedValueError,
+    UnrecognizedEnumValueError,
+    UnspecifiedEnumValueError,
 )
 
 __all__ = [
     "ClientCommonError",
-    "UnrecognizedValueError",
-    "UnspecifiedValueError",
+    "UnrecognizedEnumValueError",
+    "UnspecifiedEnumValueError",
 ]

src/frequenz/client/common/_exception.py

@@ -8,12 +8,12 @@ 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.
+class UnrecognizedEnumValueError(ClientCommonError, ValueError):
+    """Raised when a semantic accessor sees an unrecognized protobuf enum 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
+    [`UnspecifiedEnumValueError`][..UnspecifiedEnumValueError]). The raw
     unrecognized value is available as `value`.
 
     This is also a ``ValueError`` for convenience.
@@ -33,11 +33,11 @@ def __init__(self, value: int, message: str | None = None) -> None:
         )
 
 
-class UnspecifiedValueError(ClientCommonError, ValueError):
-    """Raised when a semantic accessor sees an unspecified protobuf value.
+class UnspecifiedEnumValueError(ClientCommonError, ValueError):
+    """Raised when a semantic accessor sees an unspecified protobuf enum value.
 
     For a value that is set but not recognized by this client, see
-    [`UnrecognizedValueError`][..UnrecognizedValueError].
+    [`UnrecognizedEnumValueError`][..UnrecognizedEnumValueError].
 
     This is also a [`ValueError`][] for convenience.
     """

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

@@ -9,7 +9,7 @@
 
 from frequenz.core.enum import Enum, deprecated_member, unique
 
-from .._exception import UnrecognizedValueError, UnspecifiedValueError
+from .._exception import UnrecognizedEnumValueError, UnspecifiedEnumValueError
 
 
 @unique
@@ -109,21 +109,23 @@ def get_code_type(self) -> EnergyMarketCodeType:
             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.
+            UnspecifiedEnumValueError: If the code type is unspecified.
+            UnrecognizedEnumValueError: 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")
+                    raise UnspecifiedEnumValueError(
+                        f"code type of {self} is unspecified"
+                    )
                 case EnergyMarketCodeType() as code_type:
                     return code_type
                 case int() as code_type:
-                    raise UnrecognizedValueError(
+                    raise UnrecognizedEnumValueError(
                         code_type,
                         f"code type {code_type!r} of {self} is not a recognized "
                         "EnergyMarketCodeType",

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

@@ -11,7 +11,7 @@
 
 from frequenz.core.enum import Enum, deprecated_member, unique
 
-from .._exception import UnrecognizedValueError, UnspecifiedValueError
+from .._exception import UnrecognizedEnumValueError, UnspecifiedEnumValueError
 from ._bounds import Bounds
 from ._metric import Metric
 
@@ -147,21 +147,23 @@ def get_category(self) -> MetricConnectionCategory:
             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.
+            UnspecifiedEnumValueError: If the category is unspecified (the raw
+                value `0` or a member whose value is `0`).
+            UnrecognizedEnumValueError: 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")
+                    raise UnspecifiedEnumValueError(
+                        "connection category is unspecified"
+                    )
                 case MetricConnectionCategory():
                     return self.category
                 case int():
-                    raise UnrecognizedValueError(
+                    raise UnrecognizedEnumValueError(
                         self.category,
                         f"connection category {self.category!r} is not a recognized "
                         "MetricConnectionCategory",
@@ -293,21 +295,21 @@ def get_metric(self) -> Metric:
             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.
+            UnspecifiedEnumValueError: If the metric is unspecified (the raw
+                value `0` or a member whose value is `0`).
+            UnrecognizedEnumValueError: 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")
+                    raise UnspecifiedEnumValueError("sampled metric is unspecified")
                 case Metric():
                     return self.metric
                 case int():
-                    raise UnrecognizedValueError(
+                    raise UnrecognizedEnumValueError(
                         self.metric,
                         f"sampled metric {self.metric!r} is not a recognized Metric",
                     )

src/frequenz/client/common/microgrid/_microgrid.py

@@ -6,7 +6,7 @@
 import datetime
 from dataclasses import dataclass, field
 
-from .._exception import UnspecifiedValueError
+from .._exception import UnspecifiedEnumValueError
 from ..grid._delivery_area import DeliveryArea
 from ..types._location import Location
 from ._ids import EnterpriseId, MicrogridId
@@ -77,11 +77,11 @@ def is_active(self) -> bool:
             Whether the microgrid is active.
 
         Raises:
-            UnspecifiedValueError: If the status is unspecified, so whether the
-                microgrid is active is unknown.
+            UnspecifiedEnumValueError: If the status is unspecified, so whether
+                the microgrid is active is unknown.
         """
         if self._active is None:
-            raise UnspecifiedValueError(
+            raise UnspecifiedEnumValueError(
                 f"status of microgrid {self} is unspecified; active state is unknown"
             )
         return self._active

src/frequenz/client/common/microgrid/electrical_components/_electrical_component.py

@@ -8,7 +8,7 @@
 from datetime import datetime, timezone
 from typing import Any, Self
 
-from ..._exception import UnspecifiedValueError
+from ..._exception import UnspecifiedEnumValueError
 from ...metrics import Bounds, Metric
 from ...types import Lifetime
 from .. import MicrogridId
@@ -109,11 +109,11 @@ def provides_telemetry(self) -> bool:
             Whether this electrical component provides telemetry data.
 
         Raises:
-            UnspecifiedValueError: If the operational mode is unspecified, so whether
-                telemetry is provided is unknown.
+            UnspecifiedEnumValueError: If the operational mode is unspecified,
+                so whether telemetry is provided is unknown.
         """
         if self._provides_telemetry is None:
-            raise UnspecifiedValueError(
+            raise UnspecifiedEnumValueError(
                 f"operational mode of {self} is unspecified; "
                 "telemetry availability is unknown"
             )
@@ -126,11 +126,11 @@ def accepts_control(self) -> bool:
             Whether this electrical component accepts control commands.
 
         Raises:
-            UnspecifiedValueError: If the operational mode is unspecified, so whether
-                control commands are accepted is unknown.
+            UnspecifiedEnumValueError: If the operational mode is unspecified,
+                so whether control commands are accepted is unknown.
         """
         if self._accepts_control is None:
-            raise UnspecifiedValueError(
+            raise UnspecifiedEnumValueError(
                 f"operational mode of {self} is unspecified; "
                 "control availability is unknown"
             )

src/frequenz/client/common/microgrid/electrical_components/proto/v1alpha8/_electrical_component.py

@@ -13,7 +13,7 @@
 )
 from google.protobuf.json_format import MessageToDict
 
-from ....._exception import UnrecognizedValueError
+from ....._exception import UnrecognizedEnumValueError
 from .....metrics import Bounds, Metric
 from .....metrics.proto.v1alpha8 import bounds_from_proto
 from .....proto import enum_from_proto
@@ -744,7 +744,7 @@ def electrical_component_class_from_proto(
     * `(<any other typeless category>, None)` → its concrete typeless class
       (`Breaker`, `Meter`, ... one per category).
     * `(<any known typeless category>, <non-None subtype>)` → raises
-      `UnrecognizedValueError`.
+      `UnrecognizedEnumValueError`.
     * `(<unknown category int>, <any subtype>)` → `UnrecognizedElectricalComponent`
       (subtype silently dropped).
 
@@ -771,7 +771,7 @@ def electrical_component_class_from_proto(
         The corresponding electrical component class.
 
     Raises:
-        UnrecognizedValueError: If `subtype` is not `None` for a known
+        UnrecognizedEnumValueError: If `subtype` is not `None` for a known
             typeless category — that combination has no representation in the
             protobuf wire format.
     """
@@ -787,7 +787,7 @@ def electrical_component_class_from_proto(
     typeless_class = _TYPELESS_CLASS_BY_PROTO_CATEGORY.get(category)
     if typeless_class is not None:
         if subtype is not None:
-            raise UnrecognizedValueError(int(subtype))
+            raise UnrecognizedEnumValueError(int(subtype))
         return typeless_class
 
     return UnrecognizedElectricalComponent

tests/grid/proto/v1alpha8/test_delivery_area.py

@@ -9,7 +9,7 @@
 import pytest
 from frequenz.api.common.v1alpha8.grid import delivery_area_pb2
 
-from frequenz.client.common import UnspecifiedValueError
+from frequenz.client.common import UnspecifiedEnumValueError
 from frequenz.client.common.grid import EnergyMarketCodeType
 from frequenz.client.common.grid.proto.v1alpha8 import (
     delivery_area_from_proto,
@@ -122,7 +122,7 @@ def test_from_proto(
 
 
 def test_get_code_type_from_proto_unspecified_raises() -> None:
-    """A proto-loaded unspecified code type raises UnspecifiedValueError."""
+    """A proto-loaded unspecified code type raises UnspecifiedEnumValueError."""
     proto = delivery_area_pb2.DeliveryArea(
         code="TEST",
         code_type=(
@@ -133,5 +133,5 @@ def test_get_code_type_from_proto_unspecified_raises() -> None:
         warnings.simplefilter("error", DeprecationWarning)
         area = delivery_area_from_proto(proto)
     assert area.code_type == 0
-    with pytest.raises(UnspecifiedValueError):
+    with pytest.raises(UnspecifiedEnumValueError):
         area.get_code_type()

tests/grid/test_delivery_area.py

@@ -8,7 +8,10 @@
 
 import pytest
 
-from frequenz.client.common import UnrecognizedValueError, UnspecifiedValueError
+from frequenz.client.common import (
+    UnrecognizedEnumValueError,
+    UnspecifiedEnumValueError,
+)
 from frequenz.client.common.grid import DeliveryArea, EnergyMarketCodeType
 
 
@@ -124,25 +127,25 @@ def test_get_code_type_returns_known_member(member: EnergyMarketCodeType) -> Non
 
 
 def test_get_code_type_raises_unspecified_for_int_zero() -> None:
-    """get_code_type() raises UnspecifiedValueError for a raw int 0 code type."""
+    """get_code_type() raises UnspecifiedEnumValueError for a raw int 0 code type."""
     area = DeliveryArea(code="TEST", code_type=0)
-    with pytest.raises(UnspecifiedValueError):
+    with pytest.raises(UnspecifiedEnumValueError):
         area.get_code_type()
 
 
 def test_get_code_type_raises_unspecified_for_value_zero_member() -> None:
-    """get_code_type() raises UnspecifiedValueError for the value-0 member."""
+    """get_code_type() raises UnspecifiedEnumValueError for the value-0 member."""
     with pytest.deprecated_call():
         area = DeliveryArea(code="TEST", code_type=EnergyMarketCodeType.UNSPECIFIED)
     with warnings.catch_warnings():
         warnings.simplefilter("error", DeprecationWarning)
-        with pytest.raises(UnspecifiedValueError):
+        with pytest.raises(UnspecifiedEnumValueError):
             area.get_code_type()
 
 
 def test_get_code_type_raises_unrecognized_for_unknown_int() -> None:
-    """get_code_type() raises UnrecognizedValueError carrying the raw value."""
+    """get_code_type() raises UnrecognizedEnumValueError carrying the raw value."""
     area = DeliveryArea(code="TEST", code_type=999)
-    with pytest.raises(UnrecognizedValueError) as exc_info:
+    with pytest.raises(UnrecognizedEnumValueError) as exc_info:
         area.get_code_type()
     assert exc_info.value.value == 999