diff --git a/RELEASE_NOTES.md b/RELEASE_NOTES.md index c1e6f4a..72d8090 100644 --- a/RELEASE_NOTES.md +++ b/RELEASE_NOTES.md @@ -2,7 +2,6 @@ ## Summary -This release introduces the `v1alpha8` module to support a new API version. ## Upgrading @@ -10,8 +9,8 @@ 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. +- Add new common API enums for `ElectricalComponent` (previously `Components`). ## Bug Fixes diff --git a/pyproject.toml b/pyproject.toml index 3696407..fba2428 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -27,7 +27,7 @@ classifiers = [ requires-python = ">= 3.11, < 4" dependencies = [ "typing-extensions >= 4.13.0, < 5", - "frequenz-api-common >= 0.8.0, < 9", + "frequenz-api-common >= 0.8.0, < 1", "frequenz-core >= 1.0.2, < 2", ] dynamic = ["version"] @@ -40,7 +40,7 @@ email = "floss@frequenz.com" dev-flake8 = [ "flake8 == 7.3.0", "flake8-docstrings == 1.7.0", - "flake8-pyproject == 1.2.3", # For reading the flake8 config from pyproject.toml + "flake8-pyproject == 1.2.3", # For reading the flake8 config from pyproject.toml "pydoclint == 0.6.6", "pydocstyle == 6.3.0", ] diff --git a/src/frequenz/client/common/v1alpha8/microgrid/electrical_components/__init__.py b/src/frequenz/client/common/microgrid/electrical_components/__init__.py similarity index 100% rename from src/frequenz/client/common/v1alpha8/microgrid/electrical_components/__init__.py rename to src/frequenz/client/common/microgrid/electrical_components/__init__.py diff --git a/src/frequenz/client/common/v1alpha8/streaming/__init__.py b/src/frequenz/client/common/streaming/__init__.py similarity index 100% rename from src/frequenz/client/common/v1alpha8/streaming/__init__.py rename to src/frequenz/client/common/streaming/__init__.py diff --git a/src/frequenz/client/common/v1alpha8/__init__.py b/src/frequenz/client/common/v1alpha8/__init__.py deleted file mode 100644 index adc4de1..0000000 --- a/src/frequenz/client/common/v1alpha8/__init__.py +++ /dev/null @@ -1,4 +0,0 @@ -# License: MIT -# Copyright © 2025 Frequenz Energy-as-a-Service GmbH - -"""Types introduced or modified in the v1alpha8 version of the common api.""" diff --git a/src/frequenz/client/common/v1alpha8/metric/__init__.py b/src/frequenz/client/common/v1alpha8/metric/__init__.py deleted file mode 100644 index 7f124e1..0000000 --- a/src/frequenz/client/common/v1alpha8/metric/__init__.py +++ /dev/null @@ -1,162 +0,0 @@ -# License: MIT -# Copyright © 2024 Frequenz Energy-as-a-Service GmbH - -"""Module to define the metrics used with the common client.""" - -import enum -from typing import Self - -from frequenz.api.common.v1alpha8.metrics.metrics_pb2 import Metric as PBMetric -from typing_extensions import deprecated - - -@enum.unique -class Metric(enum.Enum): - """List of supported metrics. - - AC energy metrics information: - * This energy metric is reported directly from the component, and not a - result of aggregations in our systems. If a component does not have this - metric, this field cannot be populated. - * Components that provide energy metrics reset this metric from time to - time. This behaviour is specific to each component model. E.g., some - components reset it on UTC 00:00:00. - * This energy metric does not specify the timestamp since when the energy - was being accumulated, and therefore can be inconsistent. - """ - - # Default value - UNSPECIFIED = PBMetric.METRIC_UNSPECIFIED - - # DC electricity metrics - DC_VOLTAGE = PBMetric.METRIC_DC_VOLTAGE - DC_CURRENT = PBMetric.METRIC_DC_CURRENT - DC_POWER = PBMetric.METRIC_DC_POWER - - # General AC electricity metrics - AC_FREQUENCY = PBMetric.METRIC_AC_FREQUENCY - AC_VOLTAGE = PBMetric.METRIC_AC_VOLTAGE - AC_VOLTAGE_PHASE_1_N = PBMetric.METRIC_AC_VOLTAGE_PHASE_1_N - AC_VOLTAGE_PHASE_2_N = PBMetric.METRIC_AC_VOLTAGE_PHASE_2_N - AC_VOLTAGE_PHASE_3_N = PBMetric.METRIC_AC_VOLTAGE_PHASE_3_N - AC_VOLTAGE_PHASE_1_PHASE_2 = PBMetric.METRIC_AC_VOLTAGE_PHASE_1_PHASE_2 - AC_VOLTAGE_PHASE_2_PHASE_3 = PBMetric.METRIC_AC_VOLTAGE_PHASE_2_PHASE_3 - AC_VOLTAGE_PHASE_3_PHASE_1 = PBMetric.METRIC_AC_VOLTAGE_PHASE_3_PHASE_1 - AC_CURRENT = PBMetric.METRIC_AC_CURRENT - AC_CURRENT_PHASE_1 = PBMetric.METRIC_AC_CURRENT_PHASE_1 - AC_CURRENT_PHASE_2 = PBMetric.METRIC_AC_CURRENT_PHASE_2 - AC_CURRENT_PHASE_3 = PBMetric.METRIC_AC_CURRENT_PHASE_3 - - # AC power metrics - AC_POWER_APPARENT = PBMetric.METRIC_AC_POWER_APPARENT - AC_POWER_APPARENT_PHASE_1 = PBMetric.METRIC_AC_POWER_APPARENT_PHASE_1 - AC_POWER_APPARENT_PHASE_2 = PBMetric.METRIC_AC_POWER_APPARENT_PHASE_2 - AC_POWER_APPARENT_PHASE_3 = PBMetric.METRIC_AC_POWER_APPARENT_PHASE_3 - AC_POWER_ACTIVE = PBMetric.METRIC_AC_POWER_ACTIVE - AC_POWER_ACTIVE_PHASE_1 = PBMetric.METRIC_AC_POWER_ACTIVE_PHASE_1 - AC_POWER_ACTIVE_PHASE_2 = PBMetric.METRIC_AC_POWER_ACTIVE_PHASE_2 - AC_POWER_ACTIVE_PHASE_3 = PBMetric.METRIC_AC_POWER_ACTIVE_PHASE_3 - AC_POWER_REACTIVE = PBMetric.METRIC_AC_POWER_REACTIVE - AC_POWER_REACTIVE_PHASE_1 = PBMetric.METRIC_AC_POWER_REACTIVE_PHASE_1 - AC_POWER_REACTIVE_PHASE_2 = PBMetric.METRIC_AC_POWER_REACTIVE_PHASE_2 - AC_POWER_REACTIVE_PHASE_3 = PBMetric.METRIC_AC_POWER_REACTIVE_PHASE_3 - - # AC power factor - AC_POWER_FACTOR = PBMetric.METRIC_AC_POWER_FACTOR - AC_POWER_FACTOR_PHASE_1 = PBMetric.METRIC_AC_POWER_FACTOR_PHASE_1 - AC_POWER_FACTOR_PHASE_2 = PBMetric.METRIC_AC_POWER_FACTOR_PHASE_2 - AC_POWER_FACTOR_PHASE_3 = PBMetric.METRIC_AC_POWER_FACTOR_PHASE_3 - - # AC energy metrics - Please be careful when using and check Enum docs - AC_ENERGY_APPARENT = PBMetric.METRIC_AC_ENERGY_APPARENT - AC_ENERGY_APPARENT_PHASE_1 = PBMetric.METRIC_AC_ENERGY_APPARENT_PHASE_1 - AC_ENERGY_APPARENT_PHASE_2 = PBMetric.METRIC_AC_ENERGY_APPARENT_PHASE_2 - AC_ENERGY_APPARENT_PHASE_3 = PBMetric.METRIC_AC_ENERGY_APPARENT_PHASE_3 - AC_ENERGY_ACTIVE = PBMetric.METRIC_AC_ENERGY_ACTIVE - AC_ENERGY_ACTIVE_PHASE_1 = PBMetric.METRIC_AC_ENERGY_ACTIVE_PHASE_1 - AC_ENERGY_ACTIVE_PHASE_2 = PBMetric.METRIC_AC_ENERGY_ACTIVE_PHASE_2 - AC_ENERGY_ACTIVE_PHASE_3 = PBMetric.METRIC_AC_ENERGY_ACTIVE_PHASE_3 - AC_ENERGY_ACTIVE_CONSUMED = PBMetric.METRIC_AC_ENERGY_ACTIVE_CONSUMED - AC_ENERGY_ACTIVE_CONSUMED_PHASE_1 = ( - PBMetric.METRIC_AC_ENERGY_ACTIVE_CONSUMED_PHASE_1 - ) - AC_ENERGY_ACTIVE_CONSUMED_PHASE_2 = ( - PBMetric.METRIC_AC_ENERGY_ACTIVE_CONSUMED_PHASE_2 - ) - AC_ENERGY_ACTIVE_CONSUMED_PHASE_3 = ( - PBMetric.METRIC_AC_ENERGY_ACTIVE_CONSUMED_PHASE_3 - ) - AC_ENERGY_ACTIVE_DELIVERED = PBMetric.METRIC_AC_ENERGY_ACTIVE_DELIVERED - AC_ENERGY_ACTIVE_DELIVERED_PHASE_1 = ( - PBMetric.METRIC_AC_ENERGY_ACTIVE_DELIVERED_PHASE_1 - ) - AC_ENERGY_ACTIVE_DELIVERED_PHASE_2 = ( - PBMetric.METRIC_AC_ENERGY_ACTIVE_DELIVERED_PHASE_2 - ) - AC_ENERGY_ACTIVE_DELIVERED_PHASE_3 = ( - PBMetric.METRIC_AC_ENERGY_ACTIVE_DELIVERED_PHASE_3 - ) - AC_ENERGY_REACTIVE = PBMetric.METRIC_AC_ENERGY_REACTIVE - AC_ENERGY_REACTIVE_PHASE_1 = PBMetric.METRIC_AC_ENERGY_REACTIVE_PHASE_1 - AC_ENERGY_REACTIVE_PHASE_2 = PBMetric.METRIC_AC_ENERGY_REACTIVE_PHASE_2 - AC_ENERGY_REACTIVE_PHASE_3 = PBMetric.METRIC_AC_ENERGY_REACTIVE_PHASE_3 - - # AC harmonics - AC_TOTAL_HARMONIC_DISTORTION_CURRENT = ( - PBMetric.METRIC_AC_TOTAL_HARMONIC_DISTORTION_CURRENT - ) - AC_TOTAL_HARMONIC_DISTORTION_CURRENT_PHASE_1 = ( - PBMetric.METRIC_AC_TOTAL_HARMONIC_DISTORTION_CURRENT_PHASE_1 - ) - AC_TOTAL_HARMONIC_DISTORTION_CURRENT_PHASE_2 = ( - PBMetric.METRIC_AC_TOTAL_HARMONIC_DISTORTION_CURRENT_PHASE_2 - ) - AC_TOTAL_HARMONIC_DISTORTION_CURRENT_PHASE_3 = ( - PBMetric.METRIC_AC_TOTAL_HARMONIC_DISTORTION_CURRENT_PHASE_3 - ) - - # General BMS metrics - BATTERY_CAPACITY = PBMetric.METRIC_BATTERY_CAPACITY - BATTERY_SOC_PCT = PBMetric.METRIC_BATTERY_SOC_PCT - BATTERY_TEMPERATURE = PBMetric.METRIC_BATTERY_TEMPERATURE - - # General inverter metrics - INVERTER_TEMPERATURE = PBMetric.METRIC_INVERTER_TEMPERATURE - INVERTER_TEMPERATURE_CABINET = PBMetric.METRIC_INVERTER_TEMPERATURE_CABINET - INVERTER_TEMPERATURE_HEATSINK = PBMetric.METRIC_INVERTER_TEMPERATURE_HEATSINK - INVERTER_TEMPERATURE_TRANSFORMER = PBMetric.METRIC_INVERTER_TEMPERATURE_TRANSFORMER - - # EV charging station metrics - EV_CHARGER_TEMPERATURE = PBMetric.METRIC_EV_CHARGER_TEMPERATURE - - # General sensor metrics - SENSOR_WIND_SPEED = PBMetric.METRIC_SENSOR_WIND_SPEED - SENSOR_WIND_DIRECTION = PBMetric.METRIC_SENSOR_WIND_DIRECTION - SENSOR_TEMPERATURE = PBMetric.METRIC_SENSOR_TEMPERATURE - SENSOR_RELATIVE_HUMIDITY = PBMetric.METRIC_SENSOR_RELATIVE_HUMIDITY - SENSOR_DEW_POINT = PBMetric.METRIC_SENSOR_DEW_POINT - SENSOR_AIR_PRESSURE = PBMetric.METRIC_SENSOR_AIR_PRESSURE - 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. - - Args: - metric: Metric to convert. - Returns: - Enum value corresponding to the protobuf message. - """ - if not any(m.value == metric for m in cls): - return cls(Metric.UNSPECIFIED) - - return cls(metric) - - def to_proto(self) -> PBMetric.ValueType: - """Convert a Metric object to protobuf Metric. - - Returns: - Protobuf message corresponding to the Metric object. - """ - return self.value diff --git a/src/frequenz/client/common/v1alpha8/microgrid/__init__.py b/src/frequenz/client/common/v1alpha8/microgrid/__init__.py deleted file mode 100644 index 1a47d5d..0000000 --- a/src/frequenz/client/common/v1alpha8/microgrid/__init__.py +++ /dev/null @@ -1,18 +0,0 @@ -# License: MIT -# Copyright © 2025 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/sensors.py b/src/frequenz/client/common/v1alpha8/microgrid/sensors.py deleted file mode 100644 index 0fca6a2..0000000 --- a/src/frequenz/client/common/v1alpha8/microgrid/sensors.py +++ /dev/null @@ -1,13 +0,0 @@ -# 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/src/frequenz/client/common/v1alpha8/pagination/__init__.py b/src/frequenz/client/common/v1alpha8/pagination/__init__.py deleted file mode 100644 index 6034449..0000000 --- a/src/frequenz/client/common/v1alpha8/pagination/__init__.py +++ /dev/null @@ -1,91 +0,0 @@ -# License: MIT -# Copyright © 2024 Frequenz Energy-as-a-Service GmbH - -"""Module to define the pagination used with the common client.""" - -from __future__ import annotations # required for constructor type hinting - -from dataclasses import dataclass -from typing import Self - -# pylint: disable=no-name-in-module -from frequenz.api.common.v1alpha8.pagination.pagination_info_pb2 import ( - PaginationInfo as PBPaginationInfo, -) -from frequenz.api.common.v1alpha8.pagination.pagination_params_pb2 import ( - PaginationParams as PBPaginationParams, -) - -# pylint: enable=no-name-in-module - - -@dataclass(frozen=True, kw_only=True) -class PaginationParams: - """Parameters for paginating list requests.""" - - page_size: int - """The maximum number of results to be returned per request.""" - - page_token: str - """The token identifying a specific page of the list results.""" - - @classmethod - def from_proto(cls, pagination_params: PBPaginationParams) -> Self: - """Convert a protobuf PaginationParams to python PaginationParams object. - - Args: - pagination_params: Params to convert. - Returns: - Params object corresponding to the protobuf message. - """ - return cls( - page_size=pagination_params.page_size, - page_token=pagination_params.page_token, - ) - - def to_proto(self) -> PBPaginationParams: - """Convert a Params object to protobuf PaginationParams. - - Returns: - Protobuf message corresponding to the Params object. - """ - return PBPaginationParams( - page_size=self.page_size, - page_token=self.page_token, - ) - - -@dataclass(frozen=True, kw_only=True) -class PaginationInfo: - """Information about the pagination of a list request.""" - - total_items: int - """The total number of items that match the request.""" - - next_page_token: str | None = None - """The token identifying the next page of results.""" - - @classmethod - def from_proto(cls, pagination_info: PBPaginationInfo) -> Self: - """Convert a protobuf PBPaginationInfo to Info object. - - Args: - pagination_info: Info to convert. - Returns: - Info object corresponding to the protobuf message. - """ - return cls( - total_items=pagination_info.total_items, - next_page_token=pagination_info.next_page_token, - ) - - def to_proto(self) -> PBPaginationInfo: - """Convert a Info object to protobuf PBPaginationInfo. - - Returns: - Protobuf message corresponding to the Info object. - """ - return PBPaginationInfo( - total_items=self.total_items, - next_page_token=self.next_page_token, - ) diff --git a/tests/microgrid/test_ids_alpha8.py b/tests/microgrid/test_ids_alpha8.py deleted file mode 100644 index 84b88f6..0000000 --- a/tests/microgrid/test_ids_alpha8.py +++ /dev/null @@ -1,30 +0,0 @@ -# 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)" diff --git a/tests/test_client_common_v1alpha8.py b/tests/test_client_common_v1alpha8.py deleted file mode 100644 index cb9538a..0000000 --- a/tests/test_client_common_v1alpha8.py +++ /dev/null @@ -1,33 +0,0 @@ -# License: MIT -# Copyright © 2023 Frequenz Energy-as-a-Service GmbH - -"""Tests for the frequenz.client.common package.""" - -from frequenz.client.common.v1alpha8.microgrid.electrical_components import ( - ElectricalComponentCategory, - ElectricalComponentDiagnosticCode, - ElectricalComponentStateCode, -) - - -def test_components() -> None: - """Test the components.""" - for category in ElectricalComponentCategory: - assert ElectricalComponentCategory.from_proto(category.to_proto()) == category - - -def test_component_state_code() -> None: - """Test the component state code.""" - for state_code in ElectricalComponentStateCode: - assert ( - ElectricalComponentStateCode.from_proto(state_code.to_proto()) == state_code - ) - - -def test_component_error_code() -> None: - """Test the component diagnostic code.""" - for diagnostic_code in ElectricalComponentDiagnosticCode: - assert ( - ElectricalComponentDiagnosticCode.from_proto(diagnostic_code.to_proto()) - == diagnostic_code - ) diff --git a/tests/test_streaming.py b/tests/test_streaming.py index 4075772..c7d7a1c 100644 --- a/tests/test_streaming.py +++ b/tests/test_streaming.py @@ -1,10 +1,10 @@ # License: MIT # Copyright © 2025 Frequenz Energy-as-a-Service GmbH -"""Tests for the frequenz.client.common.v1alpha8.streaming package.""" +"""Tests for the frequenz.client.common.streaming package.""" from frequenz.client.common.enum_proto import enum_from_proto -from frequenz.client.common.v1alpha8.streaming import Event +from frequenz.client.common.streaming import Event def test_event_enum() -> None: