Add support for dispatch_ids and queries filters

Signed-off-by: Mathias L. Baumann <mathias.baumann@frequenz.com>

Author: Marenz

RELEASE_NOTES.md

@@ -10,8 +10,11 @@
 
 ## New Features
 
-<!-- Here goes the main new features and examples or instructions on how to use them -->
+* Added support for `dispatch_ids` and `queries` filters in the `list` method
+  - `dispatch_ids` parameter allows filtering by specific dispatch IDs
+  - `filter_queries` parameter supports text-based filtering on dispatch `id` and `type` fields
+      - Query format: IDs are prefixed with `#` (e.g., `#4`), types are matched as substrings (e.g., `bar` matches `foobar`)
+      - Multiple queries are combined with logical OR
 
 ## Bug Fixes
 
-* The `FakeService` filter list code is now properly checking for unset fields to filter for.

src/frequenz/client/dispatch/__main__.py

@@ -273,6 +273,8 @@ async def cli(  # pylint: disable=too-many-arguments, too-many-positional-argume
 @click.option("--end-to", type=FuzzyDateTime())
 @click.option("--active", type=bool)
 @click.option("--dry-run", type=bool)
+@click.option("--dispatch-ids", type=int, multiple=True)
+@click.option("--filter-queries", type=str, multiple=True)
 @click.option("--page-size", type=int)
 @click.option("--running", type=bool)
 @click.option("--type", "-T", type=str)
@@ -282,6 +284,10 @@ async def list_(ctx: click.Context, /, **filters: Any) -> None:
     Lists all dispatches for MICROGRID_ID that match the given filters.
 
     The target option can be given multiple times.
+
+    The filter-queries option supports text-based filtering on dispatch id and type fields.
+    IDs are prefixed with '#' (e.g., '#4'), types are matched as substrings
+    (e.g., 'bar' matches 'foobar'). Multiple queries are combined with logical OR.
     """
     filter_running: bool = filters.pop("running", False)
     filter_type: str | None = filters.pop("type", None)
@@ -291,6 +297,14 @@ async def list_(ctx: click.Context, /, **filters: Any) -> None:
         # Name of the parameter in client.list()
         filters["target_components"] = target
 
+    # Convert dispatch_ids to iterator if present
+    if "dispatch_ids" in filters:
+        filters["dispatch_ids"] = iter(filters["dispatch_ids"])
+
+    # Convert filter_queries to iterator if present
+    if "filter_queries" in filters:
+        filters["filter_queries"] = iter(filters["filter_queries"])
+
     num_dispatches = 0
     num_filtered = 0
     async for page in ctx.obj["client"].list(**filters):

src/frequenz/client/dispatch/_client.py

@@ -145,6 +145,8 @@ async def list(
         end_to: datetime | None = None,
         active: bool | None = None,
         dry_run: bool | None = None,
+        dispatch_ids: Iterator[DispatchId] = iter(()),
+        filter_queries: Iterator[str] = iter(()),
         page_size: int | None = None,
     ) -> AsyncIterator[Iterator[Dispatch]]:
         """List dispatches.
@@ -166,6 +168,17 @@ async def list(
                 print(dispatch)
         ```
 
+        The `filter_queries` parameter is applied to the dispatch `id` and `type` fields.
+        Each query in the list is applied as a logical OR.
+
+        ID tokens are preceded by a `#` so we can tell if an id is intended or a type.
+
+        - input of [`#4`] will match only the record with id of `4`
+        - input of [`#not_an_id`] will match types containing `#not_an_id`
+        - input of [`bar`] will match `bar` and `foobar`
+        - input of [`#4`, `#24`, `bar`, `foo`] will match ids of `4` and `24` and
+          types `foo` `bar` `foobar` `foolish bartender`
+
         Args:
             microgrid_id: The microgrid_id to list dispatches for.
             target_components: optional, list of component ids or categories to filter by.
@@ -175,6 +188,8 @@ async def list(
             end_to: optional, filter by end_time < end_to.
             active: optional, filter by active status.
             dry_run: optional, filter by dry_run status.
+            dispatch_ids: optional, list of dispatch IDs to filter by.
+            filter_queries: optional, list of text queries to filter by.
             page_size: optional, number of dispatches to return per page.
 
         Returns:
@@ -203,6 +218,8 @@ def to_interval(
             end_time_interval=end_time_interval,
             is_active=active,
             is_dry_run=dry_run,
+            dispatch_ids=list(map(int, dispatch_ids)),
+            queries=list(filter_queries),
         )
 
         request = ListMicrogridDispatchesRequest(

src/frequenz/client/dispatch/test/_service.py

@@ -178,6 +178,27 @@ def _filter_dispatch(
                 if dispatch.dry_run != _filter.is_dry_run:
                     return False
 
+            if len(_filter.dispatch_ids) > 0 and dispatch.id not in map(
+                DispatchId, _filter.dispatch_ids
+            ):
+                return False
+
+            # Two cases:
+            #  - query starts with # and is interpretable as int: filter by id
+            #  - otherwise: filter by substring in 'type' field
+            for query in _filter.queries:
+                if query.startswith("#"):
+                    try:
+                        query_id = DispatchId(int(query[1:]))
+                        if dispatch.id != query_id:
+                            return False
+                    except ValueError:
+                        # not an int, interpret as substring
+                        if query.lower() not in dispatch.type.lower():
+                            return False
+                elif query.lower() not in dispatch.type.lower():
+                    return False
+
         return True
 
     async def CreateMicrogridDispatch(

tests/test_client.py

@@ -113,6 +113,52 @@ async def test_list_dispatches(
             assert dispatch == service_side_dispatch
 
 
+async def test_list_filter_queries(
+    client: FakeClient, generator: DispatchGenerator
+) -> None:
+    """Test listing dispatches with filter queries."""
+    microgrid_id = MicrogridId(random.randint(1, 100))
+
+    all_dispatches = [generator.generate_dispatch() for _ in range(100)]
+    client.set_dispatches(
+        microgrid_id=microgrid_id,
+        value=all_dispatches,
+    )
+
+    # Filter by type
+    filter_type = all_dispatches[0].type
+    dispatches = client.list(
+        microgrid_id=MicrogridId(1),
+        filter_queries=iter([filter_type]),
+    )
+    async for page in dispatches:
+        for dispatch in page:
+            assert dispatch.type == filter_type
+
+    # Filter by id (needs to prefix with #)
+    filter_target_id = all_dispatches[0].id
+    dispatches = client.list(
+        microgrid_id=MicrogridId(1),
+        filter_queries=iter([f"#{filter_target_id}"]),
+    )
+    async for page in dispatches:
+        for dispatch in page:
+            assert dispatch.id == filter_target_id
+
+    # Mixed filter
+    filter_mixed = [all_dispatches[3].type, f"#{all_dispatches[4].id}"]
+    dispatches = client.list(
+        microgrid_id=MicrogridId(1),
+        filter_queries=iter(filter_mixed),
+    )
+    async for page in dispatches:
+        for dispatch in page:
+            assert (
+                dispatch.type == all_dispatches[3].type
+                or dispatch.id == all_dispatches[4].id
+            )
+
+
 async def test_list_dispatches_no_duration(
     client: FakeClient, generator: DispatchGenerator
 ) -> None: