Add Battery component and sub-classes/types

Battery components have an attached battery type. To encode this into
the Python type system, we create a sub-class per each battery type,
similar to what we do with components.

The special types `UnspecifiedBattery` and `UnrecognizedBattery` are
added to represent a battery with type `UNSPECIFIED` and a battery with
a battery type we don't recognize (this could happen if using a newer
server providing new battery types) respectively.

On top of that, we define a `BatteryTypes` type alias to make it easy
to type-hint function that want to return all known battery types as a
type union instead of using inheritance.

Signed-off-by: Leandro Lucarella <[email protected]>

Author: llucax

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

@@ -3,6 +3,15 @@
 
 """All classes and functions related to microgrid components."""
 
+from ._battery import (
+    Battery,
+    BatteryType,
+    BatteryTypes,
+    LiIonBattery,
+    NaIonBattery,
+    UnrecognizedBattery,
+    UnspecifiedBattery,
+)
 from ._category import ComponentCategory
 from ._chp import Chp
 from ._component import Component
@@ -19,6 +28,9 @@
 from ._voltage_transformer import VoltageTransformer
 
 __all__ = [
+    "Battery",
+    "BatteryType",
+    "BatteryTypes",
     "Chp",
     "Component",
     "ComponentCategory",
@@ -29,8 +41,12 @@
     "Fuse",
     "GridConnectionPoint",
     "Hvac",
+    "LiIonBattery",
     "Meter",
+    "NaIonBattery",
     "Precharger",
     "Relay",
+    "UnrecognizedBattery",
+    "UnspecifiedBattery",
     "VoltageTransformer",
 ]

src/frequenz/client/microgrid/component/_battery.py

@@ -0,0 +1,129 @@
+# License: MIT
+# Copyright © 2024 Frequenz Energy-as-a-Service GmbH
+
+"""Battery component."""
+
+import dataclasses
+import enum
+from typing import Any, Literal, Self, TypeAlias
+
+from frequenz.api.common.v1.microgrid.components import battery_pb2
+
+from ._category import ComponentCategory
+from ._component import Component
+
+
+@enum.unique
+class BatteryType(enum.Enum):
+    """The known types of batteries."""
+
+    UNSPECIFIED = battery_pb2.BATTERY_TYPE_UNSPECIFIED
+    """The battery type is unspecified."""
+
+    LI_ION = battery_pb2.BATTERY_TYPE_LI_ION
+    """Lithium-ion (Li-ion) battery."""
+
+    NA_ION = battery_pb2.BATTERY_TYPE_NA_ION
+    """Sodium-ion (Na-ion) battery."""
+
+
+@dataclasses.dataclass(frozen=True, kw_only=True)
+class Battery(Component):
+    """An abstract battery component."""
+
+    category: Literal[ComponentCategory.BATTERY] = ComponentCategory.BATTERY
+    """The category of this component.
+
+    Note:
+        This should not be used normally, you should test if a component
+        [`isinstance`][] of a concrete component class instead.
+
+        It is only provided for using with a newer version of the API where the client
+        doesn't know about a new category yet (i.e. for use with
+        [`UnrecognizedComponent`][frequenz.client.microgrid.component.UnrecognizedComponent])
+        and in case some low level code needs to know the category of a component.
+    """
+
+    type: BatteryType | int
+    """The type of this battery.
+
+    Note:
+        This should not be used normally, you should test if a battery
+        [`isinstance`][] of a concrete battery class instead.
+
+        It is only provided for using with a newer version of the API where the client
+        doesn't know about the new battery type yet (i.e. for use with
+        [`UnrecognizedBattery`][frequenz.client.microgrid.component.UnrecognizedBattery]).
+    """
+
+    # pylint: disable-next=unused-argument
+    def __new__(cls, *args: Any, **kwargs: Any) -> Self:
+        """Prevent instantiation of this class."""
+        if cls is Battery:
+            raise TypeError(f"Cannot instantiate {cls.__name__} directly")
+        return super().__new__(cls)
+
+
+@dataclasses.dataclass(frozen=True, kw_only=True)
+class UnspecifiedBattery(Battery):
+    """A battery of a unspecified type."""
+
+    type: Literal[BatteryType.UNSPECIFIED] = BatteryType.UNSPECIFIED
+    """The type of this battery.
+
+    Note:
+        This should not be used normally, you should test if a battery
+        [`isinstance`][] of a concrete battery class instead.
+
+        It is only provided for using with a newer version of the API where the client
+        doesn't know about the new battery type yet (i.e. for use with
+        [`UnrecognizedBattery`][frequenz.client.microgrid.component.UnrecognizedBattery]).
+    """
+
+
+@dataclasses.dataclass(frozen=True, kw_only=True)
+class LiIonBattery(Battery):
+    """A Li-ion battery."""
+
+    type: Literal[BatteryType.LI_ION] = BatteryType.LI_ION
+    """The type of this battery.
+
+    Note:
+        This should not be used normally, you should test if a battery
+        [`isinstance`][] of a concrete battery class instead.
+
+        It is only provided for using with a newer version of the API where the client
+        doesn't know about the new battery type yet (i.e. for use with
+        [`UnrecognizedBattery`][frequenz.client.microgrid.component.UnrecognizedBattery]).
+    """
+
+
+@dataclasses.dataclass(frozen=True, kw_only=True)
+class NaIonBattery(Battery):
+    """A Na-ion battery."""
+
+    type: Literal[BatteryType.NA_ION] = BatteryType.NA_ION
+    """The type of this battery.
+
+    Note:
+        This should not be used normally, you should test if a battery
+        [`isinstance`][] of a concrete battery class instead.
+
+        It is only provided for using with a newer version of the API where the client
+        doesn't know about the new battery type yet (i.e. for use with
+        [`UnrecognizedBattery`][frequenz.client.microgrid.component.UnrecognizedBattery]).
+    """
+
+
+@dataclasses.dataclass(frozen=True, kw_only=True)
+class UnrecognizedBattery(Battery):
+    """A battery of an unrecognized type."""
+
+    type: int
+    """The unrecognized type of this battery."""
+
+
+BatteryTypes: TypeAlias = (
+    LiIonBattery | NaIonBattery | UnrecognizedBattery | UnspecifiedBattery
+)
+"""All possible battery types."""

