Implement extra classes for each target type

..and support the latest CategoryAndType target type.

This implements extra classes for each target component case:
* List of Ids `TargetIds`
* List of categories: `TargetCategories`
* List of categories + subtypes: `TargetCategoriesAndTypes`

This was easier to do together as the addition of the new type
increased the places where it
was difficult to find out what the actual target type/ids is/are.

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

Author: Marenz

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

@@ -12,6 +12,15 @@
 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 +149,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 +158,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 +175,69 @@ 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,
 )
 
@@ -116,7 +119,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,

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]),