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 api_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.api_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
• All custom exception classes have been renamed from *Exception to *Error to follow PEP 8 naming conventions (e.g. NotAuthenticatedException → NotAuthenticatedError). Additionally, NotSuchTokenException has been fixed to NoSuchTokenError (typo fix). Rename all exceptions from *Exception to *Error (N818) #1987
• CommandMode renamed to ExecutionMode, cancel_command() renamed to cancel_execution(), execute_scenario() renamed to execute_persisted_action_group(), execute_scheduled_scenario() renamed to schedule_persisted_action_group() Rename CommandMode, cancel_command, and scenario methods #1997
• 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 Improve error handling and add comprehensive client tests #2007

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
• Setup.id is now 'None' for Local API, as the Local API doesn't support this. Fix Python model for Local API (id = None) #1974
• Fix get_current_execution crashing on empty responses (cloud returns {}, local returns [] or null) Improve error handling and add comprehensive client tests #2007

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
• Add an option to disable PII masking in get_diagnostic_data (enabled by default). Add an option to disable PII masking in get_diagnostic_data (enabled by default) #1975
• boto3 is now lazy-imported by default in Nexity Auth Strategy. Lazy-import boto3 in NexityAuthStrategy #1990
• Add start_time, execution_type, and execution_sub_type fields to Execution model Improve error handling and add comprehensive client tests #2007
• Add NoSuchDeviceError and NoSuchActionGroupError exception types Improve error handling and add comprehensive client tests #2007

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?