Add UnknownEnumMixin for consistent handling of unknown enum values

Author: iMicknl

pyoverkiz/enums/base.py

@@ -0,0 +1,31 @@
+"""Shared enum helpers for consistent parsing and logging."""
+
+from __future__ import annotations
+
+import logging
+from enum import Enum
+from typing import TypeVar, cast
+
+_EnumT = TypeVar("_EnumT", bound=Enum)
+
+
+class UnknownEnumMixin:
+    """Mixin for enums that need an `UNKNOWN` fallback.
+
+    Define `UNKNOWN` on the enum and optionally override
+    `__missing_message__` to customize the log message.
+    """
+
+    __missing_message__ = "Unsupported value %s has been returned for %s"
+
+    @classmethod
+    def _missing_(cls, value):  # type: ignore[override]
+        """Return `UNKNOWN` and log unrecognized values."""
+        message = getattr(cls, "__missing_message__", cls.__missing_message__)
+        logging.getLogger(cls.__module__).warning(message, value, cls)
+        return cls.UNKNOWN
+
+    @classmethod
+    def from_value(cls: type[_EnumT], value: object) -> _EnumT:
+        """Return enum for `value`, falling back to `UNKNOWN`."""
+        return cast(_EnumT, cls(value))

pyoverkiz/enums/execution.py

@@ -1,13 +1,12 @@
 """Execution related enums (types, states and subtypes)."""
 
-import logging
 from enum import StrEnum, unique
 
-_LOGGER = logging.getLogger(__name__)
+from pyoverkiz.enums.base import UnknownEnumMixin
 
 
 @unique
-class ExecutionType(StrEnum):
+class ExecutionType(UnknownEnumMixin, StrEnum):
     """High-level execution categories returned by the API."""
 
     UNKNOWN = "UNKNOWN"
@@ -18,14 +17,9 @@ class ExecutionType(StrEnum):
     RAW_TRIGGER_SERVER = "Raw trigger (Server)"
     RAW_TRIGGER_GATEWAY = "Raw trigger (Gateway)"
 
-    @classmethod
-    def _missing_(cls, value):  # type: ignore
-        _LOGGER.warning(f"Unsupported value {value} has been returned for {cls}")
-        return cls.UNKNOWN
-
 
 @unique
-class ExecutionState(StrEnum):
+class ExecutionState(UnknownEnumMixin, StrEnum):
     """Execution lifecycle states."""
 
     UNKNOWN = "UNKNOWN"
@@ -38,14 +32,9 @@ class ExecutionState(StrEnum):
     QUEUED_GATEWAY_SIDE = "QUEUED_GATEWAY_SIDE"
     QUEUED_SERVER_SIDE = "QUEUED_SERVER_SIDE"
 
-    @classmethod
-    def _missing_(cls, value):  # type: ignore
-        _LOGGER.warning(f"Unsupported value {value} has been returned for {cls}")
-        return cls.UNKNOWN
-
 
 @unique
-class ExecutionSubType(StrEnum):
+class ExecutionSubType(UnknownEnumMixin, StrEnum):
     """Subtypes for execution reasons or sources."""
 
     UNKNOWN = "UNKNOWN"
@@ -63,8 +52,3 @@ class ExecutionSubType(StrEnum):
     NO_ERROR = "NO_ERROR"
     P2P_COMMAND_REGULATION = "P2P_COMMAND_REGULATION"
     TIME_TRIGGER = "TIME_TRIGGER"
-
-    @classmethod
-    def _missing_(cls, value):  # type: ignore
-        _LOGGER.warning(f"Unsupported value {value} has been returned for {cls}")
-        return cls.UNKNOWN

pyoverkiz/enums/protocol.py

@@ -1,13 +1,12 @@
 """Protocol enums describe device URL schemes used by Overkiz."""
 
-import logging
 from enum import StrEnum, unique
 
-_LOGGER = logging.getLogger(__name__)
+from pyoverkiz.enums.base import UnknownEnumMixin
 
 
 @unique
-class Protocol(StrEnum):
+class Protocol(UnknownEnumMixin, StrEnum):
     """Protocol used by Overkiz.
 
     Values have been retrieved from /reference/protocolTypes
@@ -46,7 +45,4 @@ class Protocol(StrEnum):
     ZIGBEE = "zigbee"
     ZWAVE = "zwave"
 
-    @classmethod
-    def _missing_(cls, value):  # type: ignore
-        _LOGGER.warning(f"Unsupported protocol {value} has been returned for {cls}")
-        return cls.UNKNOWN
+    __missing_message__ = "Unsupported protocol %s has been returned for %s"