Eliminate recursive decamelize pre-pass (~43% faster structuring) (#2062)

## Summary

- Replace the two-pass approach (recursive `decamelize()` key rename +
cattrs structure) with single-pass cattrs rename hooks via
`register_structure_hook_factory` +
`make_dict_structure_fn(override(rename=...))`
- Handle non-standard API casing (`deviceURL`, `placeOID`, `setupOID`)
directly in `camelize_key`
- Simplify `serializers.py` which no longer needs its own post-camelize
fixup

## Benchmark

Measured across all 25 setup fixtures + devices.json (median of 5 runs,
100 iterations each):

| | Old (decamelize + structure) | New (single-pass) | Speedup |
|---|---|---|---|
| **Full pass (all fixtures)** | 16.6 ms | 9.6 ms | **1.7x (42%
faster)** |

Per-call for the largest fixtures:

| Fixture | Old | New | Speedup |
|---|---|---|---|
| `setup_tahoma_daikin.json` | 2.23 ms | 1.36 ms | 1.6x |
| `setup_3_gateways.json` | 1.66 ms | 0.84 ms | 2.0x |
| `setup_cozytouch_4.json` | 1.28 ms | 0.72 ms | 1.8x |
| `setup_hue_and_low_speed.json` | 1.25 ms | 0.73 ms | 1.7x |
| `setup_local_with_climate.json` | 1.26 ms | 0.57 ms | 2.2x |

## Breaking changes

- `structure_response()` no longer calls `decamelize()` — it expects
camelCase input directly (which is what the API sends)
- `camelize_key()` now returns `deviceURL`/`placeOID`/`setupOID` for
those fields (previously required a post-fixup in serializers)
- `decamelize()` / `recursive_key_map()` remain available in
`pyoverkiz._case` but are no longer on the hot path

## Test plan

- [x] All 438 existing tests pass
- [x] mypy + ty type checking pass
- [x] ruff lint + format pass

Author: iMicknl

pyoverkiz/_case.py

@@ -3,19 +3,9 @@
 from __future__ import annotations
 
 import functools
-import re
 from collections.abc import Callable
 from typing import Any
 
-_CAMEL_RE = re.compile(r"([A-Z]+)([A-Z][a-z])|([a-z\d])([A-Z])")
-
-
-@functools.lru_cache(maxsize=1024)
-def _decamelize_key(key: str) -> str:
-    """Convert a single camelCase key to snake_case."""
-    result = _CAMEL_RE.sub(r"\1\3_\2\4", key)
-    return result.lower()
-
 
 def recursive_key_map(data: Any, key_fn: Callable[[str], str]) -> Any:
     """Recursively apply *key_fn* to every dict key in *data*."""
@@ -26,13 +16,20 @@ def recursive_key_map(data: Any, key_fn: Callable[[str], str]) -> Any:
     return data
 
 
-def decamelize(data: Any) -> Any:
-    """Recursively convert dict keys from camelCase to snake_case."""
-    return recursive_key_map(data, _decamelize_key)
+_CAMELIZE_OVERRIDES: dict[str, str] = {
+    "device_url": "deviceURL",
+    "place_oid": "placeOID",
+    "setup_oid": "setupOID",
+}
 
 
 @functools.lru_cache(maxsize=1024)
 def camelize_key(key: str) -> str:
-    """Convert a single snake_case key to camelCase."""
+    """Convert a single snake_case key to camelCase.
+
+    Handles non-standard API casing (e.g. deviceURL, placeOID) via overrides.
+    """
+    if key in _CAMELIZE_OVERRIDES:
+        return _CAMELIZE_OVERRIDES[key]
     parts = key.split("_")
     return parts[0] + "".join(word.capitalize() for word in parts[1:])

pyoverkiz/client.py

@@ -24,7 +24,7 @@
 from pyoverkiz.action_queue import ActionQueue, ActionQueueSettings
 from pyoverkiz.auth import AuthStrategy, Credentials, build_auth_strategy
 from pyoverkiz.const import SUPPORTED_SERVERS, USER_AGENT
-from pyoverkiz.converter import converter, structure_response
+from pyoverkiz.converter import converter
 from pyoverkiz.enums import APIType, ExecutionMode, Protocol, Server
 from pyoverkiz.exceptions import (
     ExecutionQueueFullError,
@@ -333,7 +333,7 @@ async def get_setup(self, refresh: bool = False) -> Setup:
 
         response = await self._get("setup")
 
-        setup = structure_response(response, Setup)
+        setup = converter.structure(response, Setup)
 
         # Cache response
         self.setup = setup
@@ -381,7 +381,7 @@ async def get_devices(self, refresh: bool = False) -> list[Device]:
             return self.devices
 
         response = await self._get("setup/devices")
-        devices = structure_response(response, list[Device])
+        devices = converter.structure(response, list[Device])
 
         # Cache response
         self.devices = devices
@@ -400,7 +400,7 @@ async def get_gateways(self, refresh: bool = False) -> list[Gateway]:
             return self.gateways
 
         response = await self._get("setup/gateways")
-        gateways = structure_response(response, list[Gateway])
+        gateways = converter.structure(response, list[Gateway])
 
         # Cache response
         self.gateways = gateways
@@ -413,7 +413,7 @@ async def get_gateways(self, refresh: bool = False) -> list[Gateway]:
     async def get_execution_history(self) -> list[HistoryExecution]:
         """List past executions and their outcomes."""
         response = await self._get("history/executions")
-        return structure_response(response, list[HistoryExecution])
+        return converter.structure(response, list[HistoryExecution])
 
     @retry_on_auth_error
     async def get_device_definition(self, device_url: str) -> Definition | None:
@@ -426,15 +426,15 @@ async def get_device_definition(self, device_url: str) -> Definition | None:
         if raw is None:
             return None
 
-        return structure_response(raw, Definition)
+        return converter.structure(raw, Definition)
 
     @retry_on_auth_error
     async def get_state(self, device_url: str) -> list[State]:
         """Retrieve states of requested device."""
         response = await self._get(
             f"setup/devices/{urllib.parse.quote_plus(device_url)}/states"
         )
-        return structure_response(response, list[State])
+        return converter.structure(response, list[State])
 
     @retry_on_auth_error
     async def refresh_states(self) -> None:
@@ -477,7 +477,7 @@ async def fetch_events(self) -> list[Event]:
         operation (polling).
         """
         response = await self._post(f"events/{self.event_listener_id}/fetch")
-        return structure_response(response, list[Event])
+        return converter.structure(response, list[Event])
 
     async def unregister_event_listener(self) -> None:
         """Unregister an event listener.
@@ -497,13 +497,13 @@ async def get_current_execution(self, exec_id: str) -> Execution | None:
         if not response or not isinstance(response, dict):
             return None
 
-        return structure_response(response, Execution)
+        return converter.structure(response, Execution)
 
     @retry_on_auth_error
     async def get_current_executions(self) -> list[Execution]:
         """Get all currently running executions."""
         response = await self._get("exec/current")
-        return structure_response(response, list[Execution])
+        return converter.structure(response, list[Execution])
 
     @retry_on_auth_error
     async def get_api_version(self) -> str:
@@ -641,7 +641,7 @@ async def cancel_execution(self, exec_id: str) -> None:
     async def get_action_groups(self) -> list[PersistedActionGroup]:
         """List action groups persisted on the server."""
         response = await self._get("actionGroups")
-        return structure_response(response, list[PersistedActionGroup])
+        return converter.structure(response, list[PersistedActionGroup])
 
     @retry_on_auth_error
     async def get_places(self) -> Place:
@@ -656,7 +656,7 @@ async def get_places(self) -> Place:
         - `sub_places`: List of nested places within this location
         """
         response = await self._get("setup/places")
-        return structure_response(response, Place)
+        return converter.structure(response, Place)
 
     @retry_on_auth_error
     async def execute_persisted_action_group(self, oid: str) -> str:
@@ -678,7 +678,7 @@ async def get_setup_options(self) -> list[Option]:
         Access scope : Full enduser API access (enduser/*).
         """
         response = await self._get("setup/options")
-        return structure_response(response, list[Option])
+        return converter.structure(response, list[Option])
 
     @retry_on_auth_error
     async def get_setup_option(self, option: str) -> Option | None:
@@ -689,7 +689,7 @@ async def get_setup_option(self, option: str) -> Option | None:
         response = await self._get(f"setup/options/{option}")
 
         if response:
-            return structure_response(response, Option)
+            return converter.structure(response, Option)
 
         return None
 
@@ -707,7 +707,7 @@ async def get_setup_option_parameter(
         response = await self._get(f"setup/options/{option}/{parameter}")
 
         if response:
-            return structure_response(response, OptionParameter)
+            return converter.structure(response, OptionParameter)
 
         return None
 
@@ -745,7 +745,7 @@ async def search_reference_devices(
             }
         """
         response = await self._post("reference/devices/search", payload)
-        return structure_response(response, DeviceSearchResult)
+        return converter.structure(response, DeviceSearchResult)
 
     @retry_on_auth_error
     async def get_reference_protocol_types(self) -> list[ProtocolType]:
@@ -758,7 +758,6 @@ async def get_reference_protocol_types(self) -> list[ProtocolType]:
         - label: Human-readable protocol label
         """
         response = await self._get("reference/protocolTypes")
-        # No decamelize — ProtocolType fields are all single-word lowercase already.
         return converter.structure(response, list[ProtocolType])
 
     @retry_on_auth_error
@@ -789,7 +788,7 @@ async def get_reference_ui_profile(self, profile_name: str) -> UIProfileDefiniti
         response = await self._get(
             f"reference/ui/profile/{urllib.parse.quote_plus(profile_name)}"
         )
-        return structure_response(response, UIProfileDefinition)
+        return converter.structure(response, UIProfileDefinition)
 
     @retry_on_auth_error
     async def get_reference_ui_profile_names(self) -> list[str]:
@@ -805,7 +804,7 @@ async def get_reference_ui_widgets(self) -> list[str]:
     async def get_devices_not_up_to_date(self) -> list[Device]:
         """Get all devices whose firmware is not up to date."""
         response = await self._get("setup/devices/notUpToDate")
-        return structure_response(response, list[Device])
+        return converter.structure(response, list[Device])
 
     @retry_on_auth_error
     async def get_device_firmware_status(
@@ -821,7 +820,7 @@ async def get_device_firmware_status(
             )
         except UnsupportedOperationError:
             return None
-        return structure_response(response, FirmwareStatus)
+        return converter.structure(response, FirmwareStatus)
 
     @retry_on_auth_error
     async def get_device_firmware_update_capability(self, device_url: str) -> bool:
@@ -868,7 +867,7 @@ async def get_device_controllable_definition(
         )
         if response is None:
             return None
-        return structure_response(response, Definition)
+        return converter.structure(response, Definition)
 
     @retry_on_auth_error
     async def get_device_alternative_controllables(self, device_url: str) -> list[str]:
@@ -885,7 +884,7 @@ async def get_device_manufacturer_references(
         response = await self._get(
             f"setup/devices/{urllib.parse.quote_plus(device_url)}/manufacturerReferences"
         )
-        return structure_response(response, list[DeviceManufacturerReference])
+        return converter.structure(response, list[DeviceManufacturerReference])
 
     async def _get(self, path: str) -> Any:
         """Make a GET request to the OverKiz API."""

pyoverkiz/converter.py

@@ -8,8 +8,9 @@
 
 import attr
 import cattrs
+from cattrs.gen import make_dict_structure_fn, override
 
-from pyoverkiz._case import decamelize
+from pyoverkiz._case import camelize_key
 from pyoverkiz.models import (
     CommandDefinition,
     CommandDefinitions,
@@ -32,10 +33,23 @@ def _is_primitive_union(t: Any) -> bool:
     non_none = [arg for arg in get_args(t) if arg is not type(None)]
     if any(isinstance(arg, type) and attr.has(arg) for arg in non_none):
         return False
-    # Exclude pure Optional[Enum] unions — those need the Enum structure hook.
     return not all(isinstance(arg, type) and issubclass(arg, Enum) for arg in non_none)
 
 
+def _rename_hook_factory(cls: type, converter: cattrs.Converter) -> Any:
+    """Generate a structuring hook that maps camelCase API keys to snake_case fields."""
+    overrides = {}
+    for f in attr.fields(cls):
+        if not f.init or f.name.startswith("_"):
+            continue
+        if f.alias and f.alias != f.name:
+            continue
+        api_key = camelize_key(f.name)
+        if api_key != f.name:
+            overrides[f.name] = override(rename=api_key)
+    return make_dict_structure_fn(cls, converter, **overrides)  # type: ignore[arg-type]
+
+
 def _make_converter() -> cattrs.Converter:
     # Converter (not GenConverter) so unknown API keys are silently dropped for forward-compat.
     c = cattrs.Converter()
@@ -50,7 +64,7 @@ def _make_converter() -> cattrs.Converter:
         lambda v, t: v if isinstance(v, t) else t(v),
     )
 
-    # Custom container types that take a list in __init__
+    # Custom container types that wrap a list in __init__
     def _structure_states(val: Any, _: type) -> States:
         if val is None:
             return States()
@@ -70,12 +84,15 @@ def _structure_state_definitions(val: Any, _: type) -> StateDefinitions:
     c.register_structure_hook(CommandDefinitions, _structure_command_definitions)
     c.register_structure_hook(StateDefinitions, _structure_state_definitions)
 
+    # For all other attrs classes: lazily generate a hook that renames camelCase
+    # API keys to snake_case on first use. This avoids manual dependency ordering.
+    skip = {States, CommandDefinitions, StateDefinitions}
+    c.register_structure_hook_factory(
+        lambda t: isinstance(t, type) and attr.has(t) and t not in skip,
+        _rename_hook_factory,
+    )
+
     return c
 
 
 converter = _make_converter()
-
-
-def structure_response[T](data: Any, cls: type[T]) -> T:
-    """Decamelize an API response and structure it into the target type."""
-    return converter.structure(decamelize(data), cls)

pyoverkiz/serializers.py

@@ -1,9 +1,8 @@
 """Helpers for preparing API payloads.
 
-This module centralizes JSON key formatting and any small transport-specific
-fixes (like mapping "deviceUrl" -> "deviceURL"). Models should produce
-logical snake_case payloads and the client should call `prepare_payload`
-before sending the payload to Overkiz.
+This module centralizes JSON key formatting for outgoing requests.
+Models produce logical snake_case payloads and the client calls
+`prepare_payload` before sending to Overkiz.
 """
 
 from __future__ import annotations
@@ -12,23 +11,12 @@
 
 from pyoverkiz._case import camelize_key, recursive_key_map
 
-_ABBREV_MAP: dict[str, str] = {"deviceUrl": "deviceURL"}
-
-
-def _camelize_key(key: str) -> str:
-    """Camelize a single key and apply abbreviation fixes in one step."""
-    camel = camelize_key(key)
-    return _ABBREV_MAP.get(camel, camel)
-
 
 def prepare_payload(payload: Any) -> Any:
-    """Convert snake_case payload to API-ready camelCase and apply fixes.
-
-    Performs camelization and abbreviation fixes in a single recursive pass
-    to avoid walking the structure twice.
+    """Convert snake_case payload to API-ready camelCase.
 
     Example:
         payload = {"device_url": "x", "commands": [{"name": "close"}]}
         => {"deviceURL": "x", "commands": [{"name": "close"}]}
     """
-    return recursive_key_map(payload, _camelize_key)
+    return recursive_key_map(payload, camelize_key)

pyproject.toml

@@ -16,7 +16,7 @@ packages = [
 dependencies = [
     "aiohttp<4.0.0,>=3.10.3",
     "backoff<3.0,>=1.10.0",
-    "attrs>=21.2",
+    "attrs>=22.2",
     "cattrs>=23.2",
 ]