From fb3ff4c302270b6d7baf0a66761083d21fc14d5e Mon Sep 17 00:00:00 2001 From: "Mathias L. Baumann" Date: Tue, 12 Aug 2025 12:16:23 +0200 Subject: [PATCH 1/2] Apply changes from v0.3.x to v1alpha8 module * replacing and deprecating from_proto * using enum.Enum in favor of Enum * using enum.unique * addition of base id types * Signed-off-by: Mathias L. Baumann --- .../client/common/v1alpha8/metric/__init__.py | 7 +++-- .../common/v1alpha8/microgrid/__init__.py | 16 +++++++++- .../electrical_components/__init__.py | 22 +++++++++++--- .../common/v1alpha8/microgrid/sensors.py | 13 ++++++++ tests/microgrid/test_ids_alpha8.py | 30 +++++++++++++++++++ 5 files changed, 81 insertions(+), 7 deletions(-) create mode 100644 src/frequenz/client/common/v1alpha8/microgrid/sensors.py create mode 100644 tests/microgrid/test_ids_alpha8.py diff --git a/src/frequenz/client/common/v1alpha8/metric/__init__.py b/src/frequenz/client/common/v1alpha8/metric/__init__.py index 7634473..7f124e1 100644 --- a/src/frequenz/client/common/v1alpha8/metric/__init__.py +++ b/src/frequenz/client/common/v1alpha8/metric/__init__.py @@ -3,13 +3,15 @@ """Module to define the metrics used with the common client.""" -from enum import Enum +import enum from typing import Self from frequenz.api.common.v1alpha8.metrics.metrics_pb2 import Metric as PBMetric +from typing_extensions import deprecated -class Metric(Enum): +@enum.unique +class Metric(enum.Enum): """List of supported metrics. AC energy metrics information: @@ -137,6 +139,7 @@ class Metric(Enum): SENSOR_IRRADIANCE = PBMetric.METRIC_SENSOR_IRRADIANCE @classmethod + @deprecated("Use `frequenz.client.common.enum_proto.enum_from_proto` instead.") def from_proto(cls, metric: PBMetric.ValueType) -> Self: """Convert a protobuf Metric value to Metric enum. diff --git a/src/frequenz/client/common/v1alpha8/microgrid/__init__.py b/src/frequenz/client/common/v1alpha8/microgrid/__init__.py index d003a01..0787943 100644 --- a/src/frequenz/client/common/v1alpha8/microgrid/__init__.py +++ b/src/frequenz/client/common/v1alpha8/microgrid/__init__.py @@ -1,4 +1,18 @@ # License: MIT -# Copyright © 2025 Frequenz Energy-as-a-Service GmbH +# Copyright © 2023 Frequenz Energy-as-a-Service GmbH """Frequenz microgrid definition.""" + +from typing import final + +from frequenz.core.id import BaseId + + +@final +class EnterpriseId(BaseId, str_prefix="EID"): + """A unique identifier for an enterprise account.""" + + +@final +class MicrogridId(BaseId, str_prefix="MID"): + """A unique identifier for a microgrid.""" diff --git a/src/frequenz/client/common/v1alpha8/microgrid/electrical_components/__init__.py b/src/frequenz/client/common/v1alpha8/microgrid/electrical_components/__init__.py index 3d667d5..4efed51 100644 --- a/src/frequenz/client/common/v1alpha8/microgrid/electrical_components/__init__.py +++ b/src/frequenz/client/common/v1alpha8/microgrid/electrical_components/__init__.py @@ -4,7 +4,8 @@ """Defines the electrical components that can be used in a microgrid.""" from __future__ import annotations -from enum import Enum +import enum +from typing import final # pylint: disable=no-name-in-module from frequenz.api.common.v1alpha8.microgrid.electrical_components.electrical_components_pb2 import ( @@ -16,11 +17,19 @@ from frequenz.api.common.v1alpha8.microgrid.electrical_components.electrical_components_pb2 import ( ElectricalComponentStateCode as PBElectricalComponentStateCode, ) +from frequenz.core.id import BaseId +from typing_extensions import deprecated # pylint: enable=no-name-in-module -class ElectricalComponentCategory(Enum): +@final +class ElectricalComponentId(BaseId, str_prefix="CID"): + """A unique identifier for a microgrid electrical component.""" + + +@enum.unique +class ElectricalComponentCategory(enum.Enum): """Possible types of microgrid electrical component.""" UNSPECIFIED = ( @@ -80,6 +89,7 @@ class ElectricalComponentCategory(Enum): """A heating, ventilation, and air conditioning (HVAC) system.""" @classmethod + @deprecated("Use `frequenz.client.common.enum_proto.enum_from_proto` instead.") def from_proto( cls, component_category: PBElectricalComponentCategory.ValueType ) -> ElectricalComponentCategory: @@ -104,7 +114,8 @@ def to_proto(self) -> PBElectricalComponentCategory.ValueType: return self.value -class ElectricalComponentStateCode(Enum): +@enum.unique +class ElectricalComponentStateCode(enum.Enum): """All possible states of a microgrid electrical component.""" UNSPECIFIED = ( @@ -206,6 +217,7 @@ class ElectricalComponentStateCode(Enum): """The precharger circuit is closed, allowing full current to flow to the main circuit.""" @classmethod + @deprecated("Use `frequenz.client.common.enum_proto.enum_from_proto` instead.") def from_proto( cls, component_state: PBElectricalComponentStateCode.ValueType ) -> ElectricalComponentStateCode: @@ -230,7 +242,8 @@ def to_proto(self) -> PBElectricalComponentStateCode.ValueType: return self.value -class ElectricalComponentDiagnosticCode(Enum): +@enum.unique +class ElectricalComponentDiagnosticCode(enum.Enum): """All diagnostics that can occur across electrical component categories.""" UNSPECIFIED = ( @@ -419,6 +432,7 @@ class ElectricalComponentDiagnosticCode(Enum): times.""" @classmethod + @deprecated("Use `frequenz.client.common.enum_proto.enum_from_proto` instead.") def from_proto( cls, component_error_code: PBElectricalComponentDiagnosticCode.ValueType ) -> ElectricalComponentDiagnosticCode: diff --git a/src/frequenz/client/common/v1alpha8/microgrid/sensors.py b/src/frequenz/client/common/v1alpha8/microgrid/sensors.py new file mode 100644 index 0000000..0fca6a2 --- /dev/null +++ b/src/frequenz/client/common/v1alpha8/microgrid/sensors.py @@ -0,0 +1,13 @@ +# License: MIT +# Copyright © 2025 Frequenz Energy-as-a-Service GmbH + +"""Microgrid sensors.""" + +from typing import final + +from frequenz.core.id import BaseId + + +@final +class SensorId(BaseId, str_prefix="SID"): + """A unique identifier for a microgrid sensor.""" diff --git a/tests/microgrid/test_ids_alpha8.py b/tests/microgrid/test_ids_alpha8.py new file mode 100644 index 0000000..84b88f6 --- /dev/null +++ b/tests/microgrid/test_ids_alpha8.py @@ -0,0 +1,30 @@ +# License: MIT +# Copyright © 2025 Frequenz Energy-as-a-Service GmbH + +"""Tests for microgrid-related IDs.""" + +import pytest +from frequenz.core.id import BaseId + +from frequenz.client.common.v1alpha8.microgrid import EnterpriseId, MicrogridId +from frequenz.client.common.v1alpha8.microgrid.electrical_components import ( + ElectricalComponentId, +) +from frequenz.client.common.v1alpha8.microgrid.sensors import SensorId + + +@pytest.mark.parametrize( + "id_class, prefix", + [ + (EnterpriseId, "EID"), + (MicrogridId, "MID"), + (ElectricalComponentId, "CID"), + (SensorId, "SID"), + ], +) +def test_string_representation(id_class: type[BaseId], prefix: str) -> None: + """Test string representation of IDs.""" + _id = id_class(123) + + assert str(_id) == f"{prefix}123" + assert repr(_id) == f"{id_class.__name__}(123)" From c5024999a603b4364342eb962603088d1e6661ad Mon Sep 17 00:00:00 2001 From: "Mathias L. Baumann" Date: Tue, 12 Aug 2025 12:44:54 +0200 Subject: [PATCH 2/2] Add streaming.Event bindings Signed-off-by: Mathias L. Baumann --- RELEASE_NOTES.md | 2 +- .../common/v1alpha8/microgrid/__init__.py | 2 +- .../common/v1alpha8/streaming/__init__.py | 26 +++++++++++++++++++ tests/test_streaming.py | 13 ++++++++++ 4 files changed, 41 insertions(+), 2 deletions(-) create mode 100644 src/frequenz/client/common/v1alpha8/streaming/__init__.py create mode 100644 tests/test_streaming.py diff --git a/RELEASE_NOTES.md b/RELEASE_NOTES.md index a057503..c1e6f4a 100644 --- a/RELEASE_NOTES.md +++ b/RELEASE_NOTES.md @@ -11,7 +11,7 @@ This release introduces the `v1alpha8` module to support a new API version. ## New Features - Provide access to new API using new `v1alpha8` module. - +- Mapping for the new `Event` message has been added. ## Bug Fixes diff --git a/src/frequenz/client/common/v1alpha8/microgrid/__init__.py b/src/frequenz/client/common/v1alpha8/microgrid/__init__.py index 0787943..1a47d5d 100644 --- a/src/frequenz/client/common/v1alpha8/microgrid/__init__.py +++ b/src/frequenz/client/common/v1alpha8/microgrid/__init__.py @@ -1,5 +1,5 @@ # License: MIT -# Copyright © 2023 Frequenz Energy-as-a-Service GmbH +# Copyright © 2025 Frequenz Energy-as-a-Service GmbH """Frequenz microgrid definition.""" diff --git a/src/frequenz/client/common/v1alpha8/streaming/__init__.py b/src/frequenz/client/common/v1alpha8/streaming/__init__.py new file mode 100644 index 0000000..263697d --- /dev/null +++ b/src/frequenz/client/common/v1alpha8/streaming/__init__.py @@ -0,0 +1,26 @@ +# License: MIT +# Copyright © 2025 Frequenz Energy-as-a-Service GmbH + +"""Type wrappers for the generated protobuf messages.""" + + +from enum import Enum + +# pylint: disable-next=no-name-in-module +from frequenz.api.common.v1alpha8.streaming import event_pb2 as PBEvent + + +class Event(Enum): + """Enum representing the type of streaming event.""" + + EVENT_UNSPECIFIED = PBEvent.EVENT_UNSPECIFIED + """Unspecified event type.""" + + EVENT_CREATED = PBEvent.EVENT_CREATED + """Event when a new resource is created.""" + + EVENT_UPDATED = PBEvent.EVENT_UPDATED + """Event when an existing resource is updated.""" + + EVENT_DELETED = PBEvent.EVENT_DELETED + """Event when a resource is deleted.""" diff --git a/tests/test_streaming.py b/tests/test_streaming.py new file mode 100644 index 0000000..4075772 --- /dev/null +++ b/tests/test_streaming.py @@ -0,0 +1,13 @@ +# License: MIT +# Copyright © 2025 Frequenz Energy-as-a-Service GmbH + +"""Tests for the frequenz.client.common.v1alpha8.streaming package.""" + +from frequenz.client.common.enum_proto import enum_from_proto +from frequenz.client.common.v1alpha8.streaming import Event + + +def test_event_enum() -> None: + """Test the Event enum.""" + for event in Event: + assert enum_from_proto(event.value, Event) == event