feat(python-sdk): reduce httpx.Proxy proxies to URLs, keep stream_idle_timeout as no-op

proxy_to_url now accepts httpx.Proxy when it reduces to a plain proxy
URL (auth folded back into the userinfo), matching the envd RPC proxy
narrowing in #1558; extras pyqwest can't express (custom headers,
ssl_context) still raise InvalidArgumentException. Applies to the REST
API, volume content, and template upload transports alike.

Volume.read_file keeps stream_idle_timeout in its signature for
backwards compatibility but ignores it — the transport-wide idle read
timeout bounds stalled streams.

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

Author: mishushakov

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

@@ -13,9 +13,9 @@ event hooks, per-request timeouts, and headers behave as before.
 For streamed volume reads (`Volume.read_file(format="stream")`), a stalled
 stream is now bounded by a transport-wide idle read timeout that resets on
 every chunk (still surfaced as `httpx.ReadTimeout`); the per-call
-`stream_idle_timeout` parameter is removed. Passing `request_timeout` to a
-streamed read (and to template uploads) now bounds the whole transfer rather
-than individual socket operations.
+`stream_idle_timeout` parameter is deprecated and ignored. Passing
+`request_timeout` to a streamed read (and to template uploads) now bounds
+the whole transfer rather than individual socket operations.
 
 Because pyqwest transports are thread-safe and loop-independent (I/O runs on
 a Rust runtime), the API connection pool is now shared process-wide per
@@ -26,10 +26,13 @@ Connection-establishment failures are retried with backoff
 (`E2B_CONNECTION_RETRIES`, default 3), matching the connect-only retries of
 the previous transports.
 
-`proxy` for API calls must now be a URL string (e.g.
+`proxy` for API calls now takes a URL string (e.g.
 `proxy="http://user:pass@localhost:8030"`, scheme http, https, socks5, or
-socks5h); the richer `httpx.Proxy` objects are rejected with
-`InvalidArgumentException` rather than partially honored.
+socks5h). `httpx.URL` and `httpx.Proxy` keep working when they reduce to
+such a URL (`httpx.Proxy` auth is folded back into the URL userinfo);
+`httpx.Proxy` extras pyqwest can't express — custom headers, an
+`ssl_context` — raise `InvalidArgumentException` rather than being silently
+dropped.
 
 envd traffic (sandbox commands, filesystem, PTY, file transfers) is not
 affected and stays on its existing stack.

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

@@ -81,15 +81,31 @@ async def on_response(response: Response) -> None:
 def proxy_to_url(proxy: Optional[ProxyTypes]) -> Optional[str]:
     """Narrow the ``proxy`` connection option to the proxy URL string pyqwest
     transports take (scheme http, https, socks5, or socks5h, credentials in
-    the URL userinfo). The richer ``httpx.Proxy`` objects the httpx transports
-    accepted (per-proxy auth, headers, TLS context) are rejected rather than
-    partially honored."""
+    the URL userinfo). ``httpx.URL`` and ``httpx.Proxy`` — which the httpx
+    transports accepted — are converted when they reduce to such a URL;
+    ``httpx.Proxy`` extras that don't (custom headers, an ssl_context) are
+    rejected rather than silently dropped."""
     if proxy is None:
         return None
     if isinstance(proxy, str):
         return proxy
     if isinstance(proxy, httpx.URL):
         return str(proxy)
+    if isinstance(proxy, httpx.Proxy):
+        if proxy.headers:
+            raise InvalidArgumentException(
+                "E2B API calls don't support httpx.Proxy custom headers; "
+                "pass credentials in the proxy URL instead, "
+                'e.g. proxy="http://user:pass@localhost:8030"'
+            )
+        if proxy.ssl_context is not None:
+            raise InvalidArgumentException(
+                "E2B API calls don't support httpx.Proxy ssl_context"
+            )
+        url = proxy.url
+        if proxy.auth is not None:
+            url = url.copy_with(username=proxy.auth[0], password=proxy.auth[1])
+        return str(url)
     raise InvalidArgumentException(
         "E2B API calls support only URL-string proxies, "
         'e.g. proxy="http://user:pass@localhost:8030"'

packages/python-sdk/e2b/volume/volume_async.py

@@ -448,13 +448,15 @@ async def read_file(
         self,
         path: str,
         format: Literal["stream"],
+        stream_idle_timeout: Optional[float] = None,
         **opts: Unpack[VolumeApiParams],
     ) -> AsyncIterator[bytes]: ...
 
     async def read_file(
         self,
         path: str,
         format: Literal["text", "bytes", "stream"] = "text",
+        stream_idle_timeout: Optional[float] = None,
         **opts: Unpack[VolumeApiParams],
     ) -> Union[str, bytes, AsyncIterator[bytes]]:
         """
