Improve code quality, consistency, and developer experience by iMicknl · Pull Request #2025 · iMicknl/python-overkiz-api

iMicknl · 2026-04-30T21:34:06Z

Summary

Make event_listener_id a read-only property
Make SUPPORTED_SERVERS immutable via MappingProxyType
Make obfuscate_sensitive_data return a new dict instead of mutating
Type Execution.state as ExecutionState instead of str
Return Definition model from get_device_definition instead of raw dict
Rename deviceurl parameter to device_url for consistency
Use None instead of empty string defaults in Location model
Raise OverkizError instead of ValueError for API data issues
Add server parameter to create_local_server_config

Test plan

All existing tests pass (pytest)
Type checking passes (mypy, ty)
Linting passes (ruff)

All other method parameters use snake_case (profile_name, controllable_name, etc.) but these 6 device methods used the unseparated form. Aligns the public API before v2 locks.

Every other typed endpoint uses structure_response() to return a proper model. This was the only one leaking untyped JSON to consumers.

These heavy AWS dependencies are only needed for Nexity auth but were imposed on all users. Now install via pyoverkiz[nexity]. A clear ImportError is raised if the extra is missing at runtime.

HistoryExecution.state was already typed as ExecutionState. The live Execution model was inconsistently using a raw string for the same concept.

The old implementation mutated its input in place, which was a footgun for callers who held a reference to the original data. Now returns a deep copy with sensitive values masked.

Prevents accidental mutation of the shared server registry at module level. Read access (subscript, iteration) is unchanged.

Consumers should not set this directly — it's managed internally by register/unregister_event_listener(). Exposed as a property for read access, backed by _event_listener_id.

Empty string defaults forced consumers to check truthiness rather than None-ness, inconsistent with all other optional fields in the models. Fields that may be absent from the API now properly default to None.

DeviceIdentifier.from_device_url() and Device validation now raise OverkizError, consistent with the rest of the exception hierarchy. ValueError is reserved for programming errors (wrong argument types).

Other brands are adding local APIs. The server parameter allows specifying which server identity to use instead of hardcoding SOMFY_DEVELOPER_MODE. Default is unchanged for backwards compat.

This reverts commit f295e02.

Copilot

Pull request overview

Consolidates pyoverkiz v2.0 breaking changes and supporting infrastructure (new auth strategies, action execution batching, cattrs-based structuring, enum refactors), plus updated docs/tests/fixtures for the v2 API.

Changes:

Introduces auth strategy + credential types and centralizes error-response mapping.
Adds ActionQueue batching, RTS command-duration injection, and payload serialization helpers.
Updates docs, tests, and fixtures for the v2 API surface and Python 3.12+ baseline.

Reviewed changes

Copilot reviewed 6 out of 6 changed files in this pull request and generated no comments.

Show a summary per file

