python-sandbox-sdk 1.0.1__tar.gz → 1.0.3__tar.gz

{python_sandbox_sdk-1.0.1 → python_sandbox_sdk-1.0.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: python-sandbox-sdk
-Version: 1.0.1
+Version: 1.0.3
 Summary: Python SDK for Python Sandbox API - Run Python code, shell commands, and manage packages in Docker containers
 Home-page: https://github.com/zjwan461/python-sandbox
 Author-email: Jerry <826935261@qq.com>
@@ -45,7 +45,8 @@ Python Sandbox 官方 Python SDK — 在隔离的 Docker 容器中执行 Python
 - 🔌 **上下文管理器**：自动管理 HTTP 连接与会话生命周期
 - 🛡️ **异常体系**：独立的 `ApiRequestError` / `SandboxError` 类型
 - 🧵 **线程安全**：`requests.Session` 复用，支持 `ThreadPoolExecutor` 并发
-- 🐍 **Python ≥ 3.8**：仅依赖 `requests>=2.31.0`
+- ⚡ **异步支持**：提供 `AsyncSandboxClient`，基于 `aiohttp` 实现完整异步 API
+- 🐍 **Python ≥ 3.8**：同步客户端仅依赖 `requests>=2.31.0`
 
 ## 📦 安装
 
@@ -57,6 +58,9 @@ pip install python-sandbox-sdk
 git clone https://github.com/zjwan461/python-sandbox.git
 cd python-sandbox/sdk/python-sandbox-sdk
 pip install -e .
+
+# 安装异步支持（可选）
+pip install python-sandbox-sdk[async]
 ```
 
 ## 🚀 快速开始
@@ -112,7 +116,6 @@ content = client.read_file(session_id, "/tmp/config.json")
 client.upload_file(session_id, "/tmp/image.png", b"\\x89PNG...")
 data = client.download_file(session_id, "/tmp/image.png")
 ```
-
 ## 📚 使用样例（覆盖全部 API 与典型场景）
 
 完整可运行样例见 [`usage/`](usage/) 目录：
@@ -130,6 +133,8 @@ data = client.download_file(session_id, "/tmp/image.png")
 | [`09_long_running.py`](usage/09_long_running.py) | 长任务：进度回报 + 异常安全 | `exec_python`, `exec_shell` |
 | [`10_concurrent_sessions.py`](usage/10_concurrent_sessions.py) | 并发：`ThreadPoolExecutor` + 上限约束 | 多会话并行 |
 | [`11_error_handling.py`](usage/11_error_handling.py) | 错误全景：鉴权 / 会话 / 黑名单 / 网络 | 全 API 错误路径 |
+| [`12_async_client.py`](usage/12_async_client.py) | 异步客户端：完整异步操作示例 | 全 API 异步版本 |
+| [`11_error_handling.py`](usage/11_error_handling.py) | 错误全景：鉴权 / 会话 / 黑名单 / 网络 | 全 API 错误路径 |
 
 运行样例：
 
@@ -160,6 +165,8 @@ for f in 0[1-9]_*.py 1[0-1]_*.py; do python "$f"; done
 
 `CommandResult` 字段：`exit_code`, `stdout`, `stderr`, `success`（property）, `combined_output`（property）。
 
+> 💡 **异步版本**：`AsyncSandboxClient` 提供完全相同的 API，所有方法均为 `async`，支持 `await` 调用和 `async with` 上下文管理器。
+
 ## ⚙️ 环境变量
 
 为避免硬编码，样例通过环境变量注入连接信息：
@@ -189,6 +196,8 @@ except OSError as e:
 
 ## 🧵 并发使用
 
+### 同步并发（ThreadPoolExecutor）
+
 ```python
 from concurrent.futures import ThreadPoolExecutor
 # 每个任务使用独立的 client + session（线程安全）
@@ -198,6 +207,33 @@ with ThreadPoolExecutor(max_workers=5) as pool:
         print(f.result())
 ```
 
+### 异步并发（AsyncSandboxClient）
+
+```python
+import asyncio
+from python_sandbox_sdk import AsyncSandboxClient
+
+async def run_task(task_id):
+    async with AsyncSandboxClient("http://localhost:8080", "sandbox-secret-key") as client:
+        session_id = await client.create_session()
+        try:
+            result = await client.exec_python(
+                session_id, f"print('Task {task_id} done')"
+            )
+            return result.stdout
+        finally:
+            await client.delete_session(session_id)
+
+async def main():
+    # 并发执行 5 个任务
+    tasks = [run_task(i) for i in range(5)]
+    results = await asyncio.gather(*tasks)
+    for r in results:
+        print(r)
+
+asyncio.run(main())
+```
+
 > ⚠️ 并发数受后端 `sandbox.max-containers`（默认 10）约束。
 
 ## 📦 打包发布

{python_sandbox_sdk-1.0.1 → python_sandbox_sdk-1.0.3}/README.md

@@ -14,7 +14,8 @@ Python Sandbox 官方 Python SDK — 在隔离的 Docker 容器中执行 Python
 - 🔌 **上下文管理器**：自动管理 HTTP 连接与会话生命周期
 - 🛡️ **异常体系**：独立的 `ApiRequestError` / `SandboxError` 类型
 - 🧵 **线程安全**：`requests.Session` 复用，支持 `ThreadPoolExecutor` 并发
-- 🐍 **Python ≥ 3.8**：仅依赖 `requests>=2.31.0`
+- ⚡ **异步支持**：提供 `AsyncSandboxClient`，基于 `aiohttp` 实现完整异步 API
+- 🐍 **Python ≥ 3.8**：同步客户端仅依赖 `requests>=2.31.0`
 
 ## 📦 安装
 
@@ -26,6 +27,9 @@ pip install python-sandbox-sdk
 git clone https://github.com/zjwan461/python-sandbox.git
 cd python-sandbox/sdk/python-sandbox-sdk
 pip install -e .
+
+# 安装异步支持（可选）
+pip install python-sandbox-sdk[async]
 ```
 
 ## 🚀 快速开始
@@ -81,7 +85,6 @@ content = client.read_file(session_id, "/tmp/config.json")
 client.upload_file(session_id, "/tmp/image.png", b"\\x89PNG...")
 data = client.download_file(session_id, "/tmp/image.png")
 ```
-
 ## 📚 使用样例（覆盖全部 API 与典型场景）
 
 完整可运行样例见 [`usage/`](usage/) 目录：
@@ -99,6 +102,8 @@ data = client.download_file(session_id, "/tmp/image.png")
 | [`09_long_running.py`](usage/09_long_running.py) | 长任务：进度回报 + 异常安全 | `exec_python`, `exec_shell` |
 | [`10_concurrent_sessions.py`](usage/10_concurrent_sessions.py) | 并发：`ThreadPoolExecutor` + 上限约束 | 多会话并行 |
 | [`11_error_handling.py`](usage/11_error_handling.py) | 错误全景：鉴权 / 会话 / 黑名单 / 网络 | 全 API 错误路径 |
+| [`12_async_client.py`](usage/12_async_client.py) | 异步客户端：完整异步操作示例 | 全 API 异步版本 |
+| [`11_error_handling.py`](usage/11_error_handling.py) | 错误全景：鉴权 / 会话 / 黑名单 / 网络 | 全 API 错误路径 |
 
 运行样例：
 
@@ -129,6 +134,8 @@ for f in 0[1-9]_*.py 1[0-1]_*.py; do python "$f"; done
 
 `CommandResult` 字段：`exit_code`, `stdout`, `stderr`, `success`（property）, `combined_output`（property）。
 
+> 💡 **异步版本**：`AsyncSandboxClient` 提供完全相同的 API，所有方法均为 `async`，支持 `await` 调用和 `async with` 上下文管理器。
+
 ## ⚙️ 环境变量
 
 为避免硬编码，样例通过环境变量注入连接信息：
@@ -158,6 +165,8 @@ except OSError as e:
 
 ## 🧵 并发使用
 
+### 同步并发（ThreadPoolExecutor）
+
 ```python
 from concurrent.futures import ThreadPoolExecutor
 # 每个任务使用独立的 client + session（线程安全）
@@ -167,6 +176,33 @@ with ThreadPoolExecutor(max_workers=5) as pool:
         print(f.result())
 ```
 
+### 异步并发（AsyncSandboxClient）
+
+```python
+import asyncio
+from python_sandbox_sdk import AsyncSandboxClient
+
+async def run_task(task_id):
+    async with AsyncSandboxClient("http://localhost:8080", "sandbox-secret-key") as client:
+        session_id = await client.create_session()
+        try:
+            result = await client.exec_python(
+                session_id, f"print('Task {task_id} done')"
+            )
+            return result.stdout
+        finally:
+            await client.delete_session(session_id)
+
+async def main():
+    # 并发执行 5 个任务
+    tasks = [run_task(i) for i in range(5)]
+    results = await asyncio.gather(*tasks)
+    for r in results:
+        print(r)
+
+asyncio.run(main())
+```
+
 > ⚠️ 并发数受后端 `sandbox.max-containers`（默认 10）约束。
 
 ## 📦 打包发布

{python_sandbox_sdk-1.0.1 → python_sandbox_sdk-1.0.3}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "python-sandbox-sdk"
-version = "1.0.1"
+version = "1.0.3"
 description = "Python SDK for Python Sandbox API - Run Python code, shell commands, and manage packages in Docker containers"
 readme = "README.md"
 requires-python = ">=3.8"

{python_sandbox_sdk-1.0.1 → python_sandbox_sdk-1.0.3}/python_sandbox_sdk/__init__.py

@@ -15,4 +15,4 @@ __all__ = [
     'ApiKeyMissingError',
     'ApiRequestError',
 ]
-__version__ = '1.0.1'
+__version__ = '1.0.2'

{python_sandbox_sdk-1.0.1 → python_sandbox_sdk-1.0.3}/python_sandbox_sdk/async_client.py

@@ -15,8 +15,7 @@
     Hello!
 """
 
-import os
-import tempfile
+import io
 from typing import Optional
 
 import aiohttp
@@ -86,6 +85,19 @@ class AsyncSandboxClient:
             data = await resp.json()
             return data["sessionId"]
 
+    async def create_default_session(self) -> str:
+        """
+        创建新的沙箱会话
+
+        Returns:
+            会话 ID
+        """
+        session = await self._get_session()
+        async with session.post(f"{self.base_url}/api/sandbox/session-default") as resp:
+            await self._raise_if_error(resp)
+            data = await resp.json()
+            return data["sessionId"]
+
     async def delete_session(self, session_id: str) -> None:
         """
         删除会话并清理容器
@@ -168,9 +180,7 @@ class AsyncSandboxClient:
                 data["exitCode"], data.get("stdout", ""), data.get("stderr", "")
             )
 
