refactor(models)!: clarify States value accessors and widen accessor typing (#2108)

## Summary

Two related, breaking v2 ergonomics fixes to the device accessor
surface, before the 2.0 freeze.

### #2105 — `States.has()`/`has_any()` conflate existence with value

`has()` returned `True` only when the state existed **and** had a
non-`None` value, which pushed call sites toward a double lookup
(`has(x)` then `get_value(x)`). The two concepts are now separated:

- `has()` → **`has_value()`**, `has_any()` → **`has_any_value()`** —
explicit about the "present AND non-None value" semantic.
- Pure existence is `name in states` (already provided by
`Mapping.__contains__`).

Many consumers don't even need `has_value` anymore: `get_value(x) == ON`
already returns `False` for a missing state, collapsing the double
lookup to one call.

### #2106 — Inconsistent accessor typing

State accessors were typed `str`-only even though
`OverkizState`/`OverkizAttribute` are `StrEnum` and worked at runtime.
Signatures now advertise enum support, matching the command helpers:

- `States.{get_value, first, first_value, has_value, has_any_value}` →
`str | OverkizState | OverkizAttribute` (the `States` class backs both
`device.states` and `device.attributes`).
- `StateDefinitions.{first, has_any}` → `str | OverkizState`.
- `CommandDefinitions` and `device.supports_command()` already accepted
enums — unchanged.

Scope deliberately excludes new device-level wrappers (e.g.
`device.has_state()`): `device.states` is a first-class container read
constantly in consumers, while `device.supports_command()` only exists
as a shortcut to the buried `device.definition.commands`. Mirroring
would duplicate the container API for no gain.

## Changes

- `pyoverkiz/models.py`: rename + widen typing (new `StateName` alias).
- `docs/device-control.md`, `docs/migration-v2.md`: updated to new
names; document `in` for pure existence.
- `tests/test_models.py`: renamed tests + new test exercising enum keys.

## Breaking changes

- `States.has()` → `States.has_value()`
- `States.has_any()` → `States.has_any_value()`

## Test plan

- [x] `ruff check` / `ruff format` / `mypy` / `ty` clean
- [x] Full suite green (502 passed)

Closes #2105
Closes #2106

Author: iMicknl

docs/device-control.md

@@ -53,13 +53,17 @@ print(f"Orientation: {slats_orientation}")
 slats_orientation = device.states.first_value([OverkizState.CORE_SLATS_ORIENTATION, OverkizState.CORE_SLATE_ORIENTATION])
 print(f"Orientation: {slats_orientation}")
 
-# Check if a single state has a non-None value
-if device.states.has(OverkizState.CORE_SLATS_ORIENTATION):
+# Check if a single state exists with a non-None value
+if device.states.has_value(OverkizState.CORE_SLATS_ORIENTATION):
     print("Device has a slats orientation")
 
-# Check if any of the states have non-None values
-if device.states.has_any([OverkizState.CORE_SLATS_ORIENTATION, OverkizState.CORE_SLATE_ORIENTATION]):
+# Check if any of the states exist with a non-None value
+if device.states.has_any_value([OverkizState.CORE_SLATS_ORIENTATION, OverkizState.CORE_SLATE_ORIENTATION]):
     print("Device has a slats orientation")
+
+# For a pure existence check (ignoring the value), use `in`
+if OverkizState.CORE_SLATS_ORIENTATION in device.states:
+    print("Device reports a slats orientation state")
 ```
 
 #### Get state definition

docs/migration-v2.md

@@ -188,8 +188,9 @@ v2 provides a consistent API on `device.states` and `device.attributes` (both ar
 | `.get_value(name)` | `StateType` | Single-key value (None if missing) |
 | `.first(names)` | `State \| None` | First non-None match from fallback list |
 | `.first_value(names)` | `StateType` | First non-None value from fallback list |
-| `.has(name)` | `bool` | Check single state exists with value |
-| `.has_any(names)` | `bool` | Check any state exists with value |
+| `.has_value(name)` | `bool` | Check single state exists with a non-None value |
+| `.has_any_value(names)` | `bool` | Check any state exists with a non-None value |
+| `name in states` | `bool` | Pure existence check (ignores the value) |
 
 ```python
 # Get a single state value
@@ -198,8 +199,12 @@ temp = device.states.get_value("core:TemperatureState")
 # Fallback chain — try multiple state names, return first hit
 temp = device.states.first_value(["core:TemperatureState", "core:TemperatureInCelsiusState"])
 
-# Existence check
-if device.states.has("core:ClosureState"):
+# Value check — state exists and has a non-None value
+if device.states.has_value("core:ClosureState"):
+    ...
+
+# Pure existence check (ignores the value)
+if "core:ClosureState" in device.states:
     ...
 
 # Same API works for attributes

pyoverkiz/models.py

@@ -30,6 +30,7 @@
 from pyoverkiz.enums.command import OverkizCommand
 from pyoverkiz.enums.protocol import Protocol
 from pyoverkiz.enums.server import APIType, Server
+from pyoverkiz.enums.state import OverkizAttribute, OverkizState
 from pyoverkiz.exceptions import OverkizError
 from pyoverkiz.obfuscate import obfuscate_email, obfuscate_id, obfuscate_string
 from pyoverkiz.types import DATA_TYPE_TO_PYTHON, CommandParameterValue, StateType
@@ -132,6 +133,12 @@ def _cast_json_value(self, raw_value: str) -> StateType:
             ) from err
 
 
