2.0

.devcontainer/devcontainer.json

@@ -12,7 +12,7 @@
 	// Use 'forwardPorts' to make a list of ports inside the container available locally.
 	// "forwardPorts": [],
 	// Use 'postCreateCommand' to run commands after the container is created.
-	"postCreateCommand": "uv sync && uv run pre-commit install",
+	"postCreateCommand": "uv sync --all-extras --dev && uv run prek install",
 	// Configure tool-specific properties.
 	"customizations": {
 		"vscode": {

.github/workflows/docs.yml

@@ -0,0 +1,56 @@
+name: docs
+
+on:
+  release:
+    types:
+      - created
+  pull_request:
+    paths:
+      - docs/**
+      - mkdocs.yml
+      - pyproject.toml
+      - README.md
+
+permissions:
+  contents: read
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.11"
+
+      - name: Set up uv
+        uses: astral-sh/setup-uv@v3
+
+      - name: Install docs dependencies
+        run: uv sync --all-extras --dev
+
+      - name: Build site
+        run: uv run mkdocs build
+
+      - name: Upload Pages artifact
+        uses: actions/upload-pages-artifact@v3
+        with:
+          path: site
+
+  deploy:
+    if: github.event_name == 'release'
+    needs: build
+    runs-on: ubuntu-latest
+    permissions:
+      pages: write
+      id-token: write
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    steps:
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@v4

.github/workflows/lint.yaml

@@ -13,7 +13,7 @@ jobs:
     strategy:
       fail-fast: false
       matrix:
-        python-version: ["3.10", "3.11", "3.12", "3.13", "3.14"]
+        python-version: ["3.12", "3.13", "3.14"]
 
     steps:
       - uses: actions/checkout@v6
@@ -32,7 +32,7 @@ jobs:
       - name: Install the project
         run: uv sync --all-extras --dev
 
-      - name: Run pre-commit
+      - name: Run prek (pre-commit checks)
         env:
           SKIP: ${{ github.ref == 'refs/heads/main' && 'no-commit-to-branch' || '' }}
-        run: uv run pre-commit run --show-diff-on-failure --color=always --all-files
+        run: uv run prek run --show-diff-on-failure --color=always --all-files

.github/workflows/test.yml

@@ -13,7 +13,7 @@ jobs:
     strategy:
       fail-fast: false
       matrix:
-        python-version: ["3.10", "3.11", "3.12", "3.13", "3.14"]
+        python-version: ["3.12", "3.13", "3.14"]
 
     steps:
       - uses: actions/checkout@v6

.pre-commit-config.yaml

@@ -16,7 +16,7 @@ repos:
     -   id: trailing-whitespace
     -   id: end-of-file-fixer
     -   id: check-json
-        exclude: .devcontainer
+        exclude: .devcontainer|.vscode
     -   id: check-yaml
     -   id: check-added-large-files
     -   id: no-commit-to-branch

.vscode/tasks.json

@@ -0,0 +1,18 @@
+{
+    // See https://go.microsoft.com/fwlink/?LinkId=733558
+    // for the documentation about the tasks.json format
+    "version": "2.0.0",
+    "tasks": [
+        {
+            "label": "Docs: Serve (development)",
+            "type": "shell",
+            "command": "uv run mkdocs serve",
+            "problemMatcher": []
+        },
+        {
+            "label": "Docs: Build",
+            "type": "shell",
+            "command": "uv run mkdocs build --clean"
+        }
+    ]
+}

AGENTS.md

@@ -29,10 +29,10 @@ Always use full type annotations, generics, and other modern practices.
   # Install all dependencies:
   uv sync
 
-  # Run linting (with ruff), pre-commit checks and type checking (with mypy).
+  # Run linting (with ruff), prek (pre-commit alternative) checks and type checking (with mypy).
   # Note when you run this, ruff will auto-format and sort imports, resolving any
   # linter warnings about import ordering:
-  uv run pre-commit run --all-files
+  uv run prek run --all-files
 
   # Run tests:
   uv run pytest

README.md

@@ -37,17 +37,19 @@ pip install pyoverkiz
 import asyncio
 import time
 
-from pyoverkiz.const import SUPPORTED_SERVERS
+from pyoverkiz.auth.credentials import UsernamePasswordCredentials
 from pyoverkiz.client import OverkizClient
-from pyoverkiz.enums import Server
+from pyoverkiz.models import Action
+from pyoverkiz.enums import Server, OverkizCommand
 
 USERNAME = ""
 PASSWORD = ""
 
 
 async def main() -> None:
     async with OverkizClient(
-        USERNAME, PASSWORD, server=SUPPORTED_SERVERS[Server.SOMFY_EUROPE]
+        server=Server.SOMFY_EUROPE,
+        credentials=UsernamePasswordCredentials(USERNAME, PASSWORD),
     ) as client:
         try:
             await client.login()
@@ -61,6 +63,19 @@ async def main() -> None:
             print(f"{device.label} ({device.id}) - {device.controllable_name}")
             print(f"{device.widget} - {device.ui_class}")
 
+        await client.execute_action_group(
+            actions=[
+                Action(
+                    device_url="io://1234-5678-1234/12345678",
+                    commands=[
+                        Command(name=OverkizCommand.SET_CLOSURE, parameters=[100])
+                    ]
+                )
+            ],
+            label="Execution via Python",
+            # mode=CommandMode.HIGH_PRIORITY
+        )
+
         while True:
             events = await client.fetch_events()
             print(events)
@@ -76,38 +91,22 @@ asyncio.run(main())
 ```python
 import asyncio
 import time
-import aiohttp
 
+from pyoverkiz.auth.credentials import LocalTokenCredentials
 from pyoverkiz.client import OverkizClient
-from pyoverkiz.const import SUPPORTED_SERVERS, OverkizServer
-from pyoverkiz.enums import Server
+from pyoverkiz.utils import create_local_server_config
 
-USERNAME = ""
-PASSWORD = ""
 LOCAL_GATEWAY = "gateway-xxxx-xxxx-xxxx.local"  # or use the IP address of your gateway
 VERIFY_SSL = True  # set verify_ssl to False if you don't use the .local hostname
 
 
 async def main() -> None:
     token = ""  # generate your token via the Somfy app and include it here
 
-    # Local Connection
-    session = aiohttp.ClientSession(
-        connector=aiohttp.TCPConnector(verify_ssl=VERIFY_SSL)
-    )
-
     async with OverkizClient(
-        username="",
-        password="",
-        token=token,
-        session=session,
+        server=create_local_server_config(host=LOCAL_GATEWAY),
+        credentials=LocalTokenCredentials(token),
         verify_ssl=VERIFY_SSL,
-        server=OverkizServer(
-            name="Somfy TaHoma (local)",
-            endpoint=f"https://{LOCAL_GATEWAY}:8443/enduser-mobile-web/1/enduserAPI/",
-            manufacturer="Somfy",
-            configuration_url=None,
-        ),
     ) as client:
         await client.login()
 

docs/action-queue.md

@@ -0,0 +1,147 @@
+# Action queue
+
+The action queue automatically groups rapid, consecutive calls to `execute_action_group()` into a single ActionGroup execution. This minimizes the number of API calls and helps prevent rate limiting issues, such as `TooManyRequestsException`, `TooManyConcurrentRequestsException`, `TooManyExecutionsException`, or `ExecutionQueueFullException` which can occur if actions are sent individually in quick succession.
+
+Important limitation:
+- Gateways only allow a single action per device in each action group. The queue
+    merges commands for the same `device_url` into a single action to keep the
+    batch valid and preserve command order for that device.
+- If you pass multiple actions for the same `device_url` in a single
+    `execute_action_group()` call, the queue will merge them for you.
+
+## Enable with defaults
+
+Set `action_queue=True` to enable batching with default settings:
+
+```python
+import asyncio
+
+from pyoverkiz.auth import UsernamePasswordCredentials
+from pyoverkiz.client import OverkizClient
+from pyoverkiz.enums import OverkizCommand, Server
+from pyoverkiz.models import Action, Command
+
+client = OverkizClient(
+    server=Server.SOMFY_EUROPE,
+    credentials=UsernamePasswordCredentials("user@example.com", "password"),
+    action_queue=True,  # uses defaults
+)
+
+action1 = Action(
+    device_url="io://1234-5678-1234/12345678",
+    commands=[Command(name=OverkizCommand.CLOSE)],
+)
+action2 = Action(
+    device_url="io://1234-5678-1234/87654321",
+    commands=[Command(name=OverkizCommand.OPEN)],
+)
+
+task1 = asyncio.create_task(client.execute_action_group([action1]))
+task2 = asyncio.create_task(client.execute_action_group([action2]))
+exec_id1, exec_id2 = await asyncio.gather(task1, task2)
+
+print(exec_id1 == exec_id2)
+```
+
+Defaults:
+- `delay=0.5`
+- `max_actions=20`
+
+## Advanced settings
+
+If you need to tune batching behavior, pass `ActionQueueSettings`:
+
+```python
+import asyncio
+
+from pyoverkiz.action_queue import ActionQueueSettings
+from pyoverkiz.client import OverkizClient
+from pyoverkiz.auth import UsernamePasswordCredentials
+from pyoverkiz.enums import OverkizCommand, Server
+from pyoverkiz.models import Action, Command
+
+client = OverkizClient(
+    server=Server.SOMFY_EUROPE,
+    credentials=UsernamePasswordCredentials("user@example.com", "password"),
+    action_queue=ActionQueueSettings(
+        delay=0.5,  # seconds to wait before auto-flush
+        max_actions=20,  # auto-flush when this count is reached
+    ),
+)
+```
+
+## `flush_action_queue()` (force immediate execution)
+
+Normally, queued actions are sent after the delay window or when `max_actions` is reached. Call `flush_action_queue()` to force the queue to execute immediately, which is useful when you want to send any pending actions without waiting for the delay timer to expire.
+
+```python
+from pyoverkiz.action_queue import ActionQueueSettings
+import asyncio
+
+from pyoverkiz.client import OverkizClient
+from pyoverkiz.auth import UsernamePasswordCredentials
+from pyoverkiz.enums import OverkizCommand, Server
+from pyoverkiz.models import Action, Command
+
+client = OverkizClient(
+    server=Server.SOMFY_EUROPE,
+    credentials=UsernamePasswordCredentials("user@example.com", "password"),
+    action_queue=ActionQueueSettings(delay=10.0),  # long delay
+)
+
+action = Action(
+    device_url="io://1234-5678-1234/12345678",
+    commands=[Command(name=OverkizCommand.CLOSE)],
+)
+
+exec_task = asyncio.create_task(client.execute_action_group([action]))
+
+# Give it time to enter the queue
+await asyncio.sleep(0.05)
+
+# Force immediate execution instead of waiting 10 seconds
+await client.flush_action_queue()
+
+exec_id = await exec_task
+print(exec_id)
+```
+
+Why this matters:
+- It lets you keep a long delay for batching, but still force a quick execution when a user interaction demands it.
+- Useful before shutdown to avoid leaving actions waiting in the queue.
+
+## `get_pending_actions_count()` (best-effort count)
+
+`get_pending_actions_count()` returns a snapshot of how many actions are currently queued. Because the queue can change concurrently (and the method does not acquire the queue lock), the value is approximate. Use it for logging, diagnostics, or UI hints—not for critical control flow.
+
+```python
+from pyoverkiz.client import OverkizClient
+from pyoverkiz.auth import UsernamePasswordCredentials
+from pyoverkiz.enums import OverkizCommand, Server
+from pyoverkiz.models import Action, Command
+
+client = OverkizClient(
+    server=Server.SOMFY_EUROPE,
+    credentials=UsernamePasswordCredentials("user@example.com", "password"),
+    action_queue=True,
+)
+
+action = Action(
+    device_url="io://1234-5678-1234/12345678",
+    commands=[Command(name=OverkizCommand.CLOSE)],
+)
+
+exec_task = asyncio.create_task(client.execute_action_group([action]))
+await asyncio.sleep(0.01)
+
+pending = client.get_pending_actions_count()
+print(f"Pending actions (approx): {pending}")
+
+exec_id = await exec_task
+print(exec_id)
+```
+
+Why it’s best-effort:
+- Actions may flush automatically while you read the count.
+- New actions may be added concurrently by other tasks.
+- The count can be briefly stale, so avoid using it to decide whether you must flush or not.

docs/api-reference.md

@@ -0,0 +1,13 @@
+::: pyoverkiz.client.OverkizClient
+
+::: pyoverkiz.models
+    options:
+      show_source: false
+
+::: pyoverkiz.enums
+    options:
+      show_source: false
+
+::: pyoverkiz.exceptions
+    options:
+      show_source: false