2.0

[iMicknl]

Breaking changes

• Minimum Python version is now Python 3.12 (Bump minimum required Python version to 3.12 #1871)
• client.get_scenarios() is replaced by client.get_action_groups() (Rename Scenario to ActionGroup (and relevant methods), reuse ActionGroup for Execution typing #1864)
• Scenario() model is replaced by ActionGroup(), where creation_timeandmetadata` are now optional fields (Rename Scenario to ActionGroup (and relevant methods), reuse ActionGroup for Execution typing #1864)
• client.execute_command() and client.execute_commands() are replaced by client.execute_action_group() Add execute_action_group method and remove other command execution methods. #1862
• OverkizServer class is renamed to ServerConfig and has additional server and type (cloud/local) property Refactor authentication handling in OverkizClient and add new credential classes #1867
• generate_local_server is renamed to create_local_server_config Refactor authentication handling in OverkizClient and add new credential classes #1867
• client.api_type is removed and now available via ServerConfig (e.g. client.server_config.type) Refactor authentication handling in OverkizClient and add new credential classes #1867
• The OverkizClient constructor now requires passing a ServerConfig via server Refactor authentication handling in OverkizClient and add new credential classes #1867
• The OverkizClient constructur now requires passing an Credentials class via credentials, e.g. UsernamePasswordCredentials(USERNAME, PASSWORD) for most server. Refactor authentication handling in OverkizClient and add new credential classes #1867
• The Device class no longer includes the id property, and the following fields have been moved into device.identifier.{}: protocol, gateway_id, device_address, and subsystem_id. Improve Device model #1930
• Device.data_properties has been removed, as it was a non-existent value. Improve Device model #1930
• Various UIClass and UIWidget enums have been renamed to proper UPPER_SNAKE_CASE. Improve enum structure #1925

Fixes

• client.get_current_executions() is now properly typed, previously the Execution() model returned a list type for action_group, what should be a dict type. (Rename Scenario to ActionGroup (and relevant methods), reuse ActionGroup for Execution typing #1864)
• Device.data_properties has been removed, as it was a non-existent value. Improve Device model #1930

Features

• client.execute_action_group() now supports multiple execution modes (high priority, internal, geolocated) Add execute_action_group method and remove other command execution methods. #1862
• client.execute_action_group() now supports multiple device actions in the same request Add execute_action_group method and remove other command execution methods. #1862
• The OverkizClient constructor now supports passing a Server enum directly, such as OverkizClient(server=Server.SOMFY_EUROPE, ...). Refactor authentication handling in OverkizClient and add new credential classes #1867
• The OverkizClient now has an optional ActionQueue for batching device executions (actions) Implement ActionQueue for batching actions in OverkizClient #1866
• Device class now has helper methods for retrieving the state value, commands and definition. Improve Device model #1930
• Device class now has an identifier property with protocol, gateway_id, device_address, subsystem_id and base_device_url fields. Improve Device model #1930
• The Device class now includes additional fields (data_properties, ui_profiles, ui_classifiers, attributes) under device.definition. Improve Device model #1930
• UIClass, UIWidget and UIProfile are now auto-generated based on server definitions. Improve enum structure #1925
• Enums that include an Unknown value now inherit from a shared base class (UnknownEnumMixin) to reduce code repetition. Improve enum structure #1925
• Add SDK functions to retrieve device information, including controllable types, devices, ui_classes, ui_classifiers, ui_profile, and ui_widgets. Improve enum structure #1925

Docs

• Developer documentation on GitHub Pages imicknl.github.io/python-overkiz-api. Improve developer documentation #1908

[tetienne]

Nice work on this v2 rewrite! The async context manager pattern, strategy/factory auth design, and action queue batching logic are all well-structured. The StrEnum usage is correct for Python 3.12+, and the parametrized fixture tests are thorough.

I went through the codebase with a focus on Python idioms. Some inline comments below, plus a few more that target lines outside the diff:

---

Blocker: Type annotations don't match runtime behavior
pyoverkiz/models.py:43, 89-96 - Multiple fields annotated str but default to None (e.g. id: str = field(repr=obfuscate_id, default=None), same for city, country, postal_code, address_line1, address_line2, longitude, latitude). Downstream code trusting the annotation will skip None checks. These should be str | None.

Blocker: StateDefinition can crash at runtime
pyoverkiz/models.py:379-383 - If both name and qualified_name are None, self.qualified_name is never assigned, but the class declares qualified_name: str (non-optional) and get_state_definition reads it unconditionally. This will raise AttributeError. I would suggest either raising ValueError in the else branch, or declaring qualified_name: str | None = None.

Suggestion: field() in __init__ parameter defaults
pyoverkiz/models.py:58, 111-118, 721 - field(repr=obfuscate_id, default=None) used as __init__ parameter defaults evaluates to an attrs Attribute object at definition time, not None. If a parameter is ever omitted, the default is the Attribute object. What about using plain None as parameter defaults and keeping field() only on class-level declarations?

Suggestion: __getitem__ should raise KeyError
pyoverkiz/models.py:473-475, 613-615 - CommandDefinitions.__getitem__ and States.__getitem__ return None on miss. Idiomatic Python expects KeyError from __getitem__; a separate get() method can return None. __contains__ (line 471) relies on the current behavior, so it would need updating too.

Suggestion: Simplify bool | None to bool
pyoverkiz/client.py:281 - register_event_listener: bool | None = True. None and False behave identically here. bool = True would be simpler.

Question: Is the manual __init__ pattern on every model intentional?
Every model uses @define(init=False) + hand-written __init__, duplicating every field. Was attrs' built-in init with converters or cattrs considered? For simple models like DataProperty, Partner, Feature, ZoneItem, the manual init adds nothing beyond self.x = x.

[tetienne]

Blocker: AuthStrategy in base.py is a Protocol. Inheriting from a Protocol makes BaseAuthStrategy also a Protocol in the type system, which means mypy/pyright won't enforce that concrete subclasses implement all required methods.

Two options:

1. Remove the inheritance entirely. Structural subtyping means BaseAuthStrategy already satisfies the AuthStrategy protocol without inheriting from it.
2. Convert AuthStrategy from Protocol to ABC if you want explicit runtime inheritance.

Option 1 is simpler and more idiomatic for a Protocol-based design. Worth considering?