Add a Percentage quantity type

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

Author: shsms

src/frequenz/sdk/timeseries/__init__.py

@@ -38,7 +38,7 @@
 from ._base_types import UNIX_EPOCH, Sample, Sample3Phase
 from ._moving_window import MovingWindow
 from ._periodic_feature_extractor import PeriodicFeatureExtractor
-from ._quantities import Current, Energy, Power, Quantity, QuantityT, Voltage
+from ._quantities import Current, Energy, Percentage, Power, Quantity, Voltage
 from ._resampling import ResamplerConfig
 
 __all__ = [
@@ -56,4 +56,5 @@
     "Energy",
     "Power",
     "Voltage",
+    "Percentage",
 ]

src/frequenz/sdk/timeseries/_quantities.py

@@ -9,7 +9,9 @@
 from datetime import timedelta
 from typing import Any, NoReturn, Self, TypeVar, overload
 
-QuantityT = TypeVar("QuantityT", "Quantity", "Power", "Current", "Voltage", "Energy")
+QuantityT = TypeVar(
+    "QuantityT", "Quantity", "Power", "Current", "Voltage", "Energy", "Percentage"
+)
 
 
 class Quantity:
@@ -704,3 +706,55 @@ def __truediv__(self, other: timedelta | Power) -> Power | timedelta:
         raise TypeError(
             f"unsupported operand type(s) for /: '{type(self)}' and '{type(other)}'"
         )
+
+
+class Percentage(
+    Quantity,
+    metaclass=_NoDefaultConstructible,
+    exponent_unit_map={0: "%"},
+):
+    """A percentage quantity."""
+
+    @classmethod
+    def from_percent(cls, percent: float) -> Self:
+        """Initialize a new percentage quantity from a percent value.
+
+        Args:
+            percent: The percent value, normally in the 0.0-100.0 range.
+
+        Returns:
+            A new percentage quantity.
+        """
+        percentage = cls.__new__(cls)
+        percentage._base_value = percent
+        return percentage
+
+    @classmethod
+    def from_fraction(cls, fraction: float) -> Self:
+        """Initialize a new percentage quantity from a fraction.
+
+        Args:
+            fraction: The fraction, normally in the 0.0-1.0 range.
+
+        Returns:
+            A new percentage quantity.
+        """
+        percentage = cls.__new__(cls)
+        percentage._base_value = fraction * 100
+        return percentage
+
+    def as_percent(self) -> float:
+        """Return this quantity as a percentage.
+
+        Returns:
+            This quantity as a percentage.
+        """
+        return self._base_value
+
+    def as_fraction(self) -> float:
+        """Return this quantity as a fraction.
+
+        Returns:
+            This quantity as a fraction.
+        """
+        return self._base_value / 100

tests/timeseries/test_quantities.py

@@ -10,6 +10,7 @@
 from frequenz.sdk.timeseries._quantities import (
     Current,
     Energy,
+    Percentage,
     Power,
     Quantity,
     Voltage,
@@ -257,3 +258,13 @@ def test_quantity_compositions() -> None:
     assert energy / power == timedelta(hours=6.2)
     assert energy / timedelta(hours=6.2) == power
     assert energy == power * timedelta(hours=6.2)
+
+
+def test_percentage() -> None:
+    """Test the percentage class."""
+    pct = Percentage.from_fraction(0.204)
+    assert f"{pct}" == "20.4 %"
+    pct = Percentage.from_percent(20.4)
+    assert f"{pct}" == "20.4 %"
+    assert pct.as_percent() == 20.4
+    assert pct.as_fraction() == 0.204