Update Docs, Readme, Release Notes

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

Author: Marenz

README.md

@@ -21,8 +21,13 @@ The [`Dispatcher` class](https://frequenz-floss.github.io/frequenz-dispatch-pyth
 
 ```python
 import os
-from frequenz.dispatch import Dispatcher
 from unittest.mock import MagicMock
+from datetime import timedelta
+
+from frequenz.dispatch import Dispatcher, DispatchInfo, MergeByType
+
+async def create_actor(dispatch: DispatchInfo, receiver: Receiver[DispatchInfo]) -> Actor:
+    return MagicMock(dispatch=dispatch, receiver=receiver)
 
 async def run():
     url = os.getenv("DISPATCH_API_URL", "grpc://fz-0004.frequenz.io:50051")
@@ -33,35 +38,19 @@ async def run():
     dispatcher = Dispatcher(
         microgrid_id=microgrid_id,
         server_url=url,
-        key=key
+        key=key,
+        autostart=True
+    )
+
+    dispatcher.start_dispatching(
+        dispatch_type="EXAMPLE_TYPE",
+        actor_factory=create_actor,
+        merge_strategy=MergeByType(),
+        retry_interval=timedelta(seconds=10)
     )
-    await dispatcher.start()
-
-    actor = MagicMock() # replace with your actor
-
-    changed_running_status_rx = dispatcher.new_running_state_event_receiver("MY_TYPE")
-
-    async for dispatch in changed_running_status_rx:
-        if dispatch.started:
-            print(f"Executing dispatch {dispatch.id}, due on {dispatch.start_time}")
-            if actor.is_running:
-                actor.reconfigure(
-                    components=dispatch.target,
-                    run_parameters=dispatch.payload, # custom actor parameters
-                    dry_run=dispatch.dry_run,
-                    until=dispatch.until,
-                )  # this will reconfigure the actor
-            else:
-                # this will start a new actor with the given components
-                # and run it for the duration of the dispatch
-                actor.start(
-                    components=dispatch.target,
-                    run_parameters=dispatch.payload, # custom actor parameters
-                    dry_run=dispatch.dry_run,
-                    until=dispatch.until,
-                )
-        else:
-            actor.stop()  # this will stop the actor
+
+    await dispatcher
+
 ```
 
 ## Supported Platforms

RELEASE_NOTES.md

@@ -6,6 +6,47 @@ This release introduces a more flexible and powerful mechanism for managing disp
 
 ## Upgrading
 
+A new simplified way to manage actors has been introduced:
+
+Change your code from:
+```python
+dispatcher = Dispatcher(
+    microgrid_id=microgrid_id,
+    server_url=url,
+    key=key
+)
+dispatcher.start()
+
+status_receiver = dispatcher.new_running_state_event_receiver("EXAMPLE_TYPE")
+
+managing_actor = ActorDispatcher(
+    actor_factory=MyActor.new_with_dispatch,
+    running_status_receiver=status_receiver,
+)
+
+await run(managing_actor)
+```
+
+to
+
+```python
+dispatcher = Dispatcher(
+    microgrid_id=microgrid_id,
+    server_url=url,
+    key=key,
+    autostart=True
+)
+
+dispatcher.start_dispatching(
+    dispatch_type="EXAMPLE_TYPE",
+    actor_factory=MyActor.new_with_dispatch,
+    merge_strategy=MergeStrategy.MergeByType,
+    retry_interval=10
+)
+```
+
+Further changes:
+
 * `Dispatcher.__init__` has a new optional parameter `autostart`, which defaults to `True`. If set to `False`, the dispatcher will not start automatically.
 * `Dispatcher.start` is no longer `async`. Remove `await` when calling it.
 * Two properties have been replaced by methods that require a type as parameter.

src/frequenz/dispatch/_actor_dispatcher.py

@@ -122,9 +122,9 @@ async def main():
         dispatcher = Dispatcher(
             microgrid_id=microgrid_id,
             server_url=url,
-            key=key
+            key=key,
+            autostart=True
         )
-        dispatcher.start()
 
         status_receiver = dispatcher.new_running_state_event_receiver("EXAMPLE_TYPE")
 

src/frequenz/dispatch/_dispatcher.py

@@ -28,7 +28,10 @@ class Dispatcher(BackgroundService):
     """A highlevel interface for the dispatch API.
 
     This class provides a highlevel interface to the dispatch API.
-    It provides two receiver functions:
+    It provides receivers for various events and management of actors based on
+    dispatches.
+
+    The receivers shortly explained:
 
     * [Lifecycle events receiver][frequenz.dispatch.Dispatcher.new_lifecycle_events_receiver]:
         Receives an event whenever a dispatch is created, updated or deleted.
@@ -42,6 +45,38 @@ class Dispatcher(BackgroundService):
         Any change that could potentially require the consumer to start, stop or
         reconfigure itself will cause a message to be sent.
 
+    Example: Managing an actor
+        ```python
+        import os
+        from frequenz.dispatch import Dispatcher, MergeByType
+        from unittest.mock import MagicMock
+
+        async def create_actor(dispatch: DispatchInfo, receiver: Receiver[DispatchInfo]) -> Actor:
+            return MagicMock(dispatch=dispatch, receiver=receiver)
+
+        async def run():
+            url = os.getenv("DISPATCH_API_URL", "grpc://fz-0004.frequenz.io:50051")
+            key  = os.getenv("DISPATCH_API_KEY", "some-key")
+
+            microgrid_id = 1
+
+            dispatcher = Dispatcher(
+                microgrid_id=microgrid_id,
+                server_url=url,
+                key=key,
+                autostart=True
+            )
+
+            dispatcher.start_dispatching(
+                dispatch_type="DISPATCH_TYPE",
+                actor_factory=create_actor,
+                merge_strategy=MergeByType(),
+                retry_interval=timedelta(seconds=60),
+            )
+
+            await dispatcher
+        ```
+
     Example: Processing running state change dispatches
         ```python
         import os
@@ -57,9 +92,9 @@ async def run():
             dispatcher = Dispatcher(
                 microgrid_id=microgrid_id,
                 server_url=url,
-                key=key
+                key=key,
+                autostart=True
             )
-            await dispatcher.start()
 
             actor = MagicMock() # replace with your actor
 
@@ -104,9 +139,9 @@ async def run():
             dispatcher = Dispatcher(
                 microgrid_id=microgrid_id,
                 server_url=url,
-                key=key
+                key=key,
+                autostart=True
             )
-            await dispatcher.start()  # this will start the actor
 
             events_receiver = dispatcher.new_lifecycle_events_receiver("DISPATCH_TYPE")
 
@@ -142,9 +177,9 @@ async def run():
             dispatcher = Dispatcher(
                 microgrid_id=microgrid_id,
                 server_url=url,
-                key=key
+                key=key,
+                autostart=True
             )
-            await dispatcher.start()  # this will start the actor
 
             # Create a new dispatch
             new_dispatch = await dispatcher.client.create(
@@ -250,13 +285,27 @@ async def start_dispatching(
     ) -> None:
         """Manage actors for a given dispatch type.
 
-        Creates and manages an ActorDispatcher for the given type that will
+        Creates and manages an
+        [`ActorDispatcher`][frequenz.dispatch.ActorDispatcher] for the given type that will
         start, stop and reconfigure actors based on received dispatches.
 
         You can await the `Dispatcher` instance to block until all types
         registered with `start_dispatching()` are stopped using
         `stop_dispatching()`
 
+        "Merging" means that when multiple dispatches are active at the same time,
+        the intervals are merged into one.
+
+        This also decides how instances are mapped from dispatches to actors:
+
+        * [`MergeByType`][frequenz.dispatch.MergeByType] — All dispatches map to
+        one single instance identified by the dispatch type.
+        * [`MergeByTypeTarget`][frequenz.dispatch.MergeByTypeTarget] — A
+        dispatch maps to an instance identified by the dispatch type and target.
+        So different dispatches with equal type and target will map to the same
+        instance.
+        * `None` — No merging, each dispatch maps to a separate instance.
+
         Args:
             dispatch_type: The type of the dispatch to manage.
             actor_factory: The factory to create actors.