+# States are keyed by core state names (OverkizState) for device.states and by
+# attribute names (OverkizAttribute) for device.attributes; both are StrEnum, so
+# plain str keys work too.
+StateName = str | OverkizState | OverkizAttribute
+
+
 @define(init=False)
 class States(Mapping[str, State]):
     """Container of State objects implementing Mapping[str, State]."""
@@ -176,34 +183,37 @@ def __len__(self) -> int:
         """Return number of states in the container."""
         return len(self._states)
 
-    def get_value(self, name: str) -> StateType:
+    def get_value(self, name: StateName) -> StateType:
         """Return the value of a state by name, or None if missing."""
         state = self._index.get(name)
         if state is not None:
             return state.value
         return None
 
-    def first(self, names: list[str]) -> State | None:
+    def first(self, names: list[StateName]) -> State | None:
         """Return the first State that exists and has a non-None value, or None."""
         for name in names:
             state = self._index.get(name)
             if state is not None and state.value is not None:
                 return state
         return None
 
-    def first_value(self, names: list[str]) -> StateType:
+    def first_value(self, names: list[StateName]) -> StateType:
         """Return the value of the first State with a non-None value, or None."""
         if state := self.first(names):
             return state.value
         return None
 
-    def has(self, name: str) -> bool:
-        """Return True if the state exists with a non-None value."""
+    def has_value(self, name: StateName) -> bool:
+        """Return True if the state exists and has a non-None value.
+
+        For a pure existence check (ignoring the value), use ``name in states``.
+        """
         state = self._index.get(name)
         return state is not None and state.value is not None
 
-    def has_any(self, names: list[str]) -> bool:
-        """Return True if any of the given state names exist with a non-None value."""
+    def has_any_value(self, names: list[StateName]) -> bool:
+        """Return True if any of the given states exist with a non-None value."""
         return self.first(names) is not None
 
 
@@ -317,14 +327,14 @@ def __len__(self) -> int:
         """Return number of state definitions."""
         return len(self._definitions)
 
-    def first(self, names: list[str]) -> StateDefinition | None:
+    def first(self, names: list[str | OverkizState]) -> StateDefinition | None:
         """Return the first StateDefinition whose qualified_name matches, or None."""
         for name in names:
             if name in self._index:
                 return self._index[name]
         return None
 
-    def has_any(self, names: list[str]) -> bool:
+    def has_any(self, names: list[str | OverkizState]) -> bool:
         """Return True if any of the given state definitions exist."""
         return self.first(names) is not None
 

tests/test_models.py

@@ -21,6 +21,7 @@
     UIProfile,
 )
 from pyoverkiz.enums.command import OverkizCommand
