Add function to allow parsing of Quantity strings

Signed-off-by: Mathias L. Baumann <[email protected]>

Author: Marenz

RELEASE_NOTES.md

@@ -72,6 +72,8 @@
 
 - The `actor.ChannelRegistry` is now type-aware.
 
+- A new class method `Quantity.from_string()` has been added to allow the creation of `Quantity` objects from strings.
+
 ## Bug Fixes
 
 - 0W power requests are now not adjusted to exclusion bounds by the `PowerManager` and `PowerDistributor`, and are sent over to the microgrid API directly.
@@ -87,4 +89,5 @@
   A bug made the resampler interpret zero values as `None` when generating new samples, so if the result of the resampling is zero, the resampler would just produce `None` values.
 
 - The PowerManager no longer holds on to proposals from dead actors forever.  If an actor hasn't sent a new proposal in 60 seconds, the available proposal from that actor is dropped.
+
 - Fix `Quantity.__format__()` sometimes skipping the number for very small values.

pyproject.toml

@@ -99,6 +99,7 @@ dev-pytest = [
   "async-solipsism == 0.5",
   # For checking docstring code examples
   "frequenz-sdk[dev-examples]",
+  "hypothesis == 6.92.1",
 ]
 dev = [
   "frequenz-sdk[dev-mkdocs,dev-flake8,dev-formatting,dev-mkdocs,dev-mypy,dev-noxfile,dev-pylint,dev-pytest]",

src/frequenz/sdk/timeseries/_quantities.py

@@ -91,6 +91,42 @@ def zero(cls) -> Self:
         assert isinstance(_zero, cls)
         return _zero
 
+    @classmethod
+    def from_string(cls, string: str) -> Self:
+        """Return a quantity from a string representation.
+
+        Args:
+            string: The string representation of the quantity.
+
+        Returns:
+            A quantity object with the value given in the string.
+
+        Raises:
+            ValueError: If the string does not match the expected format.
+
+        """
+        split_string = string.split(" ")
+
+        if len(split_string) != 2:
+            raise ValueError(
+                f"Expected a string of the form 'value unit', got {string}"
+            )
+
+        assert cls._exponent_unit_map is not None
+        exp_map = cls._exponent_unit_map
+
+        for exponent, unit in exp_map.items():
+            if unit == split_string[1]:
+                instance = cls.__new__(cls)
+                try:
+                    instance._base_value = float(split_string[0]) * 10**exponent
+                except ValueError as error:
+                    raise ValueError(f"Failed to parse string '{string}'.") from error
+
+                return instance
+
+        raise ValueError(f"Unknown unit {split_string[1]}")
+
     @property
     def base_value(self) -> float:
         """Return the value of this quantity in the base unit.

tests/timeseries/test_quantities.py

@@ -5,7 +5,9 @@
 
 from datetime import timedelta
 
+import hypothesis
 import pytest
+from hypothesis import strategies as st
 
 from frequenz.sdk.timeseries._quantities import (
     Current,
@@ -359,7 +361,7 @@ def test_frequency() -> None:
     """Test the frequency class."""
     freq = Frequency.from_hertz(0.0000002)
     assert f"{freq:.9}" == "0.0000002 Hz"
-    freq = Frequency.from_kilohertz(600000.0)
+    freq = Frequency.from_kilohertz(600_000.0)
     assert f"{freq}" == "600 MHz"
 
     freq = Frequency.from_hertz(6.0)
@@ -531,3 +533,40 @@ def test_invalid_multiplications() -> None:
             _ = quantity * 200.0  # type: ignore
         with pytest.raises(TypeError):
             quantity *= 200.0  # type: ignore
+
+
+@pytest.mark.parametrize("quantity_type", [Power, Voltage, Current, Energy, Frequency])
+@pytest.mark.parametrize("exponent", [0, 3, 6, 9])
+@hypothesis.settings(
+    max_examples=1000
+)  # Set to have a decent amount of examples (default is 100)
+@hypothesis.seed(42)  # Seed that triggers a lot of problematic edge cases
+@hypothesis.given(value=st.floats(min_value=-1.0, max_value=1.0))
+def test_to_and_from_string(
+    quantity_type: type[Quantity], exponent: int, value: float
+) -> None:
+    """Test string parsing and formatting.
+
+    The parameters for this test are constructed to stay deterministic.
+
+    With a different (or random) seed or different max_examples the
+    test will show failing examples.
+
+    Fixing those cases was considered an unreasonable amount of work
+    at the time of writing.
+
+    For the future, one idea was to parse the string number after the first
+    generation and regenerate it with the more appropriate unit and precision.
+    """
+    quantity = quantity_type.__new__(quantity_type)
+    # pylint: disable=protected-access
+    quantity._base_value = value * 10**exponent
+    quantity_str = f"{quantity:.{exponent}}"
+    from_string = quantity_type.from_string(quantity_str)
+    try:
+        assert f"{from_string:.{exponent}}" == quantity_str
+    except AssertionError as error:
+        pytest.fail(
+            f"Failed for {quantity.base_value} != from_string({from_string.base_value}) "
+            + f"with exponent {exponent} and source value '{value}': {error}"
+        )