python-sandbox-sdk 1.0.0__tar.gz → 1.0.2__tar.gz

{python_sandbox_sdk-1.0.0 → python_sandbox_sdk-1.0.2}/PKG-INFO

@@ -1,9 +1,9 @@
 Metadata-Version: 2.4
 Name: python-sandbox-sdk
-Version: 1.0.0
+Version: 1.0.2
 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: ITSU Team <826935261@qq.com>
+Author-email: Jerry <826935261@qq.com>
 License-Expression: MIT
 Project-URL: Homepage, https://github.com/zjwan461/python-sandbox
 Project-URL: Repository, https://github.com/zjwan461/python-sandbox
@@ -24,6 +24,8 @@ Classifier: Topic :: Software Development :: Libraries :: Python Modules
 Requires-Python: >=3.8
 Description-Content-Type: text/markdown
 Requires-Dist: requests>=2.31.0
+Provides-Extra: async
+Requires-Dist: aiohttp>=3.9.0; extra == "async"
 Dynamic: home-page
 Dynamic: requires-python
 
@@ -43,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`
 
 ## 📦 安装
 
@@ -55,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]
 ```
 
 ## 🚀 快速开始
@@ -110,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/) 目录：
@@ -128,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 错误路径 |
 
 运行样例：
 
@@ -158,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` 上下文管理器。
+
 ## ⚙️ 环境变量
 
 为避免硬编码，样例通过环境变量注入连接信息：
@@ -187,6 +196,8 @@ except OSError as e:
 
 ## 🧵 并发使用
 
+### 同步并发（ThreadPoolExecutor）
+
 ```python
 from concurrent.futures import ThreadPoolExecutor
 # 每个任务使用独立的 client + session（线程安全）
@@ -196,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.0 → python_sandbox_sdk-1.0.2}/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.0 → python_sandbox_sdk-1.0.2}/pyproject.toml

