Add execute_action_group method and remove other command execution methods.

[iMicknl]

Breaking changes

• client.execute_command() and client.execute_commands() are replaced by client.execute_action_group()

Enhancements

• client.execute_action_group() now supports multiple execution modes (high priority, internal, geolocated)
• client.execute_action_group() now supports multiple device actions in the same request

Proposal

The current execution methods are poorly typed and do not support concurrent execution across multiple devices, which makes it impossible to properly work around TooManyExecutionsException and TooManyConcurrentRequestsException.

The main change is the move from client.execute_command() and client.execute_commands() to a single client.execute_action_group(). An action group takes a list of actions, each of which can include multiple device actions, including multiple commands per action.

Method examples

await client.execute_action_group(
    actions=[
        Action(
            device_url="io://1234-5678-1234/12345678",
            commands=[
                Command(name="down"),
                Command(name="refresh")
            ]
        )
    ],
    label="Execution via Home Assistant"
)

New (mode) options like high priority will be possible now:

await client.execute_action_group(
    actions=[
        Action(
            device_url="io://1234-5678-1234/12345678",
            commands=[
                Command(name=OverkizCommand.SET_CLOSURE, parameters=[0])
            ]
        )
    ],
    label="Execution via Home Assistant",
    mode=CommandMode.HIGH_PRIORITY
)

Next steps

This could serve as a foundation for grouping commands that are executed within a short time window, for example when triggered by a scene or automation in Home Assistant. Requests issued close together could be batched and sent as a single action group, reducing the impact of current Overkiz limitations.

The open question is where this queue should live: inside this integration itself, or as part of the Home Assistant core implementation.

[iMicknl]

I am not a huge fan of how we serialize the models to JSON (and vice-versa) with attrs and humps. We might need to see if moving to pydantic is a cleaner option here.

[Copilot]

Pull request overview

This PR refactors command execution to use a new execute_action_group() method that replaces the existing execute_command() and execute_commands() methods. The refactoring improves type safety, enables concurrent execution across multiple devices, and introduces support for command execution modes (high priority, geolocated, internal).

Key changes:

• Introduced a new serializers module to centralize payload formatting (snake_case to camelCase conversion)
• Refactored the Command class from a dict-based model to an attrs-based class with proper typing and a to_payload() method
• Added execute_action_group() method with support for CommandMode options

Reviewed changes

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

Show a summary per file

File	Description
pyoverkiz/serializers.py	New module that handles JSON key formatting (snake_case to camelCase) and special abbreviation fixes like deviceURL
pyoverkiz/models.py	Refactored Command class to use attrs with typed parameters supporting OverkizCommandParam enums; updated Action class to accept Command objects and added to_payload methods
pyoverkiz/client.py	Replaced execute_command/execute_commands with execute_action_group that supports multiple CommandMode options (high priority, geolocated, internal)
tests/test_serializers.py	Added comprehensive tests for payload serialization including nested structures and device URL handling
tests/test_models.py	Added tests for Command and Action to_payload methods including None field omission and enum conversion
tests/test_client.py	Added test to verify execute_action_group correctly omits None fields and applies proper serialization

---

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