scalebox-sdk 0.1.0__tar.gz

scalebox_sdk-0.1.0/CHANGELOG.md

@@ -0,0 +1,44 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+### Added
+- Initial release of ScaleBox Python SDK
+- Multi-language code execution support (Python, R, Node.js, Deno/TypeScript, Java, Bash)
+- Synchronous and asynchronous sandbox execution
+- Persistent context management across executions
+- Rich result formats (text, HTML, Markdown, SVG, images, LaTeX, JSON, JavaScript, charts)
+- Real-time callbacks for stdout, stderr, results, and errors
+- Comprehensive test suite with integration tests
+- Full API client with authentication support
+- File system operations and command execution
+- PTY support for interactive sessions
+- Context managers for resource cleanup
+- Error handling with specific exception types
+- Connection configuration with environment variable support
+
+### Features
+- **Code Interpreter**: Execute code in multiple languages with rich output formats
+- **Sandbox Management**: Create, manage, and destroy isolated execution environments
+- **File Operations**: Upload, download, list, and manage files in sandboxes
+- **Command Execution**: Run shell commands with real-time output
+- **Context Persistence**: Maintain variable state across multiple executions
+- **Async Support**: Full async/await support for concurrent operations
+- **Error Handling**: Comprehensive exception handling with specific error types
+- **Authentication**: API key and token-based authentication
+- **Configuration**: Flexible configuration via environment variables or direct parameters
+
+## [0.1.0] - 2025-01-XX
+
+### Added
+- Initial release
+- Core SDK functionality
+- Multi-language support
+- Comprehensive documentation
+- Test suite with 49+ test cases
+- PyPI package configuration

scalebox_sdk-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 scalebox-dev
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

scalebox_sdk-0.1.0/MANIFEST.in

@@ -0,0 +1,23 @@
+include README.md
+include LICENSE
+include CHANGELOG.md
+include pyproject.toml
+recursive-include scalebox *.py
+recursive-include scalebox *.pyi
+recursive-include scalebox *.proto
+recursive-include scalebox *.yaml
+recursive-include scalebox *.yml
+recursive-include scalebox *.txt
+recursive-include scalebox *.md
+include scalebox/py.typed
+recursive-include scalebox/test *.py
+recursive-include scalebox/test *.md
+recursive-include scalebox/test *.sh
+global-exclude *.pyc
+global-exclude *.pyo
+global-exclude __pycache__
+global-exclude .git*
+global-exclude .DS_Store
+global-exclude *.egg-info
+global-exclude dist
+global-exclude build

scalebox_sdk-0.1.0/PKG-INFO

