frequenz-client-common 0.3.6__tar.gz → 0.3.8__tar.gz

{frequenz_client_common-0.3.6/src/frequenz_client_common.egg-info → frequenz_client_common-0.3.8}/PKG-INFO

@@ -1,9 +1,9 @@
 Metadata-Version: 2.4
 Name: frequenz-client-common
-Version: 0.3.6
+Version: 0.3.8
 Summary: Common code and utilities for Frequenz API clients
 Author-email: Frequenz Energy-as-a-Service GmbH <floss@frequenz.com>
-License: MIT
+License-Expression: MIT
 Project-URL: Documentation, https://frequenz-floss.github.io/frequenz-client-common-python/
 Project-URL: Changelog, https://github.com/frequenz-floss/frequenz-client-common-python/releases
 Project-URL: Issues, https://github.com/frequenz-floss/frequenz-client-common-python/issues
@@ -12,7 +12,6 @@ Project-URL: Support, https://github.com/frequenz-floss/frequenz-client-common-p
 Keywords: frequenz,python,lib,library,client-common
 Classifier: Development Status :: 3 - Alpha
 Classifier: Intended Audience :: Developers
-Classifier: License :: OSI Approved :: MIT License
 Classifier: Programming Language :: Python :: 3
 Classifier: Programming Language :: Python :: 3 :: Only
 Classifier: Topic :: Software Development :: Libraries
@@ -21,44 +20,48 @@ Requires-Python: <4,>=3.11
 Description-Content-Type: text/markdown
 License-File: LICENSE
 Requires-Dist: typing-extensions<5,>=4.13.0
-Requires-Dist: frequenz-api-common<1,>=0.8.0
+Requires-Dist: frequenz-api-common<1,>=0.8.4
 Requires-Dist: frequenz-core<2,>=1.0.2
+Requires-Dist: protobuf<8,>=6.33.6
 Provides-Extra: dev-flake8
 Requires-Dist: flake8==7.3.0; extra == "dev-flake8"
+Requires-Dist: flake8-datetimez==20.10.0; extra == "dev-flake8"
 Requires-Dist: flake8-docstrings==1.7.0; extra == "dev-flake8"
-Requires-Dist: flake8-pyproject==1.2.3; extra == "dev-flake8"
-Requires-Dist: pydoclint==0.6.6; extra == "dev-flake8"
+Requires-Dist: flake8-pyproject==1.2.4; extra == "dev-flake8"
+Requires-Dist: pydoclint==0.8.6; extra == "dev-flake8"
 Requires-Dist: pydocstyle==6.3.0; extra == "dev-flake8"
 Provides-Extra: dev-formatting
-Requires-Dist: black==25.1.0; extra == "dev-formatting"
-Requires-Dist: isort==6.0.1; extra == "dev-formatting"
+Requires-Dist: black==26.5.1; extra == "dev-formatting"
+Requires-Dist: isort==8.0.1; extra == "dev-formatting"
 Provides-Extra: dev-mkdocs
-Requires-Dist: Markdown==3.8.2; extra == "dev-mkdocs"
-Requires-Dist: black==25.1.0; extra == "dev-mkdocs"
-Requires-Dist: mike==2.1.3; extra == "dev-mkdocs"
-Requires-Dist: mkdocs-gen-files==0.5.0; extra == "dev-mkdocs"
-Requires-Dist: mkdocs-literate-nav==0.6.2; extra == "dev-mkdocs"
-Requires-Dist: mkdocs-macros-plugin==1.3.7; extra == "dev-mkdocs"
-Requires-Dist: mkdocs-material==9.6.16; extra == "dev-mkdocs"
-Requires-Dist: mkdocstrings[python]==0.30.0; extra == "dev-mkdocs"
-Requires-Dist: mkdocstrings-python==1.16.12; extra == "dev-mkdocs"
-Requires-Dist: frequenz-repo-config[lib]==0.13.5; extra == "dev-mkdocs"
+Requires-Dist: Markdown==3.10.2; extra == "dev-mkdocs"
+Requires-Dist: black==26.5.1; extra == "dev-mkdocs"
+Requires-Dist: mike==2.2.0; extra == "dev-mkdocs"
+Requires-Dist: mkdocs-gen-files==0.6.1; extra == "dev-mkdocs"
+Requires-Dist: mkdocs-literate-nav==0.6.3; extra == "dev-mkdocs"
+Requires-Dist: mkdocs-macros-plugin==1.5.0; extra == "dev-mkdocs"
+Requires-Dist: mkdocs-material==9.7.6; extra == "dev-mkdocs"
+Requires-Dist: mkdocstrings[python]==1.0.4; extra == "dev-mkdocs"
+Requires-Dist: mkdocstrings-python==2.0.3; extra == "dev-mkdocs"
+Requires-Dist: frequenz-repo-config[lib]==0.18.0; extra == "dev-mkdocs"
 Provides-Extra: dev-mypy
