Accept tuple for request_timeout_seconds to match requests API

The timeout parameter now accepts either a float (applied to both connect
and read timeouts) or a (connect, read) tuple, matching the requests
library's timeout interface. Updated docstrings to reference requests.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Author: adamtheturtle

src/vws/query.py

@@ -49,15 +49,17 @@ def __init__(
         client_access_key: str,
         client_secret_key: str,
         base_vwq_url: str = "https://cloudreco.vuforia.com",
-        request_timeout_seconds: float = 30.0,
+        request_timeout_seconds: float | tuple[float, float] = 30.0,
     ) -> None:
         """
         Args:
             client_access_key: A VWS client access key.
             client_secret_key: A VWS client secret key.
             base_vwq_url: The base URL for the VWQ API.
-            request_timeout_seconds: The timeout in seconds for each HTTP
-                request made to the Cloud Reco API.
+            request_timeout_seconds: The timeout for each HTTP request, as
+                used by ``requests.request``. This can be a float to set
+                both the connect and read timeouts, or a (connect, read)
+                tuple.
         """
         self._client_access_key = client_access_key
         self._client_secret_key = client_secret_key

src/vws/vws.py

@@ -68,7 +68,7 @@ def _target_api_request(
     data: bytes,
     request_path: str,
     base_vws_url: str,
-    request_timeout_seconds: float,
+    request_timeout_seconds: float | tuple[float, float],
 ) -> Response:
     """Make a request to the Vuforia Target API.
 
@@ -83,7 +83,9 @@ def _target_api_request(
         request_path: The path to the endpoint which will be used in the
             request.
         base_vws_url: The base URL for the VWS API.
-        request_timeout_seconds: The timeout in seconds for the request.
+        request_timeout_seconds: The timeout for the request, as used by
+            ``requests.request``. This can be a float to set both the
+            connect and read timeouts, or a (connect, read) tuple.
 
     Returns:
         The response to the request made by `requests`.
@@ -135,15 +137,17 @@ def __init__(
         server_access_key: str,
         server_secret_key: str,
         base_vws_url: str = "https://vws.vuforia.com",
-        request_timeout_seconds: float = 30.0,
+        request_timeout_seconds: float | tuple[float, float] = 30.0,
     ) -> None:
         """
         Args:
             server_access_key: A VWS server access key.
             server_secret_key: A VWS server secret key.
             base_vws_url: The base URL for the VWS API.
-            request_timeout_seconds: The timeout in seconds for each HTTP
-                request made to the VWS API.
+            request_timeout_seconds: The timeout for each HTTP request, as
+                used by ``requests.request``. This can be a float to set
+                both the connect and read timeouts, or a (connect, read)
+                tuple.
         """
         self._server_access_key = server_access_key
         self._server_secret_key = server_secret_key

tests/test_query.py

@@ -65,7 +65,7 @@ def test_default_timeout() -> None:
 
     @staticmethod
     def test_custom_timeout(image: io.BytesIO | BinaryIO) -> None:
-        """It is possible to set a custom request timeout."""
+        """It is possible to set a custom request timeout as a float."""
         with MockVWS() as mock:
             database = VuforiaDatabase()
             mock.add_database(database=database)
@@ -93,6 +93,35 @@ def test_custom_timeout(image: io.BytesIO | BinaryIO) -> None:
             matches = cloud_reco_client.query(image=image)
             assert len(matches) == 1
 
+    @staticmethod
+    def test_custom_timeout_tuple(image: io.BytesIO | BinaryIO) -> None:
+        """It is possible to set separate connect and read timeouts."""
+        with MockVWS() as mock:
+            database = VuforiaDatabase()
+            mock.add_database(database=database)
+            vws_client = VWS(
+                server_access_key=database.server_access_key,
+                server_secret_key=database.server_secret_key,
+            )
+            custom_timeout = (5.0, 30.0)
+            cloud_reco_client = CloudRecoService(
+                client_access_key=database.client_access_key,
+                client_secret_key=database.client_secret_key,
+                request_timeout_seconds=custom_timeout,
+            )
+            assert cloud_reco_client.request_timeout_seconds == custom_timeout
+
+            target_id = vws_client.add_target(
+                name="x",
+                width=1,
+                image=image,
+                active_flag=True,
+                application_metadata=None,
+            )
+            vws_client.wait_for_target_processed(target_id=target_id)
+            matches = cloud_reco_client.query(image=image)
+            assert len(matches) == 1
+
     @staticmethod
     def test_timeout_raises_on_slow_response(
         image: io.BytesIO | BinaryIO,

tests/test_vws.py

@@ -114,7 +114,7 @@ def test_default_timeout() -> None:
 
     @staticmethod
     def test_custom_timeout(image: io.BytesIO | BinaryIO) -> None:
-        """It is possible to set a custom request timeout."""
+        """It is possible to set a custom request timeout as a float."""
         with MockVWS() as mock:
             database = VuforiaDatabase()
             mock.add_database(database=database)
@@ -135,6 +135,28 @@ def test_custom_timeout(image: io.BytesIO | BinaryIO) -> None:
                 application_metadata=None,
             )
 
+    @staticmethod
+    def test_custom_timeout_tuple(image: io.BytesIO | BinaryIO) -> None:
+        """It is possible to set separate connect and read timeouts."""
+        with MockVWS() as mock:
+            database = VuforiaDatabase()
+            mock.add_database(database=database)
+            custom_timeout = (5.0, 30.0)
+            vws_client = VWS(
+                server_access_key=database.server_access_key,
+                server_secret_key=database.server_secret_key,
+                request_timeout_seconds=custom_timeout,
+            )
+            assert vws_client.request_timeout_seconds == custom_timeout
+
+            vws_client.add_target(
+                name="x",
+                width=1,
+                image=image,
+                active_flag=True,
+                application_metadata=None,
+            )
+
     @staticmethod
     def test_timeout_raises_on_slow_response(
         image: io.BytesIO | BinaryIO,