Add `metrics` package compatible with v1alpha8 by llucax · Pull Request #128 · frequenz-floss/frequenz-client-common-python

llucax · 2025-11-24T17:23:35Z

This PR introduces a new metrics package compatible with the v1alpha8 API version, along with a new proto package for common protobuf conversion utilities. The changes deprecate the old enum_proto module in favor of the new proto.enum_from_proto function and improve deprecation messages across the codebase to include full module paths.

Key changes:

Adds new frequenz.client.common.proto package with enum_from_proto, datetime_from_proto, and datetime_to_proto utilities
Introduces frequenz.client.common.metrics package with comprehensive metric types (Metric, MetricSample, AggregatedMetricValue, Bounds, etc.) compatible with v1alpha8
Deprecates frequenz.client.common.enum_proto module with improved deprecation messages that include full module paths
Updates all existing deprecation messages to include full module paths for better clarity

Signed-off-by: Leandro Lucarella <luca-frequenz@llucax.com>

We will start to expose conversion functions, for which we will always use a sub-module called `proto` for these conversion functions, so we we do the same with `enum_proto`. The old version is kept as deprecated. Signed-off-by: Leandro Lucarella <luca-frequenz@llucax.com>

Signed-off-by: Leandro Lucarella <luca-frequenz@llucax.com>

These functions are copied from `frequenz-client-base` and renamed to match the naming convention in this project. The functions in `frequenz-client-base` will be eventually deprecated. Signed-off-by: Leandro Lucarella <luca-frequenz@llucax.com>

Copilot

Pull request overview

This PR introduces a new metrics package compatible with the v1alpha8 API version, along with a new proto package for common protobuf conversion utilities. The changes deprecate the old enum_proto module in favor of the new proto.enum_from_proto function and improve deprecation messages across the codebase to include full module paths.

Key changes:

Adds new frequenz.client.common.proto package with enum_from_proto, datetime_from_proto, and datetime_to_proto utilities
Introduces frequenz.client.common.metrics package with comprehensive metric types (Metric, MetricSample, AggregatedMetricValue, Bounds, etc.) compatible with v1alpha8
Deprecates frequenz.client.common.enum_proto module with improved deprecation messages that include full module paths
Updates all existing deprecation messages to include full module paths for better clarity

Reviewed changes

Copilot reviewed 27 out of 27 changed files in this pull request and generated 3 comments.

Show a summary per file

File	Description
`pyproject.toml`	Adds protobuf and hypothesis dependencies with types-protobuf for mypy
`src/frequenz/client/common/proto/__init__.py`	New package exporting protobuf conversion utilities
`src/frequenz/client/common/proto/_enum.py`	New module with enum_from_proto function moved from enum_proto
`src/frequenz/client/common/proto/_timestamp.py`	New module with datetime conversion utilities
`src/frequenz/client/common/metrics/__init__.py`	New package exporting metric-related types
`src/frequenz/client/common/metrics/_metric.py`	Defines Metric enum with all supported metric types
`src/frequenz/client/common/metrics/_bounds.py`	Defines Bounds dataclass for metric constraints
`src/frequenz/client/common/metrics/_sample.py`	Defines MetricSample, AggregatedMetricValue, and related types
`src/frequenz/client/common/metrics/proto/__init__.py`	Exports protobuf conversion functions for metrics
`src/frequenz/client/common/metrics/proto/_bounds.py`	Implements bounds_from_proto conversion
`src/frequenz/client/common/metrics/proto/_sample.py`	Implements metric sample protobuf conversions with issue tracking
`src/frequenz/client/common/enum_proto.py`	Deprecates enum_from_proto with message pointing to new location
`src/frequenz/client/common/pagination/__init__.py`	Updates deprecation messages to include full module paths
`src/frequenz/client/common/microgrid/components/__init__.py`	Updates deprecation messages for from_proto methods
`src/frequenz/client/common/microgrid/electrical_components/__init__.py`	Updates deprecation messages for from_proto methods
`src/frequenz/client/common/metric/__init__.py`	Updates deprecation message for from_proto method
`tests/test_streaming.py`	Updates import to use new proto.enum_from_proto
`tests/test_enum_proto.py`	Simplifies tests to only check deprecation warnings
`tests/test_client_common.py`	Adds deprecation warning checks to existing tests
`tests/proto/test_enum.py`	New comprehensive tests for enum_from_proto
`tests/proto/test_datetime.py`	New tests for datetime conversion using hypothesis
`tests/metrics/test_bounds.py`	New tests for Bounds class
`tests/metrics/test_sample.py`	New tests for MetricSample and AggregatedMetricValue
`tests/metrics/proto/test_bounds.py`	New tests for bounds protobuf conversion
`tests/metrics/proto/test_sample.py`	New tests for metric sample protobuf conversion

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

