brimble-sandbox 0.1.0__tar.gz

brimble_sandbox-0.1.0/PKG-INFO

@@ -0,0 +1,104 @@
+Metadata-Version: 2.4
+Name: brimble-sandbox
+Version: 0.1.0
+Summary: Python SDK for the Brimble Sandbox API
+Author: Brimble Engineering
+License: MIT
+Project-URL: Homepage, https://brimble.io
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+Requires-Dist: requests>=2.31.0
+Provides-Extra: dev
+Requires-Dist: pytest>=8.3.0; extra == "dev"
+
+# brimble-sandbox
+
+Python SDK for the Brimble Sandbox API.
+
+## Install
+
+```bash
+pip install brimble-sandbox
+```
+
+## Quickstart
+
+```python
+from brimble_sandbox import SandboxClient
+
+client = SandboxClient()  # reads BRIMBLE_SANDBOX_KEY from env
+
+sandbox = client.sandboxes.create_ready(
+    {
+        "template": "node-22",
+        "persistent": True,
+        "persistentDiskGB": 20,
+    }
+)
+
+result = sandbox.exec({"cmd": "node -v"})
+print(result["stdout"])
+
+existing = client.sandboxes.get(sandbox.id)
+existing.destroy()
+```
+
+## Ergonomic helpers
+
+```python
+# Create + wait in one call
+created = client.sandboxes.create_ready({"template": "node-22"})
+
+# Get + wait in one call
+loaded = client.sandboxes.get_ready(created.id)
+
+# Create volume + attach at sandbox creation time
+with_volume = client.sandboxes.with_volume(
+    {
+        "sandbox": {"template": "node-22"},
+        "volume": {"name": "workspace-disk", "sizeGB": 20},
+    }
+)
+
+# Auto-wait on runtime calls
+with_volume.exec({"cmd": "npm -v"}, wait_until_ready=True)
+
+# Streaming SSE output
+stream = with_volume.exec_stream({"cmd": "for i in 1 2 3; do echo $i; done"})
+
+# Templates + regions
+templates = client.sandboxes.list_templates()
+node_template = client.sandboxes.get_template("node-22")
+regions = client.sandboxes.list_regions()
+
+# Iterate through all sandboxes
+for sb in client.sandboxes.iterate({"teamId": "<team>"}):
+    print(sb.id, sb.status)
+```
+
+Volume attachment is create-time only.
+Use `create(..., volumeId=...)` or `with_volume(...)`.
+
+## Auth
+
+Requests are authenticated with the `x-brimble-key` header.
+
+- Pass `api_key` to `SandboxClient(...)`
+- Or set `BRIMBLE_SANDBOX_KEY` in your environment
+
+## Retry, timeout, idempotency
+
+```python
+from brimble_sandbox import RetryOptions, SandboxClient
+
+client = SandboxClient(
+    retry=RetryOptions(max_attempts=3, base_delay_ms=250, max_delay_ms=2000),
+)
+
+sandbox = client.sandboxes.create(
+    {"template": "node-22"},
+    idempotency_key="create-sandbox-123",
+)
+```
+
+If `region` is omitted, the SDK resolves the first available sandbox region automatically.

brimble_sandbox-0.1.0/README.md

