Add ProblematicComponent and sub-classes

Problematic components are components that can't be mapped to known
category types (or are `UNSPECIFIED`).  They also include components
with mismatched a category, i.e. a component with a particular known
category but that also has category-specific information that doesn't
match the specified category. For example if the category is `BATTERY`
but the category-specific information is for a `INVERTER`.

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

Author: llucax

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

@@ -42,6 +42,12 @@
 )
 from ._meter import Meter
 from ._precharger import Precharger
+from ._problematic import (
+    MismatchedCategoryComponent,
+    ProblematicComponent,
+    UnrecognizedComponent,
+    UnspecifiedComponent,
+)
 from ._relay import Relay
 from ._status import ComponentStatus
 from ._voltage_transformer import VoltageTransformer
@@ -72,14 +78,18 @@
     "InverterType",
     "LiIonBattery",
     "Meter",
+    "MismatchedCategoryComponent",
     "NaIonBattery",
     "Precharger",
+    "ProblematicComponent",
     "Relay",
     "SolarInverter",
     "UnrecognizedBattery",
+    "UnrecognizedComponent",
     "UnrecognizedEvCharger",
     "UnrecognizedInverter",
     "UnspecifiedBattery",
+    "UnspecifiedComponent",
     "UnspecifiedEvCharger",
     "UnspecifiedInverter",
     "VoltageTransformer",

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

