Allow targeting categories with subtypes

pyproject.toml

@@ -37,10 +37,11 @@ classifiers = [
 requires-python = ">= 3.11, < 4"
 dependencies = [
   "typing-extensions >= 4.6.1, < 5",
-  "frequenz-api-dispatch == 1.0.0-rc1",
+  #  "frequenz-api-dispatch == 1.0.0-rc1",
+  "frequenz-api-dispatch @ git+https://github.com/frequenz-floss/frequenz-api-dispatch@4274d1a",
   "frequenz-client-base >= 0.8.0, < 0.10.0",
   "frequenz-client-common >= 0.1.0, < 0.4.0",
-  "grpcio >= 1.66.1, < 2",
+  "grpcio >= 1.70.0, < 2",
   "python-dateutil >= 2.8.2, < 3.0",
 ]
 dynamic = ["version"]
@@ -93,7 +94,8 @@ dev-pylint = [
   "pylint == 3.3.6",
   # For checking the noxfile, docs/ script, and tests
   "frequenz-client-dispatch[cli,dev-mkdocs,dev-noxfile,dev-pytest]",
-  "frequenz-api-dispatch == 1.0.0-rc1",
+  #  "frequenz-api-dispatch == 1.0.0-rc1",
+  "frequenz-api-dispatch @ git+https://github.com/frequenz-floss/frequenz-api-dispatch@4274d1a",
 ]
 dev-pytest = [
   "pytest == 8.3.5",

src/frequenz/client/dispatch/__main__.py

@@ -86,7 +86,8 @@ def print_dispatch(dispatch: Dispatch) -> None:
     # Format the target
     if dispatch.target:
         if len(dispatch.target) == 1:
-            target_str: str = str(dispatch.target[0])
+            (el,) = dispatch.target
+            target_str: str = str(el)
         else:
             target_str = ", ".join(str(s) for s in dispatch.target)
     else:

src/frequenz/client/dispatch/_cli_types.py

@@ -5,13 +5,23 @@
 
 import json
 from datetime import datetime, timedelta, timezone
+from sre_constants import IN
 from typing import Any, Literal, cast
 
 import asyncclick as click
 import parsedatetime  # type: ignore
 from tzlocal import get_localzone
 
 from frequenz.client.common.microgrid.components import ComponentCategory
+from frequenz.client.dispatch.types import (
+    BatteryType,
+    CategoryAndType,
+    EvChargerType,
+    InverterType,
+    TargetCategories,
+    TargetCategoryAndTypes,
+    TargetIds,
+)
 
 # Disable a false positive from pylint
 # pylint: disable=inconsistent-return-statements
@@ -140,7 +150,7 @@ class TargetComponentParamType(click.ParamType):
 
     def convert(
         self, value: Any, param: click.Parameter | None, ctx: click.Context | None
-    ) -> list[ComponentCategory] | list[int]:
+    ) -> TargetIds | TargetCategories | TargetCategoryAndTypes:
         """Convert the input value into a list of ComponentCategory or IDs.
 
         Args:
@@ -149,9 +159,13 @@ def convert(
             ctx: The Click context object.
 
         Returns:
-            A list of component ids or component categories.
+            A list of targets, either as component IDs or component categories.
         """
-        if isinstance(value, list):  # Already a list
+        if (
+            isinstance(value, TargetIds)
+            or isinstance(value, TargetCategories)
+            or isinstance(value, TargetCategoryAndTypes)
+        ):
             return value
 
         values = value.split(",")
@@ -162,20 +176,67 @@ def convert(
         error: Exception | None = None
         # Attempt to parse component ids
         try:
-            return [int(id) for id in values]
+            return TargetIds([int(id) for id in values])
         except ValueError as e:
             error = e
 
         # Attempt to parse as component categories, trim whitespace
         try:
-            return [ComponentCategory[cat.strip().upper()] for cat in values]
+            return TargetCategories(
+                [ComponentCategory[cat.strip().upper()] for cat in values]
+            )
+        except KeyError as e:
+            error = e
+
+        def valid_short_types() -> (
+            dict[str, BatteryType | InverterType | EvChargerType]
+        ):
+            """All valid types in short form."""
+            str_to_enum = {}
+
+            for enum in BatteryType:
+                short_name = enum.name.split("_")[-1]
+                str_to_enum[short_name] = enum
+
+            for enum in InverterType:
+                short_name = enum.name.split("_")[-1]
+                str_to_enum[short_name] = enum
+
+            for enum in EvChargerType:
+                short_name = enum.name.split("_")[-1]
+                str_to_enum[short_name] = enum
+
+            return str_to_enum
+
+        short_types = valid_short_types()
+
+        # Attempt to parse as component categories with types
+        try:
+            return TargetCategoryAndTypes(
+                [
+                    CategoryAndType(
+                        ComponentCategory[cat.strip().upper()],
+                        short_types[type.strip().upper()]
+                        if type in short_types
+                        else None,
+                    )
+                    for cat, type in (cat.split(":") for cat in values)
+                ]
+            )
         except KeyError as e:
             error = e
 
         self.fail(
             f'Invalid component category list or ID list: "{value}".\n'
             f'Error: "{error}"\n\n'
-            "Possible categories: BATTERY, GRID, METER, INVERTER, EV_CHARGER, CHP ",
+            "Valid formats:\n"
+            "- 1,2,3 # A list of component IDs\n"
+            "- METER,INVERTER # A list of component categories\n"
+            "- BATTERY:NA_ION,INVERTER:SOLAR # A list of component categories with types\n"
+            "Valid component categories:\n"
+            f"{', '.join([cat.name for cat in ComponentCategory])}\n"
+            "Valid component types:\n"  # using prepared short_types for better readability
+            f"{', '.join([f'{cat}:{type}' for cat, type in short_types.items()])}",
             param,
             ctx,
         )

src/frequenz/client/dispatch/_client.py

@@ -42,7 +42,10 @@
 from .types import (
     Dispatch,
     DispatchEvent,
+    TargetCategories,
+    TargetCategoryAndTypes,
     TargetComponents,
+    TargetIds,
     _target_components_to_protobuf,
 )
 
@@ -98,7 +101,7 @@ async def list(
         self,
         microgrid_id: int,
         *,
-        target_components: Iterator[TargetComponents] = iter(()),
+        target_components: TargetComponents,
         start_from: datetime | None = None,
         start_to: datetime | None = None,
         end_from: datetime | None = None,
@@ -148,7 +151,7 @@ def to_interval(
         ) -> PBTimeIntervalFilter | None:
             return (
                 PBTimeIntervalFilter(
-                    **{"from": to_timestamp(from_)}, to=to_timestamp(to)
+                    from_time=to_timestamp(from_), to_time=to_timestamp(to)
                 )
                 if from_ or to
                 else None

src/frequenz/client/dispatch/recurrence.py

@@ -88,8 +88,8 @@ def from_protobuf(cls, pb_criteria: PBRecurrenceRule.EndCriteria) -> "EndCriteri
         match pb_criteria.WhichOneof("count_or_until"):
             case "count":
                 instance.count = pb_criteria.count
-            case "until":
-                instance.until = to_datetime(pb_criteria.until)
+            case "until_time":
+                instance.until = to_datetime(pb_criteria.until_time)
         return instance
 
     def to_protobuf(self) -> PBRecurrenceRule.EndCriteria:
@@ -103,7 +103,7 @@ def to_protobuf(self) -> PBRecurrenceRule.EndCriteria:
         if self.count is not None:
             pb_criteria.count = self.count
         elif self.until is not None:
-            pb_criteria.until.CopyFrom(to_timestamp(self.until))
+            pb_criteria.until_time.CopyFrom(to_timestamp(self.until))
 
         return pb_criteria
 

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

@@ -180,20 +180,20 @@ def _filter_dispatch(
                 if target != dispatch.target:
                     return False
             if _filter.HasField("start_time_interval"):
-                if start_from := _filter.start_time_interval.__dict__["from"]:
+                if start_from := _filter.start_time_interval.from_time:
                     if dispatch.start_time < _to_dt(start_from):
                         return False
-                if start_to := _filter.start_time_interval.to:
+                if start_to := _filter.start_time_interval.to_time:
                     if dispatch.start_time >= _to_dt(start_to):
                         return False
             if _filter.HasField("end_time_interval"):
-                if end_from := _filter.end_time_interval.__dict__["from"]:
+                if end_from := _filter.end_time_interval.from_time:
                     if (
                         dispatch.duration
                         and dispatch.start_time + dispatch.duration < _to_dt(end_from)
                     ):
                         return False
-                if end_to := _filter.end_time_interval.to:
+                if end_to := _filter.end_time_interval.to_time:
                     if (
                         dispatch.duration
                         and dispatch.start_time + dispatch.duration >= _to_dt(end_to)

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

@@ -10,7 +10,17 @@
 
 from .._internal_types import rounded_start_time
 from ..recurrence import EndCriteria, Frequency, RecurrenceRule, Weekday
-from ..types import Dispatch
+from ..types import (
+    BatteryType,
+    CategoryAndType,
+    Dispatch,
+    EvChargerType,
+    InverterType,
+    TargetCategories,
+    TargetCategoryAndTypes,
+    TargetComponents,
+    TargetIds,
+)
 
 
 class DispatchGenerator:
@@ -66,6 +76,30 @@ def generate_recurrence_rule(self) -> RecurrenceRule:
             ],
         )
 
+    def generate_target_cat_and_type(self) -> CategoryAndType:
+        """Generate a random category and type.
+
+        Returns:
+            a random category and type
+        """
+        category = self._rng.choice(list(ComponentCategory)[1:])
+        type = None
+
+        match category:
+            case ComponentCategory.BATTERY:
+                type = self._rng.choice(list(BatteryType)[1:])
+            case ComponentCategory.INVERTER:
+                type = self._rng.choice(list(InverterType)[1:])
+            case ComponentCategory.EV_CHARGER:
+                type = self._rng.choice(list(EvChargerType)[1:])
+            case _:
+                type = None
+
+        return CategoryAndType(
+            category=category,
+            type=type,
+        )
+
     def generate_dispatch(self) -> Dispatch:
         """Generate a random dispatch instance.
 
@@ -94,14 +128,24 @@ def generate_dispatch(self) -> Dispatch:
             ),
             target=self._rng.choice(  # type: ignore
                 [
-                    [
-                        self._rng.choice(list(ComponentCategory)[1:])
-                        for _ in range(self._rng.randint(1, 10))
-                    ],
-                    [
-                        self._rng.randint(1, 100)
-                        for _ in range(self._rng.randint(1, 10))
-                    ],
+                    TargetCategories(
+                        [
+                            self._rng.choice(list(ComponentCategory)[1:])
+                            for _ in range(self._rng.randint(1, 10))
+                        ]
+                    ),
+                    TargetIds(
+                        [
+                            self._rng.randint(1, 100)
+                            for _ in range(self._rng.randint(1, 10))
+                        ]
+                    ),
+                    TargetCategoryAndTypes(
+                        [
+                            self.generate_target_cat_and_type()
+                            for _ in range(self._rng.randint(1, 10))
+                        ]
+                    ),
                 ]
             ),
             active=self._rng.choice([True, False]),