runbox-sdk 0.2.2__tar.gz

runbox_sdk-0.2.2/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Runbox contributors
+
+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.

runbox_sdk-0.2.2/PKG-INFO

@@ -0,0 +1,40 @@
+Metadata-Version: 2.4
+Name: runbox-sdk
+Version: 0.2.2
+Summary: Python client for Runbox, a lightweight sandbox for agent commands and files
+Author: Runbox contributors
+License: MIT
+Project-URL: Homepage, https://runbox.xyun.dev
+Project-URL: Repository, https://github.com/xy200303/runbox
+Project-URL: Documentation, https://github.com/xy200303/runbox/blob/main/docs/api.md
+Keywords: runbox,sandbox,agent,code-execution
+Classifier: Programming Language :: Python :: 3
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Dynamic: license-file
+
+# Runbox Python SDK
+
+```bash
+pip install runbox-sdk
+```
+
+```python
+from runbox import Client, Identity
+
+client = Client(
+    "http://localhost:8099",
+    api_key="...",
+    identity=Identity(namespace="team-a", principal="user-42"),
+)
+result = client.exec('python3 -c "print(6 * 7)"')
+print(result["stdout"])
+```
+
+The client uses only the Python standard library. Uploads stream from disk;
+downloads and tar archives stream to a destination path.
+
+Full API reference: [docs/api.md](../../docs/api.md).

runbox_sdk-0.2.2/README.md

@@ -0,0 +1,22 @@
+# Runbox Python SDK
+
+```bash
+pip install runbox-sdk
+```
+
+```python
+from runbox import Client, Identity
+
+client = Client(
+    "http://localhost:8099",
+    api_key="...",
+    identity=Identity(namespace="team-a", principal="user-42"),
+)
+result = client.exec('python3 -c "print(6 * 7)"')
+print(result["stdout"])
+```
+
+The client uses only the Python standard library. Uploads stream from disk;
+downloads and tar archives stream to a destination path.
+
+Full API reference: [docs/api.md](../../docs/api.md).

runbox_sdk-0.2.2/pyproject.toml

@@ -0,0 +1,29 @@
+[build-system]
+requires = ["setuptools>=68", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "runbox-sdk"
+version = "0.2.2"
+description = "Python client for Runbox, a lightweight sandbox for agent commands and files"
+readme = "README.md"
+requires-python = ">=3.9"
+license = { text = "MIT" }
+authors = [{ name = "Runbox contributors" }]
+keywords = ["runbox", "sandbox", "agent", "code-execution"]
+classifiers = [
+  "Programming Language :: Python :: 3",
+  "License :: OSI Approved :: MIT License",
+  "Operating System :: OS Independent",
+]
+
+[project.urls]
+Homepage = "https://runbox.xyun.dev"
+Repository = "https://github.com/xy200303/runbox"
+Documentation = "https://github.com/xy200303/runbox/blob/main/docs/api.md"
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.setuptools.package-data]
+runbox = ["py.typed"]

runbox_sdk-0.2.2/setup.cfg

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

runbox_sdk-0.2.2/src/runbox/__init__.py

@@ -0,0 +1,8 @@
+"""Python client for Runbox."""
+
+from .client import Client, FileUpload
+from .errors import IdentityError, RunboxError
+from .identity import Identity
+
+__all__ = ["Client", "FileUpload", "Identity", "IdentityError", "RunboxError"]
+__version__ = "0.2.2"

runbox_sdk-0.2.2/src/runbox/client.py