@@ -0,0 +1,292 @@
+Metadata-Version: 2.4
+Name: scalebox-sdk
+Version: 0.1.0
+Summary: ScaleBox Python SDK - A multi-language code execution sandbox with Python, R, Node.js, Deno/TypeScript, Java, and Bash support
+Author-email: ScaleBox Team <dev@scalebox.dev>
+Maintainer-email: ScaleBox Team <dev@scalebox.dev>
+License: MIT
+Project-URL: Homepage, https://github.com/scalebox-dev/scalebox-sdk-python
+Project-URL: Documentation, https://docs.scalebox.dev/python-sdk
+Project-URL: Repository, https://github.com/scalebox-dev/scalebox-sdk-python
+Project-URL: Issues, https://github.com/scalebox-dev/scalebox-sdk-python/issues
+Project-URL: Changelog, https://github.com/scalebox-dev/scalebox-sdk-python/blob/main/CHANGELOG.md
+Keywords: sandbox,code-execution,multi-language,python,r,nodejs,typescript,java,bash
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+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: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Topic :: Software Development :: Testing
+Classifier: Topic :: System :: Distributed Computing
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: httpx>=0.24
+Requires-Dist: aiohttp>=3.8.0
+Requires-Dist: urllib3>=1.26.0
+Requires-Dist: httpcore>=0.15.0
+Requires-Dist: grpcio>=1.70.0
+Requires-Dist: grpcio-tools>=1.70.0
+Requires-Dist: protobuf>=4.0.0
+Requires-Dist: attrs>=21.4.0
+Requires-Dist: dataclasses-json>=0.5.0
+Requires-Dist: python-dateutil>=2.8.0
+Requires-Dist: tenacity>=8.0.0
+Requires-Dist: packaging>=21.0
+Requires-Dist: typing-extensions>=4.0.0
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0.0; extra == "dev"
+Requires-Dist: pytest-asyncio>=0.21.0; extra == "dev"
+Requires-Dist: pytest-cov>=4.0.0; extra == "dev"
+Requires-Dist: black>=22.0.0; extra == "dev"
+Requires-Dist: isort>=5.0.0; extra == "dev"
+Requires-Dist: flake8>=4.0.0; extra == "dev"
+Requires-Dist: mypy>=0.950; extra == "dev"
+Requires-Dist: pre-commit>=2.17.0; extra == "dev"
+Requires-Dist: python-dotenv>=0.19.0; extra == "dev"
+Provides-Extra: connect
+Requires-Dist: connectrpc>=0.0.1; python_version >= "3.13" and extra == "connect"
+Provides-Extra: docs
+Requires-Dist: sphinx>=4.0.0; extra == "docs"
+Requires-Dist: sphinx-rtd-theme>=1.0.0; extra == "docs"
+Requires-Dist: myst-parser>=0.18.0; extra == "docs"
+Dynamic: license-file
+
+# Scalebox Python SDK
+
+一个用于在可控沙箱中执行多语言代码的 Python SDK，支持同步与异步模式，以及多语言 Kernel（Python、R、Node.js、Deno/TypeScript、Java/IJAVA、Bash）。已提供全面的真实环境测试用例与脚本。
+
+## 功能特性
+- 多语言内核：Python、R、Node.js、Deno/TypeScript、Java/IJAVA、Bash
+- 同步 `Sandbox` 与异步 `AsyncSandbox` 执行
+- 持久上下文：跨多次执行保留变量/状态
+- 回调订阅：stdout、stderr、结果与错误
+- 丰富结果格式：text、html、markdown、svg、png、jpeg、pdf、latex、json、javascript、chart、data 等
+- 真实环境测试：覆盖同步/异步与多语言示例
+
+## 环境要求
+- Python 3.12+
+- 可访问的 Scalebox 环境或本地服务
+
+## 安装
+
+```bash
+# 克隆项目
+git clone https://github.com/scalebox-dev/scalebox-sdk-python.git
+cd scalebox-sdk-python
+
+# 建议使用虚拟环境
+python3 -m venv venv
+source venv/bin/activate
+
+# 安装依赖
+pip install -r scalebox/requirements.txt
+```
+
+如果你以源码方式直接使用包（非 pip 安装），请将 `scalebox` 目录加入 Python 路径或复制到 venv 的 site-packages：
+```bash
+cp -r scalebox venv/lib/python3.12/site-packages/
+```
+
+## 配置
+支持从环境变量或 `.env` 文件读取凭据：
+
+- `SBX_API_KEY` 或 `E2B_API_KEY`
+
+示例：
+```env
+# .env
+SBX_API_KEY=***
+```
+或：
+```bash
+export SBX_API_KEY=***
+```
+
+可选：使用 `python-dotenv` 自动加载 `.env`：
+```bash
+pip install python-dotenv
+```
+
+## 快速开始（同步）
+```python
+from dotenv import load_dotenv; load_dotenv()
+from scalebox.code_interpreter import Sandbox
+
+sandbox = Sandbox.create()  # 默认生存期 5 分钟
+execution = sandbox.run_code("print('hello world')", language="python")
+print(execution.logs.stdout)
+
+files = sandbox.files.list("/")
+print(files)
+```
+
+## 快速开始（异步）
+```python
+import asyncio
+from dotenv import load_dotenv; load_dotenv()
+from scalebox.code_interpreter import AsyncSandbox
+
+async def main():
+    sandbox = await AsyncSandbox.create()
+    exec_ = await sandbox.run_code("print('async hello')", language="python")
+    print(exec_.logs.stdout)
+
+asyncio.run(main())
+```
+
+## 多语言示例
+- Python：`language="python"`
+- R：`language="r"`
+- Node.js：`language="nodejs"`
+- Deno/TypeScript：`language="typescript"`
+- Java（IJAVA/纯Java）：`language="ijava"` 或 `language="java"`
+- Bash：`language="bash"`
+
+示例（Node.js）：
+```python
+from scalebox.code_interpreter import Sandbox
+sbx = Sandbox.create()
+code = """
+console.log("Hello from Node.js!");
+const x = 1 + 2; console.log(`x=${x}`);
+"""
+result = sbx.run_code(code, language="nodejs")
+print(result.logs.stdout)
+```
+
+示例（R）：
+```python
+from scalebox.code_interpreter import Sandbox
+sbx = Sandbox.create()
+code = """
+print("Hello from R!")
+x <- mean(c(1,2,3,4,5))
+print(paste("mean:", x))
+"""
+res = sbx.run_code(code, language="r")
+print(res.logs.stdout)
+```
+
+示例（Deno/TypeScript）：
+```python
+from scalebox.code_interpreter import Sandbox
+sbx = Sandbox.create()
+ts = """
+console.log("Hello from Deno/TypeScript!")
+const nums: number[] = [1,2,3]
+console.log(nums.reduce((a,b)=>a+b, 0))
+"""
+res = sbx.run_code(ts, language="typescript")
+print(res.logs.stdout)
+```
+
+示例（Java/IJAVA）：
+```python
+from scalebox.code_interpreter import Sandbox
+sbx = Sandbox.create()
+code = """
+System.out.println("Hello from IJAVA!");
+int a = 10, b = 20; System.out.println(a + b);
+"""
+res = sbx.run_code(code, language="java")
+print(res.logs.stdout)
+```
+
+示例（Bash）：
+```python
+from scalebox.code_interpreter import Sandbox
+sbx = Sandbox.create()
+res = sbx.run_code("echo 'Hello from Bash'", language="bash")
+print(res.logs.stdout)
+```
+
+## 上下文管理（Context）
+上下文允许跨多次执行复用变量/状态：
+```python
+from scalebox.code_interpreter import Sandbox
+sbx = Sandbox.create()
+ctx = sbx.create_code_context(language="python", cwd="/tmp")
+
+sbx.run_code("counter = 0", context=ctx)
+sbx.run_code("counter += 1; print(counter)", context=ctx)
+# 使用完必须清理
+sbx.destroy_context(ctx)
+```
+异步 API：
+```python
+from scalebox.code_interpreter import AsyncSandbox
+
+async def demo():
+    sbx = await AsyncSandbox.create()
+    ctx = await sbx.create_code_context(language="python", cwd="/tmp")
+    await sbx.run_code("counter = 0", context=ctx)
+    await sbx.run_code("counter += 1; print(counter)", context=ctx)
+    await sbx.destroy_context(ctx)
+```
+
+## 回调（可选）
+```python
+from scalebox.code_interpreter import Sandbox
+from scalebox.code_interpreter import OutputMessage, Result, ExecutionError
+
+sbx = Sandbox.create()
+
+def on_stdout(msg: OutputMessage):
+    print("STDOUT:", msg.content)
+
+def on_stderr(msg: OutputMessage):
+    print("STDERR:", msg.content)
+
+def on_result(res: Result):
+    print("RESULT formats:", list(res.formats()))
+
+def on_error(err: ExecutionError):
+    print("ERROR:", err.name, err.value)
+
+sbx.run_code(
+    "print('with callbacks')",
+    language="python",
+    on_stdout=on_stdout,
+    on_stderr=on_stderr,
+    on_result=on_result,
+    on_error=on_error,
+)
+```
+
+## 结果格式（Result）
+`Result` 可能包含如下数据字段：
+- `text`, `html`, `markdown`, `svg`, `png`, `jpeg`, `pdf`, `latex`
+- `json_data`, `javascript`, `data`, `chart`
+- `execution_count`, `is_main_result`, `extra`
+
+可以通过 `list(result.formats())` 查看可用格式。
+
+## 运行测试
+项目 `test/` 目录包含全面的真实环境用例（非 unittest，直接脚本风格），覆盖：
+- 同步与异步综合用例
+- 多语言内核（Python、R、Node.js、Deno/TypeScript、Java/IJAVA、Bash）
+- 上下文管理、回调与结果格式
+
+运行语法检查：
+```bash
+cd test
+python3 -m py_compile test_code_interpreter_sync_comprehensive.py
+python3 -m py_compile test_code_interpreter_async_comprehensive.py
+```
+
+建议在虚拟环境中准备依赖并按需安装语言运行时（如 R、Node、Deno、JDK/IJAVA 等），确保各内核能够被后端执行。
+
+## 常见问题（Troubleshooting）
+- Import/依赖错误：请确认已激活 venv 并正确安装 `scalebox/requirements.txt` 所需依赖
+- `ModuleNotFoundError`：在测试脚本中添加项目根路径到 `sys.path`，或从项目根目录运行
+- 外部内核不可用：确保环境已安装对应语言运行时（R/Node/Deno/JDK）与后端已启用该内核
+- 超时/网络：检查网络与后端服务可达性，必要时增大 `timeout`/`request_timeout`
+
+## 许可证
+本项目遵循项目仓库所附许可证（LICENSE）条款。

