Add the base Component class

This class will be used to combine classic inheritance (all components
will derive from it), a mix-in to provide common functionality of all
components, and also build "algebraic data types", so they can be used
in `match` statements and easily do exhaustion checks to make sure all
possible types of components are handled when needed.

Note it doesn't make sense to make this a `abc.ABC` because there are no
abstract methods.

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

Author: llucax

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

@@ -0,0 +1,14 @@
+# License: MIT
+# Copyright © 2025 Frequenz Energy-as-a-Service GmbH
+
+"""All classes and functions related to microgrid components."""
+
+from ._category import ComponentCategory
+from ._component import Component
+from ._status import ComponentStatus
+
+__all__ = [
+    "Component",
+    "ComponentCategory",
+    "ComponentStatus",
+]

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

@@ -0,0 +1,80 @@
+# License: MIT
+# Copyright © 2024 Frequenz Energy-as-a-Service GmbH
+
+"""The component categories that can be used in a microgrid."""
+
+import enum
+
+from frequenz.api.common.v1.microgrid.components import components_pb2
+
+
+@enum.unique
+class ComponentCategory(enum.Enum):
+    """The known categories of components that can be present in a microgrid."""
+
+    UNSPECIFIED = components_pb2.COMPONENT_CATEGORY_UNSPECIFIED
+    """The component category is unspecified, probably due to an error in the message."""
+
+    GRID = components_pb2.COMPONENT_CATEGORY_GRID
+    """The point where the local microgrid is connected to the grid."""
+
+    METER = components_pb2.COMPONENT_CATEGORY_METER
+    """A meter, for measuring electrical metrics, e.g., current, voltage, etc."""
+
+    INVERTER = components_pb2.COMPONENT_CATEGORY_INVERTER
+    """An electricity generator, with batteries or solar energy."""
+
+    CONVERTER = components_pb2.COMPONENT_CATEGORY_CONVERTER
+    """A DC-DC converter."""
+
+    BATTERY = components_pb2.COMPONENT_CATEGORY_BATTERY
+    """A storage system for electrical energy, used by inverters."""
+
+    EV_CHARGER = components_pb2.COMPONENT_CATEGORY_EV_CHARGER
+    """A station for charging electrical vehicles."""
+
+    CRYPTO_MINER = components_pb2.COMPONENT_CATEGORY_CRYPTO_MINER
+    """A crypto miner."""
+
+    ELECTROLYZER = components_pb2.COMPONENT_CATEGORY_ELECTROLYZER
+    """An electrolyzer for converting water into hydrogen and oxygen."""
+
+    CHP = components_pb2.COMPONENT_CATEGORY_CHP
+    """A heat and power combustion plant (CHP stands for combined heat and power)."""
+
+    RELAY = components_pb2.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 = components_pb2.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 = components_pb2.COMPONENT_CATEGORY_FUSE
+    """A fuse."""
+
+    VOLTAGE_TRANSFORMER = components_pb2.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 = components_pb2.COMPONENT_CATEGORY_HVAC
+    """A Heating, Ventilation, and Air Conditioning (HVAC) system."""

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