@@ -0,0 +1,91 @@
+# brimble-sandbox
+
+Python SDK for the Brimble Sandbox API.
+
+## Install
+
+```bash
+pip install brimble-sandbox
+```
+
+## Quickstart
+
+```python
+from brimble_sandbox import SandboxClient
+
+client = SandboxClient()  # reads BRIMBLE_SANDBOX_KEY from env
+
+sandbox = client.sandboxes.create_ready(
+    {
+        "template": "node-22",
+        "persistent": True,
+        "persistentDiskGB": 20,
+    }
+)
+
+result = sandbox.exec({"cmd": "node -v"})
+print(result["stdout"])
+
+existing = client.sandboxes.get(sandbox.id)
+existing.destroy()
+```
+
+## Ergonomic helpers
+
+```python
+# Create + wait in one call
+created = client.sandboxes.create_ready({"template": "node-22"})
+
+# Get + wait in one call
+loaded = client.sandboxes.get_ready(created.id)
+
+# Create volume + attach at sandbox creation time
+with_volume = client.sandboxes.with_volume(
+    {
+        "sandbox": {"template": "node-22"},
+        "volume": {"name": "workspace-disk", "sizeGB": 20},
+    }
+)
+
+# Auto-wait on runtime calls
+with_volume.exec({"cmd": "npm -v"}, wait_until_ready=True)
+
+# Streaming SSE output
+stream = with_volume.exec_stream({"cmd": "for i in 1 2 3; do echo $i; done"})
+
+# Templates + regions
+templates = client.sandboxes.list_templates()
+node_template = client.sandboxes.get_template("node-22")
+regions = client.sandboxes.list_regions()
+
+# Iterate through all sandboxes
+for sb in client.sandboxes.iterate({"teamId": "<team>"}):
+    print(sb.id, sb.status)
+```
+
+Volume attachment is create-time only.
+Use `create(..., volumeId=...)` or `with_volume(...)`.
+
+## Auth
+
+Requests are authenticated with the `x-brimble-key` header.
+
+- Pass `api_key` to `SandboxClient(...)`
+- Or set `BRIMBLE_SANDBOX_KEY` in your environment
+
+## Retry, timeout, idempotency
+
+```python
+from brimble_sandbox import RetryOptions, SandboxClient
+
+client = SandboxClient(
+    retry=RetryOptions(max_attempts=3, base_delay_ms=250, max_delay_ms=2000),
+)
+
+sandbox = client.sandboxes.create(
+    {"template": "node-22"},
+    idempotency_key="create-sandbox-123",
+)
+```
+
+If `region` is omitted, the SDK resolves the first available sandbox region automatically.

brimble_sandbox-0.1.0/brimble_sandbox/__init__.py

@@ -0,0 +1,74 @@
+"""Python SDK for Brimble Sandbox."""
+
+from .client import SandboxClient
+from .constants import (
+    DEFAULT_BASE_URL,
+    DEFAULT_PAGE,
+    DEFAULT_PAGE_LIMIT,
+    DEFAULT_RETRY_BASE_DELAY_MS,
+    DEFAULT_RETRY_MAX_ATTEMPTS,
+    DEFAULT_RETRY_MAX_DELAY_MS,
+    DEFAULT_RETRY_METHODS,
+    DEFAULT_RETRY_STATUSES,
+    DEFAULT_SANDBOX_READY_POLL_INTERVAL_MS,
+    DEFAULT_SANDBOX_READY_TIMEOUT_MS,
+    DEFAULT_TIMEOUT_MS,
+    MAX_PAGE_LIMIT,
+    MIN_VOLUME_SIZE_GB,
+    SANDBOX_API_KEY_ENV_NAME,
+)
+from .enums import CodeLanguage, DestroyReason, DestroyTimeout, SandboxStatus, SnapshotMode, SnapshotStatus, VolumeType
+from .errors import AuthError, NotFoundError, RateLimitError, SandboxApiError, ValidationError
+from .resources import (
+    ExecResource,
+    FilesResource,
+    SandboxHandle,
+    SandboxesResource,
+    ScopedSandboxResource,
+    SnapshotScopeResource,
+    SnapshotsResource,
+    StatsResource,
+    VolumesResource,
+)
+from .transport import RequestOptions, RetryOptions
+
+__all__ = [
+    "DEFAULT_BASE_URL",
+    "DEFAULT_PAGE",
+    "DEFAULT_PAGE_LIMIT",
+    "DEFAULT_RETRY_BASE_DELAY_MS",
+    "DEFAULT_RETRY_MAX_ATTEMPTS",
+    "DEFAULT_RETRY_MAX_DELAY_MS",
+    "DEFAULT_RETRY_METHODS",
+    "DEFAULT_RETRY_STATUSES",
+    "DEFAULT_SANDBOX_READY_POLL_INTERVAL_MS",
+    "DEFAULT_SANDBOX_READY_TIMEOUT_MS",
+    "DEFAULT_TIMEOUT_MS",
+    "MAX_PAGE_LIMIT",
+    "MIN_VOLUME_SIZE_GB",
+    "SANDBOX_API_KEY_ENV_NAME",
+    "CodeLanguage",
+    "DestroyReason",
+    "DestroyTimeout",
+    "SandboxStatus",
+    "SnapshotMode",
+    "SnapshotStatus",
+    "VolumeType",
+    "SandboxApiError",
+    "AuthError",
+    "ValidationError",
+    "NotFoundError",
+    "RateLimitError",
+    "RetryOptions",
+    "RequestOptions",
+    "SandboxClient",
+    "ExecResource",
+    "FilesResource",
+    "SandboxHandle",
+    "SandboxesResource",
+    "ScopedSandboxResource",
+    "SnapshotScopeResource",
+    "SnapshotsResource",
+    "StatsResource",
+    "VolumesResource",
+]