-Requires-Dist: mypy==1.17.1; extra == "dev-mypy"
-Requires-Dist: types-Markdown==3.8.0.20250708; extra == "dev-mypy"
+Requires-Dist: mypy==2.1.0; extra == "dev-mypy"
+Requires-Dist: types-Markdown==3.10.2.20260518; extra == "dev-mypy"
+Requires-Dist: types-protobuf==7.34.1.20260518; extra == "dev-mypy"
 Requires-Dist: frequenz-client-common[dev-mkdocs,dev-noxfile,dev-pytest]; extra == "dev-mypy"
 Provides-Extra: dev-noxfile
-Requires-Dist: nox==2025.5.1; extra == "dev-noxfile"
-Requires-Dist: frequenz-repo-config[lib]==0.13.5; extra == "dev-noxfile"
+Requires-Dist: nox==2026.4.10; extra == "dev-noxfile"
+Requires-Dist: frequenz-repo-config[lib]==0.18.0; extra == "dev-noxfile"
 Provides-Extra: dev-pylint
-Requires-Dist: pylint==3.3.7; extra == "dev-pylint"
+Requires-Dist: pylint==4.0.5; extra == "dev-pylint"
 Requires-Dist: frequenz-client-common[dev-mkdocs,dev-noxfile,dev-pytest]; extra == "dev-pylint"
 Provides-Extra: dev-pytest
-Requires-Dist: pytest==8.4.1; extra == "dev-pytest"
-Requires-Dist: frequenz-repo-config[extra-lint-examples]==0.13.5; extra == "dev-pytest"
-Requires-Dist: pytest-mock==3.14.1; extra == "dev-pytest"
-Requires-Dist: pytest-asyncio==1.1.0; extra == "dev-pytest"
-Requires-Dist: async-solipsism==0.8; extra == "dev-pytest"
+Requires-Dist: pytest==9.0.3; extra == "dev-pytest"
+Requires-Dist: frequenz-repo-config[extra-lint-examples]==0.18.0; extra == "dev-pytest"
+Requires-Dist: hypothesis==6.155.1; extra == "dev-pytest"
+Requires-Dist: pytest-mock==3.15.1; extra == "dev-pytest"
+Requires-Dist: pytest-asyncio==1.4.0; extra == "dev-pytest"
+Requires-Dist: async-solipsism==0.9; extra == "dev-pytest"
 Provides-Extra: dev
 Requires-Dist: frequenz-client-common[dev-flake8,dev-formatting,dev-mkdocs,dev-mypy,dev-noxfile,dev-pylint,dev-pytest]; extra == "dev"
 Dynamic: license-file

frequenz_client_common-0.3.8/RELEASE_NOTES.md