@@ -39,8 +39,9 @@ class Component:  # pylint: disable=too-many-instance-attributes
         [`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, and in case some low level code needs to
-        know the category of a component.
+        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.
         """
 
     status: ComponentStatus | int = ComponentStatus.UNSPECIFIED
@@ -89,7 +90,8 @@ class Component:  # pylint: disable=too-many-instance-attributes
     Note:
         This should not be used normally, it is only useful when accessing a newer
         version of the API where the client doesn't know about the new metadata fields
-        yet.
+        yet (i.e. for use with
+        [`UnrecognizedComponent`][frequenz.client.microgrid.component.UnrecognizedComponent]).
     """
 
     def __new__(cls, *_: Any, **__: Any) -> Self:

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

@@ -0,0 +1,50 @@
+# License: MIT
+# Copyright © 2024 Frequenz Energy-as-a-Service GmbH
+
+"""Unknown component."""
+
+import dataclasses
+from typing import Any, Literal, Self
+
+from ._category import ComponentCategory
+from ._component import Component
+
+
+@dataclasses.dataclass(frozen=True, kw_only=True)
+class ProblematicComponent(Component):
+    """An abstract component with a problem."""
+
+    # pylint: disable-next=unused-argument
+    def __new__(cls, *args: Any, **kwargs: Any) -> Self:
+        """Prevent instantiation of this class."""
+        if cls is ProblematicComponent:
+            raise TypeError(f"Cannot instantiate {cls.__name__} directly")
+        return super().__new__(cls)
+
+
+@dataclasses.dataclass(frozen=True, kw_only=True)
+class UnspecifiedComponent(ProblematicComponent):
+    """A component of unspecified type."""
+
+    category: Literal[ComponentCategory.UNSPECIFIED] = ComponentCategory.UNSPECIFIED
+    """The category of this component."""
+
+
+@dataclasses.dataclass(frozen=True, kw_only=True)
+class UnrecognizedComponent(ProblematicComponent):
+    """A component of an unrecognized type."""
+
+    category: int
+    """The category of this component."""
+
+
+@dataclasses.dataclass(frozen=True, kw_only=True)
+class MismatchedCategoryComponent(ProblematicComponent):
+    """A component with a mismatch in the category.
+
+    This component declared a category but carries category specific metadata that
+    doesn't match the declared category.
+    """
+
+    category: ComponentCategory | int
+    """The category of this component."""

tests/component/test_problematic.py

@@ -0,0 +1,140 @@
+# License: MIT
+# Copyright © 2025 Frequenz Energy-as-a-Service GmbH
+
+"""Tests for ProblematicComponent components."""
+
+import pytest
+from frequenz.client.common.microgrid import MicrogridId
+from frequenz.client.common.microgrid.components import ComponentId
+
+from frequenz.client.microgrid.component import (
+    ComponentCategory,
+    ComponentStatus,
+    MismatchedCategoryComponent,
+    ProblematicComponent,
+    UnrecognizedComponent,
+    UnspecifiedComponent,
+)
+
+
+@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_problematic_component_cannot_be_instantiated(
+    component_id: ComponentId, microgrid_id: MicrogridId
+) -> None:
+    """Test that ProblematicComponent base class cannot be instantiated."""
+    with pytest.raises(
+        TypeError, match="Cannot instantiate ProblematicComponent directly"
+    ):
+        ProblematicComponent(
+            id=component_id,
+            microgrid_id=microgrid_id,
+            name="test_problematic",
+            manufacturer="test_manufacturer",
+            model_name="test_model",
+            status=ComponentStatus.ACTIVE,
+            category=ComponentCategory.UNSPECIFIED,
+        )
+
+
+def test_unspecified_component(
+    component_id: ComponentId, microgrid_id: MicrogridId
+) -> None:
+    """Test initialization and properties of UnspecifiedComponent."""
+    component = UnspecifiedComponent(
+        id=component_id,
+        microgrid_id=microgrid_id,
+        name="unspecified_component",
+        manufacturer="test_manufacturer",
+        model_name="test_model",
+        status=ComponentStatus.ACTIVE,
+    )
+
+    assert component.id == component_id
+    assert component.microgrid_id == microgrid_id
+    assert component.name == "unspecified_component"
+    assert component.manufacturer == "test_manufacturer"
+    assert component.model_name == "test_model"
+    assert component.status == ComponentStatus.ACTIVE
+    assert component.category == ComponentCategory.UNSPECIFIED
+
+
+def test_mismatched_category_component_with_known_category(
+    component_id: ComponentId, microgrid_id: MicrogridId
+) -> None:
+    """Test MismatchedCategoryComponent with a known ComponentCategory."""
+    expected_category = ComponentCategory.BATTERY
+    component = MismatchedCategoryComponent(
+        id=component_id,
+        microgrid_id=microgrid_id,
+        name="mismatched_battery",
+        manufacturer="test_manufacturer",
+        model_name="test_model",
+        status=ComponentStatus.ACTIVE,
+        category=expected_category,
+    )
+
+    assert component.id == component_id
+    assert component.microgrid_id == microgrid_id
+    assert component.name == "mismatched_battery"
+    assert component.manufacturer == "test_manufacturer"
+    assert component.model_name == "test_model"
+    assert component.status == ComponentStatus.ACTIVE
+    assert component.category == expected_category
+
+
+def test_mismatched_category_component_with_unrecognized_category(
+    component_id: ComponentId, microgrid_id: MicrogridId
+) -> None:
+    """Test MismatchedCategoryComponent with an unrecognized integer category."""
+    expected_category = 999
+    component = MismatchedCategoryComponent(
+        id=component_id,
+        microgrid_id=microgrid_id,
+        name="mismatched_unrecognized",
+        manufacturer="test_manufacturer",
+        model_name="test_model",
+        status=ComponentStatus.ACTIVE,
+        category=expected_category,
+    )
+
+    assert component.id == component_id
+    assert component.microgrid_id == microgrid_id
+    assert component.name == "mismatched_unrecognized"
+    assert component.manufacturer == "test_manufacturer"
+    assert component.model_name == "test_model"
+    assert component.status == ComponentStatus.ACTIVE
+    assert component.category == expected_category
+
+
+def test_unrecognized_component_type(
+    component_id: ComponentId, microgrid_id: MicrogridId
+) -> None:
+    """Test initialization and properties of UnrecognizedComponent type."""
+    component = UnrecognizedComponent(
+        id=component_id,
+        microgrid_id=microgrid_id,
+        name="unrecognized_component",
+        manufacturer="test_manufacturer",
+        model_name="test_model",
+        status=ComponentStatus.ACTIVE,
+        category=999,
+    )
+
+    assert component.id == component_id
+    assert component.microgrid_id == microgrid_id
+    assert component.name == "unrecognized_component"
+    assert component.manufacturer == "test_manufacturer"
+    assert component.model_name == "test_model"
+    assert component.status == ComponentStatus.ACTIVE
+    assert component.category == 999