brimble_sandbox-0.1.0/brimble_sandbox/client.py

@@ -0,0 +1,43 @@
+"""Top-level Sandbox client."""
+
+from __future__ import annotations
+
+import os
+
+import requests
+
+from .constants import DEFAULT_BASE_URL, DEFAULT_TIMEOUT_MS, SANDBOX_API_KEY_ENV_NAME
+from .resources import SandboxesResource, SnapshotsResource, VolumesResource
+from .transport import HttpTransport, RetryOptions
+
+
+class SandboxClient:
+    """Entry-point client for Brimble Sandbox API resources."""
+
+    def __init__(
+        self,
+        *,
+        api_key: str | None = None,
+        base_url: str = DEFAULT_BASE_URL,
+        timeout_ms: int = DEFAULT_TIMEOUT_MS,
+        retry: RetryOptions | None = None,
+        session: requests.Session | None = None,
+    ) -> None:
+        """Create a client from explicit key or BRIMBLE_SANDBOX_KEY env variable."""
+        resolved_api_key = api_key or os.getenv(SANDBOX_API_KEY_ENV_NAME)
+        if not resolved_api_key:
+            raise ValueError(
+                f"Sandbox API key is required. Pass api_key explicitly or set {SANDBOX_API_KEY_ENV_NAME}."
+            )
+
+        transport = HttpTransport(
+            base_url=base_url,
+            api_key=resolved_api_key,
+            timeout_ms=timeout_ms,
+            retry=retry,
+            session=session,
+        )
+
+        self.sandboxes = SandboxesResource(transport)
+        self.snapshots = SnapshotsResource(transport)
+        self.volumes = VolumesResource(transport)

brimble_sandbox-0.1.0/brimble_sandbox/constants.py

@@ -0,0 +1,25 @@
+"""Shared SDK constants."""
+
+from importlib.metadata import PackageNotFoundError, version
+
+DEFAULT_BASE_URL = "https://sandbox.brimble.io"
+DEFAULT_TIMEOUT_MS = 30_000
+SANDBOX_API_KEY_ENV_NAME = "BRIMBLE_SANDBOX_KEY"
+
+try:
+    SDK_PACKAGE_VERSION = version("brimble-sandbox")
+except PackageNotFoundError:
+    SDK_PACKAGE_VERSION = "0.1.0"
+
+DEFAULT_PAGE = 1
+DEFAULT_PAGE_LIMIT = 15
+MAX_PAGE_LIMIT = 100
+MIN_VOLUME_SIZE_GB = 10
+DEFAULT_SANDBOX_READY_TIMEOUT_MS = 60_000
+DEFAULT_SANDBOX_READY_POLL_INTERVAL_MS = 2_000
+
+DEFAULT_RETRY_MAX_ATTEMPTS = 1
+DEFAULT_RETRY_BASE_DELAY_MS = 300
+DEFAULT_RETRY_MAX_DELAY_MS = 3_000
+DEFAULT_RETRY_STATUSES = (408, 429, 500, 502, 503, 504)
+DEFAULT_RETRY_METHODS = ("GET", "DELETE", "PUT")

brimble_sandbox-0.1.0/brimble_sandbox/enums.py

@@ -0,0 +1,51 @@
+"""Enum values used by the Sandbox SDK."""
+
+from enum import StrEnum
+
+
+class CodeLanguage(StrEnum):
+    PYTHON = "python"
+    NODE = "node"
+
+
+class DestroyReason(StrEnum):
+    USER = "user"
+    IDLE_TTL = "idle_ttl"
+    MAX_LIFETIME = "max_lifetime"
+    ONE_SHOT_STOPPED = "one_shot_stopped"
+    FAILED = "failed"
+    PAUSED_TOO_LONG = "paused_too_long"
+
+
+class DestroyTimeout(StrEnum):
+    THIRTY_MINUTES = "30m"
+    ONE_HOUR = "1h"
+    THREE_HOURS = "3h"
+    SIX_HOURS = "6h"
+    TWELVE_HOURS = "12h"
+    EIGHTEEN_HOURS = "18h"
+
+
+class SandboxStatus(StrEnum):
+    STARTING = "starting"
+    READY = "ready"
+    PAUSING = "pausing"
+    PAUSED = "paused"
+    RESUMING = "resuming"
+    FAILED = "failed"
+    DESTROYED = "destroyed"
+
+
+class SnapshotMode(StrEnum):
+    MANUAL = "manual"
+    AUTOMATIC = "automatic"
+
+
+class SnapshotStatus(StrEnum):
+    CREATING = "creating"
+    READY = "ready"
+    FAILED = "failed"
+
+
+class VolumeType(StrEnum):
+    SANDBOX = "sandbox"

