together-sandbox 1.11.0__tar.gz

together_sandbox-1.11.0/.gitignore

@@ -0,0 +1,43 @@
+# Generated code
+together-sandbox-typescript/src/api-clients
+together-sandbox-cli/src/api-clients
+
+# Node
+node_modules/
+npm-debug.log*
+test-template
+
+# TypeScript SDK build output
+together-sandbox-typescript/dist/
+
+# CLI build output (esbuild bundle + compiled binaries)
+together-sandbox-cli/dist/
+
+# Python
+__pycache__/
+*.py[cod]
+*.egg-info/
+.eggs/
+dist/
+build/
+.venv/
+venv/
+*.pth
+
+# static docs
+api-docs/*.json
+
+# Python generation temp dirs
+together-sandbox-python/.tmp-api/
+together-sandbox-python/.tmp-sandbox/
+
+# Test scripts
+together-sandbox-typescript/test.ts
+together-sandbox-python/test.py
+
+# OS
+.DS_Store
+
+# Local env files
+.env
+.env.local

together_sandbox-1.11.0/CLAUDE.md

@@ -0,0 +1,176 @@
+# Python SDK — Developer Guide
+
+Package: `together-sandbox` (PyPI)
+
+## File layout
+
+```
+together_sandbox/
+├── __init__.py         # Public re-exports — keep in sync with facade.py exports
+├── facade.py           # ← hand-written facade (the only file to edit)
+├── _streaming.py       # SSE streaming helpers — hand-written
+├── api/                # Generated — management API client (openapi-python-client)
+└── sandbox/            # Generated — in-VM sandbox API client (openapi-python-client)
+```
+
+**Only `facade.py`, `_streaming.py`, and `__init__.py` are hand-edited.**
+Everything inside `api/` and `sandbox/` is regenerated by `bash generate.sh`
+(run from the repo root) and must not be modified directly.
+
+## Facade patterns
+
+### Always `from __future__ import annotations`
+
+Every facade Python file must start with `from __future__ import annotations`.
+This enables PEP 563 deferred evaluation so modern union syntax works on all
+supported Python versions (≥3.10).
+
+### Modern type annotation style
+
+Use `X | None` instead of `Optional[X]`, and `list[X]` instead of `List[X]`.
+Do **not** import `Optional` or `List` from `typing`.
+
+```python
+# ✅ correct
+def watch(self, path: str, recursive: bool | None = None) -> AsyncIterator[dict[str, Any]]: ...
+
+# ❌ wrong — legacy typing imports
+from typing import Optional, List
+def watch(self, path: str, recursive: Optional[bool] = None) -> AsyncIterator[List[dict]]: ...
+```
+
+### All method names must be snake_case
+
+Python method names follow PEP 8. Do not use camelCase even if the equivalent
+TypeScript method is camelCase.
+
+```python
+# ✅ correct
+async def list_setup(self) -> list[...]: ...
+
+# ❌ wrong — camelCase in Python
+async def listSetup(self) -> list[...]: ...
+```
+
+### Always return unwrapped data
+
+Facade methods return the actual payload value, not the raw response object:
+
+```python
+# ✅ correct
+result = await read_file_api(path, client=self._client)
+return result.content
+
+# ❌ wrong — returns the full response object
+return result
+```
+
+### Use typed models for API request bodies
+
+Never pass raw `dict` literals as request bodies. Use the typed models
+generated in the `api/` and `sandbox/` packages.
+
+```python
+# ✅ correct (when a typed body model exists)
+await stop_sandbox_api(sandbox_id, client=self._api_client,
+                       body=StopSandboxBody(stop_type="hibernate"))
+
+# ❌ wrong — raw dict
+await stop_sandbox_api(sandbox_id, client=self._api_client,
+                       body={"stop_type": "hibernate"})
+```
+
+### File uploads use `File(payload=io.BytesIO(bytes))` only
+
+String content must be encoded to bytes before wrapping in a `File` object.
+Never pass raw strings to `create_file_api`.
+
+```python
+if isinstance(content, str):
+    content_bytes = content.encode("utf-8")
+else:
+    content_bytes = content
+file_obj = File(payload=io.BytesIO(content_bytes))
+```
+
+Import `io` at the **top of the module**, not inside the method body.
+
+### Do not use `assert` for runtime type checking
+
+`assert` statements are stripped in optimised Python (`python -O`). Raise
+explicit exceptions instead.
+
+```python
+# ✅ correct
+result = await get_exec_api(id_, client=self._client)
+if result is None:
+    raise RuntimeError(f"getExec returned None for id {id_!r}")
+return result
+
+# ❌ wrong
+result = await get_exec_api(id_, client=self._client)
+assert result is not None
+return result
+```
+
+### Async context manager support
+
+Both `TogetherSandbox` and `Sandbox` must support `async with`. The context
+manager closes the HTTP client connection but does **not** shut down the VM —
+callers must call `.shutdown()` explicitly.
+
+### Always unwrap API responses with `_unwrap_or_raise`
+
+Every call to a generated API endpoint function must have its return value
+checked through `_unwrap_or_raise` — never check `None`/`Error` inline.
+Import the helper from `._utils`, not from `._sandbox`.
+
+Even void-returning endpoints (delete, stop, alias) must capture and unwrap
+their result — the generated clients can return an `Error` model on failure.
+
+```python
+# ✅ correct
+_unwrap_or_raise(
+    await delete_snapshot_api(UUID(id), client=self._api_client),
+    op="deleteSnapshot",
+    context=f"for id {id!r}"
+)
+
+# ❌ wrong — inline check, misses Error model, inconsistent
+result = await delete_snapshot_api(UUID(id), client=self._api_client)
+if result is None:
+    raise RuntimeError("deleteSnapshot returned None")
+```
+
+### Section dividers
+
+Use the established ASCII box-drawing style:
+
+```python
+# ─── Section Name ─────────────────────────────────────────────────────────────
+```
+
+## Build and test
+
+```bash
+# From repo root — regenerate generated clients first
+bash generate.sh
+
+# Install package with dev extras
+cd together-sandbox-python
+pip install ".[dev]"
+
+# Run tests
+pytest tests/ -v
+```
+
+## Testing conventions
+
+- Tests live in `together-sandbox-python/tests/`.
+- Use `pytest` with `asyncio_mode = "auto"` (set in `pyproject.toml`).
+- Use `unittest.mock.AsyncMock` + `patch` for API call mocking.
+- Use class-based test organisation (`class TestFoo:`).
+- The `_make_sandbox_model(**overrides)` helper pattern (see `test_facade.py`)
+  should be used to build minimal valid fixture `SandboxModel` mocks.
+- Mirror the TypeScript SDK's test coverage: verify namespace delegation,
+  renamed/removed methods, public API surface, and factory classmethods.

together_sandbox-1.11.0/PKG-INFO

@@ -0,0 +1,227 @@
+Metadata-Version: 2.4
+Name: together-sandbox
+Version: 1.11.0
+Summary: Together Sandbox Python SDK
+License: MIT
+Requires-Python: >=3.10
+Requires-Dist: attrs>=23.0.0
+Requires-Dist: cattrs>=23.0.0
+Requires-Dist: httpx-sse>=0.4.0
+Requires-Dist: httpx>=0.20.0
+Requires-Dist: pathspec>=0.11.0
+Requires-Dist: python-dateutil>=2.8.0
+Provides-Extra: dev
+Requires-Dist: openapi-python-client>=0.28.0; extra == 'dev'
+Requires-Dist: pytest-asyncio>=0.21.0; extra == 'dev'
+Requires-Dist: pytest-timeout>=2.0.0; extra == 'dev'
+Requires-Dist: pytest>=7.0.0; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# together-sandbox (Python)
+
+Developer guide for the `together-sandbox` Python SDK.
+
+[SDK Docs](../docs/python-sdk.md)
+
+> **Note:** The generated OpenAPI clients (`together_sandbox/api/` and
+> `together_sandbox/sandbox/`) are committed to the repository temporarily until
+> the package is published to PyPI. Once published they will be removed from
+> version control and regenerated as part of the install/build step instead.
+
+## Generating the OpenAPI clients
+
+The SDK wraps two auto-generated OpenAPI clients. Regenerate them whenever an
+OpenAPI spec changes (both specs live in the repo root):
+
+```bash
+# From the repo root
+bash generate.sh
+```
+
+This runs `together-sandbox-python/generate.sh` which invokes
+`openapi-python-client` against `api-openapi.json` and `sandbox-openapi.json`
+and writes the output to:
+
+- `together_sandbox/api/` — management API client
+- `together_sandbox/sandbox/` — in-VM sandbox API client
+
+**Never edit those directories by hand** — they are overwritten on every run.
+
+## Tests
+
+## Prerequisites
+
+1. Together AI API key
+2. Python 3.10 or higher
+3. Install dev dependencies:
+
+```bash
+cd together-sandbox-python
+pip install .[dev]
+```
+
+4. Set up a virtual environment (optional but recommended):
+
+```bash
+python -m venv .venv
+source .venv/bin/activate  # On Windows: .venv\Scripts\activate
+```
+
+5. Create a snapshot to run the tests with
+
+```bash
+node ./together-sandbox-cli/dist/together-sandbox.mjs snapshots create --context ./test-template
+```
+
+## Environment Variables
+
+Set the following environment variables before running e2e tests:
+
+```bash
+# Required
+export TOGETHER_API_KEY="your-api-key-here"
+
+# Optional
+export TOGETHER_SNAPSHOT_ID="snapshot-id"  # If you want to test with a specific snapshot
+export TOGETHER_BASE_URL="https://api.codesandbox.io"  # Override default base URL
+```
+
+## Running Tests
+
+**Note:** All `pytest` commands must be run from the `together-sandbox-python/` directory.
+
+### Unit tests
+
+```bash
+pytest tests/ -v
+```
+
+### Run all e2e tests
+
+```bash
+pytest tests/e2e/ -v
+```
+
+### Run specific e2e test file
+
+```bash
+pytest tests/e2e/test_sandbox_filesystem.py -v
+```
+
+### Run specific test class or function
+
+```bash
+# Run a specific test class
+pytest tests/e2e/test_sandbox_filesystem.py::TestSandboxFilesystem -v
+
+# Run a specific test function
+pytest tests/e2e/test_sandbox_filesystem.py::TestSandboxFilesystem::test_write_and_read_text_file -v
+```
+
+### Run with output from print statements
+
+```bash
+pytest tests/e2e/ -v -s
+```
+
+## Test Structure
+
+### Fixtures (e2e/helpers.py)
+
+The `helpers.py` module provides pytest fixtures that handle sandbox lifecycle:
+
+- `sdk`: Provides a configured `TogetherSandbox` instance
+- `sandbox`: Creates a sandbox instance and automatically cleans it up after tests
+- `retry_until`: Helper function for polling operations
+
+Example usage in tests:
+
+```python
+@pytest.mark.asyncio
+async def test_something(sandbox: Sandbox):
+    # sandbox is automatically created and will be cleaned up
+    await sandbox.files.create_file("/test.txt", "content")
+    result = await sandbox.files.read_file("/test.txt")
+    assert result.content == "content"
+```
+
+## Test Patterns
+
+### Using the sandbox fixture
+
+Most tests should use the `sandbox` fixture which handles creation and cleanup:
+
+```python
+async def test_my_feature(sandbox: Sandbox):
+    # Your test code here
+    # Sandbox will be automatically cleaned up
+    pass
+```
+
+### Manual sandbox management
+
+For lifecycle tests that need explicit control:
+
+```python
+async def test_lifecycle():
+    sdk = TogetherSandbox(api_key=get_api_key())
+    try:
+        sandbox = await sdk.sandboxes.start(template_id)
+        # Test code
+    finally:
+        await sdk.sandboxes.shutdown(sandbox.id)
+        await sdk.close()
+```
+
+### Retry polling pattern
+
+For operations that may take time:
+
+```python
+from .helpers import retry_until
+
+result = await retry_until(
+    lambda: sandbox.files.read_file("/path"),
+    lambda r: r.content == "expected",
+    timeout=5.0,
+    interval=0.1
+)
+```
+
+## Notes
+
+- E2E tests connect to real sandbox instances and may incur API costs
+- Tests automatically clean up sandboxes, but interrupted tests may leave orphaned sandboxes
+- Some exec tests are placeholders and may need implementation based on the actual API structure
+- Binary file tests verify the application/octet-stream content type handling
+- Timeout for sandbox cleanup is set to 10 seconds to prevent hanging
+
+## Troubleshooting
+
+### Tests skip with "TOGETHER_API_KEY environment variable not set"
+
+Make sure you've exported the `TOGETHER_API_KEY` environment variable:
+
+```bash
+export TOGETHER_API_KEY="your-api-key"
+```
+
+### Tests fail with timeout errors
+
+The sandbox may be taking longer to start or respond. You can:
+
+1. Check your network connection
+2. Verify the API service status
+3. Increase timeout values in the tests if needed
+
+### Tests fail with authentication errors
+
+Verify your API key is valid and has the necessary permissions for:
+
+- Creating sandboxes
+- Reading/writing files
+- Managing sandbox lifecycle
+
+### Orphaned sandboxes
+
+If tests are interrupted, sandboxes may not be cleaned up. You can manually delete them using the API or wait for automatic cleanup policies.

together_sandbox-1.11.0/README.md

@@ -0,0 +1,208 @@
+# together-sandbox (Python)
+
+Developer guide for the `together-sandbox` Python SDK.
+
+[SDK Docs](../docs/python-sdk.md)
+
+> **Note:** The generated OpenAPI clients (`together_sandbox/api/` and
+> `together_sandbox/sandbox/`) are committed to the repository temporarily until
+> the package is published to PyPI. Once published they will be removed from
+> version control and regenerated as part of the install/build step instead.
+
+## Generating the OpenAPI clients
+
+The SDK wraps two auto-generated OpenAPI clients. Regenerate them whenever an
+OpenAPI spec changes (both specs live in the repo root):
+
+```bash
+# From the repo root
+bash generate.sh
+```
+
+This runs `together-sandbox-python/generate.sh` which invokes
+`openapi-python-client` against `api-openapi.json` and `sandbox-openapi.json`
+and writes the output to:
+
+- `together_sandbox/api/` — management API client
+- `together_sandbox/sandbox/` — in-VM sandbox API client
+
+**Never edit those directories by hand** — they are overwritten on every run.
+
+## Tests
+
+## Prerequisites
+
+1. Together AI API key
+2. Python 3.10 or higher
+3. Install dev dependencies:
+
+```bash
+cd together-sandbox-python
+pip install .[dev]
+```
+
+4. Set up a virtual environment (optional but recommended):
+
+```bash
+python -m venv .venv
+source .venv/bin/activate  # On Windows: .venv\Scripts\activate
+```
+
+5. Create a snapshot to run the tests with
+
+```bash
+node ./together-sandbox-cli/dist/together-sandbox.mjs snapshots create --context ./test-template
+```
+
+## Environment Variables
+
+Set the following environment variables before running e2e tests:
+
+```bash
+# Required
+export TOGETHER_API_KEY="your-api-key-here"
+
+# Optional
+export TOGETHER_SNAPSHOT_ID="snapshot-id"  # If you want to test with a specific snapshot
+export TOGETHER_BASE_URL="https://api.codesandbox.io"  # Override default base URL
+```
+
+## Running Tests
+
+**Note:** All `pytest` commands must be run from the `together-sandbox-python/` directory.
+
+### Unit tests
+
+```bash
+pytest tests/ -v
+```
+
+### Run all e2e tests
+
+```bash
+pytest tests/e2e/ -v
+```
+
+### Run specific e2e test file
+
+```bash
+pytest tests/e2e/test_sandbox_filesystem.py -v
+```
+
+### Run specific test class or function
+
+```bash
+# Run a specific test class
+pytest tests/e2e/test_sandbox_filesystem.py::TestSandboxFilesystem -v
+
+# Run a specific test function
+pytest tests/e2e/test_sandbox_filesystem.py::TestSandboxFilesystem::test_write_and_read_text_file -v
+```
+
+### Run with output from print statements
+
+```bash
+pytest tests/e2e/ -v -s
+```
+
+## Test Structure
+
+### Fixtures (e2e/helpers.py)
+
+The `helpers.py` module provides pytest fixtures that handle sandbox lifecycle:
+
+- `sdk`: Provides a configured `TogetherSandbox` instance
+- `sandbox`: Creates a sandbox instance and automatically cleans it up after tests
+- `retry_until`: Helper function for polling operations
+
+Example usage in tests:
+
+```python
+@pytest.mark.asyncio
+async def test_something(sandbox: Sandbox):
+    # sandbox is automatically created and will be cleaned up
+    await sandbox.files.create_file("/test.txt", "content")
+    result = await sandbox.files.read_file("/test.txt")
+    assert result.content == "content"
+```
+
+## Test Patterns
+
+### Using the sandbox fixture
+
+Most tests should use the `sandbox` fixture which handles creation and cleanup:
+
+```python
+async def test_my_feature(sandbox: Sandbox):
+    # Your test code here
+    # Sandbox will be automatically cleaned up
+    pass
+```
+
+### Manual sandbox management
+
+For lifecycle tests that need explicit control:
+
+```python
+async def test_lifecycle():
+    sdk = TogetherSandbox(api_key=get_api_key())
+    try:
+        sandbox = await sdk.sandboxes.start(template_id)
+        # Test code
+    finally:
+        await sdk.sandboxes.shutdown(sandbox.id)
+        await sdk.close()
+```
+
+### Retry polling pattern
+
+For operations that may take time:
+
+```python
+from .helpers import retry_until
+
+result = await retry_until(
+    lambda: sandbox.files.read_file("/path"),
+    lambda r: r.content == "expected",
+    timeout=5.0,
+    interval=0.1
+)
+```
+
+## Notes
+
+- E2E tests connect to real sandbox instances and may incur API costs
+- Tests automatically clean up sandboxes, but interrupted tests may leave orphaned sandboxes
+- Some exec tests are placeholders and may need implementation based on the actual API structure
+- Binary file tests verify the application/octet-stream content type handling
+- Timeout for sandbox cleanup is set to 10 seconds to prevent hanging
+
+## Troubleshooting
+
+### Tests skip with "TOGETHER_API_KEY environment variable not set"
+
+Make sure you've exported the `TOGETHER_API_KEY` environment variable:
+
+```bash
+export TOGETHER_API_KEY="your-api-key"
+```
+
+### Tests fail with timeout errors
+
+The sandbox may be taking longer to start or respond. You can:
+
+1. Check your network connection
+2. Verify the API service status
+3. Increase timeout values in the tests if needed
+
+### Tests fail with authentication errors
+
+Verify your API key is valid and has the necessary permissions for:
+
+- Creating sandboxes
+- Reading/writing files
+- Managing sandbox lifecycle
+
+### Orphaned sandboxes
+
+If tests are interrupted, sandboxes may not be cleaned up. You can manually delete them using the API or wait for automatic cleanup policies.

together_sandbox-1.11.0/generate.sh

@@ -0,0 +1,25 @@
+#!/usr/bin/env bash
+# Regenerate both OpenAPI clients from the specs in the parent directory.
+# Run from the repo root: bash together-sandbox-python/generate.sh
+set -e
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+REPO_ROOT="$(dirname "$SCRIPT_DIR")"
+
+mkdir -p "$SCRIPT_DIR/together_sandbox"
+
+echo "Generating API client from api-openapi.json..."
+python3 -m openapi_python_client generate \
+  --path "$REPO_ROOT/api-openapi.json" \
+  --meta none \
+  --output-path "$SCRIPT_DIR/together_sandbox/api" \
+  --overwrite
+
+echo "Generating Sandbox client from sandbox-openapi.json..."
+python3 -m openapi_python_client generate \
+  --path "$REPO_ROOT/sandbox-openapi.json" \
+  --meta none \
+  --output-path "$SCRIPT_DIR/together_sandbox/sandbox" \
+  --overwrite
+
+echo "Done. Both clients available via: from together_sandbox import ApiClient, SandboxClient"

together_sandbox-1.11.0/pyproject.toml

@@ -0,0 +1,35 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "together-sandbox"
+version = "1.11.0"
+description = "Together Sandbox Python SDK"
+readme = "README.md"
+requires-python = ">=3.10"
+dependencies = [
+    "httpx>=0.20.0",
+    "httpx-sse>=0.4.0",
+    "cattrs>=23.0.0",
+    "attrs>=23.0.0",
+    "python-dateutil>=2.8.0",
+    "pathspec>=0.11.0",
+]
+license = { text = "MIT" }
+
+[project.optional-dependencies]
+dev = [
+    "openapi-python-client>=0.28.0",
+    "pytest>=7.0.0",
+    "pytest-asyncio>=0.21.0",
+    "pytest-timeout>=2.0.0",
+]
+
+[tool.hatch.build.targets.wheel]
+packages = ["together_sandbox"]
+
+[tool.pytest.ini_options]
+asyncio_mode = "auto"
+markers = ["e2e: end-to-end tests that require TOGETHER_API_KEY"]
+norecursedirs = ["e2e"]