Allow all quantities multiplication by float | Percentage

This is only applying a factor so it should be safe for any Quantity.

To be able to use nicer names in overloads, we use positional-only
arguments for `__mul__()`, which in practice shouldn't be much of a
breaking change as these methods should be used mostly via operators.

We also use `match` syntax in the changed methods.

Signed-off-by: Leandro Lucarella <[email protected]>

Author: llucax

src/frequenz/sdk/timeseries/_quantities.py

@@ -334,7 +334,19 @@ def __sub__(self, other: Self) -> Self:
         difference._base_value = self._base_value - other._base_value
         return difference
 
-    def __mul__(self, percent: Percentage) -> Self:
+    @overload
+    def __mul__(self, scalar: float, /) -> Self:
+        """Scale this quantity by a scalar.
+
+        Args:
+            scalar: The scaler by which to scale this quantity.
+
+        Returns:
+            The scaled quantity.
+        """
+
+    @overload
+    def __mul__(self, percent: Percentage, /) -> Self:
         """Scale this quantity by a percentage.
 
         Args:
@@ -343,12 +355,23 @@ def __mul__(self, percent: Percentage) -> Self:
         Returns:
             The scaled quantity.
         """
-        if not isinstance(percent, Percentage):
-            return NotImplemented
 
-        product = type(self).__new__(type(self))
-        product._base_value = self._base_value * percent.as_fraction()
-        return product
+    def __mul__(self, value: float | Percentage, /) -> Self:
+        """Scale this quantity by a scalar or percentage.
+
+        Args:
+            value: The scalar or percentage by which to scale this quantity.
+
+        Returns:
+            The scaled quantity.
+        """
+        match value:
+            case float():
+                return type(self)._new(self._base_value * value)
+            case Percentage():
+                return type(self)._new(self._base_value * value.as_fraction())
+            case _:
+                return NotImplemented
 
     def __gt__(self, other: Self) -> bool:
         """Return whether this quantity is greater than another.
@@ -584,18 +607,29 @@ def as_megawatts(self) -> float:
         return self._base_value / 1e6
 
     @overload  # type: ignore
-    def __mul__(self, other: Percentage) -> Self:
+    def __mul__(self, scalar: float, /) -> Self:
+        """Scale this power by a scalar.
+
+        Args:
+            scalar: The scaler by which to scale this power.
+
+        Returns:
+            The scaled quantity.
+        """
+
+    @overload
+    def __mul__(self, percent: Percentage, /) -> Self:
         """Scale this power by a percentage.
 
         Args:
-            other: The percentage by which to scale this power.
+            percent: The percentage by which to scale this power.
 
         Returns:
             The scaled power.
         """
 
     @overload
-    def __mul__(self, other: timedelta) -> Energy:
+    def __mul__(self, other: timedelta, /) -> Energy:
         """Return an energy from multiplying this power by the given duration.
 
         Args:
@@ -605,23 +639,22 @@ def __mul__(self, other: timedelta) -> Energy:
             The calculated energy.
         """
 
-    def __mul__(self, other: Percentage | timedelta) -> Self | Energy:
+    def __mul__(self, other: float | Percentage | timedelta, /) -> Self | Energy:
         """Return a power or energy from multiplying this power by the given value.
 
         Args:
-            other: The percentage or duration to multiply by.
+            other: The scalar, percentage or duration to multiply by.
 
         Returns:
             A power or energy.
         """
-        if isinstance(other, Percentage):
-            return super().__mul__(other)
-        if isinstance(other, timedelta):
-            return Energy.from_watt_hours(
-                self._base_value * other.total_seconds() / 3600.0
-            )
-
-        return NotImplemented
+        match other:
+            case float() | Percentage():
+                return super().__mul__(other)
+            case timedelta():
+                return Energy._new(self._base_value * other.total_seconds() / 3600.0)
+            case _:
+                return NotImplemented
 
     @overload
     def __truediv__(self, other: Current) -> Voltage:
@@ -726,18 +759,29 @@ def as_milliamperes(self) -> float:
         return self._base_value * 1e3
 
     @overload  # type: ignore
-    def __mul__(self, other: Percentage) -> Self:
+    def __mul__(self, scalar: float, /) -> Self:
+        """Scale this current by a scalar.
+
+        Args:
+            scalar: The scaler by which to scale this current.
+
+        Returns:
+            The scaled quantity.
+        """
+
+    @overload
+    def __mul__(self, percent: Percentage, /) -> Self:
         """Scale this current by a percentage.
 
         Args:
