fix(client): map a connect timeout to ConnectTimeout, not Timeout

requests.ConnectTimeout is both a ConnectionError and a Timeout. Mapping
httpx.ConnectTimeout to a plain Timeout — which is all httpx's own hierarchy
implies — stops every caller that catches the connection family from catching a
connect timeout.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_014f9oEEYspPH4fmPULTnLkJ

Author: chandrasekharan-zipstack

src/unstract/api_deployments/client.py

@@ -19,7 +19,7 @@
 # `requests` remains a dependency for its exception classes. Downstream code
 # catches ConnectionError and Timeout by name around these calls, and the httpx
 # equivalents are not subclasses, so they are translated at the transport seam.
-from requests.exceptions import ConnectionError, Timeout
+from requests.exceptions import ConnectionError, ConnectTimeout, Timeout
 from tenacity import (
     RetryCallState,
     Retrying,
@@ -47,6 +47,10 @@ def _translate_transport_errors(fn, *args, **kwargs):
     """
     try:
         return fn(*args, **kwargs)
+    except httpx.ConnectTimeout as e:
+        # ConnectTimeout is both a ConnectionError and a Timeout; the plain
+        # Timeout httpx implies would stop matching half the callers.
+        raise ConnectTimeout(str(e)) from e
     except httpx.TimeoutException as e:
         raise Timeout(str(e)) from e
     except httpx.ConnectError as e:

tests/test_compat.py

@@ -19,7 +19,7 @@
 import httpx
 import pytest
 import requests
-from requests.exceptions import ConnectionError, Timeout
+from requests.exceptions import ConnectionError, ConnectTimeout, Timeout
 
 from unstract.api_deployments.client import (
     _EXECUTE_SEND_ONLY,
@@ -103,7 +103,7 @@ def _requests_response(status_code=200, json_data=None, text=None):
 @pytest.mark.parametrize(
     ("raised", "expected"),
     [
-        (httpx.ConnectTimeout("connect timed out"), Timeout),
+        (httpx.ConnectTimeout("connect timed out"), ConnectTimeout),
         (httpx.ReadTimeout("read timed out"), Timeout),
         (httpx.WriteTimeout("write timed out"), Timeout),
         (httpx.PoolTimeout("pool timed out"), Timeout),
@@ -117,9 +117,9 @@ def _requests_response(status_code=200, json_data=None, text=None):
 def test_transport_errors_are_translated(raised, expected):
     """Callers catch the ``requests`` classes; httpx's are not subclasses.
 
-    ``ConnectTimeout`` is the case that makes ordering load-bearing: it is a
-    timeout, not a ``ConnectError``, and matching on connection first would
-    mislabel it.
+    ``ConnectTimeout`` is the case that makes ordering load-bearing, and it is
+    also both a ``ConnectionError`` and a ``Timeout`` — the plain ``Timeout``
+    that httpx's hierarchy implies would stop matching half the callers.
     """
     client = _client()
     with patch.object(
@@ -129,6 +129,24 @@ def test_transport_errors_are_translated(raised, expected):
             client._send("get", "/anything")
 
 
+def test_a_connect_timeout_is_still_a_connection_error():
+    client = _client()
+    with patch.object(
+        client._transport.get_httpx_client(),
+        "request",
+        side_effect=httpx.ConnectTimeout("connect timed out"),
+    ):
+        with pytest.raises(ConnectionError):
+            client._send("get", "/anything")
+    with patch.object(
+        client._transport.get_httpx_client(),
+        "request",
+        side_effect=httpx.ConnectTimeout("connect timed out"),
+    ):
+        with pytest.raises(Timeout):
+            client._send("get", "/anything")
+
+
 def test_translated_errors_keep_the_original_cause():
     client = _client()
     original = httpx.ConnectError("refused")