Improve error handling and add comprehensive client tests (#2007)

## Summary
- Fix `get_current_execution` crashing on empty responses (cloud returns
`{}`, local returns `[]` or `null`)
- Make `ActionGroup.id` and `ActionGroup.oid` optional (`str | None`) —
inline action groups from `exec/current` don't carry identifiers
- Add `start_time`, `execution_type`, and `execution_sub_type` fields to
`Execution` model (matching real API responses)
- Change `Execution.state` from `str` to `ExecutionState` enum
(consistent with `HistoryExecution`)
- Add `NoSuchDeviceError` and `NoSuchActionGroupError` exception types
with response handler mappings
- Add 8 new cloud exception fixture tests and 6 new cloud exception JSON
fixtures
- Add 13 cloud client tests covering executions, history, state, places,
action groups, and event listeners
- Add 10 local API tests verifying proper error handling for KizOs
gateway differences

## Breaking changes
- `Execution.state` is now `ExecutionState` instead of `str`,
`ActionGroup.id` and `ActionGroup.oid` are now `str | None` instead of
`str`, `get_current_execution` now returns `Execution | None` instead of
`Execution`

## Test plan
- [x] All 311 unit tests pass
- [x] All prek checks pass (ruff, mypy, ty)
- [x] Validated against real Somfy cloud API (37/37 probes pass)
- [x] Validated against real local KizOs gateway (37/37 probes pass)
- [x] JSON fixtures verified against real API response structures

Author: iMicknl

pyoverkiz/client.py

@@ -447,9 +447,16 @@ async def unregister_event_listener(self) -> None:
         self.event_listener_id = None
 
     @retry_on_auth_error
-    async def get_current_execution(self, exec_id: str) -> Execution:
-        """Get a currently running execution by its exec_id."""
+    async def get_current_execution(self, exec_id: str) -> Execution | None:
+        """Get a currently running execution by its exec_id.
+
+        Returns None if the execution does not exist.
+        """
         response = await self._get(f"exec/current/{exec_id}")
+
+        if not response or not isinstance(response, dict):
+            return None
+
         return Execution(**decamelize(response))
 
     @retry_on_auth_error

pyoverkiz/exceptions.py

@@ -97,6 +97,14 @@ class UnknownUserError(BaseOverkizError):
     """Raised when an unknown user is provided."""
 
 
+class NoSuchDeviceError(BaseOverkizError):
+    """Raised when the requested device does not exist."""
+
+
+class NoSuchActionGroupError(BaseOverkizError):
+    """Raised when the requested action group does not exist."""
+
+
 class UnknownObjectError(BaseOverkizError):
     """Raised when an unknown object is provided."""
 

pyoverkiz/models.py

@@ -805,8 +805,11 @@ class Execution:
     id: str
     description: str
     owner: str = field(repr=obfuscate_email)
-    state: str
+    state: ExecutionState
     action_group: ActionGroup
+    start_time: int | None = None
+    execution_type: ExecutionType | None = None
+    execution_sub_type: ExecutionSubType | None = None
 
     def __init__(
         self,
@@ -815,14 +818,22 @@ def __init__(
         owner: str,
         state: str,
         action_group: dict[str, Any],
+        start_time: int | None = None,
+        execution_type: str | None = None,
+        execution_sub_type: str | None = None,
         **_: Any,
     ):
         """Initialize Execution object from API fields."""
         self.id = id
         self.description = description
         self.owner = owner
-        self.state = state
+        self.state = ExecutionState(state)
         self.action_group = ActionGroup(**action_group)
+        self.start_time = start_time
+        self.execution_type = ExecutionType(execution_type) if execution_type else None
+        self.execution_sub_type = (
+            ExecutionSubType(execution_sub_type) if execution_sub_type else None
+        )
 
 
 @define(init=False, kw_only=True)
@@ -858,7 +869,7 @@ class ActionGroup:
     is composed of one or more commands to be executed on that device.
     """
 
-    id: str = field(repr=obfuscate_id)
+    id: str | None = field(default=None, repr=obfuscate_id)
     creation_time: int | None = None
     last_update_time: int | None = None
     label: str = field(repr=obfuscate_string)
@@ -869,7 +880,7 @@ class ActionGroup:
     notification_text: str | None = None
     notification_title: str | None = None
     actions: list[Action]
-    oid: str = field(repr=obfuscate_id)
+    oid: str | None = field(default=None, repr=obfuscate_id)
 
     def __init__(
         self,
@@ -888,10 +899,7 @@ def __init__(
         **_: Any,
     ) -> None:
         """Initialize ActionGroup from API data and convert nested actions."""
-        if oid is None and id is None:
-            raise ValueError("Either 'oid' or 'id' must be provided")
-
-        self.id = cast(str, oid or id)
+        self.id = oid or id
         self.creation_time = creation_time
         self.last_update_time = last_update_time
         self.label = (
@@ -904,7 +912,7 @@ def __init__(
         self.notification_text = notification_text
         self.notification_title = notification_title
         self.actions = [Action(**action) for action in actions]
-        self.oid = cast(str, oid or id)
+        self.oid = oid or id
 
 
 @define(init=False, kw_only=True)

pyoverkiz/response_handler.py

@@ -22,6 +22,8 @@
     MissingAPIKeyError,
     MissingAuthorizationTokenError,
     NoRegisteredEventListenerError,
+    NoSuchActionGroupError,
+    NoSuchDeviceError,
     NoSuchResourceError,
     NoSuchTokenError,
     NotAuthenticatedError,
@@ -46,6 +48,8 @@
     ("INVALID_FIELD_VALUE", None, ActionGroupSetupNotFoundError),
     ("INVALID_API_CALL", None, NoSuchResourceError),
     ("EXEC_QUEUE_FULL", None, ExecutionQueueFullError),
+    ("NO_SUCH_DEVICE", None, NoSuchDeviceError),
+    ("NO_SUCH_ACTION_GROUP", None, NoSuchActionGroupError),
     # --- errorCode + message substring ---
     ("AUTHENTICATION_ERROR", "Too many requests", TooManyRequestsError),
     ("AUTHENTICATION_ERROR", "Bad credentials", BadCredentialsError),

tests/fixtures/endpoints/device-states.json

@@ -0,0 +1,17 @@
+[
+    {
+        "name": "core:StatusState",
+        "type": 3,
+        "value": "available"
+    },
+    {
+        "name": "core:ClosureState",
+        "type": 1,
+        "value": 0
+    },
+    {
+        "name": "core:OpenClosedState",
+        "type": 3,
+        "value": "open"
+    }
+]

tests/fixtures/endpoints/events-register.json

@@ -0,0 +1 @@
+{"id": "a70f6d96-0a19-0483-72d9-ac5f6bd7da26"}

tests/fixtures/endpoints/exec-apply.json

@@ -0,0 +1 @@
+{"execId": "ee7a5676-c68f-43a3-956d-6f5efc745954"}

tests/fixtures/endpoints/exec-current-empty-list.json

@@ -0,0 +1 @@
+[]

tests/fixtures/endpoints/exec-current-empty-object.json

@@ -0,0 +1 @@
+{}

tests/fixtures/endpoints/exec-schedule.json

@@ -0,0 +1 @@
+{"triggerId": "abc12345-def6-7890-abcd-ef1234567890"}