fix(adapters): add a default timeout to Image.from_url / Audio.from_url (#10149)

requests.get without a timeout waits forever, so a slow or unresponsive
host hangs the caller indefinitely. Adds timeout: float | None = 30.0 to
both explicit download factories and the internal image helper (which
also serves the deprecated Image(url, download=True) shim). Pass
timeout=None for the old behavior.

Remaining half of #9993; the implicit-fetch half was resolved by #10111.

Author: immu4989

dspy/adapters/types/audio.py

@@ -80,7 +80,7 @@ def validate_input(cls, values: Any) -> Any:
         return encode_audio(values)
 
     @classmethod
-    def from_url(cls, url: str, verify: bool = True) -> "Audio":
+    def from_url(cls, url: str, verify: bool = True, timeout: float | None = 30.0) -> "Audio":
         """
         Download an audio file from URL and encode it as base64.
 
@@ -93,11 +93,14 @@ def from_url(cls, url: str, verify: bool = True) -> "Audio":
         Args:
             url: The URL of the audio to download.
             verify: Whether to verify SSL certificates. Set to False for self-signed certs.
+            timeout: Seconds to wait for the server before raising
+                ``requests.exceptions.Timeout``. ``None`` disables the timeout and can
+                hang indefinitely on an unresponsive host.
         """
         parsed_url = urlparse(url)
         if parsed_url.scheme not in ("http", "https") or not parsed_url.netloc:
             raise ValueError(f"Audio.from_url requires an HTTP(S) URL, received: {url}")
-        response = requests.get(url, verify=verify)
+        response = requests.get(url, verify=verify, timeout=timeout)
         response.raise_for_status()
         mime_type = response.headers.get("Content-Type", "audio/wav")
         if not mime_type.startswith("audio/"):

dspy/adapters/types/image.py

@@ -113,7 +113,7 @@ def format(self) -> list[dict[str, Any]] | str:
         return [{"type": "image_url", "image_url": {"url": image_url}}]
 
     @classmethod
-    def from_url(cls, url: str, verify: bool = True) -> "Image":
+    def from_url(cls, url: str, verify: bool = True, timeout: float | None = 30.0) -> "Image":
         """Download an HTTP(S) resource and encode it as a data URI.
 
         Security: this performs an explicit, caller-initiated fetch and applies no
@@ -124,7 +124,7 @@ def from_url(cls, url: str, verify: bool = True) -> "Image":
         """
         if not _is_http_url(url):
             raise ValueError(f"Image.from_url requires an HTTP(S) URL, received: {url}")
-        return cls(_encode_image_from_url(url, verify=verify))
+        return cls(_encode_image_from_url(url, verify=verify, timeout=timeout))
 
     @classmethod
     def from_path(cls, file_path: str) -> "Image":
@@ -236,14 +236,16 @@ def _encode_image_from_file(file_path: str) -> str:
     return f"data:{mime_type};base64,{encoded_data}"
 
 
-def _encode_image_from_url(image_url: str, verify: bool = True) -> str:
+def _encode_image_from_url(image_url: str, verify: bool = True, timeout: float | None = 30.0) -> str:
     """Encode a file from a URL to a base64 data URI.
 
     Args:
         image_url: The URL of the image to download.
         verify: Whether to verify SSL certificates. Set to False for self-signed certs.
+        timeout: Seconds to wait for the server before raising ``requests.exceptions.Timeout``.
+            ``None`` disables the timeout and can hang indefinitely on an unresponsive host.
     """
-    response = requests.get(image_url, verify=verify)
+    response = requests.get(image_url, verify=verify, timeout=timeout)
     response.raise_for_status()
     content_type = response.headers.get("Content-Type", "")
 

tests/adapters/test_resource_loading.py

@@ -140,6 +140,37 @@ def raise_for_status(self):
     assert base64.b64decode(encoded) == b"remote bytes"
 
 
+@pytest.mark.parametrize(
+    ("factory", "module", "mime_type"),
+    [(dspy.Image.from_url, "image", "image/png"), (dspy.Audio.from_url, "audio", "audio/wav")],
+)
+def test_from_url_applies_a_timeout_by_default(monkeypatch, factory, module, mime_type):
+    seen = {}
+
+    class Response:
+        def __init__(self):
+            self.content = b"remote bytes"
+            self.headers = {"Content-Type": mime_type}
+
+        def raise_for_status(self):
+            return None
+
+    def record_request(url, **kwargs):
+        seen.update(kwargs)
+        return Response()
+
+    monkeypatch.setattr(f"dspy.adapters.types.{module}.requests.get", record_request)
+
+    factory("https://example.com/resource")
+    assert seen.get("timeout") == 30.0
+
+    factory("https://example.com/resource", timeout=5.0)
+    assert seen.get("timeout") == 5.0
+
+    factory("https://example.com/resource", timeout=None)
+    assert seen.get("timeout") is None
+
+
 def test_in_memory_resource_construction():
     image = dspy.Image(
         base64.b64decode("iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAQAAAC1HAwCAAAAC0lEQVR42mNk+A8AAQUBAScY42YAAAAASUVORK5CYII=")