Make nones_are_zeros a keyword-only parameter (#611)

Accept keyword-only argument `nones_are_zeros` in `FormulaEngine` and
related classes and methods in order to clarify behavior at the caller's
end, eliminating the need to inspect function definitions for
understanding.

Fixes #100

Author: daniel-zullo-frequenz

RELEASE_NOTES.md

@@ -90,6 +90,8 @@ This release replaces the `@actor` decorator with a new `Actor` class.
 
 - Within the `EVChargerPool.set_bounds` method, the parameter `max_amps` has been redefined as `max_current`, and it is now represented using a `Current` object instead of a `float`.
 
+- The argument `nones_are_zeros` in `FormulaEngine` and related classes and methods is now a keyword-only argument.
+
 ## New Features
 
 - Added `DFS` to the component graph

src/frequenz/sdk/timeseries/_formula_engine/_formula_engine.py

@@ -209,6 +209,7 @@ def from_receiver(
         name: str,
         receiver: Receiver[Sample[QuantityT]],
         create_method: Callable[[float], QuantityT],
+        *,
         nones_are_zeros: bool = False,
     ) -> FormulaEngine[QuantityT]:
         """
@@ -471,6 +472,7 @@ def push_metric(
         self,
         name: str,
         data_stream: Receiver[Sample[QuantityT]],
+        *,
         nones_are_zeros: bool,
     ) -> None:
         """Push a metric receiver into the engine.
@@ -482,7 +484,7 @@ def push_metric(
                 False, the returned value will be a None.
         """
         fetcher = self._metric_fetchers.setdefault(
-            name, MetricFetcher(name, data_stream, nones_are_zeros)
+            name, MetricFetcher(name, data_stream, nones_are_zeros=nones_are_zeros)
         )
         self._steps.append(fetcher)
 
@@ -554,7 +556,8 @@ def push_average(
         fetchers: List[MetricFetcher[QuantityT]] = []
         for metric in metrics:
             fetcher = self._metric_fetchers.setdefault(
-                metric[0], MetricFetcher(*metric)
+                metric[0],
+                MetricFetcher(metric[0], metric[1], nones_are_zeros=metric[2]),
             )
             fetchers.append(fetcher)
         self._steps.append(Averager(fetchers))
@@ -806,7 +809,7 @@ class HigherOrderFormulaBuilder(Generic[QuantityT], _BaseHOFormulaBuilder[Quanti
     """A specialization of the _BaseHOFormulaBuilder for `FormulaReceiver`."""
 
     def build(
-        self, name: str, nones_are_zeros: bool = False
+        self, name: str, *, nones_are_zeros: bool = False
     ) -> FormulaEngine[QuantityT]:
         """Build a `FormulaEngine` instance from the builder.
 
@@ -825,7 +828,7 @@ def build(
                 builder.push_metric(
                     value._name,  # pylint: disable=protected-access
                     value.new_receiver(),
-                    nones_are_zeros,
+                    nones_are_zeros=nones_are_zeros,
                 )
             elif typ == TokenType.OPER:
                 assert isinstance(value, str)
@@ -844,7 +847,7 @@ class HigherOrderFormulaBuilder3Phase(
     """A specialization of the _BaseHOFormulaBuilder for `FormulaReceiver3Phase`."""
 
     def build(
-        self, name: str, nones_are_zeros: bool = False
+        self, name: str, *, nones_are_zeros: bool = False
     ) -> FormulaEngine3Phase[QuantityT]:
         """Build a `FormulaEngine3Phase` instance from the builder.
 
@@ -870,7 +873,7 @@ def build(
                         value._streams[  # pylint: disable=protected-access
                             phase
                         ].new_receiver(),
-                        nones_are_zeros,
+                        nones_are_zeros=nones_are_zeros,
                     )
             elif typ == TokenType.OPER:
                 assert isinstance(value, str)

src/frequenz/sdk/timeseries/_formula_engine/_formula_engine_pool.py

@@ -55,6 +55,7 @@ def from_string(
         self,
         formula: str,
         component_metric_id: ComponentMetricId,
+        *,
         nones_are_zeros: bool = False,
     ) -> FormulaEngine[Quantity]:
         """Get a receiver for a manual formula.
@@ -81,7 +82,7 @@ def from_string(
             component_metric_id,
             Quantity,
         )
-        formula_engine = builder.from_string(formula, nones_are_zeros)
+        formula_engine = builder.from_string(formula, nones_are_zeros=nones_are_zeros)
         self._string_engines[channel_key] = formula_engine
 
         return formula_engine

src/frequenz/sdk/timeseries/_formula_engine/_formula_steps.py

@@ -268,6 +268,7 @@ def __init__(
         self,
         name: str,
         stream: Receiver[Sample[QuantityT]],
+        *,
         nones_are_zeros: bool,
     ) -> None:
         """Create a `MetricFetcher` instance.

src/frequenz/sdk/timeseries/_formula_engine/_resampled_formula_builder.py

@@ -84,11 +84,12 @@ def push_component_metric(
                 False, the returned value will be a None.
         """
         receiver = self._get_resampled_receiver(component_id, self._metric_id)
-        self.push_metric(f"#{component_id}", receiver, nones_are_zeros)
+        self.push_metric(f"#{component_id}", receiver, nones_are_zeros=nones_are_zeros)
 
     def from_string(
         self,
         formula: str,
+        *,
         nones_are_zeros: bool,
     ) -> FormulaEngine[QuantityT]:
         """Construct a `FormulaEngine` from the given formula string.

src/frequenz/sdk/timeseries/logical_meter/_logical_meter.py

@@ -123,6 +123,7 @@ def start_formula(
         self,
         formula: str,
         component_metric_id: ComponentMetricId,
+        *,
         nones_are_zeros: bool = False,
     ) -> FormulaEngine[Quantity]:
         """Start execution of the given formula.
@@ -144,7 +145,7 @@ def start_formula(
             A FormulaEngine that applies the formula and streams values.
         """
         return self._formula_pool.from_string(
-            formula, component_metric_id, nones_are_zeros
+            formula, component_metric_id, nones_are_zeros=nones_are_zeros
         )
 
     @property

tests/timeseries/test_formula_engine.py

@@ -65,7 +65,7 @@ async def run_test(  # pylint: disable=too-many-locals
                 builder.push_metric(
                     f"#{token.value}",
                     channels[token.value].new_receiver(),
-                    nones_are_zeros,
+                    nones_are_zeros=nones_are_zeros,
                 )
             elif token.type == TokenType.OPER:
                 builder.push_oper(token.value)
@@ -345,7 +345,7 @@ async def run_test(  # pylint: disable=too-many-locals
             for ctr in range(num_items)
         ]
         builder = make_builder(*l1_engines)
-        engine = builder.build("l2 formula", nones_are_zeros)
+        engine = builder.build("l2 formula", nones_are_zeros=nones_are_zeros)
         result_chan = engine.new_receiver()
 
         now = datetime.now()
@@ -651,11 +651,15 @@ async def test_constant_value(self) -> None:
         sender_2 = channel_2.new_sender()
 
         builder = FormulaBuilder("test_constant_value", create_method=Quantity)
-        builder.push_metric("channel_1", channel_1.new_receiver(), False)
+        builder.push_metric(
+            "channel_1", channel_1.new_receiver(), nones_are_zeros=False
+        )
         builder.push_oper("+")
         builder.push_constant(2.0)
         builder.push_oper("*")
-        builder.push_metric("channel_2", channel_2.new_receiver(), False)
+        builder.push_metric(
+            "channel_2", channel_2.new_receiver(), nones_are_zeros=False
+        )
 
         engine = builder.build()
 
@@ -672,12 +676,16 @@ async def test_constant_value(self) -> None:
 
         builder = FormulaBuilder("test_constant_value", create_method=Quantity)
         builder.push_oper("(")
-        builder.push_metric("channel_1", channel_1.new_receiver(), False)
+        builder.push_metric(
+            "channel_1", channel_1.new_receiver(), nones_are_zeros=False
+        )
         builder.push_oper("+")
         builder.push_constant(2.0)
         builder.push_oper(")")
         builder.push_oper("*")
-        builder.push_metric("channel_2", channel_2.new_receiver(), False)
+        builder.push_metric(
+            "channel_2", channel_2.new_receiver(), nones_are_zeros=False
+        )
 
         engine = builder.build()
 
@@ -705,9 +713,13 @@ async def test_clipper(self) -> None:
         sender_2 = channel_2.new_sender()
 
         builder = FormulaBuilder("test_clipper", create_method=Quantity)
-        builder.push_metric("channel_1", channel_1.new_receiver(), False)
+        builder.push_metric(
+            "channel_1", channel_1.new_receiver(), nones_are_zeros=False
+        )
         builder.push_oper("+")
-        builder.push_metric("channel_2", channel_2.new_receiver(), False)
+        builder.push_metric(
+            "channel_2", channel_2.new_receiver(), nones_are_zeros=False
+        )
         builder.push_clipper(0.0, 100.0)
         engine = builder.build()
 
@@ -728,9 +740,13 @@ async def test_clipper(self) -> None:
 
         builder = FormulaBuilder("test_clipper", create_method=Quantity)
         builder.push_oper("(")
-        builder.push_metric("channel_1", channel_1.new_receiver(), False)
+        builder.push_metric(
+            "channel_1", channel_1.new_receiver(), nones_are_zeros=False
+        )
         builder.push_oper("+")
-        builder.push_metric("channel_2", channel_2.new_receiver(), False)
+        builder.push_metric(
+            "channel_2", channel_2.new_receiver(), nones_are_zeros=False
+        )
         builder.push_oper(")")
         builder.push_clipper(0.0, 100.0)
         engine = builder.build()
@@ -763,9 +779,13 @@ async def test_types(self) -> None:
         sender_2 = channel_2.new_sender()
 
         builder = FormulaBuilder("test_typing", create_method=Power.from_watts)
-        builder.push_metric("channel_1", channel_1.new_receiver(), False)
+        builder.push_metric(
+            "channel_1", channel_1.new_receiver(), nones_are_zeros=False
+        )
         builder.push_oper("+")
-        builder.push_metric("channel_2", channel_2.new_receiver(), False)
+        builder.push_metric(
+            "channel_2", channel_2.new_receiver(), nones_are_zeros=False
+        )
         engine = builder.build()
 
         results_rx = engine.new_receiver()
@@ -787,7 +807,7 @@ async def test_from_receiver(self) -> None:
         sender = channel.new_sender()
 
         builder = FormulaBuilder("test_from_receiver", create_method=Power.from_watts)
-        builder.push_metric("channel_1", channel.new_receiver(), False)
+        builder.push_metric("channel_1", channel.new_receiver(), nones_are_zeros=False)
         engine = builder.build()
 
         engine_from_receiver = FormulaEngine.from_receiver(