Make get_metric_config_bounds() mimic dict.get()

Now that an absent metric-config entry means "explicitly unbounded",
forcing users to special-case absence (catching `KeyError` or checking
for `None`) is just friction: they almost always want the bounds and an
unbounded `Bounds()` is a perfectly usable answer. Return an unbounded
`Bounds()` for absent metrics instead of raising, and accept a
keyword-only `default` (like `dict.get()`) for callers that do need to
detect absence — `default=None` recovers the old
`get_metric_config_bounds_or_none()` behavior exactly, so that accessor
is removed.

Signed-off-by: Leandro Lucarella <luca-frequenz@llucax.com>

Author: llucax

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

@@ -18,7 +18,7 @@
 from ._converter import Converter
 from ._crypto_miner import CryptoMiner
 from ._diagnostic_code import ElectricalComponentDiagnosticCode
-from ._electrical_component import ElectricalComponent
+from ._electrical_component import DefaultT, ElectricalComponent
 from ._electrical_component_connection import (
     BaseElectricalComponentConnection,
     ElectricalComponentConnection,
@@ -85,6 +85,7 @@
     "Converter",
     "CryptoMiner",
     "DcEvCharger",
+    "DefaultT",
     "ElectricalComponent",
     "ElectricalComponentCategory",
     "ElectricalComponentConnection",

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

@@ -6,14 +6,17 @@
 import dataclasses
 from collections.abc import Mapping
 from datetime import datetime, timezone
-from typing import Any, Self, assert_never
+from typing import Any, Self, TypeVar, assert_never, overload
 
 from ..._exception import UnrecognizedEnumValueError, UnspecifiedEnumValueError
 from ...metrics import Bounds, InvalidBounds, InvalidBoundsError, Metric
 from .. import MicrogridId
 from .._lifetime import InvalidLifetime, InvalidLifetimeError, Lifetime
 from ._ids import ElectricalComponentId
 
+DefaultT = TypeVar("DefaultT")
+"""A type variable for the default value of dict-like getters."""
+
 
 @dataclasses.dataclass(frozen=True, kw_only=True)
 class ElectricalComponent:  # pylint: disable=too-many-instance-attributes
@@ -96,8 +99,7 @@ class ElectricalComponent:  # pylint: disable=too-many-instance-attributes
     as plain `int` keys for forward-compatibility.
 
     Tip:
-        Prefer [`get_metric_config_bounds()`][..get_metric_config_bounds] or
-        [`get_metric_config_bounds_or_none()`][..get_metric_config_bounds_or_none]
+        Prefer [`get_metric_config_bounds()`][..get_metric_config_bounds]
         when a valid [`Bounds`][.....metrics.Bounds] is required.
     """
 
@@ -203,54 +205,56 @@ def accepts_control(self) -> bool:
             case unknown:
                 assert_never(unknown)
 
-    def get_metric_config_bounds(self, metric: Metric) -> Bounds:  # noqa: DOC502,DOC503
+    @overload
+    def get_metric_config_bounds(self, metric: Metric) -> Bounds: ...
+
+    @overload
+    def get_metric_config_bounds(
+        self, metric: Metric, *, default: DefaultT
+    ) -> Bounds | DefaultT: ...
+
+    def get_metric_config_bounds(
+        self, metric: Metric, *, default: object = Bounds()
+    ) -> object:
         """Return the configured bounds for a metric as a valid `Bounds`.
 
-        Args:
-            metric: The metric whose bounds to retrieve.
+        An absent entry returns an unbounded metric, so when no bounds are
+        configured for `metric` this returns an unbounded
+        [`Bounds`][frequenz.client.common.metrics.Bounds] by default. Pass
+        `default` to return a different value for absent entries instead,
+        mimicking [`dict.get()`][dict.get].
 
-        Returns:
-            The valid [`Bounds`][.....metrics.Bounds] configured for `metric`.
+        Example:
+            To check if a `metric` has **valid** configured bounds, you can use:
 
-        Raises:
-            KeyError: If no bounds are configured for `metric`.
-            InvalidBoundsError: If the bounds configured for `metric` are
-                malformed. The offending instance is available on the
-                exception's `bounds` attribute.
-        """
-        bounds = self.metric_config_bounds[metric]
-        match bounds:
-            case InvalidBounds() as invalid:
-                raise InvalidBoundsError(
-                    self,
-                    "metric_config_bounds",
-                    invalid,
-                    f"invalid bounds {invalid!r} for metric {metric} in {self}",
-                )
-            case Bounds() as valid:
-                return valid
-            case unknown:
-                assert_never(unknown)
+            ```py
+            component: ElectricalComponent
+            metric: Metric
+            if component.get_metric_config_bounds(metric, default=None) is not None:
+                print(f"{metric} has valid configured bounds")
+            ```
 
-    def get_metric_config_bounds_or_none(self, metric: Metric) -> Bounds | None:
-        """Return the configured bounds for a metric, or `None` when absent.
+            This is similar to accessing
+            [`metric_config_bounds`][...ElectricalComponent.metric_config_bounds]
+            directly, but avoid the special handling of invalid bounds.
 
         Args:
             metric: The metric whose bounds to retrieve.
+            default: The value to return when no bounds are configured for
+                `metric`.
 
         Returns:
             The valid [`Bounds`][.....metrics.Bounds] configured for `metric`,
-                or `None` when no bounds are configured for it.
+                or `default` when there is no entry for `metric`.
 
         Raises:
             InvalidBoundsError: If the bounds configured for `metric` are
                 malformed. The offending instance is available on the
                 exception's `bounds` attribute.
         """
-        bounds = self.metric_config_bounds.get(metric)
-        match bounds:
+        match self.metric_config_bounds.get(metric):
             case None:
-                return None
+                return default
             case InvalidBounds() as invalid:
                 raise InvalidBoundsError(
                     self,

tests/microgrid/electrical_components/test_electrical_component_base.py

@@ -237,53 +237,62 @@ def test_get_metric_config_bounds_returns_valid_bounds() -> None:
     assert result is bounds
 
 
-def test_get_metric_config_bounds_absent_raises_key_error() -> None:
-    """`get_metric_config_bounds` raises `KeyError` when no bounds are configured."""
+def test_get_metric_config_bounds_absent_returns_unbounded() -> None:
+    """`get_metric_config_bounds` returns an unbounded `Bounds` for absent metrics."""
     component = _make_component(metric_config_bounds={})
 
-    with pytest.raises(KeyError):
-        component.get_metric_config_bounds(Metric.AC_POWER_ACTIVE)
+    result = component.get_metric_config_bounds(Metric.AC_POWER_ACTIVE)
 
+    assert result == Bounds()
+    assert isinstance(result, Bounds)
 
-def test_get_metric_config_bounds_invalid_raises_error() -> None:
-    """`get_metric_config_bounds` raises `InvalidBoundsError` for malformed entries."""
-    invalid = InvalidBounds(lower=10.0, upper=-10.0)
-    component = _make_component(metric_config_bounds={Metric.AC_POWER_ACTIVE: invalid})
 
-    with pytest.raises(InvalidBoundsError) as exc_info:
-        component.get_metric_config_bounds(Metric.AC_POWER_ACTIVE)
+def test_get_metric_config_bounds_absent_returns_default() -> None:
+    """`get_metric_config_bounds` returns `default` for absent metrics."""
+    component = _make_component(metric_config_bounds={})
+    sentinel = object()
 
-    assert exc_info.value.bounds is invalid
-    assert "AC_POWER_ACTIVE" in str(exc_info.value)
+    assert (
+        component.get_metric_config_bounds(Metric.AC_POWER_ACTIVE, default=None) is None
+    )
+    assert (
+        component.get_metric_config_bounds(Metric.AC_POWER_ACTIVE, default=sentinel)
+        is sentinel
+    )
 
 
-def test_get_metric_config_bounds_or_none_returns_valid_bounds() -> None:
-    """`get_metric_config_bounds_or_none` returns the configured `Bounds`."""
+def test_get_metric_config_bounds_present_ignores_default() -> None:
+    """`get_metric_config_bounds` ignores `default` when the metric has bounds."""
     bounds = Bounds(lower=-10.0, upper=10.0)
     component = _make_component(metric_config_bounds={Metric.AC_POWER_ACTIVE: bounds})
 
-    assert component.get_metric_config_bounds_or_none(Metric.AC_POWER_ACTIVE) is bounds
-
-
-def test_get_metric_config_bounds_or_none_absent_returns_none() -> None:
-    """`get_metric_config_bounds_or_none` returns `None` when no bounds are configured."""
-    component = _make_component(metric_config_bounds={})
-
-    assert component.get_metric_config_bounds_or_none(Metric.AC_POWER_ACTIVE) is None
+    assert (
+        component.get_metric_config_bounds(Metric.AC_POWER_ACTIVE, default=None)
+        is bounds
+    )
 
 
-def test_get_metric_config_bounds_or_none_invalid_raises_error() -> None:
-    """`get_metric_config_bounds_or_none` still raises for malformed entries."""
+def test_get_metric_config_bounds_invalid_raises_error() -> None:
+    """`get_metric_config_bounds` raises `InvalidBoundsError` for malformed entries."""
     invalid = InvalidBounds(lower=10.0, upper=-10.0)
     component = _make_component(metric_config_bounds={Metric.AC_POWER_ACTIVE: invalid})
 
     with pytest.raises(InvalidBoundsError) as exc_info:
-        component.get_metric_config_bounds_or_none(Metric.AC_POWER_ACTIVE)
+        component.get_metric_config_bounds(Metric.AC_POWER_ACTIVE)
 
     assert exc_info.value.bounds is invalid
     assert "AC_POWER_ACTIVE" in str(exc_info.value)
 
 
+def test_get_metric_config_bounds_invalid_raises_despite_default() -> None:
+    """`default` only applies to absent metrics, not malformed ones."""
+    invalid = InvalidBounds(lower=10.0, upper=-10.0)
+    component = _make_component(metric_config_bounds={Metric.AC_POWER_ACTIVE: invalid})
+
+    with pytest.raises(InvalidBoundsError):
+        component.get_metric_config_bounds(Metric.AC_POWER_ACTIVE, default=None)
+
+
 @pytest.mark.parametrize(
     "name,expected_str",
     [