-    async def pip_uninstall(
-        self, session_id: str, package_name: str
-    ) -> CommandResult:
+    async def pip_uninstall(self, session_id: str, package_name: str) -> CommandResult:
         """
         卸载 Python 包
 
@@ -266,31 +276,27 @@ class AsyncSandboxClient:
             container_path: 容器内目标路径
             data: 文件字节数据
         """
-        # 写入临时文件
-        fd, tmp_path = tempfile.mkstemp(prefix="sandbox_upload_")
-        try:
-            with os.fdopen(fd, "wb") as f:
-                f.write(data)
-
-            url = f"{self.base_url}/api/sandbox/file/upload"
-            form = aiohttp.FormData()
-            form.add_field(
-                "file",
-                open(tmp_path, "rb"),
-                filename=os.path.basename(container_path),
-            )
-            form.add_field("sessionId", session_id)
-            form.add_field("path", container_path)
-
-            # 上传使用独立的 session，避免继承主 session 的 Content-Type
-            upload_timeout = aiohttp.ClientTimeout(total=120)
-            async with aiohttp.ClientSession(timeout=upload_timeout) as upload_session:
-                upload_session.headers.update({"X-Api-Key": self.api_key})
-                async with upload_session.post(url, data=form) as resp:
-                    await self._raise_if_error(resp)
-        finally:
-            if os.path.exists(tmp_path):
-                os.unlink(tmp_path)
+        import os
+
+        url = f"{self.base_url}/api/sandbox/file/upload"
+
+        # 使用 BytesIO 避免临时文件和阻塞 I/O
+        file_obj = io.BytesIO(data)
+        form = aiohttp.FormData()
+        form.add_field(
+            "file",
+            file_obj,
+            filename=os.path.basename(container_path),
+        )
+        form.add_field("sessionId", session_id)
+        form.add_field("path", container_path)
+
+        # 上传使用独立的 session，避免继承主 session 的 Content-Type
+        upload_timeout = aiohttp.ClientTimeout(total=120)
+        async with aiohttp.ClientSession(timeout=upload_timeout) as upload_session:
+            upload_session.headers.update({"X-Api-Key": self.api_key})
+            async with upload_session.post(url, data=form) as resp:
+                await self._raise_if_error(resp)
 
     async def download_file(self, session_id: str, container_path: str) -> bytes:
         """

{python_sandbox_sdk-1.0.1 → python_sandbox_sdk-1.0.3}/python_sandbox_sdk/client.py

@@ -20,16 +20,19 @@ from .dto import CommandResult
 
 class SandboxError(Exception):
     """SDK 异常基类"""
+
     pass
 
 
 class ApiKeyMissingError(SandboxError):
     """API Key 缺失错误"""
+
     pass
 
 
 class ApiRequestError(SandboxError):
     """API 请求错误"""
+
     def __init__(self, status_code: int, message: str):
         self.status_code = status_code
         super().__init__(f"HTTP {status_code}: {message}")
@@ -38,16 +41,16 @@ class ApiRequestError(SandboxError):
 class SandboxClient:
     """
     Python Sandbox 客户端