File	Description
utils/mask_fixtures.py	Switch fixture masking script to pathlib-based file iteration.
tests/test_utils.py	Update utils tests for `create_local_server_config` + small assertions cleanup.
tests/test_ui_profile.py	Add unit tests for UI profile models + structuring via converter.
tests/test_serializers.py	Add tests for `prepare_payload` key formatting behavior.
tests/test_rts_injection.py	Add tests for RTS duration injection behavior in `execute_action_group`.
tests/test_obfuscate.py	Expand obfuscation tests (including list-of-dicts input).
tests/test_enums.py	Minor test-file lint cleanup.
tests/test_client_settings.py	Add tests for `OverkizClientSettings` defaults and options.
tests/test_client_queue_integration.py	Add integration tests for client + action queue batching/flush.
tests/test_case.py	Add tests for internal camel/snake conversion utilities.
tests/test_auth.py	Add comprehensive tests for auth factory/strategies + lazy-import behavior.
tests/test_action_queue.py	Add full test suite for `ActionQueue` batching/flush/error propagation.
tests/helpers.py	Add shared aiohttp-like mock response helper.
tests/fixtures/exec/current-tahoma-switch.json	Add execution fixture sample (list response).
tests/fixtures/exec/current-single.json	Add execution fixture sample (single object response).
tests/fixtures/exceptions/cloud/unknown-user-account.json	Add error fixture for unknown user.
tests/fixtures/exceptions/cloud/unknown-resource-access-denied.json	Add error fixture for unknown access denied.
tests/fixtures/exceptions/cloud/unknown-auth-error.json	Add error fixture for unknown auth error.
tests/fixtures/exceptions/cloud/too-many-attempts-banned.json	Add error fixture for temporary ban scenario.
tests/fixtures/exceptions/cloud/session-and-bearer.json	Add error fixture for session+bearer conflict.
tests/fixtures/exceptions/cloud/resource-access-denied-gateway-not-in-setup.json	Add error fixture for gateway/setup mismatch.
tests/fixtures/exceptions/cloud/resource-access-denied-device-setup-mismatch.json	Add error fixture for device setup mismatch.
tests/fixtures/exceptions/cloud/not-such-token.json	Add error fixture for “no such token” response.
tests/fixtures/exceptions/cloud/no-such-ui-profile.json	Add error fixture for missing UI profile.
tests/fixtures/exceptions/cloud/no-such-resource.json	Add error fixture for invalid API call.
tests/fixtures/exceptions/cloud/no-such-controllable.json	Add error fixture for missing controllable.
tests/fixtures/exceptions/cloud/no-such-command.json	Add error fixture for invalid command.
tests/fixtures/exceptions/cloud/no-such-action-group.json	Add error fixture for missing action group.
tests/fixtures/exceptions/cloud/missing-api-key.json	Add error fixture for missing API key.
tests/fixtures/exceptions/cloud/invalid-token.json	Add error fixture for invalid token.
tests/fixtures/exceptions/cloud/invalid-event-listener-id.json	Add error fixture for invalid listener id.
tests/fixtures/exceptions/cloud/exec-queue-full.json	Add error fixture for execution queue full.
tests/fixtures/exceptions/cloud/action-group-setup-not-found.json	Add error fixture for action-group setup resolution failure.
tests/fixtures/endpoints/setup-places.json	Add endpoint fixture for places tree.
tests/fixtures/endpoints/history-executions.json	Add endpoint fixture for execution history.
tests/fixtures/endpoints/exec-schedule.json	Add endpoint fixture for schedule execution response.
tests/fixtures/endpoints/exec-current-empty-object.json	Add endpoint fixture for empty-object current exec response.
tests/fixtures/endpoints/exec-current-empty-list.json	Add endpoint fixture for empty-list current exec response.
tests/fixtures/endpoints/exec-apply.json	Add endpoint fixture for exec/apply response.
tests/fixtures/endpoints/events-register.json	Add endpoint fixture for event listener registration.
tests/fixtures/endpoints/device-states.json	Add endpoint fixture for device states response.
tests/conftest.py	Add shared async fixtures for cloud/local clients.
pyproject.toml	Bump to 2.0.0, require Python 3.12+, add docs extras, expand ruff config, swap pre-commit→prek.
pyoverkiz/utils.py	Replace local server generator with `create_local_server_config`/`create_server_config`.
pyoverkiz/types.py	Fix boolean parsing for string state values; add command parameter value type.
pyoverkiz/serializers.py	Add `prepare_payload` for camelCase + abbreviation normalization.
pyoverkiz/response_handler.py	Add centralized HTTP error parsing and mapping to typed errors.
pyoverkiz/obfuscate.py	Refactor masking to be non-mutating and support list inputs.
pyoverkiz/exceptions.py	Rename exceptions to `*Error` types and add new error categories.
pyoverkiz/enums/ui.py	Update auto-generated UI enums; add UnknownEnumMixin handling + member fixes.
pyoverkiz/enums/state.py	Drop StrEnum backport logic (Python 3.12+).
pyoverkiz/enums/server.py	Drop StrEnum backport logic (Python 3.12+).
pyoverkiz/enums/protocol.py	Update auto-generated Protocol enum; add UnknownEnumMixin + new members.
pyoverkiz/enums/measured_value_type.py	Drop StrEnum backport logic (Python 3.12+).
pyoverkiz/enums/general.py	Apply UnknownEnumMixin to enums that need UNKNOWN fallback; simplify imports.
pyoverkiz/enums/gateway.py	Apply UnknownEnumMixin; add update criticity enum; adjust beautify logic.
pyoverkiz/enums/execution.py	Apply UnknownEnumMixin; simplify imports.
pyoverkiz/enums/base.py	Introduce shared UnknownEnumMixin for consistent unknown-value behavior.
pyoverkiz/enums/init.py	Replace wildcard re-exports with explicit exports + `__all__`.
pyoverkiz/converter.py	Add centralized cattrs converter + `structure_response` with decamelize.
pyoverkiz/const.py	Add USER_AGENT, Rexel OAuth constants; make SUPPORTED_SERVERS immutable via MappingProxyType.
pyoverkiz/auth/strategies.py	Add auth strategies (Somfy OAuth, Rexel OAuth, Nexity Cognito, etc.).
pyoverkiz/auth/factory.py	Add factory for selecting auth strategy by server/api_type + credential validation.
pyoverkiz/auth/credentials.py	Add credential dataclasses for strategy-based auth.
pyoverkiz/auth/base.py	Add AuthContext + AuthStrategy protocol.
pyoverkiz/auth/init.py	Add public auth module re-exports.
pyoverkiz/action_queue.py	Add ActionQueue batching implementation + settings + queued execution wrapper.
pyoverkiz/_case.py	Add internal snake_case/camelCase conversion helpers.
mkdocs.yml	Add MkDocs Material site config + nav for v2 docs.
docs/troubleshooting.md	Add troubleshooting guide and retry examples using new errors/types.
docs/migration-v2.md	Add/refresh full v1→v2 migration guide (API, models, enums, errors).
docs/index.md	Add documentation landing page and supported hubs list.
docs/getting-started.md	Add getting started guide with authentication examples.
docs/event-handling.md	Add event listener registration/fetch docs + retry guidance.
docs/device-control.md	Add device control guide (actions, executions, RTS duration, etc.).
docs/core-concepts.md	Add conceptual overview (servers, setup, actions, executions).
docs/contribute.md	Add contributor guide incl. enum generation and prek usage.
docs/callable_names.txt	Remove old callable names list file.
docs/api/apiDocStyle.css	Add PATCH styling and misc UI styles.
docs/api/apiDocDyn.js	Add JS for dynamic API doc UI interactions.
docs/api-reference.md	Add mkdocstrings API reference entrypoints.
docs/action-queue.md	Add action queue documentation and usage examples.
README.md	Update README for v2 constructor/auth and async sleep usage; revise local example.
AGENTS.md	Update developer commands to use prek instead of pre-commit.
.vscode/tasks.json	Add VS Code tasks for serving/building docs.
.pre-commit-config.yaml	Update hook versions and exclude patterns.
.github/workflows/test.yml	Drop <3.12 from CI matrix.
.github/workflows/release.yml	Pin release workflow to Python 3.12.
.github/workflows/lint.yaml	Drop <3.12 from lint matrix; switch pre-commit run to prek.
.github/workflows/docs.yml	Add docs build/deploy workflow.
.devcontainer/devcontainer.json	Update devcontainer postCreate to install extras/dev + prek hooks.

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