brimble_sandbox-0.1.0/brimble_sandbox/errors.py

@@ -0,0 +1,42 @@
+"""SDK error types."""
+
+from __future__ import annotations
+
+
+class SandboxApiError(Exception):
+    """Raised when the Sandbox API returns a non-2xx HTTP response."""
+
+    def __init__(self, status: int, message: str, endpoint: str, response_body: object, request_id: str | None = None) -> None:
+        super().__init__(message)
+        self.status = status
+        self.endpoint = endpoint
+        self.response_body = response_body
+        self.request_id = request_id
+
+
+class AuthError(SandboxApiError):
+    """Raised when credentials are missing/invalid or access is denied."""
+
+
+class ValidationError(SandboxApiError):
+    """Raised when request payload/state fails validation."""
+
+
+class NotFoundError(SandboxApiError):
+    """Raised when a requested sandbox/volume/snapshot was not found."""
+
+
+class RateLimitError(SandboxApiError):
+    """Raised on 429 responses with optional retry-after guidance."""
+
+    def __init__(
+        self,
+        status: int,
+        message: str,
+        endpoint: str,
+        response_body: object,
+        request_id: str | None = None,
+        retry_after_seconds: float | None = None,
+    ) -> None:
+        super().__init__(status, message, endpoint, response_body, request_id)
+        self.retry_after_seconds = retry_after_seconds

brimble_sandbox-0.1.0/brimble_sandbox/resources/__init__.py

@@ -0,0 +1,22 @@
+"""Public resource exports."""
+
+from .exec import ExecResource
+from .files import FilesResource
+from .sandbox_handle import SandboxHandle
+from .sandboxes import SandboxesResource
+from .scoped_sandbox import ScopedSandboxResource
+from .snapshots import SnapshotScopeResource, SnapshotsResource
+from .stats import StatsResource
+from .volumes import VolumesResource
+
+__all__ = [
+    "ExecResource",
+    "FilesResource",
+    "SandboxHandle",
+    "SandboxesResource",
+    "ScopedSandboxResource",
+    "SnapshotScopeResource",
+    "SnapshotsResource",
+    "StatsResource",
+    "VolumesResource",
+]

brimble_sandbox-0.1.0/brimble_sandbox/resources/exec.py

