tyto.run 0.11.0__tar.gz

tyto_run-0.11.0/.gitignore

@@ -0,0 +1,7 @@
+.venv/
+__pycache__/
+*.pyc
+*.egg-info/
+dist/
+build/
+.env

tyto_run-0.11.0/PKG-INFO

@@ -0,0 +1,136 @@
+Metadata-Version: 2.4
+Name: tyto.run
+Version: 0.11.0
+Summary: Official Python SDK for the Tyto API
+Project-URL: Homepage, https://tyto.run
+Author: Bonya
+License: MIT
+Requires-Python: >=3.9
+Requires-Dist: httpx>=0.27.0
+Requires-Dist: websockets>=13.0
+Description-Content-Type: text/markdown
+
+# tyto
+
+Python SDK for the [Tyto API](https://api.tyto.run) — manage nests, sessions, files, previews, snapshots, and keepalive holds.
+
+## Install
+
+```bash
+pip install tyto
+```
+
+## Auth
+
+Export your API key:
+
+```bash
+export TYTO_API_KEY=your_key_here
+```
+
+Or pass it directly:
+
+```python
+from tyto import Tyto
+tyto = Tyto(api_key="your_key_here")
+```
+
+## Usage
+
+```python
+import os
+from tyto import Tyto
+
+tyto = Tyto(api_key=os.environ["TYTO_API_KEY"])
+
+# Who am I?
+me = tyto.me()
+print(me.email)
+
+# Create a nest
+nest = tyto.create(name="my-nest", template="ubuntu-24-dev")
+
+# Upload / download a file or directory
+nest.put("./hello.txt", "hello.txt")
+nest.get("hello.txt", "./hello.downloaded.txt")
+
+# Create a session and attach over WebSocket
+session = nest.create_session(argv=["bash", "-lc", "echo hi"], tty=False)
+with session.attach() as ws:
+    for message in ws:
+        print(message)
+
+# Open raw WebSocket connections
+with nest.exec() as ws: ...
+with nest.console() as ws: ...
+
+# Create a preview
+preview = nest.create_preview(port=3000, auth="private")
+print(preview.url)
+
+# Snapshot, fork, restore
+snap = nest.create_snapshot(name="v1")
+fork = nest.fork(name="my-fork")
+nest.delete_snapshot(snap.id)
+# nest.restore(snap.id)
+
+# Keepalive hold
+nest.holds.put("ci", ttl="30m", reason="CI job")
+nest.holds.heartbeat("ci", ttl="30m")
+nest.holds.delete("ci")
+
+# Lifecycle
+nest.stop()
+nest.start()
+nest.wake(reason="wakeup")
+nest.delete()
+```
+
+## Resources
+
+| Resource | Description |
+|---|---|
+| `tyto.create()` | Create a nest |
+| `tyto.nests` | Create / list / get nests |
+| `tyto.previews` | Inspect / revoke previews by ID |
+| `tyto.auth` | CLI browser auth flow |
+| `nest.put(local, remote)` | Upload a file or directory |
+| `nest.get(remote, local)` | Download a file or directory |
+| `nest.create_session()` | Create a managed session |
+| `nest.create_preview()` | Create a preview URL |
+| `nest.create_snapshot()` | Create a snapshot |
+| `nest.delete_snapshot()` | Delete a snapshot |
+| `nest.fs` | Low-level file upload / download |
+| `nest.sessions` | Managed sessions (create / list) |
+| `nest.previews` | Previews scoped to the nest |
+| `nest.snapshots` | Snapshots + fork/restore |
+| `nest.holds` | Keepalive holds |
+| `session.attach()` | WebSocket stream for a session |
+| `nest.console()` | Interactive shell WebSocket |
+| `nest.exec()` | Command WebSocket |
+
+## Configuration
+
+| Parameter | Env var | Default |
+|---|---|---|
+| `api_key` | `TYTO_API_KEY` | — (required) |
+| `api_url` | `TYTO_API_URL` | `https://api.tyto.run` |
+
+## Examples
+
+```bash
+python examples/quickstart.py
+python examples/files.py
+python examples/preview.py
+python examples/snapshot_fork.py
+python examples/websocket_exec.py
+```
+
+## Context manager
+
+The `Tyto` client can be used as a context manager to ensure the underlying HTTP connection pool is closed:
+
+```python
+with Tyto() as tyto:
+    nests = tyto.nests.list()
+```

tyto_run-0.11.0/README.md

@@ -0,0 +1,124 @@
+# tyto
+
+Python SDK for the [Tyto API](https://api.tyto.run) — manage nests, sessions, files, previews, snapshots, and keepalive holds.
+
+## Install
+
+```bash
+pip install tyto
+```
+
+## Auth
+
+Export your API key:
+
+```bash
+export TYTO_API_KEY=your_key_here
+```
+
+Or pass it directly:
+
+```python
+from tyto import Tyto
+tyto = Tyto(api_key="your_key_here")
+```
+
+## Usage
+
+```python
+import os
+from tyto import Tyto
+
+tyto = Tyto(api_key=os.environ["TYTO_API_KEY"])
+
+# Who am I?
+me = tyto.me()
+print(me.email)
+
+# Create a nest
+nest = tyto.create(name="my-nest", template="ubuntu-24-dev")
+
+# Upload / download a file or directory
+nest.put("./hello.txt", "hello.txt")
+nest.get("hello.txt", "./hello.downloaded.txt")
+
+# Create a session and attach over WebSocket
+session = nest.create_session(argv=["bash", "-lc", "echo hi"], tty=False)
+with session.attach() as ws:
+    for message in ws:
+        print(message)
+
+# Open raw WebSocket connections
+with nest.exec() as ws: ...
+with nest.console() as ws: ...
+
+# Create a preview
+preview = nest.create_preview(port=3000, auth="private")
+print(preview.url)
+
+# Snapshot, fork, restore
+snap = nest.create_snapshot(name="v1")
+fork = nest.fork(name="my-fork")
+nest.delete_snapshot(snap.id)
+# nest.restore(snap.id)
+
+# Keepalive hold
+nest.holds.put("ci", ttl="30m", reason="CI job")
+nest.holds.heartbeat("ci", ttl="30m")
+nest.holds.delete("ci")
+
+# Lifecycle
+nest.stop()
+nest.start()
+nest.wake(reason="wakeup")
+nest.delete()
+```
+
+## Resources
+
+| Resource | Description |
+|---|---|
+| `tyto.create()` | Create a nest |
+| `tyto.nests` | Create / list / get nests |
+| `tyto.previews` | Inspect / revoke previews by ID |
+| `tyto.auth` | CLI browser auth flow |
+| `nest.put(local, remote)` | Upload a file or directory |
+| `nest.get(remote, local)` | Download a file or directory |
+| `nest.create_session()` | Create a managed session |
+| `nest.create_preview()` | Create a preview URL |
+| `nest.create_snapshot()` | Create a snapshot |
+| `nest.delete_snapshot()` | Delete a snapshot |
+| `nest.fs` | Low-level file upload / download |
+| `nest.sessions` | Managed sessions (create / list) |
+| `nest.previews` | Previews scoped to the nest |
+| `nest.snapshots` | Snapshots + fork/restore |
+| `nest.holds` | Keepalive holds |
+| `session.attach()` | WebSocket stream for a session |
+| `nest.console()` | Interactive shell WebSocket |
+| `nest.exec()` | Command WebSocket |
+
+## Configuration
+
+| Parameter | Env var | Default |
+|---|---|---|
+| `api_key` | `TYTO_API_KEY` | — (required) |
+| `api_url` | `TYTO_API_URL` | `https://api.tyto.run` |
+
+## Examples
+
+```bash
+python examples/quickstart.py
+python examples/files.py
+python examples/preview.py
+python examples/snapshot_fork.py
+python examples/websocket_exec.py
+```
+
+## Context manager
+
+The `Tyto` client can be used as a context manager to ensure the underlying HTTP connection pool is closed:
+
+```python
+with Tyto() as tyto:
+    nests = tyto.nests.list()
+```

tyto_run-0.11.0/pyproject.toml

@@ -0,0 +1,25 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "tyto.run"
+version = "0.11.0"
+description = "Official Python SDK for the Tyto API"
+readme = "README.md"
+license = { text = "MIT" }
+authors = [{ name = "Bonya" }]
+requires-python = ">=3.9"
+dependencies = [
+  "httpx>=0.27.0",
+  "websockets>=13.0",
+]
+
+[project.urls]
+Homepage = "https://tyto.run"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/tyto"]
+
+[tool.hatch.build.targets.sdist]
+include = ["src/tyto", "README.md", "pyproject.toml"]

tyto_run-0.11.0/src/tyto/__init__.py

@@ -0,0 +1,62 @@
+from .client import Tyto
+from .config import TytoConfig
+from .errors import TytoAPIError, TytoError
+from .models import (
+    AuthPollResponse,
+    AuthStartResponse,
+    DeleteSnapshotResponse,
+    ForkResponse,
+    ForkStorage,
+    KeepaliveHoldData,
+    NestData,
+    NestLifecycle,
+    PreviewData,
+    ReadFileResult,
+    RestoreResponse,
+    SessionData,
+    SnapshotData,
+    SnapshotList,
+    User,
+    WakeResponse,
+)
+from .resources.auth import AuthResource
+from .resources.files import FileSystem
+from .resources.holds import HoldsResource
+from .resources.nests import Nest, NestsResource
+from .resources.previews import PreviewsResource, TopLevelPreviewsResource
+from .resources.sessions import Session, SessionsResource
+from .resources.snapshots import SnapshotsResource, TopLevelSnapshotsResource
+
+__all__ = [
+    "Tyto",
+    "TytoConfig",
+    "TytoError",
+    "TytoAPIError",
+    "User",
+    "AuthStartResponse",
+    "AuthPollResponse",
+    "NestData",
+    "NestLifecycle",
+    "WakeResponse",
+    "SessionData",
+    "PreviewData",
+    "SnapshotData",
+    "SnapshotList",
+    "RestoreResponse",
+    "ForkResponse",
+    "ForkStorage",
+    "DeleteSnapshotResponse",
+    "KeepaliveHoldData",
+    "ReadFileResult",
+    "Nest",
+    "NestsResource",
+    "Session",
+    "SessionsResource",
+    "FileSystem",
+    "PreviewsResource",
+    "TopLevelPreviewsResource",
+    "SnapshotsResource",
+    "TopLevelSnapshotsResource",
+    "HoldsResource",
+    "AuthResource",
+]

tyto_run-0.11.0/src/tyto/_http.py

@@ -0,0 +1,82 @@
+from __future__ import annotations
+
+from typing import Any, Dict, Optional
+
+import httpx
+
+from .config import TytoConfig
+from .errors import TytoAPIError
+
+
+class HttpClient:
+    def __init__(self, config: TytoConfig) -> None:
+        self._config = config
+        self._client = httpx.Client(
+            base_url=config.api_url,
+            headers={"Authorization": f"Bearer {config.api_key}"},
+            timeout=30.0,
+        )
+
+    def _raise_for_status(self, response: httpx.Response) -> None:
+        if response.is_success:
+            return
+        try:
+            body = response.json()
+            code = body.get("error")
+            message = body.get("message") or f"HTTP {response.status_code}"
+        except Exception:
+            code = None
+            message = f"HTTP {response.status_code}"
+        raise TytoAPIError(response.status_code, code, message)
+
+    def get(self, path: str, params: Optional[Dict[str, Any]] = None) -> Any:
+        resp = self._client.get(path, params={k: v for k, v in (params or {}).items() if v is not None})
+        self._raise_for_status(resp)
+        if resp.status_code == 204:
+            return None
+        return resp.json()
+
+    def post(self, path: str, json: Any = None, params: Optional[Dict[str, Any]] = None) -> Any:
+        resp = self._client.post(path, json=json, params={k: v for k, v in (params or {}).items() if v is not None})
+        self._raise_for_status(resp)
+        if resp.status_code == 204:
+            return None
+        return resp.json()
+
+    def put(self, path: str, json: Any = None) -> Any:
+        resp = self._client.put(path, json=json)
+        self._raise_for_status(resp)
+        if resp.status_code == 204:
+            return None
+        return resp.json()
+
+    def delete(self, path: str, params: Optional[Dict[str, Any]] = None) -> Any:
+        resp = self._client.delete(path, params={k: v for k, v in (params or {}).items() if v is not None})
+        self._raise_for_status(resp)
+        if resp.status_code == 204:
+            return None
+        return resp.json()
+
+    def put_binary(self, path: str, data: bytes, content_type: str, params: Dict[str, Any]) -> None:
+        resp = self._client.put(
+            path,
+            content=data,
+            headers={"Content-Type": content_type},
+            params={k: v for k, v in params.items() if v is not None},
+        )
+        self._raise_for_status(resp)
+
+    def get_binary(self, path: str, params: Optional[Dict[str, Any]] = None) -> tuple[bytes, str]:
+        resp = self._client.get(path, params={k: v for k, v in (params or {}).items() if v is not None})
+        self._raise_for_status(resp)
+        kind = resp.headers.get("X-Tyto-FS-Kind", "file")
+        return resp.content, kind
+
+    def close(self) -> None:
+        self._client.close()
+
+    def __enter__(self) -> "HttpClient":
+        return self
+
+    def __exit__(self, *args: Any) -> None:
+        self.close()

tyto_run-0.11.0/src/tyto/client.py

@@ -0,0 +1,51 @@
+from __future__ import annotations
+
+from typing import Optional
+
+from ._http import HttpClient
+from .config import TytoConfig, resolve_config
+from .models import User
+from .resources.auth import AuthResource
+from .resources.nests import Nest, NestsResource
+from .resources.previews import TopLevelPreviewsResource
+from .resources.snapshots import TopLevelSnapshotsResource
+
+
+class Tyto:
+    def __init__(
+        self,
+        api_key: Optional[str] = None,
+        api_url: Optional[str] = None,
+    ) -> None:
+        self._config = resolve_config(api_key=api_key, api_url=api_url)
+        self._http = HttpClient(self._config)
+        self.auth = AuthResource(self._http)
+        self.nests = NestsResource(self._http, self._config)
+        self.previews = TopLevelPreviewsResource(self._http)
+        self.snapshots = TopLevelSnapshotsResource(self._http)
+
+    def create(
+        self,
+        name: str,
+        template: str = "ubuntu-24-dev",
+        repo_url: Optional[str] = None,
+    ) -> Nest:
+        return self.nests.create(name=name, template=template, repo_url=repo_url)
+
+    def health(self) -> dict:
+        return self._http.get("/healthz")
+
+    def ready(self) -> dict:
+        return self._http.get("/readyz")
+
+    def me(self) -> User:
+        return User.from_dict(self._http.get("/me"))
+
+    def close(self) -> None:
+        self._http.close()
+
+    def __enter__(self) -> "Tyto":
+        return self
+
+    def __exit__(self, *args) -> None:
+        self.close()

tyto_run-0.11.0/src/tyto/config.py

@@ -0,0 +1,25 @@
+from __future__ import annotations
+
+import os
+from dataclasses import dataclass
+
+from .errors import TytoError
+
+
+@dataclass
+class TytoConfig:
+    api_key: str = ""
+    api_url: str = "https://api.tyto.run"
+
+
+def resolve_config(
+    api_key: str | None = None,
+    api_url: str | None = None,
+) -> TytoConfig:
+    key = api_key or os.environ.get("TYTO_API_KEY", "")
+    if not key:
+        raise TytoError(
+            "api_key is required. Pass it as an argument or set the TYTO_API_KEY environment variable."
+        )
+    url = (api_url or os.environ.get("TYTO_API_URL", "https://api.tyto.run")).rstrip("/")
+    return TytoConfig(api_key=key, api_url=url)

tyto_run-0.11.0/src/tyto/errors.py

@@ -0,0 +1,13 @@
+class TytoError(Exception):
+    pass
+
+
+class TytoAPIError(TytoError):
+    def __init__(self, status: int, code: str | None, message: str) -> None:
+        super().__init__(message)
+        self.status = status
+        self.code = code
+        self.message = message
+
+    def __repr__(self) -> str:
+        return f"TytoAPIError(status={self.status}, code={self.code!r}, message={self.message!r})"