Add a base class for creating IDs

Defining new IDs via the new base class is much simpler and concise now,
and avoids a lot of code duplication.

Please see the module documentation for more details.

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

Author: llucax

src/frequenz/client/microgrid/id.py

@@ -1,157 +1,218 @@
 # License: MIT
 # Copyright © 2025 Frequenz Energy-as-a-Service GmbH
 
-"""Strongly typed IDs for microgrids, components and sensors."""
+r'''Provides strongly-typed unique identifiers for entities.
 
+This module offers a base class,
+[`BaseId`][frequenz.client.microgrid.id.BaseId], which can be subclassed to
+create distinct ID types for different components or concepts within a system.
+These IDs ensure type safety, meaning that an ID for one type of entity (e.g., a
+sensor) cannot be mistakenly used where an ID for another type (e.g., a
+microgrid) is expected.
 
-from typing import final
+# Creating Custom ID Types
 
+To define a new ID type, create a class that inherits from
+[`BaseId`][frequenz.client.microgrid.id.BaseId] and provide a unique
+`str_prefix` as a keyword argument in the class definition. This prefix is used
+in the string representation of the ID and must be unique across all ID types.
 
-@final
-class MicrogridId:
-    """A unique identifier for a microgrid."""
+Note:
+    The `str_prefix` must be unique across all ID types. If you try to use a
+    prefix that is already registered, a `ValueError` will be raised when defining
+    the class.
 
-    def __init__(self, id_: int, /) -> None:
-        """Initialize this instance.
+To encourage consistency, the class name must end with the suffix "Id" (e.g.,
+`MyNewId`). This check can be bypassed by passing `allow_custom_name=True` when
+defining the class (e.g., `class MyCustomName(BaseId, str_prefix="MCN",
+allow_custom_name=True):`).
 
-        Args:
-            id_: The numeric unique identifier of the microgrid.
+Tip:
+    Use the [`@typing.final`][typing.final] decorator to prevent subclassing of
+    ID classes.
 
-        Raises:
-            ValueError: If the ID is negative.
-        """
-        if id_ < 0:
-            raise ValueError("Microgrid ID can't be negative.")
-        self._id = id_
+Example: Creating a standard ID type
+    ```python
+    from typing import final
+    from frequenz.client.microgrid.id import BaseId
 
-    def __int__(self) -> int:
-        """Return the numeric ID of this instance."""
-        return self._id
+    @final
+    class InverterId(BaseId, str_prefix="INV"):
+        """A unique identifier for an inverter."""
 
-    def __eq__(self, other: object) -> bool:
-        """Check if this instance is equal to another object."""
-        # This is not an unidiomatic typecheck, that's an odd name for the check.
-        # isinstance() returns True for subclasses, which is not what we want here.
-        # pylint: disable-next=unidiomatic-typecheck
-        return type(other) is MicrogridId and self._id == other._id
+    inv_id = InverterId(123)
+    print(inv_id)       # Output: INV123
+    print(int(inv_id))  # Output: 123
+    ```
 
-    def __lt__(self, other: object) -> bool:
-        """Check if this instance is less than another object."""
-        # pylint: disable-next=unidiomatic-typecheck
-        if type(other) is MicrogridId:
-            return self._id < other._id
-        return NotImplemented
+Example: Creating an ID type with a non-standard name
+    ```python
+    from typing import final
+    from frequenz.client.microgrid.id import BaseId
 
-    def __hash__(self) -> int:
-        """Return the hash of this instance."""
-        # We include the class because we explicitly want to avoid the same ID to give
-        # the same hash for different classes of IDs
-        return hash((MicrogridId, self._id))
+    @final
+    class CustomNameForId(BaseId, str_prefix="CST", allow_custom_name=True):
+        """An ID with a custom name, not ending in 'Id'."""
 
-    def __repr__(self) -> str:
-        """Return the string representation of this instance."""
-        return f"{type(self).__name__}({self._id!r})"
+    custom_id = CustomNameForId(456)
+    print(custom_id)       # Output: CST456
+    print(int(custom_id))  # Output: 456
+    ```
 
-    def __str__(self) -> str:
-        """Return the short string representation of this instance."""
-        return f"MID{self._id}"
+# Predefined ID Types
 
+This module predefines the following ID types:
 
-@final
-class ComponentId:
-    """A unique identifier for a microgrid component."""
+- [`ComponentId`][frequenz.client.microgrid.id.ComponentId]: For identifying
+    generic components.
+- [`MicrogridId`][frequenz.client.microgrid.id.MicrogridId]: For identifying
+    microgrids.
+- [`SensorId`][frequenz.client.microgrid.id.SensorId]: For identifying sensors.
+'''
 
