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.mdindex 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 identityBind a filesystem client to a Linux UID and GID:diff --git a/sdks/sandbox/python/pyproject.toml b/sdks/sandbox/python/pyproject.tomlindex 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.pyindex 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 jsonimport loggingimport osimport time-from collections.abc import AsyncIterator+from collections.abc import AsyncGenerator, AsyncIteratorfrom io import IOBase, TextIOBasefrom 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 chunkdiff --git a/sdks/sandbox/python/src/opensandbox/adapters/isolated_filesystem_adapter.py b/sdks/sandbox/python/src/opensandbox/adapters/isolated_filesystem_adapter.pyindex 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 jsonimport logging-from collections.abc import AsyncIterator+from collections.abc import AsyncGeneratorfrom io import IOBase, TextIOBasefrom 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 chunkdiff --git a/sdks/sandbox/python/src/opensandbox/services/filesystem.py b/sdks/sandbox/python/src/opensandbox/services/filesystem.pyindex 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 AsyncGeneratorfrom io import IOBasefrom 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.pynew file mode 100644index 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