@@ -464,6 +466,9 @@ async def read_file(
 
         :param path: Path to the file
         :param format: Format of the file content—`text` by default
+        :param stream_idle_timeout: Deprecated and ignored. A stalled streamed
+            read is bounded by a transport-wide idle read timeout instead,
+            which resets on every chunk.
         :param opts: Connection options
 
         :return: File content as string, bytes, or async iterator of bytes

packages/python-sdk/e2b/volume/volume_sync.py

@@ -445,13 +445,15 @@ def read_file(
         self,
         path: str,
         format: Literal["stream"],
+        stream_idle_timeout: Optional[float] = None,
         **opts: Unpack[VolumeApiParams],
     ) -> Iterator[bytes]: ...
 
     def read_file(
         self,
         path: str,
         format: Literal["text", "bytes", "stream"] = "text",
+        stream_idle_timeout: Optional[float] = None,
         **opts: Unpack[VolumeApiParams],
     ) -> Union[str, bytes, Iterator[bytes]]:
         """
@@ -461,6 +463,9 @@ def read_file(
 
         :param path: Path to the file
         :param format: Format of the file content—`text` by default
+        :param stream_idle_timeout: Deprecated and ignored. A stalled streamed
+            read is bounded by a transport-wide idle read timeout instead,
+            which resets on every chunk.
         :param opts: Connection options
 
         :return: File content as string, bytes, or iterator of bytes

packages/python-sdk/tests/test_api_client_transport.py

@@ -1,5 +1,6 @@
 import asyncio
 import json
+import ssl
 import threading
 from concurrent.futures import ThreadPoolExecutor
 from http.server import BaseHTTPRequestHandler, ThreadingHTTPServer
@@ -54,8 +55,31 @@ def test_proxy_to_url_narrows_to_url_strings():
     assert proxy_to_url(None) is None
     assert proxy_to_url("http://127.0.0.1:9999") == "http://127.0.0.1:9999"
     assert proxy_to_url(httpx.URL("http://127.0.0.1:9999")) == "http://127.0.0.1:9999"
+
+
+def test_proxy_to_url_reduces_httpx_proxy():
+    # httpx.Proxy converts when it reduces to a plain proxy URL, with
+    # credentials (which httpx.Proxy splits off the URL) folded back into
+    # the userinfo.
+    assert proxy_to_url(httpx.Proxy("http://127.0.0.1:9999")) == "http://127.0.0.1:9999"
+    assert (
+        proxy_to_url(httpx.Proxy("http://user:pass@127.0.0.1:9999"))
+        == "http://user:pass@127.0.0.1:9999"
+    )
+    assert (
+        proxy_to_url(httpx.Proxy("http://127.0.0.1:9999", auth=("user", "pass")))
+        == "http://user:pass@127.0.0.1:9999"
+    )
+
+    # Extras pyqwest can't express are rejected rather than silently dropped.
+    with pytest.raises(InvalidArgumentException):
+        proxy_to_url(httpx.Proxy("http://127.0.0.1:9999", headers={"X-Auth": "t"}))
     with pytest.raises(InvalidArgumentException):
-        proxy_to_url(httpx.Proxy("http://127.0.0.1:9999"))
+        proxy_to_url(
+            httpx.Proxy(
+                "https://127.0.0.1:9999", ssl_context=ssl.create_default_context()
+            )
+        )
 
 
 def test_connection_retry_policy_retries_only_connection_errors():

packages/python-sdk/tests/test_volume_client.py

@@ -180,10 +180,14 @@ def short_read_timeout(monkeypatch):
 def test_sync_stream_survives_transfers_longer_than_read_timeout(short_read_timeout):
     # The transport read timeout is an idle bound that resets on every chunk:
     # a healthy stream whose total duration exceeds it must complete.
+    # `stream_idle_timeout` is deprecated and ignored — a value shorter than
+    # every chunk gap must not abort the stream.
     api_url = _start_volume_file_server([0.15] * 4)
     volume = Volume(volume_id="v1", name="test", token="vol-token")
 
-    stream = volume.read_file("file.bin", format="stream", api_url=api_url)
+    stream = volume.read_file(
+        "file.bin", format="stream", stream_idle_timeout=0.01, api_url=api_url
+    )
     assert b"".join(stream) == CHUNK * 4
 
 
@@ -206,7 +210,9 @@ def test_async_stream_survives_transfers_longer_than_read_timeout(short_read_tim
     volume = AsyncVolume(volume_id="v1", name="test", token="vol-token")
 
     async def run():
-        stream = await volume.read_file("file.bin", format="stream", api_url=api_url)
+        stream = await volume.read_file(
+            "file.bin", format="stream", stream_idle_timeout=0.01, api_url=api_url
+        )
         return b"".join([chunk async for chunk in stream])
 
     assert asyncio.run(run()) == CHUNK * 4