-            other: The percentage by which to scale this current.
+            percent: The percentage by which to scale this current.
 
         Returns:
             The scaled current.
         """
 
     @overload
-    def __mul__(self, other: Voltage) -> Power:
+    def __mul__(self, other: Voltage, /) -> Power:
         """Multiply the current by a voltage to get a power.
 
         Args:
@@ -747,21 +791,22 @@ def __mul__(self, other: Voltage) -> Power:
             The calculated power.
         """
 
-    def __mul__(self, other: Percentage | Voltage) -> Self | Power:
+    def __mul__(self, other: float | Percentage | Voltage, /) -> Self | Power:
         """Return a current or power from multiplying this current by the given value.
 
         Args:
-            other: The percentage or voltage to multiply by.
+            other: The scalar, percentage or voltage to multiply by.
 
         Returns:
             A current or power.
         """
-        if isinstance(other, Percentage):
-            return super().__mul__(other)
-        if isinstance(other, Voltage):
-            return Power.from_watts(self._base_value * other._base_value)
-
-        return NotImplemented
+        match other:
+            case float() | Percentage():
+                return super().__mul__(other)
+            case Voltage():
+                return Power._new(self._base_value * other._base_value)
+            case _:
+                return NotImplemented
 
 
 class Voltage(
@@ -841,18 +886,29 @@ def as_kilovolts(self) -> float:
         return self._base_value / 1e3
 
     @overload  # type: ignore
-    def __mul__(self, other: Percentage) -> Self:
+    def __mul__(self, scalar: float, /) -> Self:
+        """Scale this voltage by a scalar.
+
+        Args:
+            scalar: The scaler by which to scale this voltage.
+
+        Returns:
+            The scaled quantity.
+        """
+
+    @overload
+    def __mul__(self, percent: Percentage, /) -> Self:
         """Scale this voltage by a percentage.
 
         Args:
-            other: The percentage by which to scale this voltage.
+            percent: The percentage by which to scale this voltage.
 
         Returns:
             The scaled voltage.
         """
 
     @overload
-    def __mul__(self, other: Current) -> Power:
+    def __mul__(self, other: Current, /) -> Power:
         """Multiply the voltage by the current to get the power.
 
         Args:
@@ -862,21 +918,22 @@ def __mul__(self, other: Current) -> Power:
             The calculated power.
         """
 
-    def __mul__(self, other: Percentage | Current) -> Self | Power:
+    def __mul__(self, other: float | Percentage | Current, /) -> Self | Power:
         """Return a voltage or power from multiplying this voltage by the given value.
 
         Args:
-            other: The percentage or current to multiply by.
+            other: The scalar, percentage or current to multiply by.
 
         Returns:
             The calculated voltage or power.
         """
-        if isinstance(other, Percentage):
-            return super().__mul__(other)
-        if isinstance(other, Current):
-            return Power.from_watts(self._base_value * other._base_value)
-
-        return NotImplemented
+        match other:
+            case float() | Percentage():
+                return super().__mul__(other)
+            case Current():
+                return Power._new(self._base_value * other._base_value)
+            case _:
+                return NotImplemented
 
 
 class Energy(
@@ -959,6 +1016,23 @@ def as_megawatt_hours(self) -> float:
         """
         return self._base_value / 1e6
 
+    def __mul__(self, other: float | Percentage) -> Self:
+        """Scale this energy by a percentage.
+
+        Args:
+            other: The percentage by which to scale this energy.
+
+        Returns:
+            The scaled energy.
+        """
+        match other:
+            case float():
+                return self._new(self._base_value * other)
+            case Percentage():
+                return self._new(self._base_value * other.as_fraction())
+            case _:
+                return NotImplemented
+
     @overload
     def __truediv__(self, other: timedelta) -> Power:
         """Return a power from dividing this energy by the given duration.

tests/timeseries/test_quantities.py

@@ -592,12 +592,6 @@ def test_invalid_multiplications() -> None:
         with pytest.raises(TypeError):
             energy *= quantity  # type: ignore
 
-    for quantity in [power, voltage, current, energy, Percentage.from_percent(50)]:
-        with pytest.raises(TypeError):
-            _ = quantity * 200.0  # type: ignore
-        with pytest.raises(TypeError):
-            quantity *= 200.0  # type: ignore
-
 
 # We can't use _QUANTITY_TYPES here, because it will break the tests, as hypothesis
 # will generate more values, some of which are unsupported by the quantities. See the