-    
+
     Attributes:
         base_url: Sandbox API 基础 URL (如 http://localhost:8080)
         api_key: API 认证密钥
     """
-    
+
     def __init__(self, base_url: str, api_key: str):
         """
         创建客户端实例
-        
+
         Args:
             base_url: Sandbox API 基础 URL
             api_key: API 认证密钥
@@ -55,180 +58,188 @@ class SandboxClient:
         self.base_url = base_url.rstrip("/")
         self.api_key = api_key
         self._session = requests.Session()
-        self._session.headers.update({
-            "X-Api-Key": api_key,
-            "Content-Type": "application/json"
-        })
-    
+        self._session.headers.update(
+            {"X-Api-Key": api_key, "Content-Type": "application/json"}
+        )
+
     # ==================== 会话管理 ====================
-    
+
     def create_session(self) -> str:
         """
         创建新的沙箱会话
-        
+
         Returns:
             会话 ID
         """
         resp = self._session.post(f"{self.base_url}/api/sandbox/session")
         self._raise_if_error(resp)
         return resp.json()["sessionId"]
-    
+
+    def create_default_session(self) -> str:
+        """
+        创建默认沙箱会话
+
+        Returns:
+            会话 ID
+        """
+        resp = self._session.post(f"{self.base_url}/api/sandbox/session-default")
+        self._raise_if_error(resp)
+        return resp.json()["sessionId"]
+
     def delete_session(self, session_id: str) -> None:
         """
         删除会话并清理容器
-        
+
         Args:
             session_id: 会话 ID
         """
         url = f"{self.base_url}/api/sandbox/session/{session_id}"
         resp = self._session.delete(url)
         self._raise_if_error(resp)
-    
+
     # ==================== 代码执行 ====================
-    
+
     def exec_python(self, session_id: str, code: str) -> CommandResult:
         """
         在沙箱中执行 Python 代码
-        
+
         Args:
             session_id: 会话 ID
             code: Python 源代码
-            
+
         Returns:
             命令执行结果
         """
         payload = {"sessionId": session_id, "code": code}
         resp = self._session.post(
-            f"{self.base_url}/api/sandbox/exec/python",
-            json=payload
+            f"{self.base_url}/api/sandbox/exec/python", json=payload
         )
         self._raise_if_error(resp)
         data = resp.json()
-        return CommandResult(data["exitCode"], data.get("stdout", ""), data.get("stderr", ""))
-    
+        return CommandResult(
+            data["exitCode"], data.get("stdout", ""), data.get("stderr", "")
+        )
+
     def exec_shell(self, session_id: str, command: str) -> CommandResult:
         """
         在沙箱中执行 Shell 命令
-        
+
         Args:
             session_id: 会话 ID
             command: Shell 命令
-            
+
         Returns:
             命令执行结果
         """
         payload = {"sessionId": session_id, "command": command}
         resp = self._session.post(
-            f"{self.base_url}/api/sandbox/exec/shell",
-            json=payload
+            f"{self.base_url}/api/sandbox/exec/shell", json=payload
         )
         self._raise_if_error(resp)
         data = resp.json()
-        return CommandResult(data["exitCode"], data.get("stdout", ""), data.get("stderr", ""))
-    
+        return CommandResult(
+            data["exitCode"], data.get("stdout", ""), data.get("stderr", "")
+        )
+
     # ==================== pip 包管理 ====================
-    
+
     def pip_install(self, session_id: str, package_name: str) -> CommandResult:
         """
         安装 Python 包
-        
+
         Args:
             session_id: 会话 ID
             package_name: 包名（支持版本约束）
-            
+
         Returns:
             命令执行结果
         """
         payload = {"sessionId": session_id, "pkg": package_name}
         resp = self._session.post(
-            f"{self.base_url}/api/sandbox/pip/install",
-            json=payload
+            f"{self.base_url}/api/sandbox/pip/install", json=payload
         )
         self._raise_if_error(resp)
         data = resp.json()
-        return CommandResult(data["exitCode"], data.get("stdout", ""), data.get("stderr", ""))
-    
+        return CommandResult(
+            data["exitCode"], data.get("stdout", ""), data.get("stderr", "")
+        )
+
     def pip_uninstall(self, session_id: str, package_name: str) -> CommandResult:
         """
         卸载 Python 包
-        
+
         Args:
             session_id: 会话 ID
             package_name: 包名
-            
+
         Returns:
             命令执行结果
         """
         payload = {"sessionId": session_id, "pkg": package_name}
         resp = self._session.post(
-            f"{self.base_url}/api/sandbox/pip/uninstall",
-            json=payload
+            f"{self.base_url}/api/sandbox/pip/uninstall", json=payload
         )
         self._raise_if_error(resp)
         data = resp.json()
-        return CommandResult(data["exitCode"], data.get("stdout", ""), data.get("stderr", ""))
-    
+        return CommandResult(
+            data["exitCode"], data.get("stdout", ""), data.get("stderr", "")
+        )
+
     def pip_list(self, session_id: str) -> str:
         """
         列出已安装的 Python 包
-        
+
         Args:
             session_id: 会话 ID
-            
+
         Returns:
             安装包列表文本
         """
         resp = self._session.get(
-            f"{self.base_url}/api/sandbox/pip/list",
-            params={"sessionId": session_id}
+            f"{self.base_url}/api/sandbox/pip/list", params={"sessionId": session_id}
         )
         self._raise_if_error(resp)
         return resp.json()["packages"]
-    
+
     # ==================== 文件操作 ====================
-    
+
     def write_file(self, session_id: str, container_path: str, content: str) -> None:
         """
         向沙箱写入文件内容
-        
+
         Args:
             session_id: 会话 ID
             container_path: 容器内目标路径
             content: 文件内容
         """
-        payload = {
-            "sessionId": session_id,
-            "path": container_path,
-            "content": content
-        }
+        payload = {"sessionId": session_id, "path": container_path, "content": content}
         resp = self._session.post(
-            f"{self.base_url}/api/sandbox/file/write",
-            json=payload
+            f"{self.base_url}/api/sandbox/file/write", json=payload
         )
         self._raise_if_error(resp)
-    
+
     def read_file(self, session_id: str, container_path: str) -> str:
         """
         读取沙箱中的文件内容
-        
+
         Args:
             session_id: 会话 ID
             container_path: 容器内文件路径
-            
+
         Returns:
             文件内容字符串
         """
         resp = self._session.get(
             f"{self.base_url}/api/sandbox/file/read",
-            params={"sessionId": session_id, "path": container_path}
+            params={"sessionId": session_id, "path": container_path},
         )
         self._raise_if_error(resp)
         return resp.json()["content"]
-    
+
     def upload_file(self, session_id: str, container_path: str, data: bytes) -> None:
         """
         上传二进制文件到沙箱
-        
+
         Args:
             session_id: 会话 ID
             container_path: 容器内目标路径
@@ -236,56 +247,58 @@ class SandboxClient:
         """
         import tempfile
         import os
-        
+
         # 写入临时文件
         fd, tmp_path = tempfile.mkstemp(prefix="sandbox_upload_")
         try:
             # os.fdopen 接管了 fd 的所有权，with 块结束时会自动关闭 fd
-            with os.fdopen(fd, 'wb') as f:
+            with os.fdopen(fd, "wb") as f:
                 f.write(data)
-            
-            with open(tmp_path, 'rb') as f:
-                files = {'file': (os.path.basename(container_path), f)}
-                data_params = {'sessionId': session_id, 'path': container_path}
-                
+
+            with open(tmp_path, "rb") as f:
+                files = {"file": (os.path.basename(container_path), f)}
+                data_params = {"sessionId": session_id, "path": container_path}
+
                 # 发送 multipart 请求（requests 会自动设置正确的 Content-Type）
                 url = f"{self.base_url}/api/sandbox/file/upload"
                 # 使用新的 session 避免继承主 session 的 Content-Type: application/json
                 with requests.Session() as upload_session:
                     upload_session.headers.update({"X-Api-Key": self.api_key})
-                    resp = upload_session.post(url, files=files, data=data_params, timeout=120)
+                    resp = upload_session.post(
+                        url, files=files, data=data_params, timeout=120
+                    )
                     self._raise_if_error(resp)
         finally:
             if os.path.exists(tmp_path):
                 os.unlink(tmp_path)
-    
+
     def download_file(self, session_id: str, container_path: str) -> bytes:
         """
         下载沙箱中的文件
-        
+
         Args:
             session_id: 会话 ID
             container_path: 容器内文件路径
-            
+
         Returns:
             文件字节数据
         """
         url = f"{self.base_url}/api/sandbox/file/download"
         params = {"sessionId": session_id, "path": container_path}
-        
+
         # 使用新的 session 避免继承主 session 的 Content-Type: application/json
         with requests.Session() as s:
             s.headers.update({"X-Api-Key": self.api_key})
             resp = s.get(url, params=params, timeout=60)
             self._raise_if_error(resp)
             return resp.content
-    
+
     # ==================== 健康检查 ====================
-    
+
     def is_health(self) -> bool:
         """
         检查沙箱服务是否可用
-        
+
         Returns:
             True 如果服务正常运行
         """
@@ -294,9 +307,9 @@ class SandboxClient:
             return resp.status_code == 200
         except Exception:
             return False
-    
+
     # ==================== 内部方法 ====================
-    
+
     @staticmethod
     def _raise_if_error(resp: requests.Response) -> None:
         """如果响应状态码表示错误则抛出异常"""
@@ -307,13 +320,13 @@ class SandboxClient:
             except Exception:
                 message = resp.text
             raise ApiRequestError(resp.status_code, message)
-    
+
     def close(self) -> None:
         """关闭 HTTP 会话"""
         self._session.close()
-    
+
     def __enter__(self):
         return self
-    
+
     def __exit__(self, exc_type, exc_val, exc_tb):
         self.close()

{python_sandbox_sdk-1.0.1 → python_sandbox_sdk-1.0.3}/python_sandbox_sdk.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: python-sandbox-sdk
-Version: 1.0.1
+Version: 1.0.3
 Summary: Python SDK for Python Sandbox API - Run Python code, shell commands, and manage packages in Docker containers
 Home-page: https://github.com/zjwan461/python-sandbox
 Author-email: Jerry <826935261@qq.com>
@@ -45,7 +45,8 @@ Python Sandbox 官方 Python SDK — 在隔离的 Docker 容器中执行 Python
 - 🔌 **上下文管理器**：自动管理 HTTP 连接与会话生命周期
 - 🛡️ **异常体系**：独立的 `ApiRequestError` / `SandboxError` 类型
 - 🧵 **线程安全**：`requests.Session` 复用，支持 `ThreadPoolExecutor` 并发
-- 🐍 **Python ≥ 3.8**：仅依赖 `requests>=2.31.0`
+- ⚡ **异步支持**：提供 `AsyncSandboxClient`，基于 `aiohttp` 实现完整异步 API
+- 🐍 **Python ≥ 3.8**：同步客户端仅依赖 `requests>=2.31.0`
 
 ## 📦 安装
 
@@ -57,6 +58,9 @@ pip install python-sandbox-sdk
 git clone https://github.com/zjwan461/python-sandbox.git
 cd python-sandbox/sdk/python-sandbox-sdk
 pip install -e .
+
+# 安装异步支持（可选）
+pip install python-sandbox-sdk[async]
 ```
 
 ## 🚀 快速开始
@@ -112,7 +116,6 @@ content = client.read_file(session_id, "/tmp/config.json")
 client.upload_file(session_id, "/tmp/image.png", b"\\x89PNG...")
 data = client.download_file(session_id, "/tmp/image.png")
 ```
-
 ## 📚 使用样例（覆盖全部 API 与典型场景）
 
 完整可运行样例见 [`usage/`](usage/) 目录：
@@ -130,6 +133,8 @@ data = client.download_file(session_id, "/tmp/image.png")
 | [`09_long_running.py`](usage/09_long_running.py) | 长任务：进度回报 + 异常安全 | `exec_python`, `exec_shell` |
 | [`10_concurrent_sessions.py`](usage/10_concurrent_sessions.py) | 并发：`ThreadPoolExecutor` + 上限约束 | 多会话并行 |
 | [`11_error_handling.py`](usage/11_error_handling.py) | 错误全景：鉴权 / 会话 / 黑名单 / 网络 | 全 API 错误路径 |
+| [`12_async_client.py`](usage/12_async_client.py) | 异步客户端：完整异步操作示例 | 全 API 异步版本 |
+| [`11_error_handling.py`](usage/11_error_handling.py) | 错误全景：鉴权 / 会话 / 黑名单 / 网络 | 全 API 错误路径 |
 
 运行样例：
 
@@ -160,6 +165,8 @@ for f in 0[1-9]_*.py 1[0-1]_*.py; do python "$f"; done
 
 `CommandResult` 字段：`exit_code`, `stdout`, `stderr`, `success`（property）, `combined_output`（property）。
 
+> 💡 **异步版本**：`AsyncSandboxClient` 提供完全相同的 API，所有方法均为 `async`，支持 `await` 调用和 `async with` 上下文管理器。
+
 ## ⚙️ 环境变量
 
 为避免硬编码，样例通过环境变量注入连接信息：
@@ -189,6 +196,8 @@ except OSError as e:
 
 ## 🧵 并发使用
 
+### 同步并发（ThreadPoolExecutor）
+
 ```python
 from concurrent.futures import ThreadPoolExecutor
 # 每个任务使用独立的 client + session（线程安全）
@@ -198,6 +207,33 @@ with ThreadPoolExecutor(max_workers=5) as pool:
         print(f.result())
 ```
 
+### 异步并发（AsyncSandboxClient）
+
+```python
+import asyncio
+from python_sandbox_sdk import AsyncSandboxClient
+
+async def run_task(task_id):
+    async with AsyncSandboxClient("http://localhost:8080", "sandbox-secret-key") as client:
+        session_id = await client.create_session()
+        try:
+            result = await client.exec_python(
+                session_id, f"print('Task {task_id} done')"
+            )
+            return result.stdout
+        finally:
+            await client.delete_session(session_id)
+
+async def main():
+    # 并发执行 5 个任务
+    tasks = [run_task(i) for i in range(5)]
+    results = await asyncio.gather(*tasks)
+    for r in results:
+        print(r)
+
+asyncio.run(main())
+```
+
 > ⚠️ 并发数受后端 `sandbox.max-containers`（默认 10）约束。
 
 ## 📦 打包发布

{python_sandbox_sdk-1.0.1 → python_sandbox_sdk-1.0.3}/setup.py

@@ -26,7 +26,7 @@ def _read_readme() -> str:
 
 setup(
     name="python-sandbox-sdk",
-    version="1.0.0",
+    version="1.0.3",
     description="Python SDK for Python Sandbox API - Run Python code, shell commands, and manage packages in Docker containers",
     long_description=_read_readme(),
     long_description_content_type="text/markdown",