-    def __init__(self, id_: int, /) -> None:
-        """Initialize this instance.
 
-        Args:
-            id_: The numeric unique identifier of the microgrid component.
+from typing import Any, ClassVar, Self, cast, final
 
-        Raises:
-            ValueError: If the ID is negative.
-        """
-        if id_ < 0:
-            raise ValueError("Component ID can't be negative.")
-        self._id = id_
 
-    def __int__(self) -> int:
-        """Return the numeric ID of this instance."""
-        return self._id
+class BaseId:
+    """A base class for unique identifiers.
 
-    def __eq__(self, other: object) -> bool:
-        """Check if this instance is equal to another object."""
-        # This is not an unidiomatic typecheck, that's an odd name for the check.
-        # isinstance() returns True for subclasses, which is not what we want here.
-        # pylint: disable-next=unidiomatic-typecheck
-        return type(other) is ComponentId and self._id == other._id
+    Subclasses must provide a unique `str_prefix` keyword argument during
+    definition, which is used in the string representation of the ID.
 
-    def __lt__(self, other: object) -> bool:
-        """Check if this instance is less than another object."""
-        # pylint: disable-next=unidiomatic-typecheck
-        if type(other) is ComponentId:
-            return self._id < other._id
-        return NotImplemented
+    By default, subclass names must end with "Id". This can be overridden by
+    passing `allow_custom_name=True` during class definition.
 
-    def __hash__(self) -> int:
-        """Return the hash of this instance."""
-        # We include the class because we explicitly want to avoid the same ID to give
-        # the same hash for different classes of IDs
-        return hash((ComponentId, self._id))
+    For more information and examples, see the [module's
+    documentation][frequenz.client.microgrid.id].
+    """
 
-    def __repr__(self) -> str:
-        """Return the string representation of this instance."""
-        return f"{type(self).__name__}({self._id!r})"
+    _id: int
+    _str_prefix: ClassVar[str]
+    _registered_prefixes: ClassVar[set[str]] = set()
 
-    def __str__(self) -> str:
-        """Return the short string representation of this instance."""
-        return f"CID{self._id}"
+    def __new__(cls, *_: Any, **__: Any) -> Self:
+        """Create a new instance of the ID class, only if it is a subclass of BaseId."""
+        if cls is BaseId:
+            raise TypeError("BaseId cannot be instantiated directly. Use a subclass.")
+        return super().__new__(cls)
 
+    def __init_subclass__(
+        cls,
+        *,
+        str_prefix: str,
+        allow_custom_name: bool = False,
+        **kwargs: Any,
+    ) -> None:
+        """Initialize a subclass, set its string prefix, and perform checks.
 
-@final
-class SensorId:
-    """A unique identifier for a microgrid sensor."""
+        Args:
+            str_prefix: The string prefix for the ID type (e.g., "MID").
+                Must be unique across all ID types.
+            allow_custom_name: If True, bypasses the check that the class name
+                must end with "Id". Defaults to False.
+            **kwargs: Forwarded to the parent's __init_subclass__.
+
+        Raises:
+            ValueError: If the `str_prefix` is already registered by another
+                ID type.
+            TypeError: If `allow_custom_name` is False and the class name
+                does not end with "Id".
+        """
+        super().__init_subclass__(**kwargs)
+
+        if str_prefix in BaseId._registered_prefixes:
+            raise ValueError(
+                f"Prefix '{str_prefix}' is already registered. "
+                "ID prefixes must be unique."
+            )
+        BaseId._registered_prefixes.add(str_prefix)
+
+        if not allow_custom_name and not cls.__name__.endswith("Id"):
+            raise TypeError(
+                f"Class name '{cls.__name__}' for an ID class must end with 'Id' "
+                "(e.g., 'SomeId'), or use `allow_custom_name=True`."
+            )
+
+        cls._str_prefix = str_prefix
 
     def __init__(self, id_: int, /) -> None:
         """Initialize this instance.
 
         Args:
-            id_: The numeric unique identifier of the microgrid sensor.
+            id_: The numeric unique identifier.
 
         Raises:
             ValueError: If the ID is negative.
         """
         if id_ < 0:
-            raise ValueError("Sensor ID can't be negative.")
+            raise ValueError(f"{type(self).__name__} can't be negative.")
         self._id = id_
 
+    @property
+    def str_prefix(self) -> str:
+        """The prefix used for the string representation of this ID."""
+        return self._str_prefix
+
     def __int__(self) -> int:
         """Return the numeric ID of this instance."""
         return self._id
 
     def __eq__(self, other: object) -> bool:
-        """Check if this instance is equal to another object."""
-        # This is not an unidiomatic typecheck, that's an odd name for the check.
-        # isinstance() returns True for subclasses, which is not what we want here.
+        """Check if this instance is equal to another object.
+
+        Equality is defined as being of the exact same type and having the same
+        underlying ID.
+        """
+        # pylint thinks this is not an unidiomatic typecheck, but in this case
+        # it is not. isinstance() returns True for subclasses, which is not
+        # what we want here, as different ID types should never be equal.
         # pylint: disable-next=unidiomatic-typecheck
-        return type(other) is SensorId and self._id == other._id
+        if type(other) is not type(self):
+            return NotImplemented
+        # We already checked type(other) is type(self), but mypy doesn't
+        # understand that, so we need to cast it to Self.
+        other_id = cast(Self, other)
+        return self._id == other_id._id
 
     def __lt__(self, other: object) -> bool:
-        """Check if this instance is less than another object."""
+        """Check if this instance is less than another object.
+
+        Comparison is only defined between instances of the exact same type.
+        """
         # pylint: disable-next=unidiomatic-typecheck
-        if type(other) is SensorId:
-            return self._id < other._id
-        return NotImplemented
+        if type(other) is not type(self):
+            return NotImplemented
+        other_id = cast(Self, other)
+        return self._id < other_id._id
 
     def __hash__(self) -> int:
-        """Return the hash of this instance."""
-        # We include the class because we explicitly want to avoid the same ID to give
-        # the same hash for different classes of IDs
-        return hash((SensorId, self._id))
+        """Return the hash of this instance.
+
+        The hash is based on the exact type and the underlying ID to ensure
+        that IDs of different types but with the same numeric value have different hashes.
+        """
+        return hash((type(self), self._id))
 
     def __repr__(self) -> str:
         """Return the string representation of this instance."""
         return f"{type(self).__name__}({self._id!r})"
 
     def __str__(self) -> str:
         """Return the short string representation of this instance."""
-        return f"SID{self._id}"
+        return f"{type(self)._str_prefix}{self._id}"
+
+
+@final
+class MicrogridId(BaseId, str_prefix="MID"):
+    """A unique identifier for a microgrid."""
+
+
+@final
+class ComponentId(BaseId, str_prefix="CID"):
+    """A unique identifier for a microgrid component."""
+
+
+@final
+class SensorId(BaseId, str_prefix="SID"):
+    """A unique identifier for a microgrid sensor."""

tests/test_id.py

@@ -16,14 +16,13 @@ class IdTypeInfo:
 
     id_class: type
     str_prefix: str
-    error_prefix: str
 
 
 # Define all ID types to test here
 ID_TYPES: list[IdTypeInfo] = [
-    IdTypeInfo(MicrogridId, "MID", "Microgrid"),
-    IdTypeInfo(ComponentId, "CID", "Component"),
-    IdTypeInfo(SensorId, "SID", "Sensor"),
+    IdTypeInfo(MicrogridId, "MID"),
+    IdTypeInfo(ComponentId, "CID"),
+    IdTypeInfo(SensorId, "SID"),
 ]
 
 
@@ -42,7 +41,7 @@ def test_valid_id(self, type_info: IdTypeInfo) -> None:
 
     def test_negative_id_raises(self, type_info: IdTypeInfo) -> None:
         """Test that creating a negative ID raises ValueError."""
-        error_msg = f"{type_info.error_prefix} ID can't be negative"
+        error_msg = f"{type_info.id_class.__name__} can't be negative"
         with pytest.raises(ValueError, match=error_msg):
             type_info.id_class(-1)