feat(python-sdk): keep httpx.ReadTimeout as the API timeout exception

pyqwest raises the builtin TimeoutError for its transport timeouts, which
would break callers catching httpx.TimeoutException; the adapter subclasses
re-raise it as httpx.ReadTimeout.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

Author: mishushakov

.changeset/python-pyqwest-rest-transport.md

@@ -16,7 +16,8 @@ proxy, instead of one pool per thread (sync) or per event loop (async), and
 single httpx client serves all threads and event loops.
 Connection-establishment failures are retried with backoff
 (`E2B_CONNECTION_RETRIES`, default 3), matching the connect-only retries of
-the previous transports.
+the previous transports. Timeouts keep raising `httpx.ReadTimeout` (an
+`httpx.TimeoutException`), as before.
 
 `proxy` for API calls now takes a URL string (e.g.
 `proxy="http://user:pass@localhost:8030"`, scheme http, https, socks5, or

packages/python-sdk/e2b/api/client_async/__init__.py

@@ -28,17 +28,28 @@ def get_api_client(config: ConnectionConfig, **kwargs) -> AsyncApiClient:
 
 
 class AsyncApiPyqwestTransport(AsyncPyqwestTransport):
-    """Strip the ``Host`` header httpx adds to every request: hyper derives
+    """The SDK's tweaks on the stock pyqwest httpx adapter.
+
+    Strip the ``Host`` header httpx adds to every request: hyper derives
     HTTP/1 ``Host`` and HTTP/2 ``:authority`` from the URL itself, and
     forwarding an explicit ``host`` header on an HTTP/2 connection makes the
     E2B API edge reset the stream with PROTOCOL_ERROR. (Custom ``Host``
     overrides are therefore not honored, matching hyper's URL-derived
-    behavior.)"""
+    behavior.)
+
+    Re-raise pyqwest's timeouts (the builtin ``TimeoutError``, and
+    ``asyncio.TimeoutError`` from the adapter's deadline — distinct types
+    until Python 3.11) as ``httpx.ReadTimeout``, preserving the
+    ``httpx.TimeoutException`` contract the httpx-native transport gave
+    callers."""
 
     async def handle_async_request(self, request: httpx.Request) -> httpx.Response:
         if "host" in request.headers:
             del request.headers["host"]
-        return await super().handle_async_request(request)
+        try:
+            return await super().handle_async_request(request)
+        except (TimeoutError, asyncio.TimeoutError) as e:
+            raise httpx.ReadTimeout(str(e), request=request) from e
 
 
 class ConnectionRetryTransport(RetryTransport):

packages/python-sdk/e2b/api/client_sync/__init__.py

@@ -26,17 +26,26 @@ def get_api_client(config: ConnectionConfig, **kwargs) -> ApiClient:
 
 
 class ApiPyqwestTransport(PyqwestTransport):
-    """Strip the ``Host`` header httpx adds to every request: hyper derives
+    """The SDK's tweaks on the stock pyqwest httpx adapter.
+
+    Strip the ``Host`` header httpx adds to every request: hyper derives
     HTTP/1 ``Host`` and HTTP/2 ``:authority`` from the URL itself, and
     forwarding an explicit ``host`` header on an HTTP/2 connection makes the
     E2B API edge reset the stream with PROTOCOL_ERROR. (Custom ``Host``
     overrides are therefore not honored, matching hyper's URL-derived
-    behavior.)"""
+    behavior.)
+
+    Re-raise pyqwest's timeouts (the builtin ``TimeoutError``) as
+    ``httpx.ReadTimeout``, preserving the ``httpx.TimeoutException`` contract
+    the httpx-native transport gave callers."""
 
     def handle_request(self, request: httpx.Request) -> httpx.Response:
         if "host" in request.headers:
             del request.headers["host"]
-        return super().handle_request(request)
+        try:
+            return super().handle_request(request)
+        except TimeoutError as e:
+            raise httpx.ReadTimeout(str(e), request=request) from e
 
 
 class ConnectionRetryTransport(SyncRetryTransport):

packages/python-sdk/tests/test_api_client_transport.py

@@ -2,6 +2,7 @@
 import json
 import ssl
 import threading
+import time
 from concurrent.futures import ThreadPoolExecutor
 from http.server import BaseHTTPRequestHandler, ThreadingHTTPServer
 from typing import cast
@@ -364,9 +365,12 @@ async def test_async_envd_transport_uses_separate_stack(test_api_key):
 
 
 class _EchoHandler(BaseHTTPRequestHandler):
-    """Answers every GET with a JSON echo of the request headers."""
+    """Answers every GET with a JSON echo of the request headers; a path
+    starting with ``/slow`` sleeps 5 seconds first."""
 
     def do_GET(self):
+        if self.path.startswith("/slow"):
+            time.sleep(5)
         headers = {k.lower(): v for k, v in self.headers.items()}
         body = json.dumps({"path": self.path, "headers": headers}).encode()
         self.send_response(200)
@@ -469,3 +473,36 @@ async def test_async_api_client_round_trips_through_pyqwest(test_api_key, echo_s
     finally:
         await httpx_client.aclose()
         reset_async_api_transports()
+
+
+def test_sync_api_client_timeout_raises_httpx_read_timeout(test_api_key, echo_server):
+    # pyqwest raises the builtin TimeoutError; the transport re-raises it as
+    # httpx.ReadTimeout to keep the httpx.TimeoutException contract.
+    reset_sync_api_transports()
+    config = ConnectionConfig(api_key=test_api_key, api_url=echo_server)
+    api_client = get_sync_api_client(config)
+    httpx_client = api_client.get_httpx_client()
+
+    try:
+        with pytest.raises(httpx.ReadTimeout):
+            httpx_client.request("GET", "/slow", timeout=0.2)
+    finally:
+        httpx_client.close()
+        reset_sync_api_transports()
+
+
+@pytest.mark.asyncio
+async def test_async_api_client_timeout_raises_httpx_read_timeout(
+    test_api_key, echo_server
+):
+    reset_async_api_transports()
+    config = ConnectionConfig(api_key=test_api_key, api_url=echo_server)
+    api_client = get_async_api_client(config)
+    httpx_client = api_client.get_async_httpx_client()
+
+    try:
+        with pytest.raises(httpx.ReadTimeout):
+            await httpx_client.request("GET", "/slow", timeout=0.2)
+    finally:
+        await httpx_client.aclose()
+        reset_async_api_transports()