@@ -4,13 +4,13 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "python-sandbox-sdk"
-version = "1.0.0"
+version = "1.0.2"
 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"
 license = "MIT"
 authors = [
-    {name = "ITSU Team", email = "826935261@qq.com"}
+    {name = "Jerry", email = "826935261@qq.com"}
 ]
 keywords = ["sandbox", "docker", "python", "security", "shell"]
 classifiers = [
@@ -29,6 +29,11 @@ dependencies = [
     "requests>=2.31.0",
 ]
 
+[project.optional-dependencies]
+async = [
+    "aiohttp>=3.9.0",
+]
+
 [project.urls]
 Homepage = "https://github.com/zjwan461/python-sandbox"
 Repository = "https://github.com/zjwan461/python-sandbox"

{python_sandbox_sdk-1.0.0 → python_sandbox_sdk-1.0.2}/python_sandbox_sdk/__init__.py

@@ -1,12 +1,18 @@
 from .client import SandboxClient, SandboxError, ApiKeyMissingError, ApiRequestError
 from .dto import CommandResult, SessionResponse
 
+try:
+    from .async_client import AsyncSandboxClient
+except ImportError:
+    AsyncSandboxClient = None
+
 __all__ = [
     'SandboxClient',
+    'AsyncSandboxClient',
     'CommandResult',
     'SessionResponse',
     'SandboxError',
     'ApiKeyMissingError',
     'ApiRequestError',
 ]
-__version__ = '1.0.0'
+__version__ = '1.0.2'

python_sandbox_sdk-1.0.2/python_sandbox_sdk/async_client.py

@@ -0,0 +1,351 @@
+"""
+异步 Python Sandbox 客户端
+
+使用 aiohttp 提供与 SandboxClient 相同的 API，但所有方法均为 async。
+
+使用示例：
+    >>> import asyncio
+    >>> from python_sandbox_sdk import AsyncSandboxClient
+    >>> async def main():
+    ...     async with AsyncSandboxClient("http://localhost:8080", "your-api-key") as client:
+    ...         session_id = await client.create_session()
+    ...         result = await client.exec_python(session_id, "print('Hello!')")
+    ...         print(result.stdout)
+    >>> asyncio.run(main())
+    Hello!
+"""
+
+import io
+from typing import Optional
+
+import aiohttp
+
+from .dto import CommandResult
+from .client import SandboxError, ApiRequestError
+
+
+class AsyncSandboxClient:
+    """
+    异步 Python Sandbox 客户端
+
+    所有网络请求方法均为 async，支持 async with 上下文管理器。
+
+    Attributes:
+        base_url: Sandbox API 基础 URL (如 http://localhost:8080)
+        api_key: API 认证密钥
+    """
+
+    def __init__(
+        self,
+        base_url: str,
+        api_key: str,
+        session: Optional[aiohttp.ClientSession] = None,
+        timeout: aiohttp.ClientTimeout = None,
+    ):
+        """
+        创建异步客户端实例
+
+        Args:
+            base_url: Sandbox API 基础 URL
+            api_key: API 认证密钥
+            session: 可选的自定义 aiohttp.ClientSession 实例
+            timeout: 默认请求超时（upload/download 有各自的超时）
+        """
+        self.base_url = base_url.rstrip("/")
+        self.api_key = api_key
+        self._timeout = timeout or aiohttp.ClientTimeout(total=60)
+        self._external_session = session is not None
+        self._session: Optional[aiohttp.ClientSession] = session
+
+    async def _get_session(self) -> aiohttp.ClientSession:
+        """获取或创建 aiohttp session（懒初始化）"""
+        if self._session is None or self._session.closed:
+            self._session = aiohttp.ClientSession(
+                headers={
+                    "X-Api-Key": self.api_key,
+                    "Content-Type": "application/json",
+                },
+                timeout=self._timeout,
+            )
+            self._external_session = False
+        return self._session
+
+    # ==================== 会话管理 ====================
+
+    async def create_session(self) -> str:
+        """
+        创建新的沙箱会话
+
+        Returns:
+            会话 ID
+        """
+        session = await self._get_session()
+        async with session.post(f"{self.base_url}/api/sandbox/session") as resp:
+            await self._raise_if_error(resp)
+            data = await resp.json()
+            return data["sessionId"]
+
+    async def delete_session(self, session_id: str) -> None:
+        """
+        删除会话并清理容器
+
+        Args:
+            session_id: 会话 ID
+        """
+        session = await self._get_session()
+        url = f"{self.base_url}/api/sandbox/session/{session_id}"
+        async with session.delete(url) as resp:
+            await self._raise_if_error(resp)
+
+    # ==================== 代码执行 ====================
+
+    async def exec_python(self, session_id: str, code: str) -> CommandResult:
+        """
+        在沙箱中执行 Python 代码
+
+        Args:
+            session_id: 会话 ID
+            code: Python 源代码
+
+        Returns:
+            命令执行结果
+        """
+        payload = {"sessionId": session_id, "code": code}
+        session = await self._get_session()
+        async with session.post(
+            f"{self.base_url}/api/sandbox/exec/python", json=payload
+        ) as resp:
+            await self._raise_if_error(resp)
+            data = await resp.json()
+            return CommandResult(
+                data["exitCode"], data.get("stdout", ""), data.get("stderr", "")
+            )
+
+    async def exec_shell(self, session_id: str, command: str) -> CommandResult:
+        """
+        在沙箱中执行 Shell 命令
+
+        Args:
+            session_id: 会话 ID
+            command: Shell 命令
+
+        Returns:
+            命令执行结果
+        """
+        payload = {"sessionId": session_id, "command": command}
+        session = await self._get_session()
+        async with session.post(
+            f"{self.base_url}/api/sandbox/exec/shell", json=payload
+        ) as resp:
+            await self._raise_if_error(resp)
+            data = await resp.json()
+            return CommandResult(
+                data["exitCode"], data.get("stdout", ""), data.get("stderr", "")
+            )
+
+    # ==================== pip 包管理 ====================
+
+    async 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}
+        session = await self._get_session()
+        async with session.post(
+            f"{self.base_url}/api/sandbox/pip/install", json=payload
+        ) as resp:
+            await self._raise_if_error(resp)
+            data = await resp.json()
+            return CommandResult(
+                data["exitCode"], data.get("stdout", ""), data.get("stderr", "")
+            )
+
+    async 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}
+        session = await self._get_session()
+        async with session.post(
+            f"{self.base_url}/api/sandbox/pip/uninstall", json=payload
+        ) as resp:
+            await self._raise_if_error(resp)
+            data = await resp.json()
+            return CommandResult(
+                data["exitCode"], data.get("stdout", ""), data.get("stderr", "")
+            )
+
+    async def pip_list(self, session_id: str) -> str:
+        """
+        列出已安装的 Python 包
+
+        Args:
+            session_id: 会话 ID
+
+        Returns:
+            安装包列表文本
+        """
+        session = await self._get_session()
+        async with session.get(
+            f"{self.base_url}/api/sandbox/pip/list",
+            params={"sessionId": session_id},
+        ) as resp:
+            await self._raise_if_error(resp)
+            data = await resp.json()
+            return data["packages"]
+
+    # ==================== 文件操作 ====================
+
+    async 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,
+        }
+        session = await self._get_session()
+        async with session.post(
+            f"{self.base_url}/api/sandbox/file/write", json=payload
+        ) as resp:
+            await self._raise_if_error(resp)
+
+    async def read_file(self, session_id: str, container_path: str) -> str:
+        """
+        读取沙箱中的文件内容
+
+        Args:
+            session_id: 会话 ID
+            container_path: 容器内文件路径
+
+        Returns:
+            文件内容字符串
+        """
+        session = await self._get_session()
+        async with session.get(
+            f"{self.base_url}/api/sandbox/file/read",
+            params={"sessionId": session_id, "path": container_path},
+        ) as resp:
+            await self._raise_if_error(resp)
+            data = await resp.json()
+            return data["content"]
+
+    async def upload_file(
+        self, session_id: str, container_path: str, data: bytes
+    ) -> None:
+        """
+        上传二进制文件到沙箱
+
+        Args:
+            session_id: 会话 ID
+            container_path: 容器内目标路径
+            data: 文件字节数据
+        """
+        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:
+        """
+        下载沙箱中的文件
+
+        Args:
+            session_id: 会话 ID
+            container_path: 容器内文件路径
+
+        Returns:
+            文件字节数据
+        """
+        url = f"{self.base_url}/api/sandbox/file/download"
+        params = {"sessionId": session_id, "path": container_path}
+
+        download_timeout = aiohttp.ClientTimeout(total=60)
+        async with aiohttp.ClientSession(timeout=download_timeout) as s:
+            s.headers.update({"X-Api-Key": self.api_key})
+            async with s.get(url, params=params) as resp:
+                await self._raise_if_error(resp)
+                return await resp.read()
+
+    # ==================== 健康检查 ====================
+
+    async def is_health(self) -> bool:
+        """
+        检查沙箱服务是否可用
+
+        Returns:
+            True 如果服务正常运行
+        """
+        try:
+            health_timeout = aiohttp.ClientTimeout(total=5)
+            async with aiohttp.ClientSession(timeout=health_timeout) as s:
+                async with s.get(f"{self.base_url}/health") as resp:
+                    return resp.status == 200
+        except Exception:
+            return False
+
+    # ==================== 内部方法 ====================
+
+    @staticmethod
+    async def _raise_if_error(resp: aiohttp.ClientResponse) -> None:
+        """如果响应状态码表示错误则抛出异常"""
+        if resp.status >= 400:
+            try:
+                error_data = await resp.json()
+                message = error_data.get("message", await resp.text())
+            except Exception:
+                message = await resp.text()
+            raise ApiRequestError(resp.status, message)
+
+    async def close(self) -> None:
+        """关闭 HTTP 会话（仅关闭内部创建的 session）"""
+        if self._session and not self._external_session:
+            await self._session.close()
+            self._session = None
+
+    async def __aenter__(self):
+        return self
+
+    async def __aexit__(self, exc_type, exc_val, exc_tb):
+        await self.close()