scalebox_sdk-0.1.0/README.md

@@ -0,0 +1,233 @@
+# Scalebox Python SDK
+
+一个用于在可控沙箱中执行多语言代码的 Python SDK，支持同步与异步模式，以及多语言 Kernel（Python、R、Node.js、Deno/TypeScript、Java/IJAVA、Bash）。已提供全面的真实环境测试用例与脚本。
+
+## 功能特性
+- 多语言内核：Python、R、Node.js、Deno/TypeScript、Java/IJAVA、Bash
+- 同步 `Sandbox` 与异步 `AsyncSandbox` 执行
+- 持久上下文：跨多次执行保留变量/状态
+- 回调订阅：stdout、stderr、结果与错误
+- 丰富结果格式：text、html、markdown、svg、png、jpeg、pdf、latex、json、javascript、chart、data 等
+- 真实环境测试：覆盖同步/异步与多语言示例
+
+## 环境要求
+- Python 3.12+
+- 可访问的 Scalebox 环境或本地服务
+
+## 安装
+
+```bash
+# 克隆项目
+git clone https://github.com/scalebox-dev/scalebox-sdk-python.git
+cd scalebox-sdk-python
+
+# 建议使用虚拟环境
+python3 -m venv venv
+source venv/bin/activate
+
+# 安装依赖
+pip install -r scalebox/requirements.txt
+```
+
+如果你以源码方式直接使用包（非 pip 安装），请将 `scalebox` 目录加入 Python 路径或复制到 venv 的 site-packages：
+```bash
+cp -r scalebox venv/lib/python3.12/site-packages/
+```
+
+## 配置
+支持从环境变量或 `.env` 文件读取凭据：
+
+- `SBX_API_KEY` 或 `E2B_API_KEY`
+
+示例：
+```env
+# .env
+SBX_API_KEY=***
+```
+或：
+```bash
+export SBX_API_KEY=***
+```
+
+可选：使用 `python-dotenv` 自动加载 `.env`：
+```bash
+pip install python-dotenv
+```
+
+## 快速开始（同步）
+```python
+from dotenv import load_dotenv; load_dotenv()
+from scalebox.code_interpreter import Sandbox
+
+sandbox = Sandbox.create()  # 默认生存期 5 分钟
+execution = sandbox.run_code("print('hello world')", language="python")
+print(execution.logs.stdout)
+
+files = sandbox.files.list("/")
+print(files)
+```
+
+## 快速开始（异步）
+```python
+import asyncio
+from dotenv import load_dotenv; load_dotenv()
+from scalebox.code_interpreter import AsyncSandbox
+
+async def main():
+    sandbox = await AsyncSandbox.create()
+    exec_ = await sandbox.run_code("print('async hello')", language="python")
+    print(exec_.logs.stdout)
+
+asyncio.run(main())
+```
+
+## 多语言示例
+- Python：`language="python"`
+- R：`language="r"`
+- Node.js：`language="nodejs"`
+- Deno/TypeScript：`language="typescript"`
+- Java（IJAVA/纯Java）：`language="ijava"` 或 `language="java"`
+- Bash：`language="bash"`
+
+示例（Node.js）：
+```python
+from scalebox.code_interpreter import Sandbox
+sbx = Sandbox.create()
+code = """
+console.log("Hello from Node.js!");
+const x = 1 + 2; console.log(`x=${x}`);
+"""
+result = sbx.run_code(code, language="nodejs")
+print(result.logs.stdout)
+```
+
+示例（R）：
+```python
+from scalebox.code_interpreter import Sandbox
+sbx = Sandbox.create()
+code = """
+print("Hello from R!")
+x <- mean(c(1,2,3,4,5))
+print(paste("mean:", x))
+"""
+res = sbx.run_code(code, language="r")
+print(res.logs.stdout)
+```
+
+示例（Deno/TypeScript）：
+```python
+from scalebox.code_interpreter import Sandbox
+sbx = Sandbox.create()
+ts = """
+console.log("Hello from Deno/TypeScript!")
+const nums: number[] = [1,2,3]
+console.log(nums.reduce((a,b)=>a+b, 0))
+"""
+res = sbx.run_code(ts, language="typescript")
+print(res.logs.stdout)
+```
+
+示例（Java/IJAVA）：
+```python
+from scalebox.code_interpreter import Sandbox
+sbx = Sandbox.create()
+code = """
+System.out.println("Hello from IJAVA!");
+int a = 10, b = 20; System.out.println(a + b);
+"""
+res = sbx.run_code(code, language="java")
+print(res.logs.stdout)
+```
+
+示例（Bash）：
+```python
+from scalebox.code_interpreter import Sandbox
+sbx = Sandbox.create()
+res = sbx.run_code("echo 'Hello from Bash'", language="bash")
+print(res.logs.stdout)
+```
+
+## 上下文管理（Context）
+上下文允许跨多次执行复用变量/状态：
+```python
+from scalebox.code_interpreter import Sandbox
+sbx = Sandbox.create()
+ctx = sbx.create_code_context(language="python", cwd="/tmp")
+
+sbx.run_code("counter = 0", context=ctx)
+sbx.run_code("counter += 1; print(counter)", context=ctx)
+# 使用完必须清理
+sbx.destroy_context(ctx)
+```
+异步 API：
+```python
+from scalebox.code_interpreter import AsyncSandbox
+
+async def demo():
+    sbx = await AsyncSandbox.create()
+    ctx = await sbx.create_code_context(language="python", cwd="/tmp")
+    await sbx.run_code("counter = 0", context=ctx)
+    await sbx.run_code("counter += 1; print(counter)", context=ctx)
+    await sbx.destroy_context(ctx)
+```
+
+## 回调（可选）
+```python
+from scalebox.code_interpreter import Sandbox
+from scalebox.code_interpreter import OutputMessage, Result, ExecutionError
+
+sbx = Sandbox.create()
+
+def on_stdout(msg: OutputMessage):
+    print("STDOUT:", msg.content)
+
+def on_stderr(msg: OutputMessage):
+    print("STDERR:", msg.content)
+
+def on_result(res: Result):
+    print("RESULT formats:", list(res.formats()))
+
+def on_error(err: ExecutionError):
+    print("ERROR:", err.name, err.value)
+
+sbx.run_code(
+    "print('with callbacks')",
+    language="python",
+    on_stdout=on_stdout,
+    on_stderr=on_stderr,
+    on_result=on_result,
+    on_error=on_error,
+)
+```
+
+## 结果格式（Result）
+`Result` 可能包含如下数据字段：
+- `text`, `html`, `markdown`, `svg`, `png`, `jpeg`, `pdf`, `latex`
+- `json_data`, `javascript`, `data`, `chart`
+- `execution_count`, `is_main_result`, `extra`
+
+可以通过 `list(result.formats())` 查看可用格式。
+
+## 运行测试
+项目 `test/` 目录包含全面的真实环境用例（非 unittest，直接脚本风格），覆盖：
+- 同步与异步综合用例
+- 多语言内核（Python、R、Node.js、Deno/TypeScript、Java/IJAVA、Bash）
+- 上下文管理、回调与结果格式
+
+运行语法检查：
+```bash
+cd test
+python3 -m py_compile test_code_interpreter_sync_comprehensive.py
+python3 -m py_compile test_code_interpreter_async_comprehensive.py
+```
+
+建议在虚拟环境中准备依赖并按需安装语言运行时（如 R、Node、Deno、JDK/IJAVA 等），确保各内核能够被后端执行。
+
+## 常见问题（Troubleshooting）
+- Import/依赖错误：请确认已激活 venv 并正确安装 `scalebox/requirements.txt` 所需依赖
+- `ModuleNotFoundError`：在测试脚本中添加项目根路径到 `sys.path`，或从项目根目录运行
+- 外部内核不可用：确保环境已安装对应语言运行时（R/Node/Deno/JDK）与后端已启用该内核
+- 超时/网络：检查网络与后端服务可达性，必要时增大 `timeout`/`request_timeout`
+
+## 许可证
+本项目遵循项目仓库所附许可证（LICENSE）条款。