frequenz-client-common 0.3.2__tar.gz → 0.3.3__tar.gz

{frequenz_client_common-0.3.2/src/frequenz_client_common.egg-info → frequenz_client_common-0.3.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: frequenz-client-common
-Version: 0.3.2
+Version: 0.3.3
 Summary: Common code and utilities for Frequenz API clients
 Author-email: Frequenz Energy-as-a-Service GmbH <floss@frequenz.com>
 License: MIT
@@ -21,8 +21,8 @@ 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<7,>=0.6.0
-Requires-Dist: frequenz-core<2,>=1.0.0
+Requires-Dist: frequenz-api-common<7,>=0.6.1
+Requires-Dist: frequenz-core<2,>=1.0.2
 Provides-Extra: dev-flake8
 Requires-Dist: flake8==7.2.0; extra == "dev-flake8"
 Requires-Dist: flake8-docstrings==1.7.0; extra == "dev-flake8"

frequenz_client_common-0.3.3/RELEASE_NOTES.md

@@ -0,0 +1,22 @@
+# Frequenz Client Common Library Release Notes
+
+## Summary
+
+<!-- Here goes a general summary of what this release is about -->
+
+## Upgrading
+
+- The metrics and components enums `.from_proto()` are deprecated, please use the new `enum_from_proto()` instead.
+- Some minimum dependencies have been bumped, you might need to update your minimum dependencies too:
+
+    * `frequenz-api-common` to 0.6.1
+    * `frequenz-core` to 1.0.2
+
+## New Features
+
+- A new module `frequenz.client.common.enum_proto` has been added, which provides a generic `enum_from_proto()` function to convert protobuf enums to Python enums.
+- The `frequenz.client.common.microgrid.ComponentCategory` was extended to include the missing categories.
+
+## Bug Fixes
+
+<!-- Here goes notable bug fixes that are worth a special mention or explanation -->

{frequenz_client_common-0.3.2 → frequenz_client_common-0.3.3}/pyproject.toml

@@ -27,8 +27,8 @@ classifiers = [
 requires-python = ">= 3.11, < 4"
 dependencies = [
   "typing-extensions >= 4.13.0, < 5",
-  "frequenz-api-common >= 0.6.0, < 7",
-  "frequenz-core >= 1.0.0, < 2",
+  "frequenz-api-common >= 0.6.1, < 7",
+  "frequenz-core >= 1.0.2, < 2",
 ]
 dynamic = ["version"]
 

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

@@ -0,0 +1,76 @@
+# 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
+
+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: ...
+
+
+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.2 → frequenz_client_common-0.3.3}/src/frequenz/client/common/metric/__init__.py

@@ -3,16 +3,18 @@
 
 """Module to define the metrics used with the common client."""
 
-from enum import Enum
+import enum
 from typing import Self
 
 # pylint: disable=no-name-in-module
 from frequenz.api.common.v1.metrics.metric_sample_pb2 import Metric as PBMetric
+from typing_extensions import deprecated
 
 # pylint: enable=no-name-in-module
 
 
-class Metric(Enum):
+@enum.unique
+class Metric(enum.Enum):
     """List of supported metrics.
 
     AC energy metrics information:
@@ -140,6 +142,7 @@ class Metric(Enum):
     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.
 

{frequenz_client_common-0.3.2 → frequenz_client_common-0.3.3}/src/frequenz/client/common/microgrid/components/__init__.py

@@ -5,7 +5,7 @@
 
 from __future__ import annotations
 
-from enum import Enum
+import enum
 from typing import final
 
 # pylint: disable=no-name-in-module
@@ -19,6 +19,7 @@ from frequenz.api.common.v1.microgrid.components.components_pb2 import (
     ComponentStateCode as PBComponentStateCode,
 )
 from frequenz.core.id import BaseId
+from typing_extensions import deprecated
 
 # pylint: enable=no-name-in-module
 
@@ -28,7 +29,8 @@ class ComponentId(BaseId, str_prefix="CID"):
     """A unique identifier for a microgrid component."""
 
 
-class ComponentCategory(Enum):
+@enum.unique
+class ComponentCategory(enum.Enum):
     """Possible types of microgrid component."""
 
     UNSPECIFIED = PBComponentCategory.COMPONENT_CATEGORY_UNSPECIFIED
@@ -47,16 +49,63 @@ class ComponentCategory(Enum):
     INVERTER = PBComponentCategory.COMPONENT_CATEGORY_INVERTER
     """An electricity generator, with batteries or solar energy."""
 
+    CONVERTER = PBComponentCategory.COMPONENT_CATEGORY_CONVERTER
+    """A DC-DC converter."""
+
     BATTERY = PBComponentCategory.COMPONENT_CATEGORY_BATTERY
     """A storage system for electrical energy, used by inverters."""
 
     EV_CHARGER = PBComponentCategory.COMPONENT_CATEGORY_EV_CHARGER
     """A station for charging electrical vehicles."""
 
+    CRYPTO_MINER = PBComponentCategory.COMPONENT_CATEGORY_CRYPTO_MINER
+    """A crypto miner."""
+
+    ELECTROLYZER = PBComponentCategory.COMPONENT_CATEGORY_ELECTROLYZER
+    """An electrolyzer for converting water into hydrogen and oxygen."""
+
     CHP = PBComponentCategory.COMPONENT_CATEGORY_CHP
     """A heat and power combustion plant (CHP stands for combined heat and power)."""
 
+    RELAY = PBComponentCategory.COMPONENT_CATEGORY_RELAY
+    """A relay.
+
+    Relays generally have two states: open (connected) and closed (disconnected).
+    They are generally placed in front of a component, e.g., an inverter, to
+    control whether the component is connected to the grid or not.
+    """
+
+    PRECHARGER = PBComponentCategory.COMPONENT_CATEGORY_PRECHARGER
+    """A precharge module.
+
+    Precharging involves gradually ramping up the DC voltage to prevent any
+    potential damage to sensitive electrical components like capacitors.
+
+    While many inverters and batteries come equipped with in-built precharging
+    mechanisms, some may lack this feature. In such cases, we need to use
+    external precharging modules.
+    """
+
+    FUSE = PBComponentCategory.COMPONENT_CATEGORY_FUSE
+    """A fuse."""
+
+    VOLTAGE_TRANSFORMER = PBComponentCategory.COMPONENT_CATEGORY_VOLTAGE_TRANSFORMER
+    """A voltage transformer.
+
+    Voltage transformers are used to step up or step down the voltage, keeping
+    the power somewhat constant by increasing or decreasing the current.  If voltage is
+    stepped up, current is stepped down, and vice versa.
+
+    Note:
+        Voltage transformers have efficiency losses, so the output power is
+        always less than the input power.
+    """
+
+    HVAC = PBComponentCategory.COMPONENT_CATEGORY_HVAC
+    """A Heating, Ventilation, and Air Conditioning (HVAC) system."""
+
     @classmethod
+    @deprecated("Use `frequenz.client.common.enum_proto.enum_from_proto` instead.")
     def from_proto(
         cls, component_category: PBComponentCategory.ValueType
     ) -> ComponentCategory:
@@ -81,7 +130,8 @@ class ComponentCategory(Enum):
         return self.value
 
 
-class ComponentStateCode(Enum):
+@enum.unique
+class ComponentStateCode(enum.Enum):
     """All possible states of a microgrid component."""
 
     UNSPECIFIED = PBComponentStateCode.COMPONENT_STATE_CODE_UNSPECIFIED
@@ -161,6 +211,7 @@ class ComponentStateCode(Enum):
     """The precharger circuit is closed, allowing full current to flow to the main circuit."""
 
     @classmethod
+    @deprecated("Use `frequenz.client.common.enum_proto.enum_from_proto` instead.")
     def from_proto(
         cls, component_state: PBComponentStateCode.ValueType
     ) -> ComponentStateCode:
@@ -185,7 +236,8 @@ class ComponentStateCode(Enum):
         return self.value
 
 
-class ComponentErrorCode(Enum):
+@enum.unique
+class ComponentErrorCode(enum.Enum):
     """All possible errors that can occur across all microgrid component categories."""
 
     UNSPECIFIED = PBComponentErrorCode.COMPONENT_ERROR_CODE_UNSPECIFIED
@@ -338,6 +390,7 @@ class ComponentErrorCode(Enum):
     times."""
 
     @classmethod
+    @deprecated("Use `frequenz.client.common.enum_proto.enum_from_proto` instead.")
     def from_proto(
         cls, component_error_code: PBComponentErrorCode.ValueType
     ) -> ComponentErrorCode:

{frequenz_client_common-0.3.2 → frequenz_client_common-0.3.3/src/frequenz_client_common.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: frequenz-client-common
-Version: 0.3.2
+Version: 0.3.3
 Summary: Common code and utilities for Frequenz API clients
 Author-email: Frequenz Energy-as-a-Service GmbH <floss@frequenz.com>
 License: MIT
@@ -21,8 +21,8 @@ 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<7,>=0.6.0
-Requires-Dist: frequenz-core<2,>=1.0.0
+Requires-Dist: frequenz-api-common<7,>=0.6.1
+Requires-Dist: frequenz-core<2,>=1.0.2
 Provides-Extra: dev-flake8
 Requires-Dist: flake8==7.2.0; extra == "dev-flake8"
 Requires-Dist: flake8-docstrings==1.7.0; extra == "dev-flake8"

{frequenz_client_common-0.3.2 → frequenz_client_common-0.3.3}/src/frequenz_client_common.egg-info/SOURCES.txt

@@ -5,6 +5,7 @@ RELEASE_NOTES.md
 pyproject.toml
 src/frequenz/client/common/__init__.py
 src/frequenz/client/common/conftest.py
+src/frequenz/client/common/enum_proto.py
 src/frequenz/client/common/py.typed
 src/frequenz/client/common/metric/__init__.py
 src/frequenz/client/common/microgrid/__init__.py

{frequenz_client_common-0.3.2 → frequenz_client_common-0.3.3}/src/frequenz_client_common.egg-info/requires.txt

@@ -1,6 +1,6 @@
 typing-extensions<5,>=4.13.0
-frequenz-api-common<7,>=0.6.0
-frequenz-core<2,>=1.0.0
+frequenz-api-common<7,>=0.6.1
+frequenz-core<2,>=1.0.2
 
 [dev]
 frequenz-client-common[dev-flake8,dev-formatting,dev-mkdocs,dev-mypy,dev-noxfile,dev-pylint,dev-pytest]

frequenz_client_common-0.3.2/RELEASE_NOTES.md

@@ -1,19 +0,0 @@
-# Frequenz Client Common Library Release Notes
-
-## Summary
-
-This release replaces the failed v0.3.1 release.
-
-## Upgrading
-
-- The `typing-extensions` dependency minimum version was bumped to 4.13 to support Python 3.12.
-
-## New Features
-
-- New `BaseId` class to create unique IDs for entities in the system.
-- New ID classes for microgrid-related entities:
-
-   * `EnterpriseId`
-   * `MicrogridId`
-   * `ComponentId`
-   * `SensorId`