feat: wire OverkizClientSettings into OverkizClient constructor (#766)

Replace the standalone `action_queue` parameter with
`settings: OverkizClientSettings | None` to consolidate all
behavioral configuration into a single entry point. This is a
v2 breaking change.

Author: iMicknl

pyoverkiz/client.py

@@ -21,8 +21,9 @@
 from backoff.types import Details
 
 from pyoverkiz._case import decamelize
-from pyoverkiz.action_queue import ActionQueue, ActionQueueSettings
+from pyoverkiz.action_queue import ActionQueue
 from pyoverkiz.auth import AuthStrategy, Credentials, build_auth_strategy
+from pyoverkiz.client_settings import OverkizClientSettings
 from pyoverkiz.const import SUPPORTED_SERVERS
 from pyoverkiz.converter import converter
 from pyoverkiz.enums import APIType, ExecutionMode, Server
@@ -172,6 +173,7 @@ class OverkizClient:
     _ssl: ssl.SSLContext | bool = True
     _auth: AuthStrategy
     _action_queue: ActionQueue | None = None
+    _rts_command_duration: int | None = None
 
     def __init__(
         self,
@@ -180,15 +182,15 @@ def __init__(
         credentials: Credentials,
         verify_ssl: bool = True,
         session: ClientSession | None = None,
-        action_queue: bool | ActionQueueSettings = False,
+        settings: OverkizClientSettings | None = None,
     ) -> None:
         """Constructor.
 
         :param server: ServerConfig
         :param credentials: Credentials for authentication
         :param verify_ssl: Enable SSL certificate verification
         :param session: optional ClientSession
-        :param action_queue: enable batching or provide queue settings (default False)
+        :param settings: behavioral settings for the client (default None)
         """
         self.server_config = self._normalize_server(server)
 
@@ -206,23 +208,15 @@ def __init__(
             # Use the prebuilt SSL context with disabled strict validation for local API.
             self._ssl = SSL_CONTEXT_LOCAL_API
 
-        # Initialize action queue if enabled
-        queue_settings: ActionQueueSettings | None
-        if isinstance(action_queue, ActionQueueSettings):
-            queue_settings = action_queue
-        elif isinstance(action_queue, bool):
-            queue_settings = ActionQueueSettings() if action_queue else None
-        else:
-            raise TypeError(
-                "action_queue must be a bool or ActionQueueSettings, "
-                f"got {type(action_queue).__name__}"
-            )
+        # Apply behavioral settings
+        resolved_settings = settings or OverkizClientSettings()
+        self._rts_command_duration = resolved_settings.rts_command_duration
 
-        if queue_settings:
-            queue_settings.validate()
+        if resolved_settings.action_queue:
+            resolved_settings.action_queue.validate()
             self._action_queue = ActionQueue(
                 executor=self._execute_action_group_direct,
-                settings=queue_settings,
+                settings=resolved_settings.action_queue,
             )
 
         self._auth = build_auth_strategy(

tests/test_client.py

@@ -10,13 +10,17 @@
 import pytest
 
 from pyoverkiz import exceptions
+from pyoverkiz.action_queue import ActionQueueSettings
+from pyoverkiz.auth import UsernamePasswordCredentials
 from pyoverkiz.client import OverkizClient
+from pyoverkiz.client_settings import OverkizClientSettings
 from pyoverkiz.enums import (
     APIType,
     DataType,
     ExecutionState,
     ExecutionSubType,
     ExecutionType,
+    Server,
 )
 from pyoverkiz.models import (
     Action,
@@ -1203,3 +1207,32 @@ async def test_local_schedule_persisted_action_group_unknown_object(
             await local_client.schedule_persisted_action_group(
                 "00000000-0000-0000-0000-000000000000", 9999999999
             )
+
+
+class TestOverkizClientSettings:
+    """Tests for the OverkizClientSettings integration with OverkizClient."""
+
+    def test_client_with_settings_none(self, client: OverkizClient) -> None:
+        """Client without settings has no action queue and no RTS duration."""
+        assert client._action_queue is None
+        assert client._rts_command_duration is None
+
+    @pytest.mark.asyncio
+    async def test_client_with_rts_duration(self) -> None:
+        """Client stores RTS command duration from settings."""
+        client = OverkizClient(
+            server=Server.SOMFY_EUROPE,
+            credentials=UsernamePasswordCredentials("user", "pass"),
+            settings=OverkizClientSettings(rts_command_duration=0),
+        )
+        assert client._rts_command_duration == 0
+
+    @pytest.mark.asyncio
+    async def test_client_with_action_queue_via_settings(self) -> None:
+        """Client creates action queue from settings."""
+        client = OverkizClient(
+            server=Server.SOMFY_EUROPE,
+            credentials=UsernamePasswordCredentials("user", "pass"),
+            settings=OverkizClientSettings(action_queue=ActionQueueSettings()),
+        )
+        assert client._action_queue is not None

tests/test_client_queue_integration.py

@@ -8,6 +8,7 @@
 from pyoverkiz.action_queue import ActionQueueSettings
 from pyoverkiz.auth import UsernamePasswordCredentials
 from pyoverkiz.client import OverkizClient
+from pyoverkiz.client_settings import OverkizClientSettings
 from pyoverkiz.enums import OverkizCommand, Server
 from pyoverkiz.models import Action, Command
 
@@ -18,7 +19,6 @@ async def test_client_without_queue_executes_immediately():
     client = OverkizClient(
         server=Server.SOMFY_EUROPE,
         credentials=UsernamePasswordCredentials("test@example.com", "test"),
-        action_queue=False,
     )
 
     action = Action(
@@ -48,7 +48,7 @@ async def test_client_with_queue_batches_actions():
     client = OverkizClient(
         server=Server.SOMFY_EUROPE,
         credentials=UsernamePasswordCredentials("test@example.com", "test"),
-        action_queue=ActionQueueSettings(delay=0.1),
+        settings=OverkizClientSettings(action_queue=ActionQueueSettings(delay=0.1)),
     )
 
     actions = [
@@ -98,7 +98,9 @@ async def test_client_manual_flush():
     client = OverkizClient(
         server=Server.SOMFY_EUROPE,
         credentials=UsernamePasswordCredentials("test@example.com", "test"),
-        action_queue=ActionQueueSettings(delay=10.0),  # Long delay
+        settings=OverkizClientSettings(
+            action_queue=ActionQueueSettings(delay=10.0)
+        ),  # Long delay
     )
 
     action = Action(
@@ -138,7 +140,7 @@ async def test_client_close_flushes_queue():
     client = OverkizClient(
         server=Server.SOMFY_EUROPE,
         credentials=UsernamePasswordCredentials("test@example.com", "test"),
-        action_queue=ActionQueueSettings(delay=10.0),
+        settings=OverkizClientSettings(action_queue=ActionQueueSettings(delay=10.0)),
     )
 
     action = Action(
@@ -171,9 +173,11 @@ async def test_client_queue_respects_max_actions():
     client = OverkizClient(
         server=Server.SOMFY_EUROPE,
         credentials=UsernamePasswordCredentials("test@example.com", "test"),
-        action_queue=ActionQueueSettings(
-            delay=10.0,
-            max_actions=2,  # Max 2 actions
+        settings=OverkizClientSettings(
+            action_queue=ActionQueueSettings(
+                delay=10.0,
+                max_actions=2,  # Max 2 actions
+            ),
         ),
     )