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

@@ -1,4 +1,4 @@
-# Frequenz Dispatch Client Library Release Notes
+# Frequenz Dispatch Client Library Release Note
 
 ## Summary
 

pyproject.toml

@@ -5,7 +5,7 @@
 requires = [
   "setuptools == 80.4.0",
   "setuptools_scm[toml] == 8.3.1",
-  "frequenz-repo-config[lib] == 0.13.3",
+  "frequenz-repo-config[lib] == 0.13.4",
 ]
 build-backend = "setuptools.build_meta"
 
@@ -39,6 +39,7 @@ dependencies = [
   "typing-extensions >= 4.6.1, < 5",
   #  "frequenz-api-dispatch == 1.0.0-rc1",
   "frequenz-api-dispatch @ git+https://github.com/frequenz-floss/frequenz-api-dispatch@4274d1a",
+  "frequenz-api-common @ git+https://github.com/frequenz-floss/frequenz-api-common@c75dba3",
   "frequenz-client-base >= 0.8.0, < 0.10.0",
   "frequenz-client-common >= 0.1.0, < 0.4.0",
   "grpcio >= 1.70.0, < 2",
@@ -75,10 +76,11 @@ dev-mkdocs = [
   "mike == 2.1.3",
   "mkdocs-gen-files == 0.5.0",
   "mkdocs-literate-nav == 0.6.2",
+  "frequenz-api-dispatch @ git+https://github.com/frequenz-floss/frequenz-api-dispatch@4274d1a",
   "mkdocs-macros-plugin == 1.3.7",
   "mkdocs-material == 9.6.12",
   "mkdocstrings[python] == 0.29.1",
-  "frequenz-repo-config[lib] == 0.13.3",
+  "frequenz-repo-config[lib] == 0.13.4",
 ]
 dev-mypy = [
   "mypy == 1.15.0",
@@ -89,7 +91,7 @@ dev-mypy = [
   "types-protobuf == 5.29.1.20250403",
   "types-python-dateutil == 2.9.0.20241206",
 ]
-dev-noxfile = ["nox == 2025.5.1", "frequenz-repo-config[lib] == 0.13.3"]
+dev-noxfile = ["nox == 2025.5.1", "frequenz-repo-config[lib] == 0.13.4"]
 dev-pylint = [
   "pylint == 3.3.6",
   # For checking the noxfile, docs/ script, and tests
@@ -99,7 +101,7 @@ dev-pylint = [
 ]
 dev-pytest = [
   "pytest == 8.3.5",
-  "frequenz-repo-config[extra-lint-examples] == 0.13.3",
+  "frequenz-repo-config[extra-lint-examples] == 0.13.4",
   "pytest-mock == 3.14.0",
   "pytest-asyncio == 0.26.0",
   "async-solipsism == 0.7",

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={