Expose only outer usable bounds

With this change, the SDK will just expose one set of outer bounds,
even if it has exclusion zones within.  The representation of bounds
data in the SDK is no longer exposed.

When users need additional control over what power values they
propose, they can use the `adjust_to_bounds` methods.

Signed-off-by: Sahas Subramanian <[email protected]>

Author: shsms

src/frequenz/sdk/actor/_power_managing/_base_classes.py

@@ -50,14 +50,14 @@ class Report:
     target_power: Power | None
     """The currently set power for the batteries."""
 
-    inclusion_bounds: timeseries.Bounds[Power] | None
+    _inclusion_bounds: timeseries.Bounds[Power] | None
     """The available inclusion bounds for the batteries, for the actor's priority.
 
     These bounds are adjusted to any restrictions placed by actors with higher
     priorities.
     """
 
-    exclusion_bounds: timeseries.Bounds[Power] | None
+    _exclusion_bounds: timeseries.Bounds[Power] | None
     """The exclusion bounds for the batteries.
 
     The power manager doesn't manage exclusion bounds, so these are aggregations of
@@ -73,6 +73,20 @@ class Report:
     This is `None` if no power distribution has been performed yet.
     """
 
+    @property
+    def bounds(self) -> timeseries.Bounds[Power] | None:
+        """The bounds for the batteries.
+
+        These bounds are adjusted to any restrictions placed by actors with higher
+        priorities.
+
+        There might be exclusion zones within these bounds. If necessary, the
+        [`adjust_to_bounds`][frequenz.sdk.timeseries.battery_pool.Report.adjust_to_bounds]
+        method may be used to check if a desired power value fits the bounds, or to get
+        the closest possible power values that do fit the bounds.
+        """
+        return self._inclusion_bounds
+
     def adjust_to_bounds(self, power: Power) -> tuple[Power | None, Power | None]:
         """Adjust a power value to the bounds.
 
@@ -123,14 +137,14 @@ def adjust_to_bounds(self, power: Power) -> tuple[Power | None, Power | None]:
             A tuple of the closest power values to the desired power that fall within
                 the available bounds for the actor.
         """
-        if self.inclusion_bounds is None:
+        if self._inclusion_bounds is None:
             return None, None
 
         return _clamp_to_bounds(
             power,
-            self.inclusion_bounds.lower,
-            self.inclusion_bounds.upper,
-            self.exclusion_bounds,
+            self._inclusion_bounds.lower,
+            self._inclusion_bounds.upper,
+            self._exclusion_bounds,
         )
 
 

src/frequenz/sdk/actor/_power_managing/_matryoshka.py

@@ -228,8 +228,8 @@ def get_status(
         if system_bounds.inclusion_bounds is None:
             return Report(
                 target_power=target_power,
-                inclusion_bounds=None,
-                exclusion_bounds=system_bounds.exclusion_bounds,
+                _inclusion_bounds=None,
+                _exclusion_bounds=system_bounds.exclusion_bounds,
                 distribution_result=distribution_result,
             )
 
@@ -263,9 +263,9 @@ def get_status(
                 break
         return Report(
             target_power=target_power,
-            inclusion_bounds=timeseries.Bounds[Power](
+            _inclusion_bounds=timeseries.Bounds[Power](
                 lower=lower_bound, upper=upper_bound
             ),
-            exclusion_bounds=system_bounds.exclusion_bounds,
+            _exclusion_bounds=system_bounds.exclusion_bounds,
             distribution_result=distribution_result,
         )

tests/actor/_power_managing/test_matryoshka.py

@@ -69,9 +69,11 @@ def bounds(
         else:
             assert report.target_power is not None
             assert report.target_power.as_watts() == expected_power
-        assert report.inclusion_bounds is not None
-        assert report.inclusion_bounds.lower.as_watts() == expected_bounds[0]
-        assert report.inclusion_bounds.upper.as_watts() == expected_bounds[1]
+        # pylint: disable=protected-access
+        assert report._inclusion_bounds is not None
+        assert report._inclusion_bounds.lower.as_watts() == expected_bounds[0]
+        assert report._inclusion_bounds.upper.as_watts() == expected_bounds[1]
+        # pylint: enable=protected-access
 
 
 async def test_matryoshka_no_excl() -> None:  # pylint: disable=too-many-statements

tests/actor/_power_managing/test_report.py

@@ -18,13 +18,13 @@ def __init__(
         """Initialize the tester."""
         self._report = Report(
             target_power=None,
-            inclusion_bounds=Bounds(
+            _inclusion_bounds=Bounds(  # pylint: disable=protected-access
                 Power.from_watts(inclusion_bounds[0]),
                 Power.from_watts(inclusion_bounds[1]),
             )
             if inclusion_bounds is not None
             else None,
-            exclusion_bounds=Bounds(
+            _exclusion_bounds=Bounds(  # pylint: disable=protected-access
                 Power.from_watts(exclusion_bounds[0]),
                 Power.from_watts(exclusion_bounds[1]),
             )

tests/timeseries/_battery_pool/test_battery_pool_control_methods.py

@@ -149,13 +149,16 @@ def _assert_report(
         assert report.target_power == (
             Power.from_watts(power) if power is not None else None
         )
+        # pylint: disable=protected-access
         assert (
-            report.inclusion_bounds is not None and report.exclusion_bounds is not None
+            report._inclusion_bounds is not None
+            and report._exclusion_bounds is not None
         )
-        assert report.inclusion_bounds.lower == Power.from_watts(lower)
-        assert report.inclusion_bounds.upper == Power.from_watts(upper)
-        assert report.exclusion_bounds.lower == Power.from_watts(0.0)
-        assert report.exclusion_bounds.upper == Power.from_watts(0.0)
+        assert report._inclusion_bounds.lower == Power.from_watts(lower)
+        assert report._inclusion_bounds.upper == Power.from_watts(upper)
+        assert report._exclusion_bounds.lower == Power.from_watts(0.0)
+        assert report._exclusion_bounds.upper == Power.from_watts(0.0)
+        # pylint: enable=protected-access
         if expected_result_pred is not None:
             assert report.distribution_result is not None
             assert expected_result_pred(report.distribution_result)