@@ -0,0 +1,321 @@
+"""Stdlib-only client for the Runbox HTTP API."""
+
+from __future__ import annotations
+
+import http.client
+import json
+import os
+import secrets
+import shutil
+import urllib.error
+import urllib.parse
+import urllib.request
+from dataclasses import dataclass
+from typing import Any, Dict, Iterable, List, Optional, Tuple, Union
+
+from .errors import RunboxError
+from .identity import Identity
+
+PathLike = Union[str, "os.PathLike[str]"]
+
+DEFAULT_TIMEOUT = 330.0
+
+
+@dataclass
+class FileUpload:
+    """One file sent in a multipart request.
+
+    Use ``data`` for bytes already in memory, or ``path`` to stream from disk.
+    Exactly one must be set.
+    """
+
+    name: str
+    data: Optional[bytes] = None
+    path: Optional[PathLike] = None
+    size: Optional[int] = None
+
+    def __post_init__(self) -> None:
+        if (self.data is None) == (self.path is None):
+            raise ValueError("set exactly one of data or path")
+        if self.path is not None:
+            self.size = os.path.getsize(self.path)
+        elif self.size is None:
+            self.size = len(self.data or b"")
+
+    def open(self):
+        if self.path is not None:
+            return open(self.path, "rb")
+        import io
+
+        return io.BytesIO(self.data or b"")
+
+
+@dataclass(frozen=True)
+class _Part:
+    header: bytes
+    length: int
+    value: bytes
+    path: Optional[PathLike] = None
+
+
+class Client:
+    """A Runbox HTTP client."""
+
+    def __init__(
+        self,
+        base_url: str,
+        api_key: str = "",
+        identity: Optional[Identity] = None,
+        timeout: float = DEFAULT_TIMEOUT,
+    ) -> None:
+        self.base_url = base_url.rstrip("/")
+        if not self.base_url.startswith(("http://", "https://")):
+            raise ValueError("base_url must be an absolute http(s) URL")
+        self.api_key = api_key
+        self.identity = identity
+        self.timeout = timeout
+        parts = urllib.parse.urlsplit(self.base_url)
+        self._scheme = parts.scheme
+        self._host = parts.hostname or ""
+        self._port = parts.port
+        self._prefix = parts.path.rstrip("/")
+
+    def _resolve_identity(self, identity: Optional[Identity]) -> Optional[Identity]:
+        return identity or self.identity
+
+    def _headers(
+        self,
+        identity: Optional[Identity] = None,
+        extra: Optional[Dict[str, str]] = None,
+    ) -> Dict[str, str]:
+        headers = {"Accept": "application/json", "User-Agent": "runbox-python/0.2.2"}
+        selected = self._resolve_identity(identity)
+        if selected is not None:
+            headers.update(selected.headers())
+        if self.api_key:
+            headers["Authorization"] = "Bearer " + self.api_key
+        if extra:
+            headers.update(extra)
+        return headers
+
+    def _url(self, path: str, query: Optional[Dict[str, str]] = None) -> str:
+        url = self.base_url + path
+        if query:
+            url += "?" + urllib.parse.urlencode(query, doseq=True)
+        return url
+
+    def _connection(self) -> http.client.HTTPConnection:
+        if self._scheme == "https":
+            return http.client.HTTPSConnection(self._host, self._port, timeout=self.timeout)
+        return http.client.HTTPConnection(self._host, self._port, timeout=self.timeout)
+
+    def _json(
+        self,
+        method: str,
+        path: str,
+        payload: Optional[Dict[str, Any]] = None,
+        identity: Optional[Identity] = None,
+        timeout: Optional[float] = None,
+    ) -> Any:
+        body = json.dumps(payload).encode() if payload is not None else None
+        extra = {"Content-Type": "application/json"} if body is not None else None
+        request = urllib.request.Request(
+            self._url(path),
+            data=body,
+            method=method,
+            headers=self._headers(identity, extra),
+        )
+        try:
+            with urllib.request.urlopen(request, timeout=timeout or self.timeout) as response:
+                data = response.read()
+        except urllib.error.HTTPError as error:
+            raise _error(error.code, error.read()) from None
+        if not data:
+            return None
+        return json.loads(data)
+
+    def health(self) -> Dict[str, Any]:
+        return self._json("GET", "/health")
+
+    def capabilities(self) -> Dict[str, Any]:
+        return self._json("GET", "/v1/capabilities")
+
+    def exec(
+        self,
+        command: str,
+        timeout: int = 60,
+        files: Optional[Iterable[FileUpload]] = None,
+        identity: Optional[Identity] = None,
+    ) -> Dict[str, Any]:
+        file_list = list(files or [])
+        request_timeout = max(self.timeout, timeout + 30)
+        if not file_list:
+            return self._json(
+                "POST",
+                "/v1/exec",
+                {"command": command, "timeout_seconds": timeout},
+                identity=identity,
+                timeout=request_timeout,
+            )
+        fields: List[Tuple[str, str]] = [("command", command), ("timeout_seconds", str(timeout))]
+        return self._multipart("/v1/exec", fields, file_list, identity, request_timeout)
+
+    def upload(self, name: str, data: bytes) -> Dict[str, Any]:
+        return self.upload_batch([FileUpload(name=name, data=data)])[0]
+
+    def upload_file(self, path: PathLike) -> Dict[str, Any]:
+        return self.upload_batch([FileUpload(name=os.path.basename(os.fspath(path)), path=path)])[0]
+
+    def upload_batch(
+        self,
+        files: Iterable[FileUpload],
+        identity: Optional[Identity] = None,
+    ) -> List[Dict[str, Any]]:
+        uploaded = self._multipart("/v1/files/batch", [], list(files), identity, self.timeout)
+        return list(uploaded.get("files", []))
+
+    def list(self, path: str = "", identity: Optional[Identity] = None) -> List[Dict[str, Any]]:
+        query = {"path": path} if path else None
+        data = self._json("GET", self._url_path("/v1/list", query), identity=identity)
+        return list(data.get("entries", []))
+
+    def delete_workspace(self, identity: Optional[Identity] = None) -> None:
+        self._json("DELETE", "/v1/workspace", identity=identity)
+
+    def download_path(
+        self,
+        path: str,
+        destination: PathLike,
+        identity: Optional[Identity] = None,
+        range_header: Optional[str] = None,
+    ) -> None:
+        extra = {"Range": range_header} if range_header else None
+        self._download(self._url_path("/v1/path", {"path": path}), destination, identity, extra)
+
+    def download_archive(
+        self,
+        paths: Iterable[str],
+        destination: PathLike,
+        identity: Optional[Identity] = None,
+    ) -> None:
+        query = [("path", path) for path in paths]
+        if not query:
+            raise ValueError("at least one path is required")
+        self._download(self._url_path("/v1/archive", query), destination, identity)
+
+    def _download(
+        self,
+        path: str,
+        destination: PathLike,
+        identity: Optional[Identity],
+        extra: Optional[Dict[str, str]] = None,
+    ) -> None:
+        request = urllib.request.Request(
+            self.base_url + path,
+            headers=self._headers(identity, extra),
+            method="GET",
+        )
+        try:
+            response = urllib.request.urlopen(request, timeout=self.timeout)
+        except urllib.error.HTTPError as error:
+            raise _error(error.code, error.read()) from None
+        with response, open(destination, "wb") as output:
+            shutil.copyfileobj(response, output, length=1 << 20)
+
+    @staticmethod
+    def _url_path(path: str, query: Any = None) -> str:
+        if not query:
+            return path
+        return path + "?" + urllib.parse.urlencode(query, doseq=True)
+
+    def _multipart(
+        self,
+        path: str,
+        fields: List[Tuple[str, str]],
+        files: List[FileUpload],
+        identity: Optional[Identity],
+        timeout: float,
+    ) -> Any:
+        boundary = secrets.token_hex(16)
+        parts: List[_Part] = []
+
+        for name, value in fields:
+            body = value.encode()
+            header = (
+                f"--{boundary}\r\n"
+                f'Content-Disposition: form-data; name="{_escape(name)}"\r\n\r\n'
+            ).encode()
+            parts.append(_Part(header=header, length=len(body), value=body))
+
+        for file in files:
+            safe_name = _escape(file.name)
+            header = (
+                f"--{boundary}\r\n"
+                f'Content-Disposition: form-data; name="files"; filename="{safe_name}"\r\n'
+                "Content-Type: application/octet-stream\r\n\r\n"
+            ).encode()
+            parts.append(
+                _Part(
+                    header=header,
+                    length=int(file.size or 0),
+                    value=b"",
+                    path=file.path,
+                )
+                if file.path is not None
+                else _Part(header=header, length=len(file.data or b""), value=file.data or b"")
+            )
+
+        closing = f"\r\n--{boundary}--\r\n".encode()
+        total = sum(part.length + len(part.header) for part in parts) + len(closing)
+        total += sum(2 for _ in parts)  # CRLF after each part body
+
+        connection = self._connection()
+        try:
+            connection.putrequest("POST", self._prefix + path)
+            headers = self._headers(
+                identity,
+                {"Content-Type": f"multipart/form-data; boundary={boundary}"},
+            )
+            for key, value in headers.items():
+                connection.putheader(key, value)
+            connection.putheader("Content-Length", str(total))
+            connection.endheaders()
+            for part in parts:
+                connection.send(part.header)
+                if part.path is not None:
+                    with open(part.path, "rb") as handle:
+                        while True:
+                            chunk = handle.read(1 << 20)
+                            if not chunk:
+                                break
+                            connection.send(chunk)
+                else:
+                    connection.send(part.value)
+                connection.send(b"\r\n")
+            connection.send(closing)
+            response = connection.getresponse()
+            body = response.read()
+        finally:
+            connection.close()
+
+        if response.status < 200 or response.status >= 300:
+            raise _error(response.status, body)
+        return json.loads(body) if body else None
+
+
+def _escape(value: str) -> str:
+    return value.replace("\\", "_").replace('"', "_").replace("\r", "_").replace("\n", "_")
+
+
+def _error(status: int, body: bytes) -> RunboxError:
+    code = f"http_{status}"
+    message = body.decode("utf-8", "replace").strip()
+    try:
+        payload = json.loads(body)
+        code = str(payload.get("code") or code)
+        message = str(payload.get("message") or message)
+    except (ValueError, TypeError):
+        pass
+    if not message or message.startswith("<"):
+        message = f"HTTP {status}"
+    return RunboxError(status, code, message[:2048])

