diff --git a/RELEASE_NOTES.md b/RELEASE_NOTES.md index 397301af..993c76c4 100644 --- a/RELEASE_NOTES.md +++ b/RELEASE_NOTES.md @@ -2,43 +2,15 @@ ## Summary -This release adds a new `grid` package for delivery area definitions, introduces explicit v1alpha8 protobuf conversion helpers across public modules (`metrics`, `streaming`, `electrical_components`, `pagination`, `grid`), and reorganises a number of subpackages to mirror the established `proto/v1alpha8/` layout. Several legacy conversion entry points have been deprecated in favour of the new free functions. + ## Upgrading -- v1alpha8-backed enums (`Metric`, `MetricConnectionCategory`, `Event`, electrical component enums, `EnergyMarketCodeType`) are now plain `int`s. Converting them from/to protobuf directly is no longer supported; use the explicit conversion functions in: - - `frequenz.client.common.metrics.proto.v1alpha8` - - `frequenz.client.common.streaming.proto.v1alpha8` - - `frequenz.client.common.microgrid.electrical_components.proto.v1alpha8` - - `frequenz.client.common.grid.proto.v1alpha8` - -- The metrics proto helpers have moved from `frequenz.client.common.metrics.proto` to `frequenz.client.common.metrics.proto.v1alpha8`. The old import path is kept as a deprecated shim (importing from it now emits a deprecation warning) and will be removed in a future release. Update your imports as follows: - - `from frequenz.client.common.metrics.proto import bounds_from_proto` → `from frequenz.client.common.metrics.proto.v1alpha8 import bounds_from_proto` - - `from frequenz.client.common.metrics.proto import bounds_from_proto_with_issues` → `from frequenz.client.common.metrics.proto.v1alpha8 import bounds_from_proto_with_issues` - - `from frequenz.client.common.metrics.proto import aggregated_metric_sample_from_proto` → `from frequenz.client.common.metrics.proto.v1alpha8 import aggregated_metric_sample_from_proto` - - `from frequenz.client.common.metrics.proto import metric_connection_from_proto_with_issues` → `from frequenz.client.common.metrics.proto.v1alpha8 import metric_connection_from_proto_with_issues` - - `from frequenz.client.common.metrics.proto import metric_sample_from_proto_with_issues` → `from frequenz.client.common.metrics.proto.v1alpha8 import metric_sample_from_proto_with_issues` - -- The `PaginationInfo` conversion methods are deprecated in favour of new free functions in `frequenz.client.common.pagination.proto.v1alpha8` (calling the methods now emits a deprecation warning). Migrate as follows: - - `PaginationInfo.from_proto(msg)` → `pagination_info_from_proto(msg)` (from `frequenz.client.common.pagination.proto.v1alpha8`) - - `PaginationInfo.to_proto()` → `pagination_info_to_proto(info)` (from `frequenz.client.common.pagination.proto.v1alpha8`) - - `PaginationInfo.to_proto_v1alpha8()` → `pagination_info_to_proto(info)` (from `frequenz.client.common.pagination.proto.v1alpha8`) +* Passing enum values directly to build protobuf messages is not longer supported, you need to call the conversion functions `xxx_(from|to)_proto_v1alpha8()` explicitly. ## New Features -- Added a new `frequenz.client.common.grid` package with `DeliveryArea` and `EnergyMarketCodeType` definitions for representing energy delivery areas. -- Added v1alpha8 conversion functions for `DeliveryArea` and `EnergyMarketCodeType` in `frequenz.client.common.grid.proto.v1alpha8`, preserving unrecognized code types as raw `int` values. -- Added v1alpha8 conversion functions for `MetricConnectionCategory`, `Event`, and the electrical component enums. -- Added v1alpha8 conversion functions for `PaginationInfo` in `frequenz.client.common.pagination.proto.v1alpha8` (`pagination_info_from_proto`, `pagination_info_to_proto`). -- Added new enum values up to `frequenz-api-common` 0.8.4. -- Added a new `frequenz.client.common.test` package with an `enum_parity` module providing a convenient class to test for protobuf-Python enum parity. - -## Deprecations - -- `frequenz.client.common.metrics.proto` is deprecated; use `frequenz.client.common.metrics.proto.v1alpha8` instead. -- `frequenz.client.common.pagination.PaginationInfo.from_proto` is deprecated; use `frequenz.client.common.pagination.proto.v1alpha8.pagination_info_from_proto` instead. -- `frequenz.client.common.pagination.PaginationInfo.to_proto` is deprecated; use `frequenz.client.common.pagination.proto.v1alpha8.pagination_info_to_proto` instead. -- `frequenz.client.common.pagination.PaginationInfo.to_proto_v1alpha8` is deprecated; use `frequenz.client.common.pagination.proto.v1alpha8.pagination_info_to_proto` instead. + ## Bug Fixes diff --git a/src/frequenz/client/common/metric/__init__.py b/src/frequenz/client/common/metric/__init__.py index 8afef806..b893b3d0 100644 --- a/src/frequenz/client/common/metric/__init__.py +++ b/src/frequenz/client/common/metric/__init__.py @@ -13,6 +13,10 @@ # pylint: enable=no-name-in-module +@deprecated( + "frequenz.client.common.metric.Metric is deprecated. " + "Use frequenz.client.common.metrics.Metric instead." +) @enum.unique class Metric(enum.Enum): """List of supported metrics. diff --git a/src/frequenz/client/common/microgrid/components/__init__.py b/src/frequenz/client/common/microgrid/components/__init__.py index a9ace076..e390ae13 100644 --- a/src/frequenz/client/common/microgrid/components/__init__.py +++ b/src/frequenz/client/common/microgrid/components/__init__.py @@ -24,11 +24,21 @@ # pylint: enable=no-name-in-module +@deprecated( + "frequenz.client.common.microgrid.components.ComponentId is deprecated. " + "Use frequenz.client.common.microgrid.electrical_components." + "ElectricalComponentId instead." +) @final class ComponentId(BaseId, str_prefix="CID"): """A unique identifier for a microgrid component.""" +@deprecated( + "frequenz.client.common.microgrid.components.ComponentCategory is deprecated. " + "Use frequenz.client.common.microgrid.electrical_components." + "ElectricalComponentCategory instead." +) @enum.unique class ComponentCategory(enum.Enum): """Possible types of microgrid component.""" @@ -133,6 +143,11 @@ def to_proto(self) -> PBComponentCategory.ValueType: return self.value +@deprecated( + "frequenz.client.common.microgrid.components.ComponentStateCode is deprecated. " + "Use frequenz.client.common.microgrid.electrical_components." + "ElectricalComponentStateCode instead." +) @enum.unique class ComponentStateCode(enum.Enum): """All possible states of a microgrid component.""" @@ -243,6 +258,11 @@ def to_proto(self) -> PBComponentStateCode.ValueType: return self.value +@deprecated( + "frequenz.client.common.microgrid.components.ComponentErrorCode is deprecated. " + "Use frequenz.client.common.microgrid.electrical_components." + "ElectricalComponentDiagnosticCode instead." +) @enum.unique class ComponentErrorCode(enum.Enum): """All possible errors that can occur across all microgrid component categories.""" diff --git a/src/frequenz/client/common/pagination/__init__.py b/src/frequenz/client/common/pagination/__init__.py index 3209cbaa..4e2af74c 100644 --- a/src/frequenz/client/common/pagination/__init__.py +++ b/src/frequenz/client/common/pagination/__init__.py @@ -26,7 +26,8 @@ @deprecated( "frequenz.client.common.pagination.Params is deprecated. " - "Use frequenz.api.common.v1.pagination.pagination_params_pb2.PaginationParams " + "Use frequenz.api.common.v1alpha8.pagination.pagination_params_pb2." + "PaginationParams " "from the API directly instead.", ) @dataclass(frozen=True, kw_only=True) diff --git a/tests/microgrid/test_ids.py b/tests/microgrid/test_ids.py index 482bd2bb..6ffb8e3d 100644 --- a/tests/microgrid/test_ids.py +++ b/tests/microgrid/test_ids.py @@ -8,6 +8,7 @@ from frequenz.client.common.microgrid import EnterpriseId, MicrogridId from frequenz.client.common.microgrid.components import ComponentId +from frequenz.client.common.microgrid.electrical_components import ElectricalComponentId from frequenz.client.common.microgrid.sensors import SensorId @@ -16,7 +17,7 @@ [ (EnterpriseId, "EID"), (MicrogridId, "MID"), - (ComponentId, "CID"), + (ElectricalComponentId, "CID"), (SensorId, "SID"), ], ) @@ -26,3 +27,12 @@ def test_string_representation(id_class: type[BaseId], prefix: str) -> None: assert str(_id) == f"{prefix}123" assert repr(_id) == f"{id_class.__name__}(123)" + + +def test_component_id_deprecated() -> None: + """Test that the deprecated ComponentId emits a warning and still works.""" + with pytest.deprecated_call(): + _id = ComponentId(123) + + assert str(_id) == "CID123" + assert repr(_id) == "ComponentId(123)" diff --git a/tests/test_client_common.py b/tests/test_client_common.py index cd4ccf0f..d402847f 100644 --- a/tests/test_client_common.py +++ b/tests/test_client_common.py @@ -31,3 +31,30 @@ def test_component_error_code() -> None: for error_code in ComponentErrorCode: with pytest.deprecated_call(): assert ComponentErrorCode.from_proto(error_code.to_proto()) == error_code + + +def test_component_category_class_deprecated() -> None: + """Test that using the deprecated ComponentCategory enum warns.""" + with pytest.deprecated_call(): + assert ( + ComponentCategory(ComponentCategory.UNSPECIFIED.value) + is ComponentCategory.UNSPECIFIED + ) + + +def test_component_state_code_class_deprecated() -> None: + """Test that using the deprecated ComponentStateCode enum warns.""" + with pytest.deprecated_call(): + assert ( + ComponentStateCode(ComponentStateCode.UNSPECIFIED.value) + is ComponentStateCode.UNSPECIFIED + ) + + +def test_component_error_code_class_deprecated() -> None: + """Test that using the deprecated ComponentErrorCode enum warns.""" + with pytest.deprecated_call(): + assert ( + ComponentErrorCode(ComponentErrorCode.UNSPECIFIED.value) + is ComponentErrorCode.UNSPECIFIED + ) diff --git a/tests/test_metric_deprecated.py b/tests/test_metric_deprecated.py new file mode 100644 index 00000000..7ae326de --- /dev/null +++ b/tests/test_metric_deprecated.py @@ -0,0 +1,14 @@ +# License: MIT +# Copyright © 2024 Frequenz Energy-as-a-Service GmbH + +"""Tests for the deprecated metric module.""" + +import pytest + +from frequenz.client.common.metric import Metric + + +def test_metric_class_deprecated() -> None: + """Test that using the deprecated Metric enum emits a deprecation warning.""" + with pytest.deprecated_call(): + assert Metric(Metric.UNSPECIFIED.value) is Metric.UNSPECIFIED