@@ -0,0 +1,159 @@
+# License: MIT
+# Copyright © 2024 Frequenz Energy-as-a-Service GmbH
+
+"""Base component from which all other components inherit."""
+
+import dataclasses
+import logging
+from collections.abc import Mapping
+from datetime import datetime, timezone
+from typing import Any, Self
+
+from frequenz.client.common.microgrid import MicrogridId
+from frequenz.client.common.microgrid.components import ComponentId
+
+from .._lifetime import Lifetime
+from ..metrics._bounds import Bounds
+from ..metrics._metric import Metric
+from ._category import ComponentCategory
+from ._status import ComponentStatus
+
+_logger = logging.getLogger(__name__)
+
+
+@dataclasses.dataclass(frozen=True, kw_only=True)
+class Component:  # pylint: disable=too-many-instance-attributes
+    """A base class for all components."""
+
+    id: ComponentId
+    """This component's ID."""
+
+    microgrid_id: MicrogridId
+    """The ID of the microgrid this component belongs to."""
+
+    category: ComponentCategory | int
+    """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.
+        """
+
+    status: ComponentStatus | int = ComponentStatus.UNSPECIFIED
+    """The status of this component.
+
+    Tip:
+        You can also use
+        [`is_active_now()`][frequenz.client.microgrid.component.Component.is_active_now]
+        or
+        [`is_active_at()`][frequenz.client.microgrid.component.Component.is_active_at],
+        which also checks if the component is operational.
+    """
+
+    name: str | None = None
+    """The name of this component."""
+
+    manufacturer: str | None = None
+    """The manufacturer of this component."""
+
+    model_name: str | None = None
+    """The model name of this component."""
+
+    operational_lifetime: Lifetime = dataclasses.field(default_factory=Lifetime)
+    """The operational lifetime of this component."""
+
+    rated_bounds: Mapping[Metric | int, Bounds] = dataclasses.field(
+        default_factory=dict,
+        # dict is not hashable, so we don't use this field to calculate the hash. This
+        # shouldn't be a problem since it is very unlikely that two components with all
+        # other attributes being equal would have different category specific metadata,
+        # so hash collisions should be still very unlikely.
+        hash=False,
+    )
+    """List of rated bounds present for the component identified by Metric."""
+
+    category_specific_metadata: Mapping[str, Any] = dataclasses.field(
+        default_factory=dict,
+        # dict is not hashable, so we don't use this field to calculate the hash. This
+        # shouldn't be a problem since it is very unlikely that two components with all
+        # other attributes being equal would have different category specific metadata,
+        # so hash collisions should be still very unlikely.
+        hash=False,
+    )
+    """The category specific metadata of this component.
+
+    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 (i.e. for use with
+        [`UnrecognizedComponent`][frequenz.client.microgrid.component.UnrecognizedComponent]).
+    """
+
+    def __new__(cls, *_: Any, **__: Any) -> Self:
+        """Prevent instantiation of this class."""
+        if cls is Component:
+            raise TypeError(f"Cannot instantiate {cls.__name__} directly")
+        return super().__new__(cls)
+
+    def is_active_at(self, timestamp: datetime) -> bool:
+        """Check whether this component is active at a specific timestamp.
+
+        A component is considered active if it is in the active state and is
+        operational at the given timestamp. The operational lifetime is used to
+        determine whether the component is operational at the given timestamp.
+
+        If a component has an unspecified status, it is assumed to be active
+        and a warning is logged.
+
+        Args:
+            timestamp: The timestamp to check.
+
+        Returns:
+            Whether this component is active at the given timestamp.
+        """
+        if self.status is ComponentStatus.UNSPECIFIED:
+            _logger.warning(
+                "Component %s has an unspecified status. Assuming it is active.",
+                self,
+            )
+            return self.operational_lifetime.is_operational_at(timestamp)
+
+        return (
+            self.status is ComponentStatus.ACTIVE
+            and self.operational_lifetime.is_operational_at(timestamp)
+        )
+
+    def is_active_now(self) -> bool:
+        """Check whether this component is currently active.
+
+        A component is considered active if it is in the active state and is
+        operational at the current time. The operational lifetime is used to
+        determine whether the component is operational at the current time.
+
+        If a component has an unspecified status, it is assumed to be active
+        and a warning is logged.
+
+        Returns:
+            Whether this component is active at the current time.
+        """
+        return self.is_active_at(datetime.now(timezone.utc))
+
+    @property
+    def identity(self) -> tuple[ComponentId, MicrogridId]:
+        """The identity of this component.
+
+        This uses the component ID and microgrid ID to identify a component
+        without considering the other attributes, so even if a component state
+        changed, the identity remains the same.
+        """
+        return (self.id, self.microgrid_id)
+
+    def __str__(self) -> str:
+        """Return a human-readable string representation of this instance."""
+        name = f":{self.name}" if self.name else ""
+        return f"{self.id}<{type(self).__name__}>{name}"

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

@@ -0,0 +1,22 @@
+# License: MIT
+# Copyright © 2024 Frequenz Energy-as-a-Service GmbH
+
+"""Status for a component."""
+
+import enum
+
+from frequenz.api.common.v1.microgrid.components import components_pb2
+
+
+@enum.unique
+class ComponentStatus(enum.Enum):
+    """The known statuses of a component."""
+
+    UNSPECIFIED = components_pb2.COMPONENT_STATUS_UNSPECIFIED
+    """The status is unspecified."""
+
+    ACTIVE = components_pb2.COMPONENT_STATUS_ACTIVE
+    """The component is active."""
+
+    INACTIVE = components_pb2.COMPONENT_STATUS_INACTIVE
+    """The component is inactive."""

tests/component/__init__.py

@@ -0,0 +1 @@
+"""Tests for components."""