runbox_sdk-0.2.2/src/runbox/errors.py

@@ -0,0 +1,17 @@
+"""Errors raised by the Runbox client."""
+
+from __future__ import annotations
+
+
+class RunboxError(Exception):
+    """An HTTP error returned by the runner."""
+
+    def __init__(self, status: int, code: str, message: str) -> None:
+        super().__init__(f"{status} {code}: {message}")
+        self.status = status
+        self.code = code
+        self.message = message
+
+
+class IdentityError(ValueError):
+    """An identity is missing, ambiguous or invalid."""

runbox_sdk-0.2.2/src/runbox/identity.py

@@ -0,0 +1,53 @@
+"""Runbox identity headers."""
+
+from __future__ import annotations
+
+import re
+from dataclasses import dataclass
+
+from .errors import IdentityError
+
+_SCOPED = re.compile(r"^[A-Za-z0-9._-]{1,128}$")
+
+
+@dataclass(frozen=True)
+class Identity:
+    """Either a single token or a namespace + principal pair.
+
+    Supplying both forms, or only half of the scoped form, is an error.
+    """
+
+    token: str = ""
+    namespace: str = ""
+    principal: str = ""
+
+    def __post_init__(self) -> None:
+        token = self.token.strip()
+        namespace = self.namespace.strip()
+        principal = self.principal.strip()
+        object.__setattr__(self, "token", token)
+        object.__setattr__(self, "namespace", namespace)
+        object.__setattr__(self, "principal", principal)
+
+        if token and (namespace or principal):
+            raise IdentityError("use either token or namespace+principal, not both")
+        if token:
+            if not (1 <= len(token) <= 256):
+                raise IdentityError("token must be 1-256 characters")
+            if any(char < "!" or char > "~" for char in token):
+                raise IdentityError("token must be visible ASCII without spaces")
+            return
+        if not namespace or not principal:
+            raise IdentityError("token or namespace+principal is required")
+        if not _SCOPED.fullmatch(namespace):
+            raise IdentityError("namespace must match [A-Za-z0-9._-]{1,128}")
+        if not _SCOPED.fullmatch(principal):
+            raise IdentityError("principal must match [A-Za-z0-9._-]{1,128}")
+
+    def headers(self) -> dict[str, str]:
+        if self.token:
+            return {"X-Runbox-Identity": self.token}
+        return {
+            "X-Runbox-Namespace": self.namespace,
+            "X-Runbox-Principal": self.principal,
+        }

