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

RELEASE_NOTES.md

@@ -6,14 +6,34 @@
 
 ## Upgrading
 
-<!-- Here goes notes on how to upgrade from previous versions, including deprecations and what they should be replaced with -->
+* `TargetComponents` was reworked. It now is a type alias for `TargetIds | TargetCategories`:
+ * `TargetIds` can be used to specify one or more specific target IDs:
+  * `TargetIds(1, 2, 3)` or
+  * `TargetIds(ComponentIds(1), ComponentIds(2), ComponentIds(3))`
+ * `TargetCategories` can be used to specify one or more target categories:
+  * `TargetCategories(ComponentCategory.BATTERY, ComponentCategory.SOLAR)`
 
 ## New Features
 
 * `dispatch-cli` supports now the parameter `--type` and `--running` to filter the list of running services by type and status, respectively.
 * Every call now has a default timeout of 60 seconds, streams terminate after five minutes. This can be influenced by the two new parameters for`DispatchApiClient.__init__()`:
     * `default_timeout: timedelta` (default: 60 seconds)
     * `stream_timeout: timedelta` (default: 5 minutes)
+* With the new `TargetCategory` class (providing `.category` and `.type`) we can now specify subtypes of the categories:
+ * `ComponentCategory.BATTERY` uses `BatteryType` with possible values: `LI_ION`, `NA_ION`
+ * `ComponentCategory.INVERTER` uses `InverterType` with possible values: `BATTERY`, `SOLAR`, `HYBRID`
+ * `ComponentCategory.EV_CHARGER` uses `EvChargerType`: with possible values `AC`, `DC`, `HYBRID`
+ * A few examples on how to use the new `TargetCategory`:
+    * `TargetCategory(BatteryType.LI_ION)`
+        * `category` is `ComponentCategory.BATTERY`
+        * `type` is `BatteryType.LI_ION`
+    * `TargetCategory(ComponentCategory.BATTERY)`
+        * `category` is `ComponentCategory.BATTERY`
+        * `type` is `None`
+    * `TargetCategories(InverterType.SOLAR)`
+        * `category` is `ComponentCategory.INVERTER`
+        * `type` is `InverterType.SOLAR`
+
 
 ## Bug Fixes
 

pyproject.toml

@@ -74,6 +74,7 @@ dev-mkdocs = [
   "mike == 2.1.3",
   "mkdocs-gen-files == 0.5.0",
   "mkdocs-literate-nav == 0.6.2",
+  "frequenz-api-dispatch == 1.0.0-rc2",
   "mkdocs-macros-plugin == 1.3.7",
   "mkdocs-material == 9.6.14",
   "mkdocstrings[python] == 0.29.1",

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])
+            (first_element,) = dispatch.target
+            target_str: str = str(first_element)
         else:
             target_str = ", ".join(str(s) for s in dispatch.target)
     else:

src/frequenz/client/dispatch/_cli_types.py

@@ -5,13 +5,22 @@
 
 import json
 from datetime import datetime, timedelta, timezone
+from itertools import chain
 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,
+    EvChargerType,
+    InverterType,
+    TargetCategories,
+    TargetComponents,
+    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:
         """Convert the input value into a list of ComponentCategory or IDs.
 
         Args:
@@ -149,9 +158,9 @@ 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, TargetComponents):
             return value
 
         values = value.split(",")
@@ -162,20 +171,46 @@ 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
 
+        def enum_from_str(
+            name: str,
+        ) -> InverterType | BatteryType | EvChargerType | ComponentCategory:
+            """Convert a string to an enum member."""
+            name = name.strip().upper()
+            if name in ComponentCategory.__members__:
+                return ComponentCategory[name]
+            if name in InverterType.__members__:
+                return InverterType[name]
+            if name in BatteryType.__members__:
+                return BatteryType[name]
+            if name in EvChargerType.__members__:
+                return EvChargerType[name]
+            raise KeyError(f"Invalid target specification: {name}")
+
         # Attempt to parse as component categories, trim whitespace
         try:
-            return [ComponentCategory[cat.strip().upper()] for cat in values]
+            return TargetCategories(*[enum_from_str(cat) for cat in values])
         except KeyError as e:
             error = e
 
+        types_str = ", ".join(
+            [f"{type.name}" for type in chain(BatteryType, InverterType, EvChargerType)]
+        )
+
         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"
+            "- NA_ION,SOLAR # A list of component category types (category is derived)\n"
+            "Valid categories:\n"
+            f"{', '.join([cat.name for cat in ComponentCategory])}\n"
+            "Valid types:\n"
+            f"{types_str}\n",
             param,
             ctx,
         )

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

@@ -10,7 +10,16 @@
 
 from .._internal_types import rounded_start_time
 from ..recurrence import EndCriteria, Frequency, RecurrenceRule, Weekday
-from ..types import Dispatch
+from ..types import (
+    BatteryType,
+    Dispatch,
+    EvChargerType,
+    InverterType,
+    TargetCategories,
+    TargetCategory,
+    TargetComponents,
+    TargetIds,
+)
 
 
 class DispatchGenerator:
@@ -66,6 +75,27 @@ def generate_recurrence_rule(self) -> RecurrenceRule:
             ],
         )
 
+    def generate_target_category_and_type(self) -> TargetCategory:
+        """Generate a random category and type.
+
+        Returns:
+            a random category and type
+        """
+        category = self._rng.choice(list(ComponentCategory)[1:])
+        category_type: BatteryType | InverterType | EvChargerType | None = None
+
+        match category:
+            case ComponentCategory.BATTERY:
+                category_type = self._rng.choice(list(BatteryType)[1:])
+            case ComponentCategory.INVERTER:
+                category_type = self._rng.choice(list(InverterType)[1:])
+            case ComponentCategory.EV_CHARGER:
+                category_type = self._rng.choice(list(EvChargerType)[1:])
+            case _:
+                category_type = None
+
+        return TargetCategory(category_type or category)
+
     def generate_dispatch(self) -> Dispatch:
         """Generate a random dispatch instance.
 
@@ -77,6 +107,20 @@ def generate_dispatch(self) -> Dispatch:
             self._rng.randint(0, 1000000), tz=timezone.utc
         )
 
+        target_choices: list[TargetComponents] = [
+            TargetIds(
+                *[self._rng.randint(1, 100) for _ in range(self._rng.randint(1, 10))]
+            ),
+            TargetCategories(
+                *[
+                    # Not yet used
+                    # self.generate_target_category_and_type()
+                    self._rng.choice(list(ComponentCategory)[1:])
+                    for _ in range(self._rng.randint(1, 10))
+                ]
+            ),
+        ]
+
         return Dispatch(
             id=self._last_id,
             create_time=create_time,
@@ -92,18 +136,7 @@ def generate_dispatch(self) -> Dispatch:
                     timedelta(seconds=self._rng.randint(0, 1000000)),
                 ]
             ),
-            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))
-                    ],
-                ]
-            ),
+            target=self._rng.choice(target_choices),
             active=self._rng.choice([True, False]),
             dry_run=self._rng.choice([True, False]),
             payload={