src/frequenz/client/common/metrics/_metric.py

src/frequenz/client/common/metrics/_sample.py

llucax · 2025-11-25T15:27:05Z

Will update with some better test coverage.

llucax · 2025-11-25T15:36:30Z

Updated release notes to make them ready for a release.

cwasicki · 2025-11-25T15:05:29Z

src/frequenz/client/common/metrics/proto/_bounds.py

+
+
+def bounds_from_proto(message: bounds_pb2.Bounds) -> Bounds:  # noqa: DOC502
+    """Create a `Bounds` from a protobuf message.


... Bounds object from ... ?

cwasicki · 2025-11-25T15:05:47Z

src/frequenz/client/common/metrics/proto/_bounds.py

+    major_issues: list[str],
+    minor_issues: list[str],  # pylint: disable=unused-argument
+) -> Bounds | None:  # noqa: DOC502
+    """Create a `Bounds` from a protobuf message.


cwasicki · 2025-11-25T15:32:36Z

src/frequenz/client/common/metrics/_metric.py

+    """The alternating current electric potential difference between phase 3 and phase 1."""
+
+    AC_CURRENT = metrics_pb2.METRIC_AC_CURRENT
+    """The alternating current current."""


This reads weird. I suggest to replace all "alternating current" strings with AC. If you think this needs to be defined (tbh I don't) you could do so in the beginning of the class doc.

Will change, I thought these came from the API definition but it looks like it doesn't, not sure if it was in the previous versions or if it was generated by AI but I definitely didn't write that :D

I also replaced all "direct current" with "DC".

cwasicki · 2025-11-25T15:36:27Z

src/frequenz/client/common/metrics/_metric.py

+    """The metric is unspecified (this should not be used)."""
+
+    DC_VOLTAGE = metrics_pb2.METRIC_DC_VOLTAGE
+    """The direct current voltage."""


We should state the units for all of the metrics.

I would first fix it here:

Document the unit for every metric in the Metric enum frequenz-api-common#279

And then replicate in this repo. We probably need to create an issue in this repo too so we don't forget.

OK, I added the units in the issue, and also a few more I thought it was safe to assume, but there are still some I'm not sure about.

llucax · 2025-11-25T15:59:17Z

Related: Deprecate the conversion module in favor of frequenz.client.common. proto frequenz-client-base-python#190

llucax · 2025-11-25T16:07:58Z

Updated.

The old `metric` package (not the singular) is based on the old API v0.5. Since the package name didn't match the API naming scheme, we add a new package with the right name to keep backwards compatibility. These classes are based on the microgrid API client v0.18: https://github.com/frequenz-floss/frequenz-client-microgrid-python/tree/v0.18.0/src/frequenz/client/microgrid/metrics Only some minor changes were applied to make it closer to the API names, for example, `MetricSample.sampled_at` was renamed to `.sample_time` to match the new name. Also the `MetricConnection` and `MetricConnectionCategory` classes were added. Signed-off-by: Leandro Lucarella <luca-frequenz@llucax.com>

Signed-off-by: Leandro Lucarella <luca-frequenz@llucax.com>

llucax requested a review from a team as a code owner November 24, 2025 17:23

llucax requested review from Copilot and shsms November 24, 2025 17:23

Copilot started reviewing on behalf of llucax November 24, 2025 17:24 View session

llucax added 5 commits November 24, 2025 18:25

Clear release notes

86494bc

Signed-off-by: Leandro Lucarella <luca-frequenz@llucax.com>

Improve deprecation messages

4612de7

Signed-off-by: Leandro Lucarella <luca-frequenz@llucax.com>

Make sure calls to from_proto() for enums are deprecated

be9c829

Signed-off-by: Leandro Lucarella <luca-frequenz@llucax.com>

Copilot finished reviewing on behalf of llucax November 24, 2025 17:26

Copilot AI reviewed Nov 24, 2025

View reviewed changes

src/frequenz/client/common/metrics/_metric.py Outdated Show resolved Hide resolved

src/frequenz/client/common/metrics/_sample.py Outdated Show resolved Hide resolved

src/frequenz/client/common/metrics/_sample.py Outdated Show resolved Hide resolved

llucax force-pushed the metrics-alpha8 branch from 1a6ad99 to 77dfd1d Compare November 24, 2025 17:32

github-actions bot added the part:docs Affects the documentation label Nov 24, 2025

llucax requested a review from cwasicki November 24, 2025 17:32

llucax added this to the v0.3.7 milestone Nov 24, 2025

llucax self-assigned this Nov 24, 2025

llucax force-pushed the metrics-alpha8 branch from 4d37299 to d25a06e Compare November 25, 2025 14:40

llucax enabled auto-merge November 25, 2025 14:40

llucax force-pushed the metrics-alpha8 branch from d25a06e to 9882428 Compare November 25, 2025 15:27

llucax disabled auto-merge November 25, 2025 15:33

llucax force-pushed the metrics-alpha8 branch from 9882428 to 19f9523 Compare November 25, 2025 15:36

llucax enabled auto-merge November 25, 2025 15:36

cwasicki reviewed Nov 25, 2025

View reviewed changes

llucax mentioned this pull request Nov 25, 2025

Deprecate the conversion module in favor of frequenz.client.common. proto frequenz-floss/frequenz-client-base-python#190

Open

llucax force-pushed the metrics-alpha8 branch from 19f9523 to b54bd26 Compare November 25, 2025 16:07

llucax force-pushed the metrics-alpha8 branch from b54bd26 to a0f3349 Compare November 25, 2025 16:22

llucax added 2 commits November 25, 2025 17:33

Update release notes

9121ffc

Signed-off-by: Leandro Lucarella <luca-frequenz@llucax.com>

llucax force-pushed the metrics-alpha8 branch from a0f3349 to 9121ffc Compare November 25, 2025 16:35

cwasicki approved these changes Nov 25, 2025

View reviewed changes

llucax disabled auto-merge November 26, 2025 08:27

llucax added this pull request to the merge queue Nov 26, 2025

Merged via the queue into frequenz-floss:v0.x.x with commit 7bdac82 Nov 26, 2025
6 checks passed

llucax deleted the metrics-alpha8 branch November 26, 2025 08:29



		def bounds_from_proto(message: bounds_pb2.Bounds) -> Bounds: # noqa: DOC502
		"""Create a `Bounds` from a protobuf message.

Conversation

llucax commented Nov 24, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Uh oh!

Uh oh!

Uh oh!

llucax commented Nov 25, 2025

Uh oh!

llucax commented Nov 25, 2025

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

llucax Nov 25, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

llucax commented Nov 25, 2025

Uh oh!

llucax commented Nov 25, 2025

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

llucax commented Nov 24, 2025 •

edited

Loading

llucax Nov 25, 2025 •

edited

Loading