runbox_sdk-0.2.2/src/runbox_sdk.egg-info/PKG-INFO

@@ -0,0 +1,40 @@
+Metadata-Version: 2.4
+Name: runbox-sdk
+Version: 0.2.2
+Summary: Python client for Runbox, a lightweight sandbox for agent commands and files
+Author: Runbox contributors
+License: MIT
+Project-URL: Homepage, https://runbox.xyun.dev
+Project-URL: Repository, https://github.com/xy200303/runbox
+Project-URL: Documentation, https://github.com/xy200303/runbox/blob/main/docs/api.md
+Keywords: runbox,sandbox,agent,code-execution
+Classifier: Programming Language :: Python :: 3
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Dynamic: license-file
+
+# Runbox Python SDK
+
+```bash
+pip install runbox-sdk
+```
+
+```python
+from runbox import Client, Identity
+
+client = Client(
+    "http://localhost:8099",
+    api_key="...",
+    identity=Identity(namespace="team-a", principal="user-42"),
+)
+result = client.exec('python3 -c "print(6 * 7)"')
+print(result["stdout"])
+```
+
+The client uses only the Python standard library. Uploads stream from disk;
+downloads and tar archives stream to a destination path.
+
+Full API reference: [docs/api.md](../../docs/api.md).

runbox_sdk-0.2.2/src/runbox_sdk.egg-info/SOURCES.txt