+from pyoverkiz.enums.state import OverkizAttribute, OverkizState
 from pyoverkiz.models import (
     Action,
     ActionGroup,
@@ -348,17 +349,44 @@ def test_states_first_value(self):
         value = device.states.first_value(["nonexistent", "core:ClosureState"])
         assert value == 100
 
-    def test_states_has(self):
-        """device.states.has() checks if a single state exists with non-None value."""
+    def test_states_has_value(self):
+        """device.states.has_value() checks if a single state exists with non-None value."""
         device = _make_device()
-        assert device.states.has("core:ClosureState")
-        assert not device.states.has("nonexistent")
+        assert device.states.has_value("core:ClosureState")
+        assert not device.states.has_value("nonexistent")
 
-    def test_states_has_any(self):
-        """device.states.has_any() checks if any state exists with non-None value."""
+    def test_states_has_any_value(self):
+        """device.states.has_any_value() checks if any state exists with non-None value."""
         device = _make_device()
-        assert device.states.has_any(["nonexistent", "core:ClosureState"])
-        assert not device.states.has_any(["nonexistent"])
+        assert device.states.has_any_value(["nonexistent", "core:ClosureState"])
+        assert not device.states.has_any_value(["nonexistent"])
+
+    def test_states_accept_enum_keys(self):
+        """States accessors accept OverkizState enums, not just plain strings."""
+        device = _make_device()
+        assert OverkizState.CORE_CLOSURE in device.states
+        assert device.states.has_value(OverkizState.CORE_CLOSURE)
+        assert device.states.get_value(OverkizState.CORE_CLOSURE) == 100
+        assert device.states.first([OverkizState.CORE_CLOSURE]) is not None
+        assert device.states.has_any_value([OverkizState.CORE_CLOSURE])
+
+    def test_attributes_accept_enum_keys(self):
+        """Attribute accessors accept OverkizAttribute enums, not just plain strings."""
+        device = _make_device(
+            {
+                **RAW_DEVICES,
+                "attributes": [
+                    {"name": "core:Manufacturer", "type": 3, "value": "VELUX"},
+                ],
+            }
+        )
+        assert OverkizAttribute.CORE_MANUFACTURER in device.attributes
+        assert device.attributes.has_value(OverkizAttribute.CORE_MANUFACTURER)
+        assert (
+            device.attributes.get_value(OverkizAttribute.CORE_MANUFACTURER) == "VELUX"
+        )
+        assert device.attributes.first([OverkizAttribute.CORE_MANUFACTURER]) is not None
+        assert device.attributes.has_any_value([OverkizAttribute.CORE_MANUFACTURER])
 
     def test_definition_states_get(self):
         """device.definition.states.get() returns StateDefinition for a single state."""
@@ -500,25 +528,25 @@ def test_first_value_returns_none_when_no_match(self):
         states = self._make_states(RAW_STATES)
         assert states.first_value(["nonexistent"]) is None
 
-    def test_has_returns_true(self):
-        """has() returns True when the state exists with a non-None value."""
+    def test_has_value_returns_true(self):
+        """has_value() returns True when the state exists with a non-None value."""
         states = self._make_states(RAW_STATES)
-        assert states.has("core:NameState")
+        assert states.has_value("core:NameState")
 
-    def test_has_returns_false(self):
-        """has() returns False when the state does not exist."""
+    def test_has_value_returns_false(self):
+        """has_value() returns False when the state does not exist."""
         states = self._make_states(RAW_STATES)
-        assert not states.has("nonexistent")
+        assert not states.has_value("nonexistent")
 
-    def test_has_any_true(self):
-        """has_any() returns True when at least one state exists."""
+    def test_has_any_value_true(self):
+        """has_any_value() returns True when at least one state exists."""
         states = self._make_states(RAW_STATES)
-        assert states.has_any(["nonexistent", "core:NameState"])
+        assert states.has_any_value(["nonexistent", "core:NameState"])
 
-    def test_has_any_false(self):
-        """has_any() returns False when no state exists."""
+    def test_has_any_value_false(self):
+        """has_any_value() returns False when no state exists."""
         states = self._make_states(RAW_STATES)
-        assert not states.has_any(["nonexistent", "also_nonexistent"])
+        assert not states.has_any_value(["nonexistent", "also_nonexistent"])
 
     def test_getitem_raises_keyerror_on_missing(self):
         """Subscript access raises KeyError for missing states."""