Add zero() constructor for Quantities (#535)

It is a very common case which becomes very verbose, and it includes
unit information that is completely irrelevant (zero is zero in any
unit).

Author: llucax

RELEASE_NOTES.md

@@ -13,11 +13,15 @@
 
 ## New Features
 
-- Add `abs()` support for quantities.
-- Add quantity class `Frequency` for frequency values.
-- Quantities can now be multiplied with `Percentage` types.
-- `FormulaEngine` arithmetics now supports scalar multiplication with floats and addition with Quantities.
-- Add a `isclose()` method on quantities to compare them to other values of the same type.  Because `Quantity` types are just wrappers around `float`s, direct comparison might not always be desirable.
+- Quantities
+
+  * Add `abs()`.
+  * Add a `isclose()` method on quantities to compare them to other values of the same type.  Because `Quantity` types are just wrappers around `float`s, direct comparison might not always be desirable.
+  * Add `zero()` constructor (which returns a singleton) to easily get a zero value.
+  * Add multiplication by `Percentage` types.
+  * Add a new quantity class `Frequency` for frequency values.
+
+- `FormulaEngine` arithmetics now supports scalar multiplication with floats and addition with Quantities
 
 ## Bug Fixes
 

src/frequenz/sdk/timeseries/_quantities.py

@@ -24,7 +24,10 @@
 
 
 class Quantity:
-    """A quantity with a unit."""
+    """A quantity with a unit.
+
+    Quantities try to behave like float and are also immutable.
+    """
 
     _base_value: float
     """The value of this quantity in the base unit."""
@@ -62,6 +65,30 @@ def __init_subclass__(cls, exponent_unit_map: dict[int, str]) -> None:
         cls._exponent_unit_map = exponent_unit_map
         super().__init_subclass__()
 
+    _zero_cache: dict[type, Quantity] = {}
+    """Cache for zero singletons.
+
+    This is a workaround for mypy getting confused when using @functools.cache and
+    @classmethod combined with returning Self. It believes the resulting type of this
+    method is Self and complains that members of the actual class don't exist in Self,
+    so we need to implement the cache ourselves.
+    """
+
+    @classmethod
+    def zero(cls) -> Self:
+        """Return a quantity with value 0.
+
+        Returns:
+            A quantity with value 0.
+        """
+        _zero = cls._zero_cache.get(cls, None)
+        if _zero is None:
+            _zero = cls.__new__(cls)
+            _zero._base_value = 0
+            cls._zero_cache[cls] = _zero
+        assert isinstance(_zero, cls)
+        return _zero
+
     @property
     def base_value(self) -> float:
         """Return the value of this quantity in the base unit.
@@ -249,48 +276,6 @@ def __mul__(self, percent: Percentage) -> Self:
         product._base_value = self._base_value * percent.as_fraction()
         return product
 
-    def __iadd__(self, other: Self) -> Self:
-        """Add another quantity to this one.
-
-        Args:
-            other: The other quantity.
-
-        Returns:
-            This quantity.
-        """
-        if not type(other) is type(self):
-            return NotImplemented
-        self._base_value += other._base_value
-        return self
-
-    def __isub__(self, other: Self) -> Self:
-        """Subtract another quantity from this one.
-
-        Args:
-            other: The other quantity.
-
-        Returns:
-            This quantity.
-        """
-        if not type(other) is type(self):
-            return NotImplemented
-        self._base_value -= other._base_value
-        return self
-
-    def __imul__(self, percent: Percentage) -> Self:
-        """Multiply this quantity by a percentage.
-
-        Args:
-            percent: The percentage.
-
-        Returns:
-            This quantity.
-        """
-        if not isinstance(percent, Percentage):
-            return NotImplemented
-        self._base_value *= percent.as_fraction()
-        return self
-
     def __gt__(self, other: Self) -> bool:
         """Return whether this quantity is greater than another.
 
@@ -413,7 +398,7 @@ class Power(
 ):
     """A power quantity.
 
-    Objects of this type are wrappers around `float` values.
+    Objects of this type are wrappers around `float` values and are immutable.
 
     The constructors accept a single `float` value, the `as_*()` methods return a
     `float` value, and each of the arithmetic operators supported by this type are
@@ -586,7 +571,7 @@ class Current(
 ):
     """A current quantity.
 
-    Objects of this type are wrappers around `float` values.
+    Objects of this type are wrappers around `float` values and are immutable.
 
     The constructors accept a single `float` value, the `as_*()` methods return a
     `float` value, and each of the arithmetic operators supported by this type are
@@ -682,7 +667,7 @@ class Voltage(
 ):
     """A voltage quantity.
 
-    Objects of this type are wrappers around `float` values.
+    Objects of this type are wrappers around `float` values and are immutable.
 
     The constructors accept a single `float` value, the `as_*()` methods return a
     `float` value, and each of the arithmetic operators supported by this type are
@@ -804,7 +789,7 @@ class Energy(
 ):
     """An energy quantity.
 
-    Objects of this type are wrappers around `float` values.
+    Objects of this type are wrappers around `float` values and are immutable.
 
     The constructors accept a single `float` value, the `as_*()` methods return a
     `float` value, and each of the arithmetic operators supported by this type are
@@ -923,7 +908,7 @@ class Frequency(
 ):
     """A frequency quantity.
 
-    Objects of this type are wrappers around `float` values.
+    Objects of this type are wrappers around `float` values and are immutable.
 
     The constructors accept a single `float` value, the `as_*()` methods return a
     `float` value, and each of the arithmetic operators supported by this type are
@@ -1036,7 +1021,7 @@ class Percentage(
 ):
     """A percentage quantity.
 
-    Objects of this type are wrappers around `float` values.
+    Objects of this type are wrappers around `float` values and are immutable.
 
     The constructors accept a single `float` value, the `as_*()` methods return a
     `float` value, and each of the arithmetic operators supported by this type are

tests/timeseries/test_quantities.py

@@ -42,6 +42,62 @@ class Fz2(
     """Frequency quantity with broad exponent unit map."""
 
 
+def test_zero() -> None:
+    """Test the zero value for quantity."""
+    assert Quantity(0.0) == Quantity.zero()
+    assert Quantity(0.0, exponent=100) == Quantity.zero()
+    assert Quantity.zero() is Quantity.zero()  # It is a "singleton"
+    assert Quantity.zero().base_value == 0.0
+
+    # Test the singleton is immutable
+    one = Quantity.zero()
+    one += Quantity(1.0)
+    assert one != Quantity.zero()
+    assert Quantity.zero() == Quantity(0.0)
+
+    assert Power.from_watts(0.0) == Power.zero()
+    assert Power.from_kilowatts(0.0) == Power.zero()
+    assert isinstance(Power.zero(), Power)
+    assert Power.zero().as_watts() == 0.0
+    assert Power.zero().as_kilowatts() == 0.0
+    assert Power.zero() is Power.zero()  # It is a "singleton"
+
+    assert Current.from_amperes(0.0) == Current.zero()
+    assert Current.from_milliamperes(0.0) == Current.zero()
+    assert isinstance(Current.zero(), Current)
+    assert Current.zero().as_amperes() == 0.0
+    assert Current.zero().as_milliamperes() == 0.0
+    assert Current.zero() is Current.zero()  # It is a "singleton"
+
+    assert Voltage.from_volts(0.0) == Voltage.zero()
+    assert Voltage.from_kilovolts(0.0) == Voltage.zero()
+    assert isinstance(Voltage.zero(), Voltage)
+    assert Voltage.zero().as_volts() == 0.0
+    assert Voltage.zero().as_kilovolts() == 0.0
+    assert Voltage.zero() is Voltage.zero()  # It is a "singleton"
+
+    assert Energy.from_kilowatt_hours(0.0) == Energy.zero()
+    assert Energy.from_megawatt_hours(0.0) == Energy.zero()
+    assert isinstance(Energy.zero(), Energy)
+    assert Energy.zero().as_kilowatt_hours() == 0.0
+    assert Energy.zero().as_megawatt_hours() == 0.0
+    assert Energy.zero() is Energy.zero()  # It is a "singleton"
+
+    assert Frequency.from_hertz(0.0) == Frequency.zero()
+    assert Frequency.from_megahertz(0.0) == Frequency.zero()
+    assert isinstance(Frequency.zero(), Frequency)
+    assert Frequency.zero().as_hertz() == 0.0
+    assert Frequency.zero().as_megahertz() == 0.0
+    assert Frequency.zero() is Frequency.zero()  # It is a "singleton"
+
+    assert Percentage.from_percent(0.0) == Percentage.zero()
+    assert Percentage.from_fraction(0.0) == Percentage.zero()
+    assert isinstance(Percentage.zero(), Percentage)
+    assert Percentage.zero().as_percent() == 0.0
+    assert Percentage.zero().as_fraction() == 0.0
+    assert Percentage.zero() is Percentage.zero()  # It is a "singleton"
+
+
 def test_string_representation() -> None:
     """Test the string representation of the quantities."""
     assert str(Quantity(1.024445, exponent=0)) == "1.024"