@@ -0,0 +1,38 @@
+# Frequenz Client Common Library Release Notes
+
+## 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 new free functions.
+
+## 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
+
+> [!IMPORTANT]
+> Passing enum values directly to build protobuf messages is now deprecated, but it **does NOT emit a deprecation warning**, so migration needs to be done manually. Use the new conversion functions to convert enum values to their protobuf equivalents before passing them to message builders.
+>
+> **Implicit conversions will fail type checking in v0.4.0.**
+
+- `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.
+- `frequenz.client.common.microgrid.electrical_components.ElectricalComponentCategory.from_proto()` is deprecated; use `frequenz.client.common.microgrid.electrical_components.proto.v1alpha8.electrical_component_category_from_proto` instead.
+- `frequenz.client.common.microgrid.electrical_components.ElectricalComponentCategory.to_proto()` is deprecated; use `frequenz.client.common.microgrid.electrical_components.proto.v1alpha8.electrical_component_category_to_proto` instead.
+- `frequenz.client.common.microgrid.electrical_components.ElectricalComponentStateCode.from_proto()` is deprecated; use `frequenz.client.common.microgrid.electrical_components.proto.v1alpha8.electrical_component_state_code_from_proto` instead.
+- `frequenz.client.common.microgrid.electrical_components.ElectricalComponentStateCode.to_proto()` is deprecated; use `frequenz.client.common.microgrid.electrical_components.proto.v1alpha8.electrical_component_state_code_to_proto` instead.
+- `frequenz.client.common.microgrid.electrical_components.ElectricalComponentDiagnosticCode.from_proto()` is deprecated; use `frequenz.client.common.microgrid.electrical_components.proto.v1alpha8.electrical_component_diagnostic_code_from_proto` instead.
+- `frequenz.client.common.microgrid.electrical_components.ElectricalComponentDiagnosticCode.to_proto()` is deprecated; use `frequenz.client.common.microgrid.electrical_components.proto.v1alpha8.electrical_component_diagnostic_code_to_proto` instead.
+- `frequenz.client.common.enum_proto.enum_from_proto` is deprecated; use `frequenz.client.common.proto.enum_from_proto` instead.
+- `frequenz.client.common.metric.Metric` (based on the deprecated `frequenz.api.common.v1` namespace) is deprecated; use `frequenz.client.common.metrics.Metric` instead.
+- `frequenz.client.common.microgrid.components.ComponentCategory` (based on the deprecated `frequenz.api.common.v1` namespace) is deprecated; use `frequenz.client.common.microgrid.electrical_components.ElectricalComponentCategory` instead.
+- `frequenz.client.common.microgrid.components.ComponentStateCode` (based on the deprecated `frequenz.api.common.v1` namespace) is deprecated; use `frequenz.client.common.microgrid.electrical_components.ElectricalComponentStateCode` instead.
+- `frequenz.client.common.microgrid.components.ComponentErrorCode` (based on the deprecated `frequenz.api.common.v1` namespace) is deprecated; use `frequenz.client.common.microgrid.electrical_components.ElectricalComponentDiagnosticCode` instead.
+- `frequenz.client.common.microgrid.components.ComponentId` is deprecated; use `frequenz.client.common.microgrid.electrical_components.ElectricalComponentId` instead.

{frequenz_client_common-0.3.6 → frequenz_client_common-0.3.8}/pyproject.toml

@@ -3,9 +3,9 @@
 
 [build-system]
 requires = [
-  "setuptools == 80.9.0",
-  "setuptools_scm[toml] == 8.3.1",
-  "frequenz-repo-config[lib] == 0.13.5",
+  "setuptools == 82.0.1",
+  "setuptools_scm[toml] == 10.0.5",
+  "frequenz-repo-config[lib] == 0.18.0",
 ]
 build-backend = "setuptools.build_meta"
 
@@ -13,12 +13,12 @@ build-backend = "setuptools.build_meta"
 name = "frequenz-client-common"
 description = "Common code and utilities for Frequenz API clients"
 readme = "README.md"
-license = { text = "MIT" }
+license = "MIT"
+license-files = ["LICENSE"]
 keywords = ["frequenz", "python", "lib", "library", "client-common"]
 classifiers = [
   "Development Status :: 3 - Alpha",
   "Intended Audience :: Developers",
-  "License :: OSI Approved :: MIT License",
   "Programming Language :: Python :: 3",
   "Programming Language :: Python :: 3 :: Only",
   "Topic :: Software Development :: Libraries",
@@ -27,8 +27,9 @@ classifiers = [
 requires-python = ">= 3.11, < 4"
 dependencies = [
   "typing-extensions >= 4.13.0, < 5",
-  "frequenz-api-common >= 0.8.0, < 1",
+  "frequenz-api-common >= 0.8.4, < 1",
   "frequenz-core >= 1.0.2, < 2",
+  "protobuf >= 6.33.6, < 8",
 ]
 dynamic = ["version"]
 
@@ -39,42 +40,45 @@ email = "floss@frequenz.com"
 [project.optional-dependencies]
 dev-flake8 = [
   "flake8 == 7.3.0",
+  "flake8-datetimez == 20.10.0",
   "flake8-docstrings == 1.7.0",
-  "flake8-pyproject == 1.2.3", # For reading the flake8 config from pyproject.toml
-  "pydoclint == 0.6.6",
+  "flake8-pyproject == 1.2.4", # For reading the flake8 config from pyproject.toml
+  "pydoclint == 0.8.6",
   "pydocstyle == 6.3.0",
 ]
-dev-formatting = ["black == 25.1.0", "isort == 6.0.1"]
+dev-formatting = ["black == 26.5.1", "isort == 8.0.1"]
 dev-mkdocs = [
-  "Markdown == 3.8.2",
-  "black == 25.1.0",
-  "mike == 2.1.3",
-  "mkdocs-gen-files == 0.5.0",
-  "mkdocs-literate-nav == 0.6.2",
-  "mkdocs-macros-plugin == 1.3.7",
-  "mkdocs-material == 9.6.16",
-  "mkdocstrings[python] == 0.30.0",
-  "mkdocstrings-python == 1.16.12",
-  "frequenz-repo-config[lib] == 0.13.5",
+  "Markdown == 3.10.2",
+  "black == 26.5.1",
+  "mike == 2.2.0",
+  "mkdocs-gen-files == 0.6.1",
+  "mkdocs-literate-nav == 0.6.3",
+  "mkdocs-macros-plugin == 1.5.0",
+  "mkdocs-material == 9.7.6",
+  "mkdocstrings[python] == 1.0.4",
+  "mkdocstrings-python == 2.0.3",
+  "frequenz-repo-config[lib] == 0.18.0",
 ]
 dev-mypy = [
-  "mypy == 1.17.1",
-  "types-Markdown == 3.8.0.20250708",
+  "mypy == 2.1.0",
+  "types-Markdown == 3.10.2.20260518",
+  "types-protobuf == 7.34.1.20260518",
   # For checking the noxfile, docs/ script, and tests
   "frequenz-client-common[dev-mkdocs,dev-noxfile,dev-pytest]",
 ]
-dev-noxfile = ["nox == 2025.5.1", "frequenz-repo-config[lib] == 0.13.5"]
+dev-noxfile = ["nox == 2026.4.10", "frequenz-repo-config[lib] == 0.18.0"]
 dev-pylint = [
-  "pylint == 3.3.7",
+  "pylint == 4.0.5",
   # For checking the noxfile, docs/ script, and tests
   "frequenz-client-common[dev-mkdocs,dev-noxfile,dev-pytest]",
 ]
 dev-pytest = [
-  "pytest == 8.4.1",
-  "frequenz-repo-config[extra-lint-examples] == 0.13.5",
-  "pytest-mock == 3.14.1",
-  "pytest-asyncio == 1.1.0",
-  "async-solipsism == 0.8",
+  "pytest == 9.0.3",
+  "frequenz-repo-config[extra-lint-examples] == 0.18.0",
+  "hypothesis == 6.155.1",
+  "pytest-mock == 3.15.1",
+  "pytest-asyncio == 1.4.0",
+  "async-solipsism == 0.9",
 ]
 dev = [
   "frequenz-client-common[dev-mkdocs,dev-flake8,dev-formatting,dev-mkdocs,dev-mypy,dev-noxfile,dev-pylint,dev-pytest]",

frequenz_client_common-0.3.8/src/frequenz/client/common/enum_proto.py

@@ -0,0 +1,82 @@
+# License: MIT
+# Copyright © 2025 Frequenz Energy-as-a-Service GmbH
+
+"""Conversion of protobuf int enums to Python enums."""
+
+import enum
+from typing import Literal, TypeVar, overload
+
+from typing_extensions import deprecated
+
+EnumT = TypeVar("EnumT", bound=enum.Enum)
+"""A type variable that is bound to an enum."""
+
+
+@overload
+def enum_from_proto(
+    value: int, enum_type: type[EnumT], *, allow_invalid: Literal[False]
+) -> EnumT: ...
+
+
+@overload
+def enum_from_proto(
+    value: int, enum_type: type[EnumT], *, allow_invalid: Literal[True] = True
+) -> EnumT | int: ...
+
+
+@deprecated(
+    "frequenz.client.common.enum_proto.enum_from_proto is deprecated. "
+    "Please use frequenz.client.common.proto.enum_from_proto instead."
+)
+def enum_from_proto(
+    value: int, enum_type: type[EnumT], *, allow_invalid: bool = True
+) -> EnumT | int:
+    """Convert a protobuf int enum value to a python enum.
+
+    Example:
+        ```python
+        import enum
+
+        from proto import proto_pb2  # Just an example. pylint: disable=import-error
+
+        @enum.unique
+        class SomeEnum(enum.Enum):
+            # These values should match the protobuf enum values.
+            UNSPECIFIED = 0
+            SOME_VALUE = 1
+
+        enum_value = enum_from_proto(proto_pb2.SomeEnum.SOME_ENUM_SOME_VALUE, SomeEnum)
+        # -> SomeEnum.SOME_VALUE
+
+        enum_value = enum_from_proto(42, SomeEnum)
+        # -> 42
+
+        enum_value = enum_from_proto(
+            proto_pb2.SomeEnum.SOME_ENUM_UNKNOWN_VALUE, SomeEnum, allow_invalid=False
+        )
+        # -> ValueError
+        ```
+
+    Args:
+        value: The protobuf int enum value.
+        enum_type: The python enum type to convert to.
+        allow_invalid: If `True`, return the value as an `int` if the value is not
+            a valid member of the enum (this allows for forward-compatibility with new
+            enum values defined in the protocol but not added to the Python enum yet).
+            If `False`, raise a `ValueError` if the value is not a valid member of the
+            enum.
+
+    Returns:
+        The resulting python enum value if the protobuf value is known, otherwise
+            the input value converted to a plain `int`.
+
+    Raises:
+        ValueError: If `allow_invalid` is `False` and the value is not a valid member
+            of the enum.
+    """
+    try:
+        return enum_type(value)
+    except ValueError:
+        if allow_invalid:
+            return value
+        raise

frequenz_client_common-0.3.8/src/frequenz/client/common/grid/__init__.py

@@ -0,0 +1,11 @@
+# License: MIT
+# Copyright © 2025 Frequenz Energy-as-a-Service GmbH
+
+"""Grid definitions for the energy market."""
+
+from ._delivery_area import DeliveryArea, EnergyMarketCodeType
+
+__all__ = [
+    "DeliveryArea",
+    "EnergyMarketCodeType",
+]

frequenz_client_common-0.3.8/src/frequenz/client/common/grid/_delivery_area.py

@@ -0,0 +1,89 @@
+# License: MIT
+# Copyright © 2025 Frequenz Energy-as-a-Service GmbH
+
+"""Delivery area information for the energy market."""
+
+import enum
+from dataclasses import dataclass
+
+from frequenz.api.common.v1alpha8.grid import delivery_area_pb2
+
+
+@enum.unique
+class EnergyMarketCodeType(enum.Enum):
+    """The identification code types used in the energy market.
+
+    CodeType specifies the type of identification code used for uniquely
+    identifying various entities such as delivery areas, market participants,
+    and grid components within the energy market.
+
+    This enumeration aims to
+    offer compatibility across different jurisdictional standards.
+
+    Note: Understanding Code Types
+        Different regions or countries may have their own standards for uniquely
+        identifying various entities within the energy market. For example, in
+        Europe, the Energy Identification Code (EIC) is commonly used for this
+        purpose.
+
+    Note: Extensibility
+        New code types can be added to this enum to accommodate additional regional
+        standards, enhancing the API's adaptability.
+
+    Danger: Validation Required
+        The chosen code type should correspond correctly with the `code` field in
+        the relevant message objects, such as `DeliveryArea` or `Counterparty`.
+        Failure to match the code type with the correct code could lead to
+        processing errors.
+    """
+
+    UNSPECIFIED = delivery_area_pb2.ENERGY_MARKET_CODE_TYPE_UNSPECIFIED
+    """Unspecified type. This value is a placeholder and should not be used."""
+
+    EUROPE_EIC = delivery_area_pb2.ENERGY_MARKET_CODE_TYPE_EUROPE_EIC
+    """European Energy Identification Code Standard."""
+
+    US_NERC = delivery_area_pb2.ENERGY_MARKET_CODE_TYPE_US_NERC
+    """North American Electric Reliability Corporation identifiers."""
+
+
+@dataclass(frozen=True, kw_only=True)
+class DeliveryArea:
+    """A geographical or administrative region where electricity deliveries occur.
+
+    DeliveryArea represents the geographical or administrative region, usually defined
+    and maintained by a Transmission System Operator (TSO), where electricity deliveries
+    for a contract occur.
+
+    The concept is important to energy trading as it delineates the agreed-upon delivery
+    location. Delivery areas can have different codes based on the jurisdiction in
+    which they operate.
+
+    Note: Jurisdictional Differences
+        This is typically represented by specific codes according to local jurisdiction.
+
+        In Europe, this is represented by an
+        [EIC](https://en.wikipedia.org/wiki/Energy_Identification_Code) (Energy
+        Identification Code). [List of
+        EICs](https://www.entsoe.eu/data/energy-identification-codes-eic/eic-approved-codes/).
+    """
+
+    code: str | None
+    """The code representing the unique identifier for the delivery area."""
+
+    code_type: EnergyMarketCodeType | int
+    """Type of code used for identifying the delivery area itself.
+
+    This code could be extended in the future, in case an unknown code type is
+    encountered, a plain integer value is used to represent it.
+    """
+
+    def __str__(self) -> str:
+        """Return a human-readable string representation of this instance."""
+        code = self.code or "<NO CODE>"
+        code_type = (
+            f"type={self.code_type}"
+            if isinstance(self.code_type, int)
+            else self.code_type.name
+        )
+        return f"{code}[{code_type}]"

frequenz_client_common-0.3.8/src/frequenz/client/common/grid/proto/__init__.py

@@ -0,0 +1,4 @@
+# License: MIT
+# Copyright © 2026 Frequenz Energy-as-a-Service GmbH
+
+"""Grid objects from/to proto conversion functions."""

frequenz_client_common-0.3.8/src/frequenz/client/common/grid/proto/v1alpha8/__init__.py

@@ -0,0 +1,16 @@
+# License: MIT
+# Copyright © 2025 Frequenz Energy-as-a-Service GmbH
+
+"""Conversion of grid objects from/to protobuf v1alpha8."""
+
+from ._delivery_area import (
+    delivery_area_from_proto,
+    energy_market_code_type_from_proto,
+    energy_market_code_type_to_proto,
+)
+
+__all__ = [
+    "delivery_area_from_proto",
+    "energy_market_code_type_from_proto",
+    "energy_market_code_type_to_proto",
+]

frequenz_client_common-0.3.8/src/frequenz/client/common/grid/proto/v1alpha8/_delivery_area.py

@@ -0,0 +1,73 @@
+# License: MIT
+# Copyright © 2025 Frequenz Energy-as-a-Service GmbH
+
+"""Conversion of DeliveryArea and EnergyMarketCodeType to/from protobuf v1alpha8."""
+
+import logging
+
+from frequenz.api.common.v1alpha8.grid import delivery_area_pb2
+
+from ....proto import enum_from_proto
+from ..._delivery_area import DeliveryArea, EnergyMarketCodeType
+
+_logger = logging.getLogger(__name__)
+
+
+def energy_market_code_type_from_proto(
+    message: delivery_area_pb2.EnergyMarketCodeType.ValueType,
+) -> EnergyMarketCodeType | int:
+    """Convert a protobuf EnergyMarketCodeType enum value to an enum member.
+
+    Args:
+        message: A protobuf EnergyMarketCodeType enum value.
+
+    Returns:
+        The corresponding EnergyMarketCodeType enum member, or the raw `int` if the
+            protobuf value is not recognized.
+    """
+    return enum_from_proto(message, EnergyMarketCodeType)
+
+
+def energy_market_code_type_to_proto(
+    code_type: EnergyMarketCodeType,
+) -> delivery_area_pb2.EnergyMarketCodeType.ValueType:
+    """Convert an EnergyMarketCodeType enum member to a protobuf enum value.
+
+    Args:
+        code_type: An EnergyMarketCodeType enum member.
+
+    Returns:
+        The corresponding protobuf EnergyMarketCodeType enum value.
+    """
+    return delivery_area_pb2.EnergyMarketCodeType.ValueType(code_type.value)
+
+
+def delivery_area_from_proto(message: delivery_area_pb2.DeliveryArea) -> DeliveryArea:
+    """Convert a protobuf delivery area message to a delivery area object.
+
+    Args:
+        message: The protobuf message to convert.
+
+    Returns:
+        The resulting delivery area object.
+    """
+    issues: list[str] = []
+
+    code = message.code or None
+    if code is None:
+        issues.append("code is empty")
+
+    code_type = energy_market_code_type_from_proto(message.code_type)
+    if code_type is EnergyMarketCodeType.UNSPECIFIED:
+        issues.append("code_type is unspecified")
+    elif isinstance(code_type, int):
+        issues.append("code_type is unrecognized")
+
+    if issues:
+        _logger.warning(
+            "Found issues in delivery area: %s | Protobuf message:\n%s",
+            ", ".join(issues),
+            message,
+        )
+
+    return DeliveryArea(code=code, code_type=code_type)

{frequenz_client_common-0.3.6 → frequenz_client_common-0.3.8}/src/frequenz/client/common/metric/__init__.py

@@ -13,6 +13,10 @@ from typing_extensions import deprecated
 # 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.
@@ -142,7 +146,10 @@ class Metric(enum.Enum):
     SENSOR_IRRADIANCE = PBMetric.METRIC_SENSOR_IRRADIANCE
 
     @classmethod
-    @deprecated("Use `frequenz.client.common.enum_proto.enum_from_proto` instead.")
+    @deprecated(
+        "frequenz.client.common.metric.Metric.from_proto() is deprecated. "
+        "Use frequenz.client.common.proto.enum_from_proto instead."
+    )
     def from_proto(cls, metric: PBMetric.ValueType) -> Self:
         """Convert a protobuf Metric value to Metric enum.
 

frequenz_client_common-0.3.8/src/frequenz/client/common/metrics/__init__.py

@@ -0,0 +1,24 @@
+# License: MIT
+# Copyright © 2025 Frequenz Energy-as-a-Service GmbH
+
+"""Metrics definitions."""
+
+from ._bounds import Bounds
+from ._metric import Metric
+from ._sample import (
+    AggregatedMetricValue,
+    AggregationMethod,
+    MetricConnection,
+    MetricConnectionCategory,
+    MetricSample,
+)
+
+__all__ = [
+    "AggregatedMetricValue",
+    "AggregationMethod",
+    "Bounds",
+    "Metric",
+    "MetricConnection",
+    "MetricConnectionCategory",
+    "MetricSample",
+]

frequenz_client_common-0.3.8/src/frequenz/client/common/metrics/_bounds.py

@@ -0,0 +1,45 @@
+# License: MIT
+# Copyright © 2024 Frequenz Energy-as-a-Service GmbH
+
+
+"""Definitions for bounds."""
+
+import dataclasses
+
+
+@dataclasses.dataclass(frozen=True, kw_only=True)
+class Bounds:
+    """A set of lower and upper bounds for any metric.
+
+    The lower bound must be less than or equal to the upper bound.
+
+    The units of the bounds are always the same as the related metric.
+    """
+
+    lower: float | None = None
+    """The lower bound.
+
+    If `None`, there is no lower bound.
+    """
+
+    upper: float | None = None
+    """The upper bound.
+
+    If `None`, there is no upper bound.
+    """
+
+    def __post_init__(self) -> None:
+        """Validate these bounds."""
+        if self.lower is None:
+            return
+        if self.upper is None:
+            return
+        if self.lower > self.upper:
+            raise ValueError(
+                f"Lower bound ({self.lower}) must be less than or equal to upper "
+                f"bound ({self.upper})"
+            )
+
+    def __str__(self) -> str:
+        """Return a string representation of these bounds."""
+        return f"[{self.lower}, {self.upper}]"