{python_sandbox_sdk-1.0.0 → python_sandbox_sdk-1.0.2}/python_sandbox_sdk.egg-info/PKG-INFO

@@ -1,9 +1,9 @@
 Metadata-Version: 2.4
 Name: python-sandbox-sdk
-Version: 1.0.0
+Version: 1.0.2
 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: ITSU Team <826935261@qq.com>
+Author-email: Jerry <826935261@qq.com>
 License-Expression: MIT
 Project-URL: Homepage, https://github.com/zjwan461/python-sandbox
 Project-URL: Repository, https://github.com/zjwan461/python-sandbox
@@ -24,6 +24,8 @@ Classifier: Topic :: Software Development :: Libraries :: Python Modules
 Requires-Python: >=3.8
 Description-Content-Type: text/markdown
 Requires-Dist: requests>=2.31.0
+Provides-Extra: async
+Requires-Dist: aiohttp>=3.9.0; extra == "async"
 Dynamic: home-page
 Dynamic: requires-python
 
@@ -43,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`
 
 ## 📦 安装
 
@@ -55,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]
 ```
 
 ## 🚀 快速开始
@@ -110,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/) 目录：
@@ -128,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 错误路径 |
 
 运行样例：
 
@@ -158,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` 上下文管理器。
+
 ## ⚙️ 环境变量
 
 为避免硬编码，样例通过环境变量注入连接信息：
@@ -187,6 +196,8 @@ except OSError as e:
 
 ## 🧵 并发使用
 
+### 同步并发（ThreadPoolExecutor）
+
 ```python
 from concurrent.futures import ThreadPoolExecutor
 # 每个任务使用独立的 client + session（线程安全）
@@ -196,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.0 → python_sandbox_sdk-1.0.2}/python_sandbox_sdk.egg-info/SOURCES.txt

@@ -2,9 +2,11 @@ README.md
 pyproject.toml
 setup.py
 ./python_sandbox_sdk/__init__.py
+./python_sandbox_sdk/async_client.py
 ./python_sandbox_sdk/client.py
 ./python_sandbox_sdk/dto.py
 python_sandbox_sdk/__init__.py
+python_sandbox_sdk/async_client.py
 python_sandbox_sdk/client.py
 python_sandbox_sdk/dto.py
 python_sandbox_sdk.egg-info/PKG-INFO

python_sandbox_sdk-1.0.2/python_sandbox_sdk.egg-info/requires.txt

@@ -0,0 +1,4 @@
+requests>=2.31.0
+
+[async]
+aiohttp>=3.9.0

python_sandbox_sdk-1.0.0/python_sandbox_sdk.egg-info/requires.txt

@@ -1 +0,0 @@
-requests>=2.31.0