tests/component/test_battery.py

@@ -0,0 +1,122 @@
+# License: MIT
+# Copyright © 2025 Frequenz Energy-as-a-Service GmbH
+
+"""Tests for Battery components."""
+
+import dataclasses
+
+import pytest
+from frequenz.client.common.microgrid import MicrogridId
+from frequenz.client.common.microgrid.components import ComponentId
+
+from frequenz.client.microgrid.component import (
+    Battery,
+    BatteryType,
+    ComponentCategory,
+    ComponentStatus,
+    LiIonBattery,
+    NaIonBattery,
+    UnrecognizedBattery,
+    UnspecifiedBattery,
+)
+
+
+@dataclasses.dataclass(frozen=True, kw_only=True)
+class BatteryTestCase:
+    """Test case for battery components."""
+
+    cls: type[UnspecifiedBattery | LiIonBattery | NaIonBattery]
+    expected_type: BatteryType
+    name: str
+
+
+@pytest.fixture
+def component_id() -> ComponentId:
+    """Provide a test component ID."""
+    return ComponentId(42)
+
+
+@pytest.fixture
+def microgrid_id() -> MicrogridId:
+    """Provide a test microgrid ID."""
+    return MicrogridId(1)
+
+
+def test_abstract_battery_cannot_be_instantiated(
+    component_id: ComponentId, microgrid_id: MicrogridId
+) -> None:
+    """Test that Battery base class cannot be instantiated."""
+    with pytest.raises(TypeError, match="Cannot instantiate Battery directly"):
+        Battery(
+            id=component_id,
+            microgrid_id=microgrid_id,
+            name="test_battery",
+            manufacturer="test_manufacturer",
+            model_name="test_model",
+            status=ComponentStatus.ACTIVE,
+            type=BatteryType.LI_ION,
+        )
+
+
+@pytest.mark.parametrize(
+    "case",
+    [
+        BatteryTestCase(
+            cls=UnspecifiedBattery,
+            expected_type=BatteryType.UNSPECIFIED,
+            name="unspecified",
+        ),
+        BatteryTestCase(
+            cls=LiIonBattery, expected_type=BatteryType.LI_ION, name="li_ion"
+        ),
+        BatteryTestCase(
+            cls=NaIonBattery, expected_type=BatteryType.NA_ION, name="na_ion"
+        ),
+    ],
+    ids=lambda case: case.name,
+)
+def test_recognized_battery_types(
+    case: BatteryTestCase, component_id: ComponentId, microgrid_id: MicrogridId
+) -> None:
+    """Test initialization and properties of different battery types."""
+    battery = case.cls(
+        id=component_id,
+        microgrid_id=microgrid_id,
+        name=case.name,
+        manufacturer="test_manufacturer",
+        model_name="test_model",
+        status=ComponentStatus.ACTIVE,
+    )
+
+    assert battery.id == component_id
+    assert battery.microgrid_id == microgrid_id
+    assert battery.name == case.name
+    assert battery.manufacturer == "test_manufacturer"
+    assert battery.model_name == "test_model"
+    assert battery.status == ComponentStatus.ACTIVE
+    assert battery.category == ComponentCategory.BATTERY
+    assert battery.type == case.expected_type
+
+
+def test_unrecognized_battery_type(
+    component_id: ComponentId, microgrid_id: MicrogridId
+) -> None:
+    """Test initialization and properties of different battery types."""
+    battery = UnrecognizedBattery(
+        id=component_id,
+        microgrid_id=microgrid_id,
+        name="unrecognized_battery",
+        manufacturer="test_manufacturer",
+        model_name="test_model",
+        status=ComponentStatus.ACTIVE,
+        type=999,
+    )
+
+    assert battery.id == component_id
+    assert battery.microgrid_id == microgrid_id
+    assert battery.name == "unrecognized_battery"
+    assert battery.manufacturer == "test_manufacturer"
+    assert battery.model_name == "test_model"
+    assert battery.status == ComponentStatus.ACTIVE
+    assert battery.category == ComponentCategory.BATTERY
+    assert battery.type == 999