feat(gateway): surface gateway subType 0 as None (#2111)

## Summary

Gateways such as the Rexel Energeasy Connect report `subType: 0`, which
means "no specific sub-type". Previously this structured to
`GatewaySubType.UNKNOWN` (via the `UnknownEnumMixin` fallback),
conflating "no sub-type" with "an unrecognised sub-type". This maps
`subType: 0` to `None` on `Gateway.sub_type` instead.

`GatewaySubType.UNKNOWN` stays reserved for genuinely unrecognised
**non-zero** values.

## Approach

A field `converter=` won't work: cattrs structures the raw `0` into
`GatewaySubType.UNKNOWN` *before* `__init__` runs, so the converter
couldn't tell `subType: 0` apart from a real unknown. The fix is a
cattrs **exact-type structure hook** for `GatewaySubType`, which sees
the raw value. It's registered with `register_structure_hook` (direct
dispatch) so it overrides cattrs' generic enum factory.

No enum member for `0` is added — `None` is the honest representation
and the field is already typed `GatewaySubType | None`.

## Behaviour

| `subType` | `Gateway.sub_type` |
|-----------|--------------------|
| `0` | `None` |
| `1` (known) | `GatewaySubType.TAHOMA_BASIC` |
| `99` (unknown, non-zero) | `GatewaySubType.UNKNOWN` |
| absent | `None` |

## Test plan

- New `TestGateway` class in `tests/test_models.py` covering all four
cases above, including the `setup_rexel.json` fixture.
- `pytest` → 506 passed
- `mypy pyoverkiz/converter.py` → clean

Author: iMicknl

pyoverkiz/converter.py

@@ -11,6 +11,7 @@
 from cattrs.gen import make_dict_structure_fn, override
 
 from pyoverkiz._case import camelize_key
+from pyoverkiz.enums import GatewaySubType
 from pyoverkiz.models import (
     CommandDefinition,
     CommandDefinitions,
@@ -64,6 +65,16 @@ def _make_converter() -> cattrs.Converter:
         lambda v, t: v if isinstance(v, t) else t(v),
     )
 
+    # Gateways report subType 0 to mean "no specific sub-type" — surface that as None
+    # rather than GatewaySubType.UNKNOWN, which stays reserved for genuinely unrecognised
+    # values. Scoped to the Optional field (GatewaySubType | None) so bare GatewaySubType
+    # structuring keeps the generic enum behaviour; exact-type hook (direct dispatch) so it
+    # overrides the primitive-union and generic enum hooks.
+    c.register_structure_hook(
+        GatewaySubType | None,
+        lambda v, _: None if v in (0, None) else c.structure(v, GatewaySubType),
+    )
+
     # Custom container types that wrap a list in __init__
     def _structure_states(val: Any, _: type) -> States:
         if val is None:

tests/test_models.py

@@ -14,6 +14,7 @@
     EventName,
     ExecutionState,
     FailureType,
+    GatewaySubType,
     Protocol,
     StateDefinitionType,
     UIClassifier,
@@ -29,6 +30,7 @@
     Device,
     Event,
     EventState,
+    Gateway,
     PersistedActionGroup,
     Setup,
     State,
@@ -137,6 +139,53 @@ def test_id_is_none_without_input_id(self):
         assert setup.id is None
 
 
+class TestGateway:
+    """Tests for Gateway model parsing, focused on sub_type handling."""
+
+    @staticmethod
+    def _structure(sub_type: int | None) -> Gateway:
+        raw: dict = {
+            "gatewayId": "1234-5678-9012",
+            "connectivity": {"status": "OK", "protocolVersion": "1"},
+        }
+        if sub_type is not None:
+            raw["subType"] = sub_type
+        return converter.structure(raw, Gateway)
+
+    def test_sub_type_zero_is_none(self):
+        """A subType of 0 means 'no specific sub-type' and structures as None."""
+        assert self._structure(0).sub_type is None
+
+    def test_sub_type_zero_in_fixture_is_none(self):
+        """The Rexel gateway reports subType 0, which should surface as None."""
+        raw_setup = json.loads(
+            (FIXTURES_DIR / "setup_rexel.json").read_text(encoding="utf-8")
+        )
+        setup = converter.structure(raw_setup, Setup)
+
+        assert setup.gateways[0].sub_type is None
+
+    def test_known_sub_type_is_preserved(self):
+        """A known non-zero subType still maps to its enum member."""
+        assert self._structure(1).sub_type is GatewaySubType.TAHOMA_BASIC
+
+    def test_unknown_non_zero_sub_type_falls_back_to_unknown(self):
+        """An unrecognised non-zero subType stays UNKNOWN, not None."""
+        assert self._structure(99).sub_type is GatewaySubType.UNKNOWN
+
+    def test_missing_sub_type_is_none(self):
+        """When subType is absent, sub_type defaults to None."""
+        assert self._structure(None).sub_type is None
+
+    def test_bare_enum_zero_is_unaffected(self):
+        """Bare GatewaySubType structuring is unaffected by the 0 -> None scoping.
+
+        The special-case lives on GatewaySubType | None, so structuring a plain
+        GatewaySubType still uses the generic enum hook (0 -> UNKNOWN).
+        """
+        assert converter.structure(0, GatewaySubType) is GatewaySubType.UNKNOWN
+
+
 class TestDevice:
     """Tests for Device model parsing and property extraction."""