Merge tag 'v0.3.8' into 'v0.x.x'

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.
+<!-- Here goes a general summary of what this release is about -->
 
 ## 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.
+<!-- Here goes the main new features and examples or instructions on how to use them -->
 
 ## Bug Fixes
 

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.

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."""

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)

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)"

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
+        )

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