refactor: Adapt code to v1alpha8 API of frequenz-client-common

The `frequenz-client-common` dependency has been updated, which introduced breaking changes from the new `v1alpha8` API. This commit adapts the codebase to these changes, resolving the resulting `nox` failures across `mypy`, `pytest`, and formatters.

Key changes include:
- Replacing the deprecated `ComponentCategory` with `v1alpha8`'s `ElectricalComponentCategory`.
- Updating enum members to match the new API, such as `ElectricalComponentCategory.GRID` to `GRID_CONNECTION_POINT` and `InverterType.PV` to `InverterType.SOLAR`.
- Adjusting `Event` enum usage (e.g., `Event.CREATED` is now `Event.EVENT_CREATED`).

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

Author: Marenz

RELEASE_NOTES.md

@@ -6,6 +6,12 @@
 
 ## Upgrading
 
+* The client has been updated to support breaking changes in the `v1alpha8` API of the `frequenz-client-common` dependency.
+  * `ComponentCategory` has been replaced with `ElectricalComponentCategory`.
+  * Enum members were updated to align with the new API (e.g., `ElectricalComponentCategory.GRID` is now `ElectricalComponentCategory.GRID_CONNECTION_POINT`).
+  * `Event` enum usage was updated (e.g., `Event.CREATED` is now `Event.EVENT_CREATED`).
+  * The `DispatchApiClient.list()` method signature was updated to use new filter argument names.
+
 <!-- Here goes notes on how to upgrade from previous versions, including deprecations and what they should be replaced with -->
 
 ## New Features
@@ -19,3 +25,11 @@
 ## Bug Fixes
 
 <!-- Here goes notable bug fixes that are worth a special mention or explanation -->
+
+## Changed
+
+* Adapted the client to breaking changes in the `v1alpha8` API of the `frequenz-client-common` dependency.
+  * Replaced `ComponentCategory` with `ElectricalComponentCategory`.
+  * Updated various enum members to match the new API (e.g., `ElectricalComponentCategory.GRID` is now `ElectricalComponentCategory.GRID_CONNECTION_POINT`).
+  * Aligned `Event` enum usage with the new API (e.g., `Event.CREATED` is now `Event.EVENT_CREATED`).
+  * Updated `DispatchApiClient.list()` method signature to use new filter argument names.

pyproject.toml