@@ -0,0 +1,106 @@
+"""Sandbox exec/code operations."""
+
+from __future__ import annotations
+
+import requests
+
+from ..transport import HttpTransport, RequestOptions, RetryOptions
+from ..types import CodeInput, ExecInput, ExecResult
+
+
+class ExecResource:
+    """Run shell commands or code snippets in one sandbox."""
+
+    def __init__(self, transport: HttpTransport, sandbox_id: str) -> None:
+        self._transport = transport
+        self._sandbox_id = sandbox_id
+
+    def exec(
+        self,
+        input: ExecInput,
+        *,
+        timeout_ms: int | None = None,
+        idempotency_key: str | None = None,
+        retry: RetryOptions | bool | None = None,
+    ) -> ExecResult | requests.Response:
+        """Run a shell command in the sandbox."""
+        options = RequestOptions(timeout_ms=timeout_ms, idempotency_key=idempotency_key, retry=retry)
+
+        if input.get("stream") is True:
+            return self._transport.request_sse(
+                endpoint=f"/sandboxes/{self._sandbox_id}/exec",
+                method="POST",
+                body=input,
+                options=options,
+            )
+
+        return self._transport.request_json(
+            endpoint=f"/sandboxes/{self._sandbox_id}/exec",
+            method="POST",
+            body=input,
+            options=options,
+        )
+
+    def run_code(
+        self,
+        input: CodeInput,
+        *,
+        timeout_ms: int | None = None,
+        idempotency_key: str | None = None,
+        retry: RetryOptions | bool | None = None,
+    ) -> ExecResult | requests.Response:
+        """Run a code snippet in the sandbox."""
+        options = RequestOptions(timeout_ms=timeout_ms, idempotency_key=idempotency_key, retry=retry)
+
+        if input.get("stream") is True:
+            return self._transport.request_sse(
+                endpoint=f"/sandboxes/{self._sandbox_id}/code",
+                method="POST",
+                body=input,
+                options=options,
+            )
+
+        return self._transport.request_json(
+            endpoint=f"/sandboxes/{self._sandbox_id}/code",
+            method="POST",
+            body=input,
+            options=options,
+        )
+
+    def exec_stream(
+        self,
+        input: ExecInput,
+        *,
+        timeout_ms: int | None = None,
+        idempotency_key: str | None = None,
+        retry: RetryOptions | bool | None = None,
+    ) -> requests.Response:
+        """Run a shell command and stream SSE output frames."""
+        payload = dict(input)
+        payload["stream"] = True
+        options = RequestOptions(timeout_ms=timeout_ms, idempotency_key=idempotency_key, retry=retry)
+        return self._transport.request_sse(
+            endpoint=f"/sandboxes/{self._sandbox_id}/exec",
+            method="POST",
+            body=payload,
+            options=options,
+        )
+
+    def run_code_stream(
+        self,
+        input: CodeInput,
+        *,
+        timeout_ms: int | None = None,
+        idempotency_key: str | None = None,
+        retry: RetryOptions | bool | None = None,
+    ) -> requests.Response:
+        """Run a code snippet and stream SSE output frames."""
+        payload = dict(input)
+        payload["stream"] = True
+        options = RequestOptions(timeout_ms=timeout_ms, idempotency_key=idempotency_key, retry=retry)
+        return self._transport.request_sse(
+            endpoint=f"/sandboxes/{self._sandbox_id}/code",
+            method="POST",
+            body=payload,
+            options=options,
+        )

brimble_sandbox-0.1.0/brimble_sandbox/resources/files.py

@@ -0,0 +1,58 @@
+"""Sandbox file upload/download operations."""
+
+from __future__ import annotations
+
+import requests
+
+from ..transport import HttpTransport, RequestOptions, RetryOptions
+from ..types import FileUploadBody
+from .path import encode_file_path
+
+
+class FilesResource:
+    """Upload and download files for one sandbox."""
+
+    def __init__(self, transport: HttpTransport, sandbox_id: str) -> None:
+        self._transport = transport
+        self._sandbox_id = sandbox_id
+
+    def put(
+        self,
+        path: str,
+        body: FileUploadBody,
+        *,
+        timeout_ms: int | None = None,
+        idempotency_key: str | None = None,
+        retry: RetryOptions | bool | None = None,
+    ) -> None:
+        """Upload bytes to a path inside the sandbox."""
+        headers: dict[str, str] = {
+            "content-type": "application/octet-stream",
+        }
+
+        if isinstance(body, (bytes, bytearray)):
+            headers["content-length"] = str(len(body))
+
+        options = RequestOptions(timeout_ms=timeout_ms, idempotency_key=idempotency_key, retry=retry)
+        self._transport.request_binary(
+            endpoint=f"/sandboxes/{self._sandbox_id}/files/{encode_file_path(path)}",
+            method="PUT",
+            body=body,
+            headers=headers,
+            options=options,
+        )
+
+    def get(
+        self,
+        path: str,
+        *,
+        timeout_ms: int | None = None,
+        retry: RetryOptions | bool | None = None,
+    ) -> requests.Response:
+        """Download a file from the sandbox as a streamed response."""
+        options = RequestOptions(timeout_ms=timeout_ms, retry=retry)
+        return self._transport.request_stream(
+            endpoint=f"/sandboxes/{self._sandbox_id}/files/{encode_file_path(path)}",
+            method="GET",
+            options=options,
+        )

brimble_sandbox-0.1.0/brimble_sandbox/resources/path.py

@@ -0,0 +1,13 @@
+"""Path helpers for file endpoints."""
+
+from urllib.parse import quote
+
+
+def encode_path_segment(value: str) -> str:
+    """Encode one path segment for URL use."""
+    return quote(value, safe="")
+
+
+def encode_file_path(path: str) -> str:
+    """Encode a file path while preserving slash separators."""
+    return "/".join(encode_path_segment(segment) for segment in path.split("/") if segment)