iMicknl added 11 commits April 30, 2026 20:33

Rename deviceurl parameter to device_url for consistency

9369b4d

All other method parameters use snake_case (profile_name, controllable_name, etc.) but these 6 device methods used the unseparated form. Aligns the public API before v2 locks.

Return Definition model from get_device_definition instead of raw dict

7195a38

Every other typed endpoint uses structure_response() to return a proper model. This was the only one leaking untyped JSON to consumers.

Move boto3 and warrant-lite to optional "nexity" extra

f295e02

These heavy AWS dependencies are only needed for Nexity auth but were imposed on all users. Now install via pyoverkiz[nexity]. A clear ImportError is raised if the extra is missing at runtime.

Type Execution.state as ExecutionState instead of str

36886dd

HistoryExecution.state was already typed as ExecutionState. The live Execution model was inconsistently using a raw string for the same concept.

Make obfuscate_sensitive_data return a new dict instead of mutating

d61f930

The old implementation mutated its input in place, which was a footgun for callers who held a reference to the original data. Now returns a deep copy with sensitive values masked.

Make SUPPORTED_SERVERS immutable via MappingProxyType

34af7b0

Prevents accidental mutation of the shared server registry at module level. Read access (subscript, iteration) is unchanged.

Make event_listener_id a read-only property

91079ca

Consumers should not set this directly — it's managed internally by register/unregister_event_listener(). Exposed as a property for read access, backed by _event_listener_id.

Use None instead of empty string defaults in Location model

ba18a7f

Empty string defaults forced consumers to check truthiness rather than None-ness, inconsistent with all other optional fields in the models. Fields that may be absent from the API now properly default to None.

Raise OverkizError instead of ValueError for API data issues

c629405

DeviceIdentifier.from_device_url() and Device validation now raise OverkizError, consistent with the rest of the exception hierarchy. ValueError is reserved for programming errors (wrong argument types).

Add server parameter to create_local_server_config

c7131ec

Other brands are adding local APIs. The server parameter allows specifying which server identity to use instead of hardcoding SOMFY_DEVELOPER_MODE. Default is unchanged for backwards compat.

Revert "Move boto3 and warrant-lite to optional "nexity" extra"

7cfa833

This reverts commit f295e02.

Copilot AI review requested due to automatic review settings April 30, 2026 21:34

iMicknl requested a review from tetienne as a code owner April 30, 2026 21:34

Copilot started reviewing on behalf of iMicknl April 30, 2026 21:34 View session

iMicknl changed the title ~~v2: Final breaking changes for pyoverkiz 2.0~~ Final breaking changes before v2 release Apr 30, 2026

iMicknl changed the base branch from main to v2/main April 30, 2026 21:34

iMicknl changed the title ~~Final breaking changes before v2 release~~ Improve code quality, consistency, and developer experience Apr 30, 2026

Copilot AI reviewed Apr 30, 2026

View reviewed changes

Fix UIProfile docstring formatting by removing extra newline

57b93c6

iMicknl merged commit dc914c8 into v2/main May 1, 2026
6 checks passed

iMicknl deleted the v2/final-breaking-changes branch May 1, 2026 15:26

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Improve code quality, consistency, and developer experience#2025

Improve code quality, consistency, and developer experience#2025
iMicknl merged 12 commits intov2/mainfrom
v2/final-breaking-changes

iMicknl commented Apr 30, 2026 •

edited

Loading

Uh oh!

Copilot AI left a comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

Conversation

iMicknl commented Apr 30, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

Test plan

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

iMicknl commented Apr 30, 2026 •

edited

Loading