Skip to content

Commit 74933ff

Browse files
llucaxllucax
authored
Reorganise subpackages to mirror the proto/v1alpha8 layout (#193)
This is a followup on #181 and #182. It moves the per-domain types and conversions into their own modules so the source layout mirrors the established `proto/v1alpha8/` structure used by the other domains: - `Event`, `SensorId`, the microgrid IDs, `ElectricalComponentId`, the electrical component enums and `PaginationInfo` are split into their own (private) modules. - The `metrics` proto conversions move from `frequenz.client.common.metrics.proto` to `frequenz.client.common.metrics.proto.v1alpha8`, keeping the old import path as a deprecated shim. - The tests are reorganised to mirror the new source layout. It also adds explicit `v1alpha8` conversion functions for `PaginationInfo` (`pagination_info_from_proto`, `pagination_info_to_proto`) and deprecates the old `PaginationInfo.from_proto`/`to_proto`/`to_proto_v1alpha8` methods in favour of them. Part of #141.
2 parents e910dfd + 553c44b commit 74933ff

48 files changed

Lines changed: 1110 additions & 572 deletions

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

‎RELEASE_NOTES.md‎

Lines changed: 31 additions & 11 deletions
Original file line numberDiff line numberDiff line change
@@ -2,23 +2,43 @@
22

33
## Summary
44

5-
This release adds a new `grid` package for delivery area definitions and
6-
continues the move to explicit v1alpha8 protobuf conversion helpers for public
7-
enums.
5+
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.
86

97
## Upgrading
108

11-
- Converting v1alpha8-backed enums from/to protobuf directly is not supported anymore, you need to use explicit conversion functions in `frequenz.client.common.metrics.proto.v1alpha8`, `frequenz.client.common.streaming.proto.v1alpha8`, or `frequenz.client.common.microgrid.electrical_components.proto.v1alpha8`.
9+
- 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:
10+
- `frequenz.client.common.metrics.proto.v1alpha8`
11+
- `frequenz.client.common.streaming.proto.v1alpha8`
12+
- `frequenz.client.common.microgrid.electrical_components.proto.v1alpha8`
13+
- `frequenz.client.common.grid.proto.v1alpha8`
14+
15+
- 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:
16+
- `from frequenz.client.common.metrics.proto import bounds_from_proto` → `from frequenz.client.common.metrics.proto.v1alpha8 import bounds_from_proto`
17+
- `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`
18+
- `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`
19+
- `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`
20+
- `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`
21+
22+
- 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:
23+
- `PaginationInfo.from_proto(msg)` → `pagination_info_from_proto(msg)` (from `frequenz.client.common.pagination.proto.v1alpha8`)
24+
- `PaginationInfo.to_proto()` → `pagination_info_to_proto(info)` (from `frequenz.client.common.pagination.proto.v1alpha8`)
25+
- `PaginationInfo.to_proto_v1alpha8()` → `pagination_info_to_proto(info)` (from `frequenz.client.common.pagination.proto.v1alpha8`)
1226

1327
## New Features
1428

15-
- Added a new `frequenz.client.common.grid` package with `DeliveryArea` and
16-
`EnergyMarketCodeType` definitions for representing energy delivery areas.
17-
- Added v1alpha8 conversion functions for `DeliveryArea` and
18-
`EnergyMarketCodeType` in `frequenz.client.common.grid.proto.v1alpha8`,
19-
preserving unrecognized code types as raw `int` values.
20-
- Added v1alpha8 conversion functions for `MetricConnectionCategory`, `Event`, and electrical component enums.
21-
- Added a new `frequenz.client.common.test` package with a `enum_parity` module providing a convenient class to test for protobuf-Python enum parity.
29+
- Added a new `frequenz.client.common.grid` package with `DeliveryArea` and `EnergyMarketCodeType` definitions for representing energy delivery areas.
30+
- Added v1alpha8 conversion functions for `DeliveryArea` and `EnergyMarketCodeType` in `frequenz.client.common.grid.proto.v1alpha8`, preserving unrecognized code types as raw `int` values.
31+
- Added v1alpha8 conversion functions for `MetricConnectionCategory`, `Event`, and the electrical component enums.
32+
- Added v1alpha8 conversion functions for `PaginationInfo` in `frequenz.client.common.pagination.proto.v1alpha8` (`pagination_info_from_proto`, `pagination_info_to_proto`).
33+
- Added new enum values up to `frequenz-api-common` 0.8.4.
34+
- Added a new `frequenz.client.common.test` package with an `enum_parity` module providing a convenient class to test for protobuf-Python enum parity.
35+
36+
## Deprecations
37+
38+
- `frequenz.client.common.metrics.proto` is deprecated; use `frequenz.client.common.metrics.proto.v1alpha8` instead.
39+
- `frequenz.client.common.pagination.PaginationInfo.from_proto` is deprecated; use `frequenz.client.common.pagination.proto.v1alpha8.pagination_info_from_proto` instead.
40+
- `frequenz.client.common.pagination.PaginationInfo.to_proto` is deprecated; use `frequenz.client.common.pagination.proto.v1alpha8.pagination_info_to_proto` instead.
41+
- `frequenz.client.common.pagination.PaginationInfo.to_proto_v1alpha8` is deprecated; use `frequenz.client.common.pagination.proto.v1alpha8.pagination_info_to_proto` instead.
2242

2343
## Bug Fixes
2444

‎src/frequenz/client/common/metrics/proto/__init__.py‎

Lines changed: 106 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -1,15 +1,115 @@
11
# License: MIT
22
# Copyright © 2025 Frequenz Energy-as-a-Service GmbH
33

4-
"""Metrics objects to proto conversion functions."""
4+
"""Deprecated compatibility shim for metrics proto conversion functions."""
55

6-
from ._bounds import bounds_from_proto, bounds_from_proto_with_issues
7-
from ._sample import (
8-
aggregated_metric_sample_from_proto,
9-
metric_connection_from_proto_with_issues,
10-
metric_sample_from_proto_with_issues,
6+
from frequenz.api.common.v1alpha8.metrics import bounds_pb2, metrics_pb2
7+
from typing_extensions import deprecated
8+
9+
from .._bounds import Bounds
10+
from .._sample import AggregatedMetricValue, MetricConnection, MetricSample
11+
from . import v1alpha8
12+
13+
_DEPRECATED_MESSAGE = (
14+
"frequenz.client.common.metrics.proto is deprecated. "
15+
"Use frequenz.client.common.metrics.proto.v1alpha8 instead."
1116
)
1217

18+
19+
@deprecated(_DEPRECATED_MESSAGE)
20+
def bounds_from_proto(message: bounds_pb2.Bounds) -> Bounds:
21+
"""Create a `Bounds` object from a protobuf message.
22+
23+
Args:
24+
message: The protobuf message to convert.
25+
26+
Returns:
27+
The corresponding `Bounds` object.
28+
"""
29+
return v1alpha8.bounds_from_proto(message)
30+
31+
32+
@deprecated(_DEPRECATED_MESSAGE)
33+
def bounds_from_proto_with_issues(
34+
message: bounds_pb2.Bounds,
35+
*,
36+
major_issues: list[str],
37+
minor_issues: list[str],
38+
) -> Bounds | None:
39+
"""Create a `Bounds` object from a protobuf message, collecting issues.
40+
41+
Args:
42+
message: The protobuf message to convert.
43+
major_issues: A list to append major issues to.
44+
minor_issues: A list to append minor issues to.
45+
46+
Returns:
47+
The corresponding `Bounds` object.
48+
"""
49+
return v1alpha8.bounds_from_proto_with_issues(
50+
message, major_issues=major_issues, minor_issues=minor_issues
51+
)
52+
53+
54+
@deprecated(_DEPRECATED_MESSAGE)
55+
def aggregated_metric_sample_from_proto(
56+
message: metrics_pb2.AggregatedMetricValue,
57+
) -> AggregatedMetricValue:
58+
"""Convert a protobuf message to a `AggregatedMetricValue` object.
59+
60+
Args:
61+
message: The protobuf message to convert.
62+
63+
Returns:
64+
The resulting `AggregatedMetricValue` object.
65+
"""
66+
return v1alpha8.aggregated_metric_sample_from_proto(message)
67+
68+
69+
@deprecated(_DEPRECATED_MESSAGE)
70+
def metric_connection_from_proto_with_issues(
71+
message: metrics_pb2.MetricConnection,
72+
*,
73+
major_issues: list[str],
74+
minor_issues: list[str],
75+
) -> MetricConnection:
76+
"""Convert a protobuf message to a `MetricConnection` object.
77+
78+
Args:
79+
message: The protobuf message to convert.
80+
major_issues: A list to append major issues to.
81+
minor_issues: A list to append minor issues to.
82+
83+
Returns:
84+
The resulting `MetricConnection` object.
85+
"""
86+
return v1alpha8.metric_connection_from_proto_with_issues(
87+
message, major_issues=major_issues, minor_issues=minor_issues
88+
)
89+
90+
91+
@deprecated(_DEPRECATED_MESSAGE)
92+
def metric_sample_from_proto_with_issues(
93+
message: metrics_pb2.MetricSample,
94+
*,
95+
major_issues: list[str],
96+
minor_issues: list[str],
97+
) -> MetricSample:
98+
"""Convert a protobuf message to a `MetricSample` object.
99+
100+
Args:
101+
message: The protobuf message to convert.
102+
major_issues: A list to append major issues to.
103+
minor_issues: A list to append minor issues to.
104+
105+
Returns:
106+
The resulting `MetricSample` object.
107+
"""
108+
return v1alpha8.metric_sample_from_proto_with_issues(
109+
message, major_issues=major_issues, minor_issues=minor_issues
110+
)
111+
112+
13113
__all__ = [
14114
"aggregated_metric_sample_from_proto",
15115
"bounds_from_proto",

‎src/frequenz/client/common/metrics/proto/v1alpha8/__init__.py‎

Lines changed: 11 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -3,15 +3,26 @@
33

44
"""Conversion of metrics enums from/to protobuf v1alpha8."""
55

6+
from ._bounds import bounds_from_proto, bounds_from_proto_with_issues
67
from ._metric import metric_from_proto, metric_to_proto
78
from ._metric_connection_category import (
89
metric_connection_category_from_proto,
910
metric_connection_category_to_proto,
1011
)
12+
from ._sample import (
13+
aggregated_metric_sample_from_proto,
14+
metric_connection_from_proto_with_issues,
15+
metric_sample_from_proto_with_issues,
16+
)
1117

1218
__all__ = [
19+
"aggregated_metric_sample_from_proto",
20+
"bounds_from_proto",
21+
"bounds_from_proto_with_issues",
1322
"metric_connection_category_from_proto",
1423
"metric_connection_category_to_proto",
24+
"metric_connection_from_proto_with_issues",
1525
"metric_from_proto",
26+
"metric_sample_from_proto_with_issues",
1627
"metric_to_proto",
1728
]

src/frequenz/client/common/metrics/proto/_bounds.py renamed to src/frequenz/client/common/metrics/proto/v1alpha8/_bounds.py

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -5,7 +5,7 @@
55

66
from frequenz.api.common.v1alpha8.metrics import bounds_pb2
77

8-
from .._bounds import Bounds
8+
from ..._bounds import Bounds
99

1010

1111
def bounds_from_proto(message: bounds_pb2.Bounds) -> Bounds: # noqa: DOC502

src/frequenz/client/common/metrics/proto/_sample.py renamed to src/frequenz/client/common/metrics/proto/v1alpha8/_sample.py

Lines changed: 6 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -7,17 +7,18 @@
77

88
from frequenz.api.common.v1alpha8.metrics import bounds_pb2, metrics_pb2
99

10-
from ...proto import datetime_from_proto
11-
from .._bounds import Bounds
12-
from .._metric import Metric
13-
from .._sample import (
10+
from ....proto import datetime_from_proto
11+
from ..._bounds import Bounds
12+
from ..._metric import Metric
13+
from ..._sample import (
1414
AggregatedMetricValue,
1515
MetricConnection,
1616
MetricConnectionCategory,
1717
MetricSample,
1818
)
1919
from ._bounds import bounds_from_proto
20-
from .v1alpha8 import metric_connection_category_from_proto, metric_from_proto
20+
from ._metric import metric_from_proto
21+
from ._metric_connection_category import metric_connection_category_from_proto
2122

2223

2324
def aggregated_metric_sample_from_proto(

‎src/frequenz/client/common/microgrid/__init__.py‎

Lines changed: 5 additions & 12 deletions
Original file line numberDiff line numberDiff line change
@@ -3,16 +3,9 @@
33

44
"""Frequenz microgrid definition."""
55

6-
from typing import final
6+
from ._ids import EnterpriseId, MicrogridId
77

8-
from frequenz.core.id import BaseId
9-
10-
11-
@final
12-
class EnterpriseId(BaseId, str_prefix="EID"):
13-
"""A unique identifier for an enterprise account."""
14-
15-
16-
@final
17-
class MicrogridId(BaseId, str_prefix="MID"):
18-
"""A unique identifier for a microgrid."""
8+
__all__ = [
9+
"EnterpriseId",
10+
"MicrogridId",
11+
]

‎src/frequenz/client/common/microgrid/_ids.py‎

Lines changed: 18 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,18 @@
1+
# License: MIT
2+
# Copyright © 2023 Frequenz Energy-as-a-Service GmbH
3+
4+
"""Microgrid entity identifiers."""
5+
6+
from typing import final
7+
8+
from frequenz.core.id import BaseId
9+
10+
11+
@final
12+
class EnterpriseId(BaseId, str_prefix="EID"):
13+
"""A unique identifier for an enterprise account."""
14+
15+
16+
@final
17+
class MicrogridId(BaseId, str_prefix="MID"):
18+
"""A unique identifier for a microgrid."""

0 commit comments

Comments
 (0)