Use exclusion bounds while calculating target_power

Also extract the calculation logic into a separate function.

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

Author: shsms

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

@@ -36,6 +36,60 @@
 _logger = logging.getLogger(__name__)
 
 
+# Just 20 lines of code in this function, but unfortunately 8 of those are return
+# statements, and that's too many for pylint.
+def _clamp_to_bounds(  # pylint: disable=too-many-return-statements
+    value: Power,
+    lower_bound: Power,
+    upper_bound: Power,
+    exclusion_bounds: timeseries.Bounds[Power] | None,
+) -> Power:
+    """Clamp the given value to the given bounds.
+
+    Args:
+        value: The value to clamp.
+        lower_bound: The lower bound to clamp to.
+        upper_bound: The upper bound to clamp to.
+        exclusion_bounds: The exclusion bounds to clamp outside of.
+
+    Returns:
+        The clamped value.
+    """
+    # If the given bounds are within the exclusion bounds, return zero.
+    #
+    # And if the given bounds overlap with the exclusion bounds on one side, and the
+    # given power is in that overlap region, clamp it to the exclusion bounds on that
+    # side.
+    if exclusion_bounds is not None:
+        match _check_exclusion_bounds_overlap(
+            lower_bound, upper_bound, exclusion_bounds
+        ):
+            case (True, True):
+                return Power.zero()
+            case (True, False):
+                if value < exclusion_bounds.upper:
+                    return exclusion_bounds.upper
+            case (False, True):
+                if value > exclusion_bounds.lower:
+                    return exclusion_bounds.lower
+
+    # If the given value is outside the given bounds, clamp it to the closest bound.
+    if value < lower_bound:
+        return lower_bound
+    if value > upper_bound:
+        return upper_bound
+
+    # If the given value is within the exclusion bounds and the exclusion bounds are
+    # within the given bounds, clamp the given value to the closest exclusion bound.
+    if exclusion_bounds is not None:
+        if exclusion_bounds.lower < value < exclusion_bounds.upper:
+            if value - exclusion_bounds.lower < exclusion_bounds.upper - value:
+                return exclusion_bounds.lower
+            return exclusion_bounds.upper
+
+    return value
+
+
 def _check_exclusion_bounds_overlap(
     lower_bound: Power,
     upper_bound: Power,
@@ -148,12 +202,12 @@ def _calc_target_power(
             if upper_bound < lower_bound:
                 break
             if next_proposal.preferred_power:
-                if next_proposal.preferred_power > upper_bound:
-                    target_power = upper_bound
-                elif next_proposal.preferred_power < lower_bound:
-                    target_power = lower_bound
-                else:
-                    target_power = next_proposal.preferred_power
+                target_power = _clamp_to_bounds(
+                    next_proposal.preferred_power,
+                    lower_bound,
+                    upper_bound,
+                    exclusion_bounds,
+                )
             proposal_lower, proposal_upper = (
                 next_proposal.bounds.lower or lower_bound,
                 next_proposal.bounds.upper or upper_bound,
@@ -308,10 +362,8 @@ def get_status(
             calc_lower_bound = max(lower_bound, proposal_lower)
             calc_upper_bound = min(upper_bound, proposal_upper)
             if calc_lower_bound <= calc_upper_bound:
-                lower_bound = calc_lower_bound
-                upper_bound = calc_upper_bound
                 lower_bound, upper_bound = _adjust_exclusion_bounds(
-                    lower_bound, upper_bound, exclusion_bounds
+                    calc_lower_bound, calc_upper_bound, exclusion_bounds
                 )
             else:
                 break