python-sandbox-sdk 1.0.0__tar.gz

python_sandbox_sdk-1.0.0/PKG-INFO

@@ -0,0 +1,228 @@
+Metadata-Version: 2.4
+Name: python-sandbox-sdk
+Version: 1.0.0
+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>
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/zjwan461/python-sandbox
+Project-URL: Repository, https://github.com/zjwan461/python-sandbox
+Project-URL: Documentation, https://github.com/zjwan461/python-sandbox#readme
+Project-URL: Issues, https://github.com/zjwan461/python-sandbox/issues
+Project-URL: Changelog, https://github.com/zjwan461/python-sandbox/blob/main/CHANGELOG.md
+Project-URL: Usage Examples, https://github.com/zjwan461/python-sandbox/tree/main/sdk/python-sandbox-sdk/usage
+Keywords: sandbox,docker,python,security,shell
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.8
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+Requires-Dist: requests>=2.31.0
+Dynamic: home-page
+Dynamic: requires-python
+
+# python-sandbox-sdk
+
+[![Python](https://img.shields.io/badge/python-≥3.8-blue)](https://www.python.org)
+[![License: MIT](https://img.shields.io/badge/license-MIT-green)](LICENSE)
+[![Docker](https://img.shields.io/badge/docker-required-blue)](https://www.docker.com)
+
+Python Sandbox 官方 Python SDK — 在隔离的 Docker 容器中执行 Python 代码、Shell 命令、管理 pip 包、读写文件。
+
+对应后端：[`python-sandbox`](https://github.com/zjwan461/python-sandbox)（Spring Boot 3 + Java 17）。
+
+## ✨ 特性
+
+- 🚀 **简洁 API**：10 个方法覆盖会话、代码执行、Shell、pip、文件读写、文件上传下载、健康检查
+- 🔌 **上下文管理器**：自动管理 HTTP 连接与会话生命周期
+- 🛡️ **异常体系**：独立的 `ApiRequestError` / `SandboxError` 类型
+- 🧵 **线程安全**：`requests.Session` 复用，支持 `ThreadPoolExecutor` 并发
+- 🐍 **Python ≥ 3.8**：仅依赖 `requests>=2.31.0`
+
+## 📦 安装
+
+```bash
+# 方式 A：从 PyPI 安装（推荐）
+pip install python-sandbox-sdk
+
+# 方式 B：从源码安装
+git clone https://github.com/zjwan461/python-sandbox.git
+cd python-sandbox/sdk/python-sandbox-sdk
+pip install -e .
+```
+
+## 🚀 快速开始
+
+### 0. 启动后端服务
+
+参考 [`python-sandbox/README.md`](https://github.com/zjwan461/python-sandbox/blob/main/python-sandbox/README.md) 启动：
+
+```bash
+cd python-sandbox
+cp .env.example .env
+docker-compose up -d --build
+curl http://localhost:8080/health
+```
+
+### 1. 最简示例
+
+```python
+from python_sandbox_sdk import SandboxClient
+
+with SandboxClient("http://localhost:8080", "sandbox-secret-key") as client:
+    if not client.is_health():
+        raise SystemExit("Sandbox not ready")
+
+    session_id = client.create_session()
+    try:
+        result = client.exec_python(session_id, "print('Hello from sandbox!')")
+        print(result.stdout)              # Hello from sandbox!
+        print(result.exit_code)           # 0
+        print(result.success)             # True
+    finally:
+        client.delete_session(session_id)
+```
+
+### 2. 安装并使用第三方包
+
+```python
+client.pip_install(session_id, "requests==2.31.0")
+result = client.exec_python(session_id, """
+import requests
+print(requests.get('https://httpbin.org/get', timeout=5).status_code)
+""")
+```
+
+### 3. 文件读写
+
+```python
+# 文本
+client.write_file(session_id, "/tmp/config.json", '{"key": "value"}')
+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/) 目录：
+
+| 编号 | 场景 | 覆盖 API |
+|---|---|---|
+| [`01_hello_world.py`](usage/01_hello_world.py) | 入门：连通性 + Hello World | `is_health`, `create_session`, `exec_python`, `delete_session` |
+| [`02_session_management.py`](usage/02_session_management.py) | 会话管理：独立 / 复用 / 异常清理 | `create_session`, `delete_session` |
+| [`03_python_execution.py`](usage/03_python_execution.py) | Python 执行：语法 / 异常 / 状态 / 长任务 | `exec_python` |
+| [`04_shell_execution.py`](usage/04_shell_execution.py) | Shell 执行：基础 + 黑名单 + 安全路径 | `exec_shell` |
+| [`05_pip_packages.py`](usage/05_pip_packages.py) | pip 管理：安装 / 卸载 / 列表 / 版本约束 | `pip_install`, `pip_uninstall`, `pip_list` |
+| [`06_text_file_ops.py`](usage/06_text_file_ops.py) | 文本文件：JSON / CSV / 中文 / 日志 | `write_file`, `read_file` |
+| [`07_binary_file_ops.py`](usage/07_binary_file_ops.py) | 二进制：图片缩略图 + numpy 序列化 | `upload_file`, `download_file` |
+| [`08_data_analysis.py`](usage/08_data_analysis.py) | 数据分析实战：requests + pandas + matplotlib | 综合 |
+| [`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 错误路径 |
+
+运行样例：
+
+```bash
+cd usage/
+export SANDBOX_API_KEY="sandbox-secret-key"
+
+python 01_hello_world.py
+for f in 0[1-9]_*.py 1[0-1]_*.py; do python "$f"; done
+```
+
+## 🔧 API 速查
+
+| 方法 | 返回 | 说明 |
+|---|---|---|
+| `is_health()` | `bool` | 健康检查（无需 API Key） |
+| `create_session()` | `str` | 创建沙箱会话 |
+| `delete_session(session_id)` | `None` | 删除会话并清理容器 |
+| `exec_python(session_id, code)` | `CommandResult` | 执行 Python 代码 |
+| `exec_shell(session_id, command)` | `CommandResult` | 执行 Shell 命令 |
+| `pip_install(session_id, pkg)` | `CommandResult` | 安装 pip 包（支持版本约束） |
+| `pip_uninstall(session_id, pkg)` | `CommandResult` | 卸载 pip 包 |
+| `pip_list(session_id)` | `str` | 列出已安装包 |
+| `write_file(session_id, path, content)` | `None` | 写文本文件 |
+| `read_file(session_id, path)` | `str` | 读文本文件 |
+| `upload_file(session_id, path, data)` | `None` | 上传二进制文件 |
+| `download_file(session_id, path)` | `bytes` | 下载文件 |
+
+`CommandResult` 字段：`exit_code`, `stdout`, `stderr`, `success`（property）, `combined_output`（property）。
+
+## ⚙️ 环境变量
+
+为避免硬编码，样例通过环境变量注入连接信息：
+
+| 变量 | 默认值 | 说明 |
+|---|---|---|
+| `SANDBOX_BASE_URL` | `http://localhost:8080` | Sandbox 服务地址 |
+| `SANDBOX_API_KEY` | `sandbox-secret-key` | API 鉴权密钥（与后端 `SANDBOX_API_KEY` 保持一致） |
+
+## 🛡️ 异常处理
+
+```python
+from python_sandbox_sdk import SandboxClient, ApiRequestError, SandboxError
+
+try:
+    client.exec_python(session_id, "print(1)")
+except ApiRequestError as e:
+    # 后端返回的 4xx / 5xx（鉴权失败、会话不存在、黑名单、容器上限等）
+    print(f"API Error: HTTP {e.status_code} - {e}")
+except SandboxError as e:
+    # SDK 抛出的通用错误
+    print(f"SDK Error: {e}")
+except OSError as e:
+    # 网络错误（连接失败、超时等）
+    print(f"Network Error: {e}")
+```
+
+## 🧵 并发使用
+
+```python
+from concurrent.futures import ThreadPoolExecutor
+# 每个任务使用独立的 client + session（线程安全）
+with ThreadPoolExecutor(max_workers=5) as pool:
+    futures = [pool.submit(run_one_task, i) for i in range(5)]
+    for f in futures:
+        print(f.result())
+```
+
+> ⚠️ 并发数受后端 `sandbox.max-containers`（默认 10）约束。
+
+## 📦 打包发布
+
+```bash
+# 安装构建工具
+pip install build twine
+
+# 构建
+cd sdk/python-sandbox-sdk
+python -m build
+
+# 上传到 TestPyPI
+twine upload --repository testpypi dist/*
+
+# 上传到 PyPI
+twine upload dist/*
+```
+
+发布前请修改 `pyproject.toml` 中的 `version` 与 `urls` 字段。
+
+## 🔗 相关项目
+
+- 后端服务：[`python-sandbox/`](https://github.com/zjwan461/python-sandbox)
+- Java SDK：[`sdk/java-sandbox-sdk/`](https://github.com/zjwan461/python-sandbox/tree/main/sdk/java-sandbox-sdk)
+- SDK 总览：[`sdk/README.md`](https://github.com/zjwan461/python-sandbox/tree/main/sdk)
+
+## 📄 许可证
+
+MIT License

python_sandbox_sdk-1.0.0/README.md

@@ -0,0 +1,199 @@
+# python-sandbox-sdk
+
+[![Python](https://img.shields.io/badge/python-≥3.8-blue)](https://www.python.org)
+[![License: MIT](https://img.shields.io/badge/license-MIT-green)](LICENSE)
+[![Docker](https://img.shields.io/badge/docker-required-blue)](https://www.docker.com)
+
+Python Sandbox 官方 Python SDK — 在隔离的 Docker 容器中执行 Python 代码、Shell 命令、管理 pip 包、读写文件。
+
+对应后端：[`python-sandbox`](https://github.com/zjwan461/python-sandbox)（Spring Boot 3 + Java 17）。
+
+## ✨ 特性
+
+- 🚀 **简洁 API**：10 个方法覆盖会话、代码执行、Shell、pip、文件读写、文件上传下载、健康检查
+- 🔌 **上下文管理器**：自动管理 HTTP 连接与会话生命周期
+- 🛡️ **异常体系**：独立的 `ApiRequestError` / `SandboxError` 类型
+- 🧵 **线程安全**：`requests.Session` 复用，支持 `ThreadPoolExecutor` 并发
+- 🐍 **Python ≥ 3.8**：仅依赖 `requests>=2.31.0`
+
+## 📦 安装
+
+```bash
+# 方式 A：从 PyPI 安装（推荐）
+pip install python-sandbox-sdk
+
+# 方式 B：从源码安装
+git clone https://github.com/zjwan461/python-sandbox.git
+cd python-sandbox/sdk/python-sandbox-sdk
+pip install -e .
+```
+
+## 🚀 快速开始
+
+### 0. 启动后端服务
+
+参考 [`python-sandbox/README.md`](https://github.com/zjwan461/python-sandbox/blob/main/python-sandbox/README.md) 启动：
+
+```bash
+cd python-sandbox
+cp .env.example .env
+docker-compose up -d --build
+curl http://localhost:8080/health
+```
+
+### 1. 最简示例
+
+```python
+from python_sandbox_sdk import SandboxClient
+
+with SandboxClient("http://localhost:8080", "sandbox-secret-key") as client:
+    if not client.is_health():
+        raise SystemExit("Sandbox not ready")
+
+    session_id = client.create_session()
+    try:
+        result = client.exec_python(session_id, "print('Hello from sandbox!')")
+        print(result.stdout)              # Hello from sandbox!
+        print(result.exit_code)           # 0
+        print(result.success)             # True
+    finally:
+        client.delete_session(session_id)
+```
+
+### 2. 安装并使用第三方包
+
+```python
+client.pip_install(session_id, "requests==2.31.0")
+result = client.exec_python(session_id, """
+import requests
+print(requests.get('https://httpbin.org/get', timeout=5).status_code)
+""")
+```
+
+### 3. 文件读写
+
+```python
+# 文本
+client.write_file(session_id, "/tmp/config.json", '{"key": "value"}')
+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/) 目录：
+
+| 编号 | 场景 | 覆盖 API |
+|---|---|---|
+| [`01_hello_world.py`](usage/01_hello_world.py) | 入门：连通性 + Hello World | `is_health`, `create_session`, `exec_python`, `delete_session` |
+| [`02_session_management.py`](usage/02_session_management.py) | 会话管理：独立 / 复用 / 异常清理 | `create_session`, `delete_session` |
+| [`03_python_execution.py`](usage/03_python_execution.py) | Python 执行：语法 / 异常 / 状态 / 长任务 | `exec_python` |
+| [`04_shell_execution.py`](usage/04_shell_execution.py) | Shell 执行：基础 + 黑名单 + 安全路径 | `exec_shell` |
+| [`05_pip_packages.py`](usage/05_pip_packages.py) | pip 管理：安装 / 卸载 / 列表 / 版本约束 | `pip_install`, `pip_uninstall`, `pip_list` |
+| [`06_text_file_ops.py`](usage/06_text_file_ops.py) | 文本文件：JSON / CSV / 中文 / 日志 | `write_file`, `read_file` |
+| [`07_binary_file_ops.py`](usage/07_binary_file_ops.py) | 二进制：图片缩略图 + numpy 序列化 | `upload_file`, `download_file` |
+| [`08_data_analysis.py`](usage/08_data_analysis.py) | 数据分析实战：requests + pandas + matplotlib | 综合 |
+| [`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 错误路径 |
+
+运行样例：
+
+```bash
+cd usage/
+export SANDBOX_API_KEY="sandbox-secret-key"
+
+python 01_hello_world.py
+for f in 0[1-9]_*.py 1[0-1]_*.py; do python "$f"; done
+```
+
+## 🔧 API 速查
+
+| 方法 | 返回 | 说明 |
+|---|---|---|
+| `is_health()` | `bool` | 健康检查（无需 API Key） |
+| `create_session()` | `str` | 创建沙箱会话 |
+| `delete_session(session_id)` | `None` | 删除会话并清理容器 |
+| `exec_python(session_id, code)` | `CommandResult` | 执行 Python 代码 |
+| `exec_shell(session_id, command)` | `CommandResult` | 执行 Shell 命令 |
+| `pip_install(session_id, pkg)` | `CommandResult` | 安装 pip 包（支持版本约束） |
+| `pip_uninstall(session_id, pkg)` | `CommandResult` | 卸载 pip 包 |
+| `pip_list(session_id)` | `str` | 列出已安装包 |
+| `write_file(session_id, path, content)` | `None` | 写文本文件 |
+| `read_file(session_id, path)` | `str` | 读文本文件 |
+| `upload_file(session_id, path, data)` | `None` | 上传二进制文件 |
+| `download_file(session_id, path)` | `bytes` | 下载文件 |
+
+`CommandResult` 字段：`exit_code`, `stdout`, `stderr`, `success`（property）, `combined_output`（property）。
+
+## ⚙️ 环境变量
+
+为避免硬编码，样例通过环境变量注入连接信息：
+
+| 变量 | 默认值 | 说明 |
+|---|---|---|
+| `SANDBOX_BASE_URL` | `http://localhost:8080` | Sandbox 服务地址 |
+| `SANDBOX_API_KEY` | `sandbox-secret-key` | API 鉴权密钥（与后端 `SANDBOX_API_KEY` 保持一致） |
+
+## 🛡️ 异常处理
+
+```python
+from python_sandbox_sdk import SandboxClient, ApiRequestError, SandboxError
+
+try:
+    client.exec_python(session_id, "print(1)")
+except ApiRequestError as e:
+    # 后端返回的 4xx / 5xx（鉴权失败、会话不存在、黑名单、容器上限等）
+    print(f"API Error: HTTP {e.status_code} - {e}")
+except SandboxError as e:
+    # SDK 抛出的通用错误
+    print(f"SDK Error: {e}")
+except OSError as e:
+    # 网络错误（连接失败、超时等）
+    print(f"Network Error: {e}")
+```
+
+## 🧵 并发使用
+
+```python
+from concurrent.futures import ThreadPoolExecutor
+# 每个任务使用独立的 client + session（线程安全）
+with ThreadPoolExecutor(max_workers=5) as pool:
+    futures = [pool.submit(run_one_task, i) for i in range(5)]
+    for f in futures:
+        print(f.result())
+```
+
+> ⚠️ 并发数受后端 `sandbox.max-containers`（默认 10）约束。
+
+## 📦 打包发布
+
+```bash
+# 安装构建工具
+pip install build twine
+
+# 构建
+cd sdk/python-sandbox-sdk
+python -m build
+
+# 上传到 TestPyPI
+twine upload --repository testpypi dist/*
+
+# 上传到 PyPI
+twine upload dist/*
+```
+
+发布前请修改 `pyproject.toml` 中的 `version` 与 `urls` 字段。
+
+## 🔗 相关项目
+
+- 后端服务：[`python-sandbox/`](https://github.com/zjwan461/python-sandbox)
+- Java SDK：[`sdk/java-sandbox-sdk/`](https://github.com/zjwan461/python-sandbox/tree/main/sdk/java-sandbox-sdk)
+- SDK 总览：[`sdk/README.md`](https://github.com/zjwan461/python-sandbox/tree/main/sdk)
+
+## 📄 许可证
+
+MIT License

python_sandbox_sdk-1.0.0/pyproject.toml

@@ -0,0 +1,42 @@
+[build-system]
+requires = ["setuptools>=68.0", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "python-sandbox-sdk"
+version = "1.0.0"
+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"}
+]
+keywords = ["sandbox", "docker", "python", "security", "shell"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.8",
+    "Programming Language :: Python :: 3.9",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Topic :: Software Development :: Libraries :: Python Modules",
+]
+
+dependencies = [
+    "requests>=2.31.0",
+]
+
+[project.urls]
+Homepage = "https://github.com/zjwan461/python-sandbox"
+Repository = "https://github.com/zjwan461/python-sandbox"
+Documentation = "https://github.com/zjwan461/python-sandbox#readme"
+Issues = "https://github.com/zjwan461/python-sandbox/issues"
+Changelog = "https://github.com/zjwan461/python-sandbox/blob/main/CHANGELOG.md"
+"Usage Examples" = "https://github.com/zjwan461/python-sandbox/tree/main/sdk/python-sandbox-sdk/usage"
+
+[tool.setuptools.packages.find]
+where = ["."]
+include = ["python_sandbox_sdk*"]

python_sandbox_sdk-1.0.0/python_sandbox_sdk/__init__.py

@@ -0,0 +1,12 @@
+from .client import SandboxClient, SandboxError, ApiKeyMissingError, ApiRequestError
+from .dto import CommandResult, SessionResponse
+
+__all__ = [
+    'SandboxClient',
+    'CommandResult',
+    'SessionResponse',
+    'SandboxError',
+    'ApiKeyMissingError',
+    'ApiRequestError',
+]
+__version__ = '1.0.0'

python_sandbox_sdk-1.0.0/python_sandbox_sdk/client.py

@@ -0,0 +1,319 @@
+"""
+Python Sandbox SDK
+==================
+
+提供简洁的 API 客户端以与 Python Sandbox 服务交互。
+
+使用示例：
+    >>> from python_sandbox_sdk import SandboxClient
+    >>> client = SandboxClient("http://localhost:8080", "your-api-key")
+    >>> session_id = client.create_session()
+    >>> result = client.exec_python(session_id, "print('Hello!')")
+    >>> print(result.stdout)
+    Hello!
+"""
+
+import requests
+
+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}")
+
+
+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 认证密钥
+        """
+        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"
+        })
+    
+    # ==================== 会话管理 ====================
+    
+    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 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
+        )
+        self._raise_if_error(resp)
+        data = resp.json()
+        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
+        )
+        self._raise_if_error(resp)
+        data = resp.json()
+        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
+        )
+        self._raise_if_error(resp)
+        data = resp.json()
+        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
+        )
+        self._raise_if_error(resp)
+        data = resp.json()
+        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}
+        )
+        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
+        }
+        resp = self._session.post(
+            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}
+        )
+        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: 容器内目标路径
+            data: 文件字节数据
+        """
+        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:
+                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}
+                
+                # 发送 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)
+                    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 如果服务正常运行
+        """
+        try:
+            resp = requests.get(f"{self.base_url}/health", timeout=5)
+            return resp.status_code == 200
+        except Exception:
+            return False
+    
+    # ==================== 内部方法 ====================
+    
+    @staticmethod
+    def _raise_if_error(resp: requests.Response) -> None:
+        """如果响应状态码表示错误则抛出异常"""
+        if resp.status_code >= 400:
+            try:
+                error_data = resp.json()
+                message = error_data.get("message", resp.text)
+            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.0/python_sandbox_sdk/dto.py

@@ -0,0 +1,32 @@
+"""
+数据传输对象定义
+"""
+from dataclasses import dataclass
+from typing import Optional
+
+
+@dataclass
+class CommandResult:
+    """命令执行结果"""
+    exit_code: int
+    stdout: str = ""
+    stderr: str = ""
+
+    @property
+    def success(self) -> bool:
+        """是否执行成功"""
+        return self.exit_code == 0
+
+    @property
+    def combined_output(self) -> str:
+        """合并输出"""
+        if not self.stderr:
+            return self.stdout
+        return f"{self.stdout}\n{self.stderr}"
+
+
+@dataclass
+class SessionResponse:
+    """会话响应"""
+    session_id: str
+    message: Optional[str] = None

python_sandbox_sdk-1.0.0/python_sandbox_sdk.egg-info/PKG-INFO

@@ -0,0 +1,228 @@
+Metadata-Version: 2.4
+Name: python-sandbox-sdk
+Version: 1.0.0
+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>
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/zjwan461/python-sandbox
+Project-URL: Repository, https://github.com/zjwan461/python-sandbox
+Project-URL: Documentation, https://github.com/zjwan461/python-sandbox#readme
+Project-URL: Issues, https://github.com/zjwan461/python-sandbox/issues
+Project-URL: Changelog, https://github.com/zjwan461/python-sandbox/blob/main/CHANGELOG.md
+Project-URL: Usage Examples, https://github.com/zjwan461/python-sandbox/tree/main/sdk/python-sandbox-sdk/usage
+Keywords: sandbox,docker,python,security,shell
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.8
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+Requires-Dist: requests>=2.31.0
+Dynamic: home-page
+Dynamic: requires-python
+
+# python-sandbox-sdk
+
+[![Python](https://img.shields.io/badge/python-≥3.8-blue)](https://www.python.org)
+[![License: MIT](https://img.shields.io/badge/license-MIT-green)](LICENSE)
+[![Docker](https://img.shields.io/badge/docker-required-blue)](https://www.docker.com)
+
+Python Sandbox 官方 Python SDK — 在隔离的 Docker 容器中执行 Python 代码、Shell 命令、管理 pip 包、读写文件。
+
+对应后端：[`python-sandbox`](https://github.com/zjwan461/python-sandbox)（Spring Boot 3 + Java 17）。
+
+## ✨ 特性
+
+- 🚀 **简洁 API**：10 个方法覆盖会话、代码执行、Shell、pip、文件读写、文件上传下载、健康检查
+- 🔌 **上下文管理器**：自动管理 HTTP 连接与会话生命周期
+- 🛡️ **异常体系**：独立的 `ApiRequestError` / `SandboxError` 类型
+- 🧵 **线程安全**：`requests.Session` 复用，支持 `ThreadPoolExecutor` 并发
+- 🐍 **Python ≥ 3.8**：仅依赖 `requests>=2.31.0`
+
+## 📦 安装
+
+```bash
+# 方式 A：从 PyPI 安装（推荐）
+pip install python-sandbox-sdk
+
+# 方式 B：从源码安装
+git clone https://github.com/zjwan461/python-sandbox.git
+cd python-sandbox/sdk/python-sandbox-sdk
+pip install -e .
+```
+
+## 🚀 快速开始
+
+### 0. 启动后端服务
+
+参考 [`python-sandbox/README.md`](https://github.com/zjwan461/python-sandbox/blob/main/python-sandbox/README.md) 启动：
+
+```bash
+cd python-sandbox
+cp .env.example .env
+docker-compose up -d --build
+curl http://localhost:8080/health
+```
+
+### 1. 最简示例
+
+```python
+from python_sandbox_sdk import SandboxClient
+
+with SandboxClient("http://localhost:8080", "sandbox-secret-key") as client:
+    if not client.is_health():
+        raise SystemExit("Sandbox not ready")
+
+    session_id = client.create_session()
+    try:
+        result = client.exec_python(session_id, "print('Hello from sandbox!')")
+        print(result.stdout)              # Hello from sandbox!
+        print(result.exit_code)           # 0
+        print(result.success)             # True
+    finally:
+        client.delete_session(session_id)
+```
+
+### 2. 安装并使用第三方包
+
+```python
+client.pip_install(session_id, "requests==2.31.0")
+result = client.exec_python(session_id, """
+import requests
+print(requests.get('https://httpbin.org/get', timeout=5).status_code)
+""")
+```
+
+### 3. 文件读写
+
+```python
+# 文本
+client.write_file(session_id, "/tmp/config.json", '{"key": "value"}')
+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/) 目录：
+
+| 编号 | 场景 | 覆盖 API |
+|---|---|---|
+| [`01_hello_world.py`](usage/01_hello_world.py) | 入门：连通性 + Hello World | `is_health`, `create_session`, `exec_python`, `delete_session` |
+| [`02_session_management.py`](usage/02_session_management.py) | 会话管理：独立 / 复用 / 异常清理 | `create_session`, `delete_session` |
+| [`03_python_execution.py`](usage/03_python_execution.py) | Python 执行：语法 / 异常 / 状态 / 长任务 | `exec_python` |
+| [`04_shell_execution.py`](usage/04_shell_execution.py) | Shell 执行：基础 + 黑名单 + 安全路径 | `exec_shell` |
+| [`05_pip_packages.py`](usage/05_pip_packages.py) | pip 管理：安装 / 卸载 / 列表 / 版本约束 | `pip_install`, `pip_uninstall`, `pip_list` |
+| [`06_text_file_ops.py`](usage/06_text_file_ops.py) | 文本文件：JSON / CSV / 中文 / 日志 | `write_file`, `read_file` |
+| [`07_binary_file_ops.py`](usage/07_binary_file_ops.py) | 二进制：图片缩略图 + numpy 序列化 | `upload_file`, `download_file` |
+| [`08_data_analysis.py`](usage/08_data_analysis.py) | 数据分析实战：requests + pandas + matplotlib | 综合 |
+| [`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 错误路径 |
+
+运行样例：
+
+```bash
+cd usage/
+export SANDBOX_API_KEY="sandbox-secret-key"
+
+python 01_hello_world.py
+for f in 0[1-9]_*.py 1[0-1]_*.py; do python "$f"; done
+```
+
+## 🔧 API 速查
+
+| 方法 | 返回 | 说明 |
+|---|---|---|
+| `is_health()` | `bool` | 健康检查（无需 API Key） |
+| `create_session()` | `str` | 创建沙箱会话 |
+| `delete_session(session_id)` | `None` | 删除会话并清理容器 |
+| `exec_python(session_id, code)` | `CommandResult` | 执行 Python 代码 |
+| `exec_shell(session_id, command)` | `CommandResult` | 执行 Shell 命令 |
+| `pip_install(session_id, pkg)` | `CommandResult` | 安装 pip 包（支持版本约束） |
+| `pip_uninstall(session_id, pkg)` | `CommandResult` | 卸载 pip 包 |
+| `pip_list(session_id)` | `str` | 列出已安装包 |
+| `write_file(session_id, path, content)` | `None` | 写文本文件 |
+| `read_file(session_id, path)` | `str` | 读文本文件 |
+| `upload_file(session_id, path, data)` | `None` | 上传二进制文件 |
+| `download_file(session_id, path)` | `bytes` | 下载文件 |
+
+`CommandResult` 字段：`exit_code`, `stdout`, `stderr`, `success`（property）, `combined_output`（property）。
+
+## ⚙️ 环境变量
+
+为避免硬编码，样例通过环境变量注入连接信息：
+
+| 变量 | 默认值 | 说明 |
+|---|---|---|
+| `SANDBOX_BASE_URL` | `http://localhost:8080` | Sandbox 服务地址 |
+| `SANDBOX_API_KEY` | `sandbox-secret-key` | API 鉴权密钥（与后端 `SANDBOX_API_KEY` 保持一致） |
+
+## 🛡️ 异常处理
+
+```python
+from python_sandbox_sdk import SandboxClient, ApiRequestError, SandboxError
+
+try:
+    client.exec_python(session_id, "print(1)")
+except ApiRequestError as e:
+    # 后端返回的 4xx / 5xx（鉴权失败、会话不存在、黑名单、容器上限等）
+    print(f"API Error: HTTP {e.status_code} - {e}")
+except SandboxError as e:
+    # SDK 抛出的通用错误
+    print(f"SDK Error: {e}")
+except OSError as e:
+    # 网络错误（连接失败、超时等）
+    print(f"Network Error: {e}")
+```
+
+## 🧵 并发使用
+
+```python
+from concurrent.futures import ThreadPoolExecutor
+# 每个任务使用独立的 client + session（线程安全）
+with ThreadPoolExecutor(max_workers=5) as pool:
+    futures = [pool.submit(run_one_task, i) for i in range(5)]
+    for f in futures:
+        print(f.result())
+```
+
+> ⚠️ 并发数受后端 `sandbox.max-containers`（默认 10）约束。
+
+## 📦 打包发布
+
+```bash
+# 安装构建工具
+pip install build twine
+
+# 构建
+cd sdk/python-sandbox-sdk
+python -m build
+
+# 上传到 TestPyPI
+twine upload --repository testpypi dist/*
+
+# 上传到 PyPI
+twine upload dist/*
+```
+
+发布前请修改 `pyproject.toml` 中的 `version` 与 `urls` 字段。
+
+## 🔗 相关项目
+
+- 后端服务：[`python-sandbox/`](https://github.com/zjwan461/python-sandbox)
+- Java SDK：[`sdk/java-sandbox-sdk/`](https://github.com/zjwan461/python-sandbox/tree/main/sdk/java-sandbox-sdk)
+- SDK 总览：[`sdk/README.md`](https://github.com/zjwan461/python-sandbox/tree/main/sdk)
+
+## 📄 许可证
+
+MIT License

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

@@ -0,0 +1,14 @@
+README.md
+pyproject.toml
+setup.py
+./python_sandbox_sdk/__init__.py
+./python_sandbox_sdk/client.py
+./python_sandbox_sdk/dto.py
+python_sandbox_sdk/__init__.py
+python_sandbox_sdk/client.py
+python_sandbox_sdk/dto.py
+python_sandbox_sdk.egg-info/PKG-INFO
+python_sandbox_sdk.egg-info/SOURCES.txt
+python_sandbox_sdk.egg-info/dependency_links.txt
+python_sandbox_sdk.egg-info/requires.txt
+python_sandbox_sdk.egg-info/top_level.txt

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

@@ -0,0 +1 @@
+

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

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

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

@@ -0,0 +1 @@
+python_sandbox_sdk

python_sandbox_sdk-1.0.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

python_sandbox_sdk-1.0.0/setup.py

@@ -0,0 +1,58 @@
+"""Setuptools configuration for python-sandbox-sdk.
+
+本文件同时作为：
+1. 兼容 setup.py 的安装入口（`pip install .`）
+2. 长描述来源 — PyPI 包页面会展示 README.md 的渲染结果
+"""
+import os
+from pathlib import Path
+
+from setuptools import setup, find_packages
+
+
+def _read_readme() -> str:
+    """读取 README.md 作为 long_description。
+
+    README.md 位于 sdk/python-sandbox-sdk/README.md，
+    通过相对路径回溯到仓库根再定位的方式不可靠，因此固定使用当前文件同级目录。
+    """
+    here = Path(__file__).resolve().parent
+    readme_path = here / "README.md"
+    if readme_path.exists():
+        return readme_path.read_text(encoding="utf-8")
+    # 兜底：仅返回一行标题，避免发布到 PyPI 时缺失描述
+    return "python-sandbox-sdk: Python SDK for Python Sandbox API"
+
+
+setup(
+    name="python-sandbox-sdk",
+    version="1.0.0",
+    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",
+    author_email="826935261@qq.com",
+    url="https://github.com/zjwan461/python-sandbox",
+    project_urls={
+        "Repository": "https://github.com/zjwan461/python-sandbox",
+        "Documentation": "https://github.com/zjwan461/python-sandbox#readme",
+        "Issues": "https://github.com/zjwan461/python-sandbox/issues",
+        "Changelog": "https://github.com/zjwan461/python-sandbox/blob/main/CHANGELOG.md",
+        "Usage Examples": "https://github.com/zjwan461/python-sandbox/tree/main/sdk/python-sandbox-sdk/usage",
+    },
+    packages=find_packages(where="."),
+    package_dir={"": "."},
+    python_requires=">=3.8",
+    classifiers=[
+        "Development Status :: 4 - Beta",
+        "Intended Audience :: Developers",
+        "Programming Language :: Python :: 3",
+        "Programming Language :: Python :: 3.8",
+        "Programming Language :: Python :: 3.9",
+        "Programming Language :: Python :: 3.10",
+        "Programming Language :: Python :: 3.11",
+        "Programming Language :: Python :: 3.12",
+        "Topic :: Software Development :: Libraries :: Python Modules",
+        "Topic :: System :: Sandboxing",
+    ],
+    keywords="sandbox docker python security shell",
+)