v2.0.0

This is the stable release of pyOverkiz 2.0, the result of a large modernization effort with many breaking changes, new capabilities, and greatly improved documentation. If you are upgrading from v1, please read the migration guide.

Highlights

• Modern, typed API surface — models are now pure cattrs-structured data classes, exceptions follow PEP 8 (*Error), and many enums were regenerated from server definitions.
• Typed events — fetch_events() now returns strongly-typed Event subclasses (device, execution, failure, gateway, and zone events) you can narrow with isinstance.
• Rexel support — full OAuth2 PKCE authentication, externally-managed tokens, and multi-gateway discovery/selection.
• Local API tooling — endpoints for local token management, developer mode, and local pairing.
• Leaner dependencies & faster structuring — pyhumps replaced by an internal _case module, boto3/warrant-lite made optional, and ~43% faster response structuring.

Breaking changes

Python & client construction

• Minimum Python version is now Python 3.12 (#1871)
• The OverkizClient constructor now requires a ServerConfig via server and a Credentials class via credentials, e.g. UsernamePasswordCredentials(USERNAME, PASSWORD) (#1867)
• OverkizServer class renamed to ServerConfig, with additional server and api_type (cloud/local) properties (#1867)
• ServerConfig.type renamed to ServerConfig.api_type (#1995)
• generate_local_server renamed to create_local_server_config (#1867)
• client.api_type removed — now available via client.server_config.api_type (#1867)

Action groups & execution

• client.get_scenarios() replaced by client.get_action_groups() (#1864)
• Scenario() model replaced by ActionGroup() (#1864)
• client.execute_command() / client.execute_commands() replaced by client.execute_action_group() (#1862)
• CommandMode renamed to ExecutionMode, cancel_command() to cancel_execution(), execute_scenario() to execute_persisted_action_group(), execute_scheduled_scenario() to schedule_persisted_action_group() (#1997)
• get_action_groups() returns list[PersistedActionGroup] instead of list[ActionGroup]; ActionGroup no longer has oid, creation_time, or last_update_time fields (#2017)
• Execution.state is now ExecutionState instead of str; ActionGroup.id/ActionGroup.oid are now str | None; get_current_execution returns Execution | None (#2007)
• Execution.action_group type changed from list[Action] to ActionGroup | None (#1994)

Device & models

• The Device class no longer includes the id property; protocol, gateway_id, device_address, and subsystem_id moved to device.identifier.{} (#1930)
• Device.data_properties removed (was a non-existent value) (#1930)
• Gateway.id and Place.id changed from mutable fields to read-only properties (#1994)
• States.__getitem__ and CommandDefinitions.__getitem__ now raise KeyError instead of returning None — use .get() for the old behavior (#1994)
• Location model uses None instead of empty string defaults (#2025)

Events

• The Event base was slimmed to universal fields; fetch_events() now returns typed Event subclasses dispatched by name (DeviceStateChangedEvent, ExecutionStateChangedEvent, FailureEvent, GatewayEvent subtypes, ZoneEvent subtypes, device lifecycle events, …). Code that accessed event-specific fields off the base Event should narrow with isinstance first.
• failure_type_code was removed from FailureEvent (never sent by the API there); it remains on ExecutionStateChangedEvent.

Enums & exceptions

• Various UIClass and UIWidget enums renamed to proper UPPER_SNAKE_CASE (#1925)
• All custom exception classes renamed from *Exception to *Error (PEP 8); NotSuchTokenException fixed to NoSuchTokenError (#1987)
• Raises OverkizError instead of ValueError for API data issues (#2025)

Misc API surface

• get_diagnostic_data() return shape changed from a flat setup dict to {"setup": ..., "action_groups": ...} (#2016)
• OverkizClient.check_response removed, replaced by module-level pyoverkiz.response_handler.check_response (#1977)
• event_listener_id is now a read-only property (#2025)
• SUPPORTED_SERVERS is now immutable via MappingProxyType (#2025)
• obfuscate_sensitive_data returns a new dict instead of mutating (#2025)
• get_device_definition returns a Definition model instead of a raw dict (#2025)
• deviceurl parameter renamed to device_url for consistency (#2025)

Dependencies

• pyhumps dependency removed and replaced with internal _case module (#1988)
• boto3 and warrant-lite moved from required to an optional [nexity] extra (#2020)

Features

Authentication & gateways

• Rexel authentication — OAuth2 PKCE interactive login (RexelAuthStrategy) and externally-managed tokens (RexelTokenCredentials / RexelTokenAuthStrategy), plus gateway discovery/selection (GatewayCandidate, SupportsGatewaySelection) (#2090)
• Added Rexel server data definitions and regenerated enums/docs (#2094)
• Added Rexel Energeasy Connect gateway types and corrected the Energeasy Connect mapping with V3 variants (#2100, #2110)
• OverkizClient constructor supports passing a Server enum directly, e.g. OverkizClient(server=Server.SOMFY_EUROPE, ...) (#1867)

Local API

• Local token management endpoints (generate_local_token, activate_local_token, get_local_tokens, delete_local_token), a LocalToken model, plus developer-mode and local-pairing endpoints (#2112)

Action execution

• client.execute_action_group() supports multiple execution modes (high priority, internal, geolocated) (#1862)
• client.execute_action_group() supports multiple device actions in the same request (#1862)
• OverkizClient has an optional ActionQueue for batching device executions (#1866)
• Command.parameters now accepts dict/list values, which some commands require (e.g. setAbsenceStartDate) (#2089, #2091)
• OverkizClientSettings for RTS default duration and future extensibility (#2018)

Devices, events & definitions

• Device class has helper methods for retrieving state value, commands, and definition (#1930)
• Device class has an identifier property with protocol, gateway_id, device_address, subsystem_id, base_device_url (#1930)
• Device class exposes additional fields (data_properties, ui_profiles, ui_classifiers, attributes) under device.definition (#1930)
• Typed event subclasses for device state changes, executions, failures, gateway events, zone events, and device lifecycle events, with reliable identity fields guaranteed non-None after isinstance narrowing (#2061 and related)
• Event auto-converts dicts in device_states to EventState, so direct construction (e.g. in tests) no longer needs manual wrapping (#2061)
• UIClass, UIWidget, and UIProfile are auto-generated from server definitions; enums with an Unknown value inherit from UnknownEnumMixin (#1925)
• SDK functions to retrieve device info: controllable types, devices, ui_classes, ui_classifiers, ui_profile, ui_widgets (#1925)
• Firmware management methods (get_firmware_versions, check_firmware_update, start_firmware_update) and UnsupportedOperationError exception
• NoSuchDeviceError and NoSuchActionGroupError exception types added (#2007)
• start_time, execution_type, execution_sub_type fields added to Execution model (#2007)
• Added HLRR_WIFI Hitachi states and hi_kumo_europe device data (#2086)

Diagnostics & privacy

• Option to disable PII masking in get_diagnostic_data (enabled by default) (#1975)
• Additional sensitive states redacted: IP addresses, MAC/serial numbers, labels, and lat/long location states, among others (#2037, #2098)

Fixes

• client.get_current_executions() is now properly typed; Execution.action_group previously had the wrong type (#1864)
• Setup.id is now None for the Local API, which doesn't support it (#1974)
• get_current_execution no longer crashes on empty responses (cloud returns {}, local returns [] or null) (#2007)
• Fixed boolean parsing in the Cloud API; "false" is no longer mapped to True (#2015)
• Raise typed ServiceUnavailableError when a vendor OAuth token endpoint returns an HTTP 5xx (with HTML body) instead of leaking an aiohttp ContentTypeError (#2099)
• Surface gateway subType: 0 as None rather than conflating it with an unknown sub-type (#2111)
• Fixed overly broad INVALID_FIELD_VALUE error mapping — now requires the "Unable to determine action group setup" substring
• Removed redundant _refresh_token_if_expired() calls in fetch_events and unregister_event_listener (already handled by _post())
• Fixed obfuscate_string regex to handle Unicode characters (e.g. accented letters) (#2037)
• Fixed command_to_enum_name() to treat digits as word boundaries (e.g. discover1WayController → DISCOVER_1_WAY_CONTROLLER) (#2032)
• Fixed enum generation to produce _4T instead of 4_T suffixes (#2057)

Internal / DX

• ~43% faster response structuring by eliminating the recursive decamelize pre-pass in favor of single-pass cattrs rename hooks (#2062)
• Migrated to cattrs for centralized model structuring — models are now pure @define(kw_only=True) data classes (#1994)
• Migrated from pyhumps to an internal _case module — 8.4x faster decamelize, 94% smaller; lru_cache added to camelize_key (#1988)
• boto3 and warrant-lite are now optional [nexity] dependencies, with boto3 lazy-imported in the Nexity auth strategy (#2020, #1990)
• A typed structure_response / structure_response helper consolidates response deserialization (PEP 695 type-param syntax) (#2024)
• Harvest enum values from controllable definitions and fixtures, with improved generation workflow (#2085, #2084, #2082)
• Added backoff max_time and jitter to all retry decorators (#1993)
• Replaced magic HTTP status codes with HTTPStatus constants
• Stop Dependabot from ratcheting dependency floors upward (#2121)
• Pinned all GitHub Actions to full-length commit SHAs (security hardening) (#2122)
• Migrated pre-commit to prek (Rust-based) (#1887)
• Developer documentation on GitHub Pages: imicknl.github.io/python-overkiz-api (#1908)
• Comprehensive v1 → v2 migration guide, with gaps filled and enum/auth breaking changes documented (#2119, #2102)
• Documented that ExecutionMode is Cloud API only (#2088)
• Expanded ruff rule coverage (PT, N, ERA, FURB/PERF/RSE/RET/PIE, PYI, PTH, A, PL, W, LOG, DTZ, FLY, ISC, PGH, SLF, SLOT, TID, INP, ICN, G, BLE, TRY, Q)