@@ -0,0 +1,14 @@
+LICENSE
+README.md
+pyproject.toml
+src/runbox/__init__.py
+src/runbox/client.py
+src/runbox/errors.py
+src/runbox/identity.py
+src/runbox/py.typed
+src/runbox_sdk.egg-info/PKG-INFO
+src/runbox_sdk.egg-info/SOURCES.txt
+src/runbox_sdk.egg-info/dependency_links.txt
+src/runbox_sdk.egg-info/top_level.txt
+tests/test_client.py
+tests/test_identity.py

runbox_sdk-0.2.2/src/runbox_sdk.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

runbox_sdk-0.2.2/src/runbox_sdk.egg-info/top_level.txt

@@ -0,0 +1 @@
+runbox

runbox_sdk-0.2.2/tests/test_client.py

@@ -0,0 +1,149 @@
+import json
+import tempfile
+import threading
+import unittest
+from http.server import BaseHTTPRequestHandler, ThreadingHTTPServer
+from pathlib import Path
+
+from runbox import Client, FileUpload, Identity, RunboxError
+
+
+class Handler(BaseHTTPRequestHandler):
+    requests = []
+
+    def log_message(self, *_args):
+        return
+
+    def _record(self):
+        length = int(self.headers.get("Content-Length", "0"))
+        body = self.rfile.read(length)
+        Handler.requests.append(
+            {
+                "method": self.command,
+                "path": self.path,
+                "headers": dict(self.headers),
+                "body": body,
+            }
+        )
+        return body
+
+    def do_POST(self):
+        body = self._record()
+        if self.path == "/v1/exec":
+            payload = json.loads(body)
+            self._json(200, {"exit_code": 0, "stdout": payload["command"], "files": []})
+            return
+        if self.path == "/v1/files/batch":
+            self._json(
+                200,
+                {
+                    "files": [
+                        {"path": "files/a.txt", "name": "a.txt", "size": 3},
+                        {"path": "files/b.txt", "name": "b.txt", "size": 3},
+                    ]
+                },
+            )
+            return
+        self._json(404, {"code": "not_found", "message": "not found"})
+
+    def do_GET(self):
+        self._record()
+        if self.path.startswith("/v1/path"):
+            if "missing" in self.path:
+                self._json(404, {"code": "not_found", "message": "not found"})
+                return
+            self._bytes(200, b"path-data")
+            return
+        if self.path.startswith("/v1/archive"):
+            self._bytes(200, b"tar-data")
+            return
+        if self.path.startswith("/v1/list"):
+            self._json(200, {"entries": [{"name": "out", "is_dir": True}]})
+            return
+        if self.path == "/health":
+            self._json(200, {"status": "healthy"})
+            return
+        self._json(404, {"code": "not_found", "message": "not found"})
+
+    def do_DELETE(self):
+        self._record()
+        self._json(200, {"deleted": True})
+
+    def _json(self, status, payload):
+        body = json.dumps(payload).encode()
+        self.send_response(status)
+        self.send_header("Content-Type", "application/json")
+        self.send_header("Content-Length", str(len(body)))
+        self.end_headers()
+        self.wfile.write(body)
+
+    def _bytes(self, status, body):
+        self.send_response(status)
+        self.send_header("Content-Type", "application/octet-stream")
+        self.send_header("Content-Length", str(len(body)))
+        self.end_headers()
+        self.wfile.write(body)
+
+
+class ClientTest(unittest.TestCase):
+    @classmethod
+    def setUpClass(cls):
+        cls.server = ThreadingHTTPServer(("127.0.0.1", 0), Handler)
+        cls.thread = threading.Thread(target=cls.server.serve_forever, daemon=True)
+        cls.thread.start()
+        host, port = cls.server.server_address
+        cls.client = Client(
+            f"http://{host}:{port}",
+            api_key="test-key",
+            identity=Identity(namespace="team-a", principal="user-42"),
+        )
+
+    @classmethod
+    def tearDownClass(cls):
+        cls.server.shutdown()
+        cls.server.server_close()
+
+    def setUp(self):
+        Handler.requests.clear()
+
+    def test_exec_sends_auth_and_identity(self):
+        result = self.client.exec("echo hello")
+        self.assertEqual(result["stdout"], "echo hello")
+        request = Handler.requests[0]
+        self.assertEqual(request["headers"]["Authorization"], "Bearer test-key")
+        self.assertEqual(request["headers"]["X-Runbox-Namespace"], "team-a")
+        self.assertEqual(request["headers"]["X-Runbox-Principal"], "user-42")
+
+    def test_batch_upload_streams_files(self):
+        with tempfile.TemporaryDirectory() as directory:
+            first = Path(directory, "a.txt")
+            second = Path(directory, "b.txt")
+            first.write_bytes(b"aaa")
+            second.write_bytes(b"bbb")
+            uploaded = self.client.upload_batch(
+                [FileUpload("a.txt", path=first), FileUpload("b.txt", path=second)]
+            )
+        self.assertEqual([item["path"] for item in uploaded], ["files/a.txt", "files/b.txt"])
+        request = Handler.requests[0]
+        self.assertIn(b"aaa", request["body"])
+        self.assertIn(b"bbb", request["body"])
+        self.assertEqual(int(request["headers"]["Content-Length"]), len(request["body"]))
+
+    def test_download_path_and_archive(self):
+        with tempfile.TemporaryDirectory() as directory:
+            path_file = Path(directory, "path.bin")
+            archive_file = Path(directory, "archive.tar")
+            self.client.download_path("out/report.txt", path_file)
+            self.client.download_archive(["out", "tmp"], archive_file)
+            self.assertEqual(path_file.read_bytes(), b"path-data")
+            self.assertEqual(archive_file.read_bytes(), b"tar-data")
+
+    def test_server_error_is_typed(self):
+        with self.assertRaises(RunboxError) as caught:
+            self.client.download_path("missing", Path(tempfile.gettempdir(), "missing.bin"))
+        self.assertEqual(caught.exception.status, 404)
+        self.assertEqual(caught.exception.code, "not_found")
+
+
+if __name__ == "__main__":
+    unittest.main()

runbox_sdk-0.2.2/tests/test_identity.py

@@ -0,0 +1,37 @@
+import unittest
+
+from runbox import Identity, IdentityError
+
+
+class IdentityTest(unittest.TestCase):
+    def test_token_headers(self):
+        identity = Identity(token="01J-token")
+        self.assertEqual(identity.headers(), {"X-Runbox-Identity": "01J-token"})
+
+    def test_scoped_headers(self):
+        identity = Identity(namespace="team-a", principal="user-42")
+        self.assertEqual(
+            identity.headers(),
+            {
+                "X-Runbox-Namespace": "team-a",
+                "X-Runbox-Principal": "user-42",
+            },
+        )
+
+    def test_ambiguous_is_rejected(self):
+        with self.assertRaises(IdentityError):
+            Identity(token="alice", namespace="team-a", principal="alice")
+
+    def test_partial_scoped_is_rejected(self):
+        with self.assertRaises(IdentityError):
+            Identity(namespace="team-a")
+
+    def test_invalid_characters_are_rejected(self):
+        with self.assertRaises(IdentityError):
+            Identity(namespace="team a", principal="alice")
+        with self.assertRaises(IdentityError):
+            Identity(token="a b")
+
+
+if __name__ == "__main__":
+    unittest.main()