Add component types

pyproject.toml

@@ -15,7 +15,6 @@ description = "Common code and utilities for Frequenz API clients"
 readme = "README.md"
 license = { text = "MIT" }
 keywords = ["frequenz", "python", "lib", "library", "client-common"]
-# TODO(cookiecutter): Remove and add more classifiers if appropriate
 classifiers = [
   "Development Status :: 3 - Alpha",
   "Intended Audience :: Developers",
@@ -26,17 +25,16 @@ classifiers = [
   "Typing :: Typed",
 ]
 requires-python = ">= 3.11, < 4"
-# TODO(cookiecutter): Remove and add more dependencies if appropriate
 dependencies = [
   "typing-extensions >= 4.5.0, < 5",
+  "frequenz-api-common >= 0.5.4, < 6",
 ]
 dynamic = ["version"]
 
 [[project.authors]]
 name = "Frequenz Energy-as-a-Service GmbH"
 email = "floss@frequenz.com"
 
-# TODO(cookiecutter): Remove and add more optional dependencies if appropriate
 [project.optional-dependencies]
 dev-flake8 = [
   "flake8 == 6.1.0",

src/frequenz/client/common/__init__.py

@@ -1,25 +1,4 @@
 # License: MIT
 # Copyright © 2023 Frequenz Energy-as-a-Service GmbH
 
-"""Common code and utilities for Frequenz API clients.
-
-TODO(cookiecutter): Add a more descriptive module description.
-"""
-
-
-# TODO(cookiecutter): Remove this function
-def delete_me(*, blow_up: bool = False) -> bool:
-    """Do stuff for demonstration purposes.
-
-    Args:
-        blow_up: If True, raise an exception.
-
-    Returns:
-        True if no exception was raised.
-
-    Raises:
-        RuntimeError: if blow_up is True.
-    """
-    if blow_up:
-        raise RuntimeError("This function should be removed!")
-    return True
+"""Common code and utilities for Frequenz API clients."""

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

@@ -0,0 +1,4 @@
+# License: MIT
+# Copyright © 2023 Frequenz Energy-as-a-Service GmbH
+
+"""Frequenz microgrid definition."""

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

@@ -0,0 +1,67 @@
+# License: MIT
+# Copyright © 2022 Frequenz Energy-as-a-Service GmbH
+
+"""Defines the components that can be used in a microgrid."""
+from __future__ import annotations
+
+from enum import Enum
+
+# pylint: disable=no-name-in-module
+from frequenz.api.common.v1.microgrid.components.components_pb2 import (
+    ComponentCategory as PBComponentCategory,
+)
+
+# pylint: enable=no-name-in-module
+
+
+class ComponentCategory(Enum):
+    """Possible types of microgrid component."""
+
+    UNSPECIFIED = PBComponentCategory.COMPONENT_CATEGORY_UNSPECIFIED
+    """An unknown component category.
+
+    Useful for error handling, and marking unknown components in
+    a list of components with otherwise known categories.
+    """
+
+    GRID = PBComponentCategory.COMPONENT_CATEGORY_GRID
+    """The point where the local microgrid is connected to the grid."""
+
+    METER = PBComponentCategory.COMPONENT_CATEGORY_METER
+    """A meter, for measuring electrical metrics, e.g., current, voltage, etc."""
+
+    INVERTER = PBComponentCategory.COMPONENT_CATEGORY_INVERTER
+    """An electricity generator, with batteries or solar energy."""
+
+    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."""
+
+    CHP = PBComponentCategory.COMPONENT_CATEGORY_CHP
+    """A heat and power combustion plant (CHP stands for combined heat and power)."""
+
+    @classmethod
+    def from_proto(
+        cls, component_category: PBComponentCategory.ValueType
+    ) -> ComponentCategory:
+        """Convert a protobuf ComponentCategory message to ComponentCategory enum.
+
+        Args:
+            component_category: protobuf enum to convert
+
+        Returns:
+            Enum value corresponding to the protobuf message.
+        """
+        if not any(t.value == component_category for t in ComponentCategory):
+            return ComponentCategory.UNSPECIFIED
+        return cls(component_category)
+
+    def to_proto(self) -> PBComponentCategory.ValueType:
+        """Convert a ComponentCategory enum to protobuf ComponentCategory message.
+
+        Returns:
+            Enum value corresponding to the protobuf message.
+        """
+        return self.value

tests/test_client_common.py

@@ -2,17 +2,11 @@
 # Copyright © 2023 Frequenz Energy-as-a-Service GmbH
 
 """Tests for the frequenz.client.common package."""
-import pytest
 
-from frequenz.client.common import delete_me
+from frequenz.client.common.microgrid.components import ComponentCategory
 
 
-def test_client_common_succeeds() -> None:  # TODO(cookiecutter): Remove
-    """Test that the delete_me function succeeds."""
-    assert delete_me() is True
-
-
-def test_client_common_fails() -> None:  # TODO(cookiecutter): Remove
-    """Test that the delete_me function fails."""
-    with pytest.raises(RuntimeError, match="This function should be removed!"):
-        delete_me(blow_up=True)
+def test_components() -> None:
+    """Test the components."""
+    for category in ComponentCategory:
+        assert ComponentCategory.from_proto(category.to_proto()) == category