@@ -37,11 +37,11 @@ classifiers = [
 requires-python = ">= 3.11, < 4"
 dependencies = [
   "typing-extensions >= 4.13.0, < 5",
-  "frequenz-api-dispatch == 1.0.0-rc2",
+  "frequenz-api-dispatch == 1.0.0-rc3",
   "frequenz-client-base >= 0.11.0, < 0.12.0",
-  "frequenz-client-common >= 0.3.2,  < 0.4.0",
+  "frequenz-client-common >= 0.3.4,  < 0.4.0",
   "frequenz-core >= 1.0.2, < 2.0.0",
-  "grpcio >= 1.70.0, < 2",
+  "grpcio >= 1.72.1, < 2",
   "python-dateutil >= 2.8.2, < 3.0",
 ]
 dynamic = ["version"]
@@ -75,7 +75,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",
+  "frequenz-api-dispatch == 1.0.0-rc3",
   "mkdocs-macros-plugin == 1.3.7",
   "mkdocs-material == 9.6.16",
   "mkdocstrings[python] == 0.30.0",
@@ -95,7 +95,7 @@ dev-pylint = [
   "pylint == 3.3.7",
   # For checking the noxfile, docs/ script, and tests
   "frequenz-client-dispatch[cli,dev-mkdocs,dev-noxfile,dev-pytest]",
-  "frequenz-api-dispatch == 1.0.0-rc2",
+  "frequenz-api-dispatch == 1.0.0-rc3",
 ]
 dev-pytest = [
   "pytest == 8.4.1",

src/frequenz/client/dispatch/_cli_types.py

@@ -12,7 +12,9 @@
 import parsedatetime  # type: ignore
 from tzlocal import get_localzone
 
-from frequenz.client.common.microgrid.components import ComponentCategory
+from frequenz.client.common.v1alpha8.microgrid.electrical_components import (
+    ElectricalComponentCategory,
+)
 from frequenz.client.dispatch.types import (
     BatteryType,
     EvChargerType,
@@ -177,11 +179,11 @@ def convert(
 
         def enum_from_str(
             name: str,
-        ) -> InverterType | BatteryType | EvChargerType | ComponentCategory:
+        ) -> InverterType | BatteryType | EvChargerType | ElectricalComponentCategory:
             """Convert a string to an enum member."""
             name = name.strip().upper()
-            if name in ComponentCategory.__members__:
-                return ComponentCategory[name]
+            if name in ElectricalComponentCategory.__members__:
+                return ElectricalComponentCategory[name]
             if name in InverterType.__members__:
                 return InverterType[name]
             if name in BatteryType.__members__:
@@ -208,7 +210,7 @@ def enum_from_str(
             "- 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"
+            f"{', '.join([cat.name for cat in ElectricalComponentCategory])}\n"
             "Valid types:\n"
             f"{types_str}\n",
             param,

src/frequenz/client/dispatch/_client.py

@@ -7,8 +7,11 @@
 from datetime import datetime, timedelta
 from typing import Any, AsyncIterator, Awaitable, Iterator, Literal, cast
 
-# pylint: disable=no-name-in-module
-from frequenz.api.common.v1.pagination.pagination_params_pb2 import PaginationParams
+# pylint: disable-next=no-name-in-module
+from frequenz.api.common.v1alpha8.pagination.pagination_params_pb2 import (
+    PaginationParams,
+)
+from frequenz.api.common.v1alpha8.types.interval_pb2 import Interval as PBInterval
 from frequenz.api.dispatch.v1 import dispatch_pb2_grpc
 from frequenz.api.dispatch.v1.dispatch_pb2 import (
     CreateMicrogridDispatchResponse,
@@ -20,11 +23,6 @@
     ListMicrogridDispatchesResponse,
     StreamMicrogridDispatchesRequest,
     StreamMicrogridDispatchesResponse,
-)
-from frequenz.api.dispatch.v1.dispatch_pb2 import (
-    TimeIntervalFilter as PBTimeIntervalFilter,
-)
-from frequenz.api.dispatch.v1.dispatch_pb2 import (
     UpdateMicrogridDispatchRequest,
     UpdateMicrogridDispatchResponse,
 )
@@ -170,11 +168,9 @@ async def list(
 
         def to_interval(
             from_: datetime | None, to: datetime | None
-        ) -> PBTimeIntervalFilter | None:
+        ) -> PBInterval | None:
             return (
-                PBTimeIntervalFilter(
-                    from_time=to_timestamp(from_), to_time=to_timestamp(to)
-                )
+                PBInterval(start_time=to_timestamp(from_), end_time=to_timestamp(to))
                 if from_ or to
                 else None
             )

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

@@ -14,7 +14,8 @@
 import grpc.aio
 
 # pylint: disable=no-name-in-module
-from frequenz.api.common.v1.pagination.pagination_info_pb2 import PaginationInfo
+from frequenz.api.common.v1alpha8.pagination.pagination_info_pb2 import PaginationInfo
+from frequenz.api.common.v1alpha8.streaming.event_pb2 import Event as PBEvent
 from frequenz.api.dispatch.v1.dispatch_pb2 import (
     CreateMicrogridDispatchRequest as PBDispatchCreateRequest,
 )
@@ -36,9 +37,10 @@
 # pylint: enable=no-name-in-module
 from frequenz.client.base.conversion import to_datetime as _to_dt
 from frequenz.client.common.microgrid import MicrogridId
+from frequenz.client.common.v1alpha8.streaming import Event
 
 from .._internal_types import DispatchCreateRequest
-from ..types import Dispatch, DispatchEvent, DispatchId, Event
+from ..types import Dispatch, DispatchEvent, DispatchId
 
 _logger = logging.getLogger(__name__)
 
@@ -148,20 +150,20 @@ def _filter_dispatch(
                 if target != dispatch.target:
                     return False
             if _filter.HasField("start_time_interval"):
-                if start_from := _filter.start_time_interval.from_time:
+                if start_from := _filter.start_time_interval.start_time:
                     if dispatch.start_time < _to_dt(start_from):
                         return False
-                if start_to := _filter.start_time_interval.to_time:
+                if start_to := _filter.start_time_interval.end_time:
                     if dispatch.start_time >= _to_dt(start_to):
                         return False
             if _filter.HasField("end_time_interval"):
-                if end_from := _filter.end_time_interval.from_time:
+                if end_from := _filter.end_time_interval.start_time:
                     if (
                         dispatch.duration
                         and dispatch.start_time + dispatch.duration < _to_dt(end_from)
                     ):
                         return False
-                if end_to := _filter.end_time_interval.to_time:
+                if end_to := _filter.end_time_interval.end_time:
                     if (
                         dispatch.duration
                         and dispatch.start_time + dispatch.duration >= _to_dt(end_to)
@@ -198,7 +200,9 @@ async def CreateMicrogridDispatch(
         await self._stream_sender.send(
             self.StreamEvent(
                 microgrid_id,
-                DispatchEvent(dispatch=new_dispatch, event=Event.CREATED),
+                DispatchEvent(
+                    dispatch=new_dispatch, event=Event(PBEvent.EVENT_CREATED)
+                ),
             )
         )
 
@@ -289,7 +293,7 @@ async def UpdateMicrogridDispatch(
         await self._stream_sender.send(
             self.StreamEvent(
                 microgrid_id,
-                DispatchEvent(dispatch=dispatch, event=Event.UPDATED),
+                DispatchEvent(dispatch=dispatch, event=Event(PBEvent.EVENT_UPDATED)),
             )
         )
 
@@ -347,7 +351,7 @@ async def DeleteMicrogridDispatch(
                 microgrid_id,
                 DispatchEvent(
                     dispatch=dispatch_to_delete,
-                    event=Event.DELETED,
+                    event=Event(PBEvent.EVENT_DELETED),
                 ),
             )
         )

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

@@ -6,7 +6,9 @@
 import random
 from datetime import datetime, timedelta, timezone
 
-from frequenz.client.common.microgrid.components import ComponentCategory
+from frequenz.client.common.v1alpha8.microgrid.electrical_components import (
+    ElectricalComponentCategory,
+)
 
 from .._internal_types import rounded_start_time
 from ..recurrence import EndCriteria, Frequency, RecurrenceRule, Weekday
@@ -82,15 +84,15 @@ def generate_target_category_and_type(self) -> TargetCategory:
         Returns:
             a random category and type
         """
-        category = self._rng.choice(list(ComponentCategory)[1:])
+        category = self._rng.choice(list(ElectricalComponentCategory)[1:])
         category_type: BatteryType | InverterType | EvChargerType | None = None
 
         match category:
-            case ComponentCategory.BATTERY:
+            case ElectricalComponentCategory.BATTERY:
                 category_type = self._rng.choice(list(BatteryType)[1:])
-            case ComponentCategory.INVERTER:
+            case ElectricalComponentCategory.INVERTER:
                 category_type = self._rng.choice(list(InverterType)[1:])
-            case ComponentCategory.EV_CHARGER:
+            case ElectricalComponentCategory.EV_CHARGER:
                 category_type = self._rng.choice(list(EvChargerType)[1:])
             case _:
                 category_type = None
@@ -116,7 +118,7 @@ def generate_dispatch(self) -> Dispatch:
                 *[
                     # Not yet used
                     # self.generate_target_category_and_type()
-                    self._rng.choice(list(ComponentCategory)[1:])
+                    self._rng.choice(list(ElectricalComponentCategory)[1:])
                     for _ in range(self._rng.randint(1, 10))
                 ]
             ),

src/frequenz/client/dispatch/types.py

@@ -10,13 +10,13 @@
 from typing import Any, Self, SupportsInt, TypeAlias, cast, final
 
 # pylint: enable=no-name-in-module
-from frequenz.api.common.v1.microgrid.components.battery_pb2 import (
+from frequenz.api.common.v1alpha8.microgrid.electrical_components.electrical_components_pb2 import (
     BatteryType as PBBatteryType,
 )
-from frequenz.api.common.v1.microgrid.components.ev_charger_pb2 import (
+from frequenz.api.common.v1alpha8.microgrid.electrical_components.electrical_components_pb2 import (
     EvChargerType as PBEvChargerType,
 )
-from frequenz.api.common.v1.microgrid.components.inverter_pb2 import (
+from frequenz.api.common.v1alpha8.microgrid.electrical_components.electrical_components_pb2 import (
     InverterType as PBInverterType,
 )
 
@@ -33,7 +33,10 @@
 from google.protobuf.struct_pb2 import Struct
 
 from frequenz.client.base.conversion import to_datetime, to_timestamp
-from frequenz.client.common.microgrid.components import ComponentCategory
+from frequenz.client.common.v1alpha8.microgrid.electrical_components import (
+    ElectricalComponentCategory,
+)
+from frequenz.client.common.v1alpha8.streaming import Event
 
 from .recurrence import Frequency, RecurrenceRule, Weekday
 
@@ -81,7 +84,7 @@ class InverterType(Enum):
     BATTERY = PBInverterType.INVERTER_TYPE_BATTERY
     """Battery inverter."""
 
-    SOLAR = PBInverterType.INVERTER_TYPE_SOLAR
+    PV = PBInverterType.INVERTER_TYPE_PV
     """Solar inverter."""
 
     HYBRID = PBInverterType.INVERTER_TYPE_HYBRID
@@ -92,28 +95,28 @@ class InverterType(Enum):
 class TargetCategory:
     """Represents a category and optionally a type."""
 
-    target: ComponentCategory | BatteryType | EvChargerType | InverterType
+    target: ElectricalComponentCategory | BatteryType | EvChargerType | InverterType
     """The target category of the dispatch.
 
     Implicitly derived from the types.
     """
 
     @property
-    def category(self) -> ComponentCategory:
+    def category(self) -> ElectricalComponentCategory:
         """Get the category of the target.
 
         Returns:
             The category of the target.
         """
         match self.target:
-            case ComponentCategory():
+            case ElectricalComponentCategory():
                 return self.target
             case BatteryType():
-                return ComponentCategory.BATTERY
+                return ElectricalComponentCategory.BATTERY
             case EvChargerType():
-                return ComponentCategory.EV_CHARGER
+                return ElectricalComponentCategory.EV_CHARGER
             case InverterType():
-                return ComponentCategory.INVERTER
+                return ElectricalComponentCategory.INVERTER
 
     @property
     def type(self) -> BatteryType | EvChargerType | InverterType | None:
@@ -151,7 +154,11 @@ def __new__(cls, *ids: SupportsInt) -> Self:
 
 # Define the union of types that can be passed to TargetCategories constructor
 TargetCategoryInputType = (
-    TargetCategory | ComponentCategory | BatteryType | InverterType | EvChargerType
+    TargetCategory
+    | ElectricalComponentCategory
+    | BatteryType
+    | InverterType
+    | EvChargerType
 )
 """Type for the input to TargetCategories constructor."""
 
@@ -181,7 +188,8 @@ def __new__(cls, *categories_input: TargetCategoryInputType) -> Self:
             if isinstance(item, TargetCategory):
                 processed_elements.append(item)
             elif isinstance(
-                item, (ComponentCategory, BatteryType, InverterType, EvChargerType)
+                item,
+                (ElectricalComponentCategory, BatteryType, InverterType, EvChargerType),
             ):
                 # Wrap raw categories/types into TargetCategory instances
                 processed_elements.append(TargetCategory(target=item))
@@ -236,15 +244,15 @@ def _target_components_from_protobuf(
         case "component_categories":
             return TargetCategories(
                 *map(
-                    ComponentCategory.from_proto,
+                    ElectricalComponentCategory.from_proto,
                     pb_target.component_categories.categories,
                 )
             )
         case "component_categories_types":
             return TargetCategories(
                 *map(
                     lambda cat_and_type: _extract_category_type(cat_and_type)
-                    or ComponentCategory.from_proto(cat_and_type.category),
+                    or ElectricalComponentCategory.from_proto(cat_and_type.category),
                     pb_target.component_categories_types.categories,
                 )
             )
@@ -617,15 +625,6 @@ def to_protobuf(self) -> PBDispatch:
         )
 
 
-class Event(Enum):
-    """Enum representing the type of event that occurred during a dispatch operation."""
-
-    UNSPECIFIED = StreamMicrogridDispatchesResponse.Event.EVENT_UNSPECIFIED
-    CREATED = StreamMicrogridDispatchesResponse.Event.EVENT_CREATED
-    UPDATED = StreamMicrogridDispatchesResponse.Event.EVENT_UPDATED
-    DELETED = StreamMicrogridDispatchesResponse.Event.EVENT_DELETED
-
-
 @dataclass(kw_only=True, frozen=True)
 class DispatchEvent:
     """Represents an event that occurred during a dispatch operation."""