Make all examples validate correctly

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

Author: Marenz

src/frequenz/sdk/actor/_decorator.py

@@ -76,7 +76,9 @@ def actor(cls: Type[Any]) -> Type[Any]:
         TypeError: when the class doesn't have a `run` method as per spec.
 
     Example (one actor receiving from two receivers):
-    ``` python
+    ```python
+    from frequenz.channels import Broadcast, Receiver, Sender
+    from frequenz.channels.util import Select
     @actor
     class EchoActor:
         def __init__(
@@ -115,11 +117,12 @@ async def run(self) -> None:
     echo_rx = echo_chan.new_receiver()
 
     await input_chan_2.new_sender().send(True)
-    msg = await echo_rx.receive()
+    received_msg = await echo_rx.receive()
     ```
 
     Example (two Actors composed):
-    ``` python
+    ```python
+    from frequenz.channels import Broadcast, Receiver, Sender
     @actor
     class Actor1:
         def __init__(
@@ -153,16 +156,15 @@ async def run(self) -> None:
             async for msg in self._recv:
                 await self._output.send(msg)
 
-
     input_chan: Broadcast[bool] = Broadcast("Input to A1")
-    a1_chan: Broadcast[bool] = Broadcast["A1 stream"]
-    a2_chan: Broadcast[bool] = Broadcast["A2 stream"]
-    a1 = Actor1(
+    a1_chan: Broadcast[bool] = Broadcast("A1 stream")
+    a2_chan: Broadcast[bool] = Broadcast("A2 stream")
+    a_1 = Actor1(
         name="ActorOne",
         recv=input_chan.new_receiver(),
         output=a1_chan.new_sender(),
     )
-    a2 = Actor2(
+    a_2 = Actor2(
         name="ActorTwo",
         recv=a1_chan.new_receiver(),
         output=a2_chan.new_sender(),
@@ -171,7 +173,7 @@ async def run(self) -> None:
     a2_rx = a2_chan.new_receiver()
 
     await input_chan.new_sender().send(True)
-    msg = await a2_rx.receive()
+    received_msg = await a2_rx.receive()
     ```
 
     """

src/frequenz/sdk/actor/power_distributing/power_distributing.py

@@ -89,11 +89,10 @@ class PowerDistributingActor:
     printed.
 
     Example:
-        ``` python
-        import grpc.aio as grpcaio
-
-        from frequenz.sdk.microgrid.graph import _MicrogridComponentGraph
+        ```python
+        from frequenz.sdk import microgrid
         from frequenz.sdk.microgrid.component import ComponentCategory
+        from frequenz.sdk.actor import ResamplerConfig
         from frequenz.sdk.actor.power_distributing import (
             PowerDistributingActor,
             Request,
@@ -103,29 +102,45 @@ class PowerDistributingActor:
             PartialFailure,
             Ignored,
         )
+        from frequenz.channels import Bidirectional, Broadcast, Receiver, Sender
+        from datetime import timedelta
+        from frequenz.sdk import actor
 
+        HOST = "localhost"
+        PORT = 50051
 
-        target = f"{host}:{port}"
-        grpc_channel = grpcaio.insecure_channel(target)
-        api = MicrogridGrpcClient(grpc_channel, target)
+        await microgrid.initialize(
+            HOST,
+            PORT,
+            ResamplerConfig(resampling_period=timedelta(seconds=1))
+        )
 
-        graph = _MicrogridComponentGraph()
-        await graph.refresh_from_api(api)
+        graph = microgrid.connection_manager.get().component_graph
 
         batteries = graph.components(component_category={ComponentCategory.BATTERY})
         batteries_ids = {c.component_id for c in batteries}
 
+        battery_status_channel = Broadcast[BatteryStatus]("battery-status")
+
         channel = Bidirectional[Request, Result]("user1", "power_distributor")
         power_distributor = PowerDistributingActor(
-            mock_api, component_graph, {"user1": channel.service_handle}
+            users_channels={"user1": channel.service_handle},
+            battery_status_sender=battery_status_channel.new_sender(),
         )
 
+        # Start the actor
+        await actor.run(power_distributor)
+
         client_handle = channel.client_handle
 
         # Set power 1200W to given batteries.
         request = Request(power=1200.0, batteries=batteries_ids, request_timeout_sec=10.0)
         await client_handle.send(request)
 
+        # Set power 1200W to given batteries.
+        request = Request(power=1200, batteries=batteries_ids, request_timeout_sec=10.0)
+        await client_handle.send(request)
+
         # It is recommended to use timeout when waiting for the response!
         result: Result = await asyncio.wait_for(client_handle.receive(), timeout=10)
 
@@ -134,9 +149,10 @@ class PowerDistributingActor:
         elif isinstance(result, PartialFailure):
             print(
                 f"Batteries {result.failed_batteries} failed, total failed power" \
-                    f"{result.failed_power}")
+                f"{result.failed_power}"
+            )
         elif isinstance(result, Ignored):
-            print(f"Request was ignored, because of newer request")
+            print("Request was ignored, because of newer request")
         elif isinstance(result, Error):
             print(f"Request failed with error: {result.msg}")
         ```

src/frequenz/sdk/power/_distribution_algorithm.py

@@ -71,26 +71,26 @@ class DistributionAlgorithm:
 
     We would like our distribution to meet the equation:
 
-    ``` python
+    ```
     distribution[i] = power_w * capacity_ratio[i] * x[i]
     ```
 
     where:
 
-    ``` python
+    ```
     sum(capacity_ratio[i] * x[i] for i in range(N)) == 1
     ```
 
     Let `y` be our unknown, the proportion to discharge each battery would be
     (1):
 
-    ``` python
+    ```
     x[i] = available_soc[i]*y
     ```
 
     We can compute `y` from equation above (2):
 
-    ``` python
+    ```
     sum(capacity_ratio[i] * x[i] for i in range(N)) == 1
     # =>
     sum(capacity_ratio[i] * available_soc[i] * y for i in range(N)) == 1
@@ -100,7 +100,7 @@ class DistributionAlgorithm:
 
     Now we know everything and we can compute distribution:
 
-    ``` python
+    ```
     distribution[i] = power_w * capacity_ratio[i] * x[i]  # from (1)
     distribution[i] = \
             power_w * capacity_ratio[i] * available_soc[i] * y  # from (2)
@@ -110,13 +110,13 @@ class DistributionAlgorithm:
 
     Let:
 
-    ``` python
+    ```
     battery_availability_ratio[i] = capacity_ratio[i] * available_soc[i]
     total_battery_availability_ratio = sum(battery_availability_ratio)
     ```
 
     Then:
-    ``` python
+    ```
     distribution[i] = power_w * battery_availability_ratio[i] \
             / total_battery_availability_ratio
     ```
@@ -151,29 +151,33 @@ def __init__(self, distributor_exponent: float = 1) -> None:
             If `distribution_exponent` is:
 
             * `0`: distribution for each battery will be the equal.
-              ``` python
-              Bat1.distribution = 4000; Bat2.distribution = 4000
+              ```python
+              BAT1_DISTRIBUTION = 4000
+              BAT2_DISTRIBUTION = 4000
               ```
 
             * `1`: then `Bat2` will have 3x more power assigned then `Bat1`.
-              ``` python
-              10 * x + 30 * x = 8000
-              x = 200
-              Bat1.distribution = 2000; Bat2.distribution = 6000
+              ```python
+              # 10 * x + 30 * x = 8000
+              X = 200
+              BAT1_DISTRIBUTION = 2000
+              BAT2_DISTRIBUTION = 6000
               ```
 
             * `2`: then `Bat2` will have 9x more power assigned then `Bat1`.
-              ``` python
-              10^2 * x + 30^2 * x = 8000
-              x = 80
-              Bat1.distribution = 800; Bat2.distribution = 7200
+              ```python
+              # 10^2 * x + 30^2 * x = 8000
+              X = 80
+              BAT1_DISTRIBUTION = 800
+              BAT2_DISTRIBUTION = 7200
               ```
 
             * `3`: then `Bat2` will have 27x more power assigned then `Bat1`.
-              ``` python
-              10^3 * x + 30^3 * x = 8000
-              x = 0,285714286
-              Bat1.distribution = 285; Bat2.distribution = 7715
+              ```python
+              # 10^3 * x + 30^3 * x = 8000
+              X = 0.285714286
+              BAT1_DISTRIBUTION = 285
+              BAT2_DISTRIBUTION = 7715
               ```
 
             # Example 2
@@ -189,29 +193,33 @@ def __init__(self, distributor_exponent: float = 1) -> None:
             If `distribution_exponent` is:
 
             * `0`: distribution for each battery will be the same.
-              ``` python
-              Bat1.distribution = 4500; Bat2.distribution = 450
+              ```python
+              BAT1_DISTRIBUTION = 4500
+              BAT2_DISTRIBUTION = 450
               ```
 
             * `1`: then `Bat2` will have 2x more power assigned then `Bat1`.
-              ``` python
-              30 * x + 60 * x = 900
-              x = 100
-              Bat1.distribution = 300; Bat2.distribution = 600
+              ```python
+              # 30 * x + 60 * x = 900
+              X = 100
+              BAT1_DISTRIBUTION = 300
+              BAT2_DISTRIBUTION = 600
               ```
 
             * `2`: then `Bat2` will have 4x more power assigned then `Bat1`.
-              ``` python
-              30^2 * x + 60^2 * x = 900
-              x = 0.2
-              Bat1.distribution = 180; Bat2.distribution = 720
+              ```python
+              # 30^2 * x + 60^2 * x = 900
+              X = 0.2
+              BAT1_DISTRIBUTION = 180
+              BAT2_DISTRIBUTION = 720
               ```
 
             * `3`: then `Bat2` will have 8x more power assigned then `Bat1`.
-              ``` python
-              30^3 * x + 60^3 * x = 900
-              x = 0,003703704
-              Bat1.distribution = 100; Bat2.distribution = 800
+              ```python
+              # 30^3 * x + 60^3 * x = 900
+              X = 0.003703704
+              BAT1_DISTRIBUTION = 100
+              BAT2_DISTRIBUTION = 800
               ```
 
             # Example 3
@@ -226,15 +234,17 @@ def __init__(self, distributor_exponent: float = 1) -> None:
             If `distribution_exponent` is:
 
             * `0`: distribution for each battery will be the equal.
-              ``` python
-              Bat1.distribution = 450; Bat2.distribution = 450
+              ```python
+              BAT1_DISTRIBUTION = 450
+              BAT2_DISTRIBUTION = 450
               ```
 
             * `0.5`: then `Bat2` will have 6/4x more power assigned then `Bat1`.
-              ``` python
-              sqrt(36) * x + sqrt(16) * x = 900
-              x = 100
-              Bat1.distribution = 600; Bat2.distribution = 400
+              ```python
+              # sqrt(36) * x + sqrt(16) * x = 900
+              X = 100
+              BAT1_DISTRIBUTION = 600
+              BAT2_DISTRIBUTION = 400
               ```
 
         Raises:

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

@@ -411,10 +411,13 @@ class FormulaBuilder:
         following calls need to be made:
 
         ```python
-        builder = FormulaBuilder()
-        builder.push_metric("metric_1", receiver_1)
+        channel = Broadcast[Sample]("channel")
+        receiver_1 = channel.new_receiver("receiver_1")
+        receiver_2 = channel.new_receiver("receiver_2")
+        builder = FormulaBuilder("addition")
+        builder.push_metric("metric_1", receiver_1, nones_are_zeros=True)
         builder.push_oper("+")
-        builder.push_metric("metric_2", receiver_2)
+        builder.push_metric("metric_2", receiver_2, nones_are_zeros=True)
         engine = builder.build()
         ```
 
@@ -503,20 +506,30 @@ def push_clipper(self, min_value: float | None, max_value: float | None) -> None
         For example, this clips the output of the entire expression:
 
         ```python
+        builder = FormulaBuilder("example")
+        channel = Broadcast[Sample]("channel")
+        receiver_1 = channel.new_receiver("receiver_1")
+        receiver_2 = channel.new_receiver("receiver_2")
+
         builder.push_oper("(")
-        builder.push_metric("metric_1", receiver_1)
+        builder.push_metric("metric_1", receiver_1, nones_are_zeros=True)
         builder.push_oper("+")
-        builder.push_metric("metric_2", receiver_2)
+        builder.push_metric("metric_2", receiver_2, nones_are_zeros=True)
         builder.push_oper(")")
         builder.push_clipper(min_value=0.0, max_value=None)
         ```
 
         And this clips the output of metric_2 only, and not the final result:
 
         ```python
-        builder.push_metric("metric_1", receiver_1)
+        builder = FormulaBuilder("example")
+        channel = Broadcast[Sample]("channel")
+        receiver_1 = channel.new_receiver("receiver_1")
+        receiver_2 = channel.new_receiver("receiver_2")
+
+        builder.push_metric("metric_1", receiver_1, nones_are_zeros=True)
         builder.push_oper("+")
-        builder.push_metric("metric_2", receiver_2)
+        builder.push_metric("metric_2", receiver_2, nones_are_zeros=True)
         builder.push_clipper(min_value=0.0, max_value=None)
         ```
 

src/frequenz/sdk/timeseries/_moving_window.py

@@ -57,6 +57,9 @@ class MovingWindow:
     Example: Calculate the mean of a time interval
 
         ```python
+        from datetime import datetime, timedelta, timezone
+        resampled_data_recv = Broadcast[Sample]("sample-data").new_receiver()
+
         window = MovingWindow(
             size=timedelta(minutes=5),
             resampled_data_recv=resampled_data_recv,
@@ -78,7 +81,11 @@ class MovingWindow:
     Example: Create a polars data frame from a `MovingWindow`
 
         ```python
+        # pylint: disable=import-error
         import polars as pl
+        from datetime import datetime, timedelta, timezone
+
+        sample_receiver = Broadcast[Sample]("sample-data").new_receiver()
 
         # create a window that stores two days of data
         # starting at 1.1.23 with samplerate=1
@@ -94,7 +101,7 @@ class MovingWindow:
         # create a polars series with one full day of data
         time_start = datetime(2023, 1, 1, tzinfo=timezone.utc)
         time_end = datetime(2023, 1, 2, tzinfo=timezone.utc)
-        s = pl.Series("Jan_1", mv[time_start:time_end])
+        s = pl.Series("Jan_1", window[time_start:time_end])
         ```
     """