Make .create() return the new created dispatch

There is hardly any use-case for wanting to use `create()` and not have the
new dispatch available.

This is also in anticipation of the upcoming server-side feature that will
return the newly created dispatch.

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

Author: Marenz

RELEASE_NOTES.md

@@ -14,6 +14,7 @@
 
 - A new module `frequenz.client.dispatch.test` has been added, providing a fake Service and Client as well as a `DispatchGenerator` to generate `Dispatch` instances filled with random data.
 - The `DispatchGenerator.generate_dispatch` method now accepts a `microgrid_id` parameter to generate `Dispatch` instances with a specific microgrid ID.
+- The `Client.create()` method now returns the newly created `Dispatch` object.
 
 ## Bug Fixes
 

src/frequenz/client/dispatch/_client.py

@@ -22,7 +22,7 @@
 
 from frequenz.client.base.conversion import to_timestamp
 
-from ._internal_types import DispatchCreateRequest
+from ._internal_types import DispatchCreateRequest, rounded_start_time
 from .types import (
     ComponentSelector,
     Dispatch,
@@ -123,9 +123,12 @@ async def create(
         dry_run: bool = False,
         payload: dict[str, Any] | None = None,
         recurrence: RecurrenceRule | None = None,
-    ) -> None:
+    ) -> Dispatch:
         """Create a dispatch.
 
+        Will try to return the created dispatch, identifying it by
+        the same fields as the request.
+
         Args:
             microgrid_id: The microgrid_id to create the dispatch for.
             _type: User defined string to identify the dispatch type.
@@ -137,8 +140,12 @@ async def create(
             payload: The payload of the dispatch.
             recurrence: The recurrence rule of the dispatch.
 
+        Returns:
+            Dispatch: The created dispatch
+
         Raises:
             ValueError: If start_time is in the past.
+            ValueError: If the created dispatch could not be found.
         """
         if start_time <= datetime.now(tz=start_time.tzinfo):
             raise ValueError("start_time must not be in the past")
@@ -157,9 +164,14 @@ async def create(
             dry_run=dry_run,
             payload=payload or {},
             recurrence=recurrence or RecurrenceRule(),
-        ).to_protobuf()
+        )
 
-        await self._stub.CreateMicrogridDispatch(request)  # type: ignore
+        await self._stub.CreateMicrogridDispatch(request.to_protobuf())  # type: ignore
+
+        if dispatch := await self._try_fetch_created_dispatch(request):
+            return dispatch
+
+        raise ValueError("Could not find the created dispatch")
 
     async def update(
         self,
@@ -255,3 +267,31 @@ async def delete(self, dispatch_id: int) -> None:
         """
         request = DispatchDeleteRequest(id=dispatch_id)
         await self._stub.DeleteMicrogridDispatch(request)  # type: ignore
+
+    async def _try_fetch_created_dispatch(
+        self,
+        request: DispatchCreateRequest,
+    ) -> Dispatch | None:
+        """Try to fetch the created dispatch.
+
+        Will return the created dispatch if it was found, otherwise None.
+
+        Args:
+            request: The dispatch create request.
+
+        Returns:
+            Dispatch: The created dispatch, if it was found.
+        """
+        async for dispatch in self.list(microgrid_id=request.microgrid_id):
+            found = True
+            for key, value in request.__dict__.items():
+                if key == "start_time":
+                    value = rounded_start_time(value)
+
+                if not (found := getattr(dispatch, key) == value):
+                    break
+
+            if found:
+                return dispatch
+
+        return None

tests/test_dispatch_client.py

@@ -52,6 +52,24 @@ async def test_create_dispatch() -> None:
     assert stored_dispatches[0] == sample
 
 
+async def test_create_return_dispatch() -> None:
+    """Test creating a dispatch and returning the created dispatch."""
+    # Make sure we don't rely on the order of the dispatches
+    generator = DispatchGenerator()
+    client = FakeClient(shuffle_after_create=True)
+
+    for _ in range(100):
+        sample = generator.generate_dispatch()
+
+        dispatch = await client.create(**to_create_params(sample))
+
+        # Before we can compare, we need to set the create_time and update_time
+        # as they are generated by the (fake) remote point
+        sample = _update(sample, dispatch)
+
+        assert dispatch == sample
+
+
 async def test_list_dispatches() -> None:
     """Test listing dispatches."""
     sampler = DispatchGenerator()