cubesandbox 0.1.0__tar.gz

cubesandbox-0.1.0/PKG-INFO

@@ -0,0 +1,14 @@
+Metadata-Version: 2.4
+Name: cubesandbox
+Version: 0.1.0
+Summary: Python SDK for CubeSandbox
+Author: TencentCloud CubeSandbox Team
+License: Apache-2.0
+Project-URL: Homepage, https://github.com/TencentCloud/CubeSandbox
+Requires-Python: >=3.9
+Requires-Dist: httpx>=0.27
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0; extra == "dev"
+Requires-Dist: pytest-cov>=4.0; extra == "dev"
+Requires-Dist: mypy>=1.0; extra == "dev"
+Requires-Dist: ruff>=0.4; extra == "dev"

cubesandbox-0.1.0/README.md

@@ -0,0 +1,233 @@
+<p align="center">
+  <strong>cubesandbox</strong> — Python SDK for CubeSandbox
+</p>
+
+<p align="center">
+  <a href="https://github.com/TencentCloud/CubeSandbox"><img src="https://img.shields.io/badge/CubeSandbox-GitHub-blue" alt="CubeSandbox" /></a>
+  <a href="../../LICENSE"><img src="https://img.shields.io/badge/License-Apache_2.0-green" alt="Apache 2.0" /></a>
+  <img src="https://img.shields.io/badge/Python-3.9%2B-blue" alt="Python 3.9+" />
+  <img src="https://img.shields.io/badge/version-0.1.0-orange" alt="v0.1.0" />
+</p>
+
+---
+
+`cubesandbox` is the official Python SDK for [CubeSandbox](https://github.com/TencentCloud/CubeSandbox).
+It provides a simple, Pythonic interface to create sandboxes, execute code,
+and control the full sandbox lifecycle — including pause/resume with memory snapshot.
+
+## Installation
+
+```bash
+pip install cubesandbox
+```
+
+Or install from source:
+
+```bash
+cd sdk/python
+pip install -e .
+```
+
+## Quick Start
+
+Set the required environment variables:
+
+```bash
+export CUBE_API_URL=http://<your-cubeapi-host>:3000
+export CUBE_TEMPLATE_ID=<your-template-id>
+
+# Required for remote access (bypasses DNS for *.cube.app)
+export CUBE_PROXY_NODE_IP=<your-cubeproxy-node-ip>
+```
+
+Run your first sandbox:
+
+```python
+from cubesandbox import Sandbox
+
+with Sandbox.create() as sb:
+    result = sb.run_code("1 + 1")
+    print(result.text)   # "2"
+```
+
+## Features
+
+### Execute code
+
+```python
+from cubesandbox import Sandbox
+
+with Sandbox.create() as sb:
+    # Simple expression
+    result = sb.run_code("x = 42\nx * 2")
+    print(result.text)          # "84"
+
+    # Capture stdout
+    result = sb.run_code('print("hello")')
+    print(result.logs.stdout)   # ["hello\n"]
+
+    # Stream output in real time
+    sb.run_code(
+        'for i in range(3): print(i)',
+        on_stdout=lambda msg: print("out:", msg.text),
+    )
+```
+
+### Persistent variables within a sandbox
+
+Variables assigned in one `run_code` call persist for the lifetime of the sandbox —
+no separate context object needed:
+
+```python
+with Sandbox.create() as sb:
+    sb.run_code("x = 100")
+    result = sb.run_code("x + 1")
+    print(result.text)   # "101"
+```
+
+
+### Pause & resume
+
+```python
+sb = Sandbox.create()
+
+# Pause — preserves memory snapshot, polls until state=paused
+sb.pause()                         # wait=True, timeout=30s by default
+sb.pause(wait=False)               # fire-and-forget
+sb.pause(timeout=60, interval=0.5) # custom poll params
+
+# Resume by connecting — auto-resumes paused sandbox
+sb2 = Sandbox.connect(sb.sandbox_id)
+```
+
+### Network policy
+
+```python
+import json
+from cubesandbox import Sandbox
+
+# Deny all outbound traffic
+with Sandbox.create(metadata={"network-policy": "deny-all"}) as sb:
+    result = sb.run_code(
+        "import urllib.request; urllib.request.urlopen('http://example.com')"
+    )
+    print(result.error.name)   # "URLError"
+
+# Custom allow-list — NOTE: only IP addresses are supported, not domain names
+rules = json.dumps({"allow": ["151.101.0.0/16"]})
+with Sandbox.create(
+    metadata={"network-policy": "custom", "network-rules": rules}
+) as sb:
+    sb.run_code("import subprocess; subprocess.run(['pip', 'install', 'requests'])")
+```
+
+### Host-directory mount
+
+```python
+import json
+from cubesandbox import Sandbox
+
+mounts = json.dumps([{"hostPath": "/data/shared", "mountPath": "/mnt/data"}])
+with Sandbox.create(metadata={"hostdir-mount": mounts}) as sb:
+    result = sb.run_code("open('/mnt/data/hello.txt').read()")
+    print(result.text)
+```
+
+### List & health check
+
+```python
+from cubesandbox import Sandbox
+
+print(Sandbox.health())     # {"status": "ok", "sandboxes": 4}
+print(Sandbox.list())       # list of running sandbox dicts
+print(Sandbox.list_v2())    # v2 API (supports filtering)
+```
+
+## Configuration
+
+| Environment Variable | Required | Default | Description |
+|---|:---:|---|---|
+| `CUBE_API_URL` | ✅ | `http://127.0.0.1:3000` | CubeAPI management plane address |
+| `CUBE_TEMPLATE_ID` | ✅ | — | Template ID for sandbox creation |
+| `CUBE_PROXY_NODE_IP` | remote | — | CubeProxy node IP, bypasses DNS for `*.cube.app` |
+| `CUBE_PROXY_PORT_HTTP` | | `80` | CubeProxy HTTP port |
+| `CUBE_SANDBOX_DOMAIN` | | `cube.app` | Sandbox domain suffix |
+
+You can also pass a `Config` object directly:
+
+```python
+from cubesandbox import Config, Sandbox
+
+cfg = Config(
+    api_url="http://10.0.0.1:3000",
+    template_id="tpl-xxxxxxxxxxxxxxxxxxxxxxxx",
+    proxy_node_ip="10.0.0.1",
+)
+with Sandbox.create(config=cfg) as sb:
+    print(sb.run_code("2 ** 10").text)   # "1024"
+```
+
+## API Reference
+
+### `Sandbox` — class methods
+
+| Method | Description |
+|---|---|
+| `Sandbox.create(template, *, timeout, env_vars, metadata, config)` | `POST /sandboxes` — create a new sandbox |
+| `Sandbox.connect(sandbox_id, *, config)` | `POST /sandboxes/:id/connect` — connect (auto-resumes if paused) |
+| `Sandbox.list(config)` | `GET /sandboxes` — list running sandboxes (v1) |
+| `Sandbox.list_v2(config)` | `GET /v2/sandboxes` — list sandboxes (v2) |
+| `Sandbox.health(config)` | `GET /health` — service health check |
+
+### `Sandbox` — instance methods
+
+| Method | Description |
+|---|---|
+| `sb.run_code(code, *, on_stdout, on_stderr, on_result, on_error, envs, timeout)` | `POST /execute` — execute code, returns `Execution` |
+| `sb.get_info()` | `GET /sandboxes/:id` — get sandbox state and metadata |
+| `sb.get_info()` | `GET /sandboxes/:id` — get sandbox detail |
+| `sb.pause(*, wait, timeout, interval)` | `POST /sandboxes/:id/pause` — pause sandbox |
+| `sb.resume(timeout)` | `POST /sandboxes/:id/resume` — resume (deprecated, use `connect`) |
+| `sb.kill()` | `DELETE /sandboxes/:id` — destroy sandbox |
+| `sb.get_host(port)` | Return virtual hostname `{port}-{id}.{domain}` |
+
+### `Execution` object
+
+| Attribute | Type | Description |
+|---|---|---|
+| `.text` | `str \| None` | Final expression value (main result) |
+| `.logs.stdout` | `list[str]` | All stdout lines |
+| `.logs.stderr` | `list[str]` | All stderr lines |
+| `.error` | `ExecutionError \| None` | Exception info if execution failed |
+| `.results` | `list[Result]` | All result events |
+
+## Examples
+
+| Script | Description |
+|---|---|
+| `examples/create_and_run.py` | Create sandbox and run code |
+| `examples/context.py` | Kernel context (server-side not yet implemented) |
+| `examples/lifecycle.py` | Pause / connect / kill |
+| `examples/list_and_health.py` | List sandboxes and health check |
+| `examples/network_policy.py` | Network policy (deny-all / custom) |
+| `examples/volume.py` | Host-directory mount |
+| `examples/run_all.py` | Run all examples |
+
+## DNS Bypass (Remote Access)
+
+When running outside the CubeSandbox node, `*.cube.app` cannot be resolved by the OS DNS.
+Set `CUBE_PROXY_NODE_IP` to enable `IPOverrideTransport`: all data-plane connections are
+routed directly to that IP with the virtual `Host` header preserved for CubeProxy routing.
+
+```
+Without CUBE_PROXY_NODE_IP:
+  SDK → OS DNS (*.cube.app) → CubeProxy
+
+With CUBE_PROXY_NODE_IP:
+  SDK → TCP direct to CUBE_PROXY_NODE_IP:80
+        Host: 49999-{sandboxID}.cube.app (preserved for routing)
+```
+
+## License
+
+Apache-2.0 © 2026 Tencent Inc.

cubesandbox-0.1.0/cubesandbox/__init__.py

@@ -0,0 +1,24 @@
+# Copyright (c) 2026 Tencent Inc.
+# SPDX-License-Identifier: Apache-2.0
+
+from .sandbox import Sandbox
+from ._config import Config
+from ._models import Execution, Result, Logs, ExecutionError, OutputMessage
+from ._exceptions import CubeSandboxError, SandboxNotFoundError, ApiError
+from ._commands import CommandResult
+
+__all__ = [
+    "Sandbox",
+    "Config",
+    "Execution",
+    "Result",
+    "Logs",
+    "ExecutionError",
+    "OutputMessage",
+    "CubeSandboxError",
+    "SandboxNotFoundError",
+    "ApiError",
+    "CommandResult",
+]
+
+__version__ = "0.1.0"

cubesandbox-0.1.0/cubesandbox/_commands.py

@@ -0,0 +1,51 @@
+# Copyright (c) 2026 Tencent Inc.
+# SPDX-License-Identifier: Apache-2.0
+
+from __future__ import annotations
+from dataclasses import dataclass
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from .sandbox import Sandbox
+
+
+@dataclass
+class CommandResult:
+    stdout: str
+    stderr: str
+    exit_code: int
+
+
+class Commands:
+    def __init__(self, sandbox: "Sandbox") -> None:
+        self._sandbox = sandbox
+
+    def run(self, cmd: str, *, timeout: float | None = None, **kwargs) -> CommandResult:
+        """Run a shell command inside the sandbox via Python subprocess."""
+        code = (
+            "import subprocess as _sp\n"
+            f"_r = _sp.run({cmd!r}, shell=True, capture_output=True, text=True)\n"
+            "import sys as _sys\n"
+            "_sys.stdout.write(_r.stdout)\n"
+            "_sys.stderr.write(_r.stderr)\n"
+            "print(_r.returncode)\n"
+        )
+        stdout_lines: list[str] = []
+        execution = self._sandbox.run_code(
+            code,
+            timeout=timeout,
+            on_stdout=lambda m: stdout_lines.append(m.text),
+        )
+        # last stdout line is the exit code printed by the wrapper
+        all_stdout = "".join(stdout_lines)
+        lines = all_stdout.splitlines()
+        if lines and lines[-1].strip().lstrip("-").isdigit():
+            exit_code = int(lines[-1].strip())
+            stdout = "\n".join(lines[:-1])
+            if lines[:-1]:  # restore trailing newline if there was content
+                stdout += "\n"
+        else:
+            exit_code = 1 if execution.error else 0
+            stdout = all_stdout
+        stderr = "".join(execution.logs.stderr)
+        return CommandResult(stdout=stdout, stderr=stderr, exit_code=exit_code)

cubesandbox-0.1.0/cubesandbox/_config.py

@@ -0,0 +1,33 @@
+# Copyright (c) 2026 Tencent Inc.
+# SPDX-License-Identifier: Apache-2.0
+
+from __future__ import annotations
+
+import os
+from dataclasses import dataclass, field
+
+
+@dataclass
+class Config:
+    """SDK configuration. All fields can be set via environment variables."""
+
+    api_url: str = field(
+        default_factory=lambda: os.environ.get("CUBE_API_URL", "http://127.0.0.1:3000")
+    )
+    template_id: str | None = field(
+        default_factory=lambda: os.environ.get("CUBE_TEMPLATE_ID")
+    )
+    proxy_node_ip: str | None = field(
+        default_factory=lambda: os.environ.get("CUBE_PROXY_NODE_IP")
+    )
+    proxy_port: int = field(
+        default_factory=lambda: int(os.environ.get("CUBE_PROXY_PORT_HTTP", "80"))
+    )
+    sandbox_domain: str = field(
+        default_factory=lambda: os.environ.get("CUBE_SANDBOX_DOMAIN", "cube.app")
+    )
+    timeout: int = 300
+    request_timeout: float = 30.0
+
+    def __post_init__(self) -> None:
+        self.api_url = self.api_url.rstrip("/")

cubesandbox-0.1.0/cubesandbox/_exceptions.py

@@ -0,0 +1,16 @@
+# Copyright (c) 2026 Tencent Inc.
+# SPDX-License-Identifier: Apache-2.0
+
+from __future__ import annotations
+
+
+class CubeSandboxError(Exception):
+    def __init__(self, message: str, status_code: int | None = None):
+        super().__init__(message)
+        self.status_code = status_code
+
+
+class SandboxNotFoundError(CubeSandboxError): ...
+class TemplateNotFoundError(CubeSandboxError): ...
+class AuthenticationError(CubeSandboxError): ...
+class ApiError(CubeSandboxError): ...

cubesandbox-0.1.0/cubesandbox/_filesystem.py

@@ -0,0 +1,19 @@
+# Copyright (c) 2026 Tencent Inc.
+# SPDX-License-Identifier: Apache-2.0
+
+from __future__ import annotations
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from .sandbox import Sandbox
+
+
+class Filesystem:
+    def __init__(self, sandbox: "Sandbox") -> None:
+        self._sandbox = sandbox
+
+    def read(self, path: str) -> str:
+        result = self._sandbox.run_code(f"open({path!r}).read()")
+        if result.error:
+            raise IOError(f"Failed to read {path}: {result.error.value}")
+        return result.text or ""

cubesandbox-0.1.0/cubesandbox/_models.py

@@ -0,0 +1,62 @@
+# Copyright (c) 2026 Tencent Inc.
+# SPDX-License-Identifier: Apache-2.0
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import List, Optional
+
+
+@dataclass
+class Logs:
+    stdout: List[str] = field(default_factory=list)
+    stderr: List[str] = field(default_factory=list)
+
+
+@dataclass
+class ExecutionError:
+    name: str
+    value: str
+    traceback: List[str] = field(default_factory=list)
+
+
+@dataclass
+class Result:
+    text: Optional[str] = None
+    html: Optional[str] = None
+    markdown: Optional[str] = None
+    svg: Optional[str] = None
+    png: Optional[str] = None
+    jpeg: Optional[str] = None
+    pdf: Optional[str] = None
+    latex: Optional[str] = None
+    json_data: Optional[dict] = None
+    javascript: Optional[str] = None
+    is_main_result: bool = False
+    extra: Optional[dict] = None
+
+
+@dataclass
+class Execution:
+    results: List[Result] = field(default_factory=list)
+    logs: Logs = field(default_factory=Logs)
+    error: Optional[ExecutionError] = None
+    execution_count: Optional[int] = None
+
+    @property
+    def text(self) -> Optional[str]:
+        """Text of the main result (last expression value)."""
+        for r in self.results:
+            if r.is_main_result:
+                return r.text
+        return None
+
+    def __repr__(self) -> str:
+        return f"Execution(text={self.text!r}, error={self.error})"
+
+
+@dataclass
+class OutputMessage:
+    text: str
+    timestamp: str = ""
+    is_stderr: bool = False

cubesandbox-0.1.0/cubesandbox/_stream.py

@@ -0,0 +1,64 @@
+# Copyright (c) 2026 Tencent Inc.
+# SPDX-License-Identifier: Apache-2.0
+
+from __future__ import annotations
+
+import json
+import logging
+from typing import Callable, Optional
+
+from ._models import Execution, ExecutionError, OutputMessage, Result
+
+logger = logging.getLogger(__name__)
+
+
+def _parse_line(
+    execution: Execution,
+    line: str,
+    on_stdout: Optional[Callable[[OutputMessage], None]] = None,
+    on_stderr: Optional[Callable[[OutputMessage], None]] = None,
+    on_result: Optional[Callable[[Result], None]] = None,
+    on_error: Optional[Callable[[ExecutionError], None]] = None,
+) -> None:
+    if not line:
+        return
+    try:
+        data = json.loads(line)
+    except json.JSONDecodeError:
+        logger.debug("_parse_line: malformed JSON, skipping: %r", line)
+        return
+
+    event_type = data.pop("type", None)
+
+    if event_type == "result":
+        result = Result(**{k: v for k, v in data.items() if k in Result.__dataclass_fields__})
+        execution.results.append(result)
+        if on_result:
+            on_result(result)
+
+    elif event_type == "stdout":
+        text = data.get("text", "")
+        execution.logs.stdout.append(text)
+        if on_stdout:
+            on_stdout(OutputMessage(text, data.get("timestamp", "")))
+
+    elif event_type == "stderr":
+        text = data.get("text", "")
+        execution.logs.stderr.append(text)
+        if on_stderr:
+            on_stderr(OutputMessage(text, data.get("timestamp", ""), is_stderr=True))
+
+    elif event_type == "error":
+        execution.error = ExecutionError(
+            name=data.get("name", ""),
+            value=data.get("value", ""),
+            traceback=data.get("traceback", []),
+        )
+        if on_error:
+            on_error(execution.error)
+
+    elif event_type == "number_of_executions":
+        execution.execution_count = data.get("execution_count")
+
+    else:
+        logger.debug("_parse_line: unknown event type %r, skipping", event_type)

cubesandbox-0.1.0/cubesandbox/_transport.py

@@ -0,0 +1,56 @@
+# Copyright (c) 2026 Tencent Inc.
+# SPDX-License-Identifier: Apache-2.0
+
+from __future__ import annotations
+
+import ssl
+
+import httpx
+
+from ._config import Config
+
+
+class IPOverrideTransport(httpx.HTTPTransport):
+    """Routes all TCP connections to a fixed IP:port while preserving the Host header.
+
+    Equivalent to ``curl --resolve host:port:ip``.
+    Used when ``CUBE_PROXY_NODE_IP`` is set to bypass DNS resolution of ``*.cube.app``.
+    """
+
+    def __init__(self, ip: str, port: int, ssl_context: ssl.SSLContext | None = None, **kw):
+        super().__init__(verify=ssl_context or True, **kw)
+        self._ip = ip
+        self._port = port
+
+    def handle_request(self, request: httpx.Request) -> httpx.Response:
+        original_host = request.url.host
+        url = request.url.copy_with(host=self._ip, port=self._port)
+        proxied = httpx.Request(
+            method=request.method,
+            url=url,
+            headers=[
+                (k, original_host if k.lower() == "host" else v)
+                for k, v in request.headers.raw
+            ],
+            content=request.content,
+        )
+        return super().handle_request(proxied)
+
+
+def build_client(config: Config) -> httpx.Client:
+    """Build an httpx client for sandbox stream requests.
+
+    When ``config.proxy_node_ip`` is set, all connections are routed directly
+    to that IP, bypassing DNS. The ``Host`` header retains the virtual hostname
+    so CubeProxy can route to the correct sandbox.
+    """
+    if config.proxy_node_ip:
+        transport = IPOverrideTransport(config.proxy_node_ip, config.proxy_port)
+    else:
+        transport = httpx.HTTPTransport()
+
+    return httpx.Client(
+        transport=transport,
+        timeout=httpx.Timeout(connect=config.request_timeout, read=None, write=30, pool=30),
+        follow_redirects=True,
+    )