Skip to content

Secure, Fast, and Extensible Sandbox runtime for AI agents.

fix(sdk-python): expose closable download stream types

redyyangc387d22d4a32
diff --git a/docs/sdks/python.md b/docs/sdks/python.md
index b532dc397..b9dbd48ba 100644
--- a/docs/sdks/python.md
+++ b/docs/sdks/python.md
@@ -413,6 +413,15 @@ For binary data, pass `bytes` to `WriteEntry.data` and use `read_bytes()`; use `
Async download iterators release their HTTP response when iteration finishes, fails, or is cancelled. If you stop consuming a download early, close the started iterator with `aclose()` (for example, using `contextlib.aclosing`) to release the connection promptly. This applies to both `sandbox.files` and isolated-session files.
+```python
+from contextlib import aclosing
+
+async with aclosing(await sandbox.files.read_bytes_stream("/tmp/large.bin")) as chunks:
+ async for chunk in chunks:
+ if enough_data(chunk):
+ break
+```
+
#### File operations with an explicit identity
Bind a filesystem client to a Linux UID and GID:
diff --git a/sdks/sandbox/python/pyproject.toml b/sdks/sandbox/python/pyproject.toml
index ef4e53e88..62dd4b486 100644
--- a/sdks/sandbox/python/pyproject.toml
+++ b/sdks/sandbox/python/pyproject.toml
@@ -114,7 +114,7 @@ typeCheckingMode = "standard"
pythonVersion = "3.10"
pythonPlatform = "All"
-include = ["src"]
+include = ["src", "tests/typecheck"]
exclude = [
"**/node_modules",
diff --git a/sdks/sandbox/python/src/opensandbox/adapters/filesystem_adapter.py b/sdks/sandbox/python/src/opensandbox/adapters/filesystem_adapter.py
index f4dba00ee..9be39f2db 100644
--- a/sdks/sandbox/python/src/opensandbox/adapters/filesystem_adapter.py
+++ b/sdks/sandbox/python/src/opensandbox/adapters/filesystem_adapter.py
@@ -24,7 +24,7 @@ import json
import logging
import os
import time
-from collections.abc import AsyncIterator
+from collections.abc import AsyncGenerator, AsyncIterator
from io import IOBase, TextIOBase
from typing import TypedDict
@@ -215,7 +215,7 @@ class FilesystemAdapter(Filesystem):
range_header: str | None = None,
offset: int | None = None,
limit: int | None = None,
- ) -> AsyncIterator[bytes]:
+ ) -> AsyncGenerator[bytes, None]:
"""Stream file content as bytes chunks via HTTP (true streaming)."""
logger.debug(f"Streaming file as bytes: {path} (chunk_size={chunk_size})")
try:
@@ -247,7 +247,7 @@ class FilesystemAdapter(Filesystem):
request_id=extract_request_id(response.headers),
)
- async def _iter() -> AsyncIterator[bytes]:
+ async def _iter() -> AsyncGenerator[bytes, None]:
try:
async for chunk in response.aiter_bytes(chunk_size=chunk_size):
yield chunk
diff --git a/sdks/sandbox/python/src/opensandbox/adapters/isolated_filesystem_adapter.py b/sdks/sandbox/python/src/opensandbox/adapters/isolated_filesystem_adapter.py
index f9fc6dab5..ff537b5dc 100644
--- a/sdks/sandbox/python/src/opensandbox/adapters/isolated_filesystem_adapter.py
+++ b/sdks/sandbox/python/src/opensandbox/adapters/isolated_filesystem_adapter.py
@@ -21,7 +21,7 @@ Uses auto-generated isolated_execution API modules with explicit session_id.
import json
import logging
-from collections.abc import AsyncIterator
+from collections.abc import AsyncGenerator
from io import IOBase, TextIOBase
from uuid import UUID
@@ -151,7 +151,7 @@ class IsolatedFilesystemAdapter(Filesystem):
range_header: str | None = None,
offset: int | None = None,
limit: int | None = None,
- ) -> AsyncIterator[bytes]:
+ ) -> AsyncGenerator[bytes, None]:
try:
url = self._get_url(self.DOWNLOAD_PATH)
params: dict[str, str] = {"path": path}
@@ -179,7 +179,7 @@ class IsolatedFilesystemAdapter(Filesystem):
request_id=extract_request_id(response.headers),
)
- async def _iter() -> AsyncIterator[bytes]:
+ async def _iter() -> AsyncGenerator[bytes, None]:
try:
async for chunk in response.aiter_bytes(chunk_size=chunk_size):
yield chunk
diff --git a/sdks/sandbox/python/src/opensandbox/services/filesystem.py b/sdks/sandbox/python/src/opensandbox/services/filesystem.py
index 61095be75..27990ac0a 100644
--- a/sdks/sandbox/python/src/opensandbox/services/filesystem.py
+++ b/sdks/sandbox/python/src/opensandbox/services/filesystem.py
@@ -18,7 +18,7 @@ Filesystem service interface.
Protocol for sandbox filesystem operations.
"""
-from collections.abc import AsyncIterator
+from collections.abc import AsyncGenerator
from io import IOBase
from typing import Protocol
@@ -109,9 +109,9 @@ class Filesystem(Protocol):
range_header: str | None = None,
offset: int | None = None,
limit: int | None = None,
- ) -> AsyncIterator[bytes]:
+ ) -> AsyncGenerator[bytes, None]:
"""
- Stream file content as bytes chunks (read_* naming).
+ Stream file content as bytes chunks; close the started generator on early exit.
"""
...
diff --git a/sdks/sandbox/python/tests/typecheck/filesystem_download.py b/sdks/sandbox/python/tests/typecheck/filesystem_download.py
new file mode 100644
index 000000000..37f749d54
--- /dev/null
+++ b/sdks/sandbox/python/tests/typecheck/filesystem_download.py
@@ -0,0 +1,32 @@
+# Copyright 2026 The OpenSandbox Authors
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+"""Type-check the public download cleanup examples without a live sandbox."""
+
+from contextlib import aclosing
+
+from opensandbox.adapters.filesystem_adapter import FilesystemAdapter
+from opensandbox.adapters.isolated_filesystem_adapter import IsolatedFilesystemAdapter
+from opensandbox.services.filesystem import Filesystem
+
+
+async def close_download(
+ files: Filesystem | FilesystemAdapter | IsolatedFilesystemAdapter,
+) -> None:
+ chunks = await files.read_bytes_stream("/tmp/large.bin")
+ await chunks.aclose()
+
+ async with aclosing(await files.read_bytes_stream("/tmp/large.bin")) as chunks:
+ async for _chunk in chunks:
+ break