runta-sdk 0.0.4__tar.gz

runta_sdk-0.0.4/PKG-INFO

@@ -0,0 +1,136 @@
+Metadata-Version: 2.4
+Name: runta-sdk
+Version: 0.0.4
+Summary: Python SDK for Runta runtime management
+Author: Runta
+License-Expression: MIT
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+Requires-Dist: httpx>=0.27
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0; extra == "dev"
+Requires-Dist: pytest-asyncio>=0.23; extra == "dev"
+
+# Runta Python SDK
+
+This package provides matching async and sync SDKs. Both call the public
+`runta-api` HTTP/JSON service; they do not speak control-plane gRPC directly.
+
+## Install
+
+```bash
+pip install runta-sdk
+```
+
+For user-facing installation, configuration, and workflow examples, see
+[`doc.md`](doc.md).
+
+For a full API reference with every public method, parameter, return value, and
+model field, see [`manual.md`](manual.md).
+
+```python
+import asyncio
+
+from runta import AsyncRunta
+
+
+async def main():
+    async with AsyncRunta(endpoint="http://127.0.0.1:8080") as runta:
+        runtime = await runta.runtimes.create("example")
+        result = await runtime.exec("echo hello")
+        print(result.stdout_text)
+
+
+asyncio.run(main())
+```
+
+```python
+from runta import Runta
+
+runta = Runta(endpoint="http://127.0.0.1:8080")
+runtime = runta.runtimes.create("example")
+result = runtime.exec("echo hello")
+print(result.stdout_text)
+runta.close()
+```
+
+Authentication uses `Runta(token="rt_...")` or `RUNTA_TOKEN`. The endpoint uses
+`Runta(endpoint="...")`, `RUNTA_ENDPOINT`, or `endpoint` from the optional
+Runta config file.
+
+## Public REST endpoint lifecycle test
+
+You can test the SDK against the hosted REST API by pointing the client at
+`https://rest.runta.me` and providing a Runta token:
+
+```bash
+export RUNTA_TOKEN="rt_..."
+uv run python scripts/runta-lifecycle.py
+```
+
+The lifecycle script creates a runtime, starts it, runs a command, writes and
+reads a remote file, uploads a local file, downloads it back, pauses/resumes the
+runtime, then stops and deletes it. To pass credentials explicitly:
+
+```bash
+uv run python scripts/runta-lifecycle.py \
+  --endpoint https://rest.runta.me \
+  --token "$RUNTA_TOKEN"
+```
+
+Use `--keep` to leave the runtime behind for inspection.
+
+The SDK is aligned with the current `crates/runta-api` REST routes. The OpenAPI
+contract exposes single-file raw byte routes at
+`/v1/runtimes/{runtime_id}/files` for `runtime.files.read`,
+`runtime.files.write`, `runtime.files.upload`, and `runtime.files.download`.
+SDK `sessions` are SDK-owned handles because persistent server-side session
+routes are not exposed.
+
+## REST contract
+
+`contracts/runta-api.openapi.yaml` is copied from
+`runta/crates/runta-api/openapi.yaml` and is used by the SDK contract tests.
+CI refreshes this file from the latest successful `runta` OpenAPI contract
+artifact before running tests. If the artifact is unavailable, it falls back to
+the `dev` branch raw YAML and then to the checked-in contract.
+
+To refresh it locally after changing `runta-api`:
+
+```bash
+cd ~/runta
+cargo make openapi
+cp crates/runta-api/openapi.yaml ~/RuntaPythonSDK/contracts/runta-api.openapi.yaml
+cd ~/RuntaPythonSDK
+uv run pytest tests/test_openapi_contract.py
+```
+
+To fetch the latest published contract directly:
+
+```bash
+scripts/fetch-runta-openapi.py
+```
+
+## Live tests
+
+The live test module runs mocked SDK workflow tests by default:
+
+```bash
+python -m unittest tests/test_live.py -v
+```
+
+Pass `--live` to run the real runtime tests. They create real runtimes and use
+external egress, so run them only with `scripts/dev-api.sh` already running:
+
+```bash
+uv run pytest --live
+```
+
+Local pytest loads `.env` automatically. The default local file uses:
+
+```bash
+RUNTA_ENDPOINT=http://127.0.0.1:8080
+RUNTA_TOKEN_FILE=../runta/.dev/cli_token_dev-a
+```
+
+Copy or edit `.env.example` if your checkout paths differ.

runta_sdk-0.0.4/README.md

@@ -0,0 +1,123 @@
+# Runta Python SDK
+
+This package provides matching async and sync SDKs. Both call the public
+`runta-api` HTTP/JSON service; they do not speak control-plane gRPC directly.
+
+## Install
+
+```bash
+pip install runta-sdk
+```
+
+For user-facing installation, configuration, and workflow examples, see
+[`doc.md`](doc.md).
+
+For a full API reference with every public method, parameter, return value, and
+model field, see [`manual.md`](manual.md).
+
+```python
+import asyncio
+
+from runta import AsyncRunta
+
+
+async def main():
+    async with AsyncRunta(endpoint="http://127.0.0.1:8080") as runta:
+        runtime = await runta.runtimes.create("example")
+        result = await runtime.exec("echo hello")
+        print(result.stdout_text)
+
+
+asyncio.run(main())
+```
+
+```python
+from runta import Runta
+
+runta = Runta(endpoint="http://127.0.0.1:8080")
+runtime = runta.runtimes.create("example")
+result = runtime.exec("echo hello")
+print(result.stdout_text)
+runta.close()
+```
+
+Authentication uses `Runta(token="rt_...")` or `RUNTA_TOKEN`. The endpoint uses
+`Runta(endpoint="...")`, `RUNTA_ENDPOINT`, or `endpoint` from the optional
+Runta config file.
+
+## Public REST endpoint lifecycle test
+
+You can test the SDK against the hosted REST API by pointing the client at
+`https://rest.runta.me` and providing a Runta token:
+
+```bash
+export RUNTA_TOKEN="rt_..."
+uv run python scripts/runta-lifecycle.py
+```
+
+The lifecycle script creates a runtime, starts it, runs a command, writes and
+reads a remote file, uploads a local file, downloads it back, pauses/resumes the
+runtime, then stops and deletes it. To pass credentials explicitly:
+
+```bash
+uv run python scripts/runta-lifecycle.py \
+  --endpoint https://rest.runta.me \
+  --token "$RUNTA_TOKEN"
+```
+
+Use `--keep` to leave the runtime behind for inspection.
+
+The SDK is aligned with the current `crates/runta-api` REST routes. The OpenAPI
+contract exposes single-file raw byte routes at
+`/v1/runtimes/{runtime_id}/files` for `runtime.files.read`,
+`runtime.files.write`, `runtime.files.upload`, and `runtime.files.download`.
+SDK `sessions` are SDK-owned handles because persistent server-side session
+routes are not exposed.
+
+## REST contract
+
+`contracts/runta-api.openapi.yaml` is copied from
+`runta/crates/runta-api/openapi.yaml` and is used by the SDK contract tests.
+CI refreshes this file from the latest successful `runta` OpenAPI contract
+artifact before running tests. If the artifact is unavailable, it falls back to
+the `dev` branch raw YAML and then to the checked-in contract.
+
+To refresh it locally after changing `runta-api`:
+
+```bash
+cd ~/runta
+cargo make openapi
+cp crates/runta-api/openapi.yaml ~/RuntaPythonSDK/contracts/runta-api.openapi.yaml
+cd ~/RuntaPythonSDK
+uv run pytest tests/test_openapi_contract.py
+```
+
+To fetch the latest published contract directly:
+
+```bash
+scripts/fetch-runta-openapi.py
+```
+
+## Live tests
+
+The live test module runs mocked SDK workflow tests by default:
+
+```bash
+python -m unittest tests/test_live.py -v
+```
+
+Pass `--live` to run the real runtime tests. They create real runtimes and use
+external egress, so run them only with `scripts/dev-api.sh` already running:
+
+```bash
+uv run pytest --live
+```
+
+Local pytest loads `.env` automatically. The default local file uses:
+
+```bash
+RUNTA_ENDPOINT=http://127.0.0.1:8080
+RUNTA_TOKEN_FILE=../runta/.dev/cli_token_dev-a
+```
+
+Copy or edit `.env.example` if your checkout paths differ.

runta_sdk-0.0.4/pyproject.toml

@@ -0,0 +1,31 @@
+[build-system]
+requires = ["setuptools>=77.0.3", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "runta-sdk"
+version = "0.0.4"
+description = "Python SDK for Runta runtime management"
+readme = "README.md"
+requires-python = ">=3.10"
+license = "MIT"
+authors = [{ name = "Runta" }]
+dependencies = [
+    "httpx>=0.27",
+]
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=8.0",
+    "pytest-asyncio>=0.23",
+]
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.setuptools.package-data]
+asyncrunta = ["py.typed"]
+runta = ["py.typed"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]

runta_sdk-0.0.4/setup.cfg

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

runta_sdk-0.0.4/src/asyncrunta/__init__.py

@@ -0,0 +1,45 @@
+"""Async Runta Python SDK."""
+
+from .client import AsyncRunta, Runtime, Session
+from .errors import ApiError, CommandError, ConfigError, RuntaError
+from .models import (
+    CommandResult,
+    CpuArch,
+    EgressAuditEvent,
+    EgressPolicy,
+    Injection,
+    IngressSpec,
+    RuntimeInfo,
+    RuntimeStatus,
+    SecretInfo,
+    SecretInjectionRuleInfo,
+    SecretRuleInfo,
+    SnapshotInfo,
+    SnapshotState,
+)
+
+Runta = AsyncRunta
+
+__all__ = [
+    "ApiError",
+    "AsyncRunta",
+    "CommandError",
+    "CommandResult",
+    "ConfigError",
+    "CpuArch",
+    "EgressAuditEvent",
+    "EgressPolicy",
+    "Injection",
+    "IngressSpec",
+    "Runta",
+    "RuntaError",
+    "Runtime",
+    "RuntimeInfo",
+    "RuntimeStatus",
+    "SecretInfo",
+    "SecretInjectionRuleInfo",
+    "SecretRuleInfo",
+    "Session",
+    "SnapshotInfo",
+    "SnapshotState",
+]

runta_sdk-0.0.4/src/asyncrunta/_config.py

@@ -0,0 +1,69 @@
+"""Configuration resolution."""
+
+from __future__ import annotations
+
+import os
+import tomllib
+from pathlib import Path
+
+from .errors import ConfigError
+
+
+def resolve_config(
+    *,
+    endpoint: str | None,
+    token: str | None,
+    config_path: str | Path | None,
+) -> tuple[str, str]:
+    file_config = _read_config(config_path)
+    resolved_endpoint = _clean(endpoint) or _clean(os.getenv("RUNTA_ENDPOINT")) or file_config[0]
+    resolved_token = (
+        _clean(token)
+        or _clean(os.getenv("RUNTA_TOKEN"))
+        or _read_token_file(os.getenv("RUNTA_TOKEN_FILE"))
+        or file_config[1]
+    )
+    if not resolved_endpoint:
+        raise ConfigError(
+            "missing endpoint: pass endpoint=..., set RUNTA_ENDPOINT, or set endpoint in config"
+        )
+    if not resolved_token:
+        raise ConfigError("missing token: pass token=... or set RUNTA_TOKEN")
+    return resolved_endpoint, resolved_token
+
+
+def _read_config(config_path: str | Path | None) -> tuple[str | None, str | None]:
+    path = (
+        Path(config_path).expanduser()
+        if config_path is not None
+        else Path(os.getenv("RUNTA_CONFIG", "~/.config/runta/config.toml")).expanduser()
+    )
+    if not path.exists():
+        return None, None
+    try:
+        data = tomllib.loads(path.read_text())
+    except OSError as exc:
+        raise ConfigError(f"failed to read config file {path}: {exc}") from exc
+    except tomllib.TOMLDecodeError as exc:
+        raise ConfigError(f"failed to parse config file {path}: {exc}") from exc
+    return _clean(data.get("endpoint")), _clean(data.get("token"))
+
+
+def _read_token_file(token_file: str | None) -> str | None:
+    token_file = _clean(token_file)
+    if token_file is None:
+        return None
+    path = Path(token_file).expanduser()
+    if not path.exists():
+        return None
+    try:
+        return _clean(path.read_text())
+    except OSError as exc:
+        raise ConfigError(f"failed to read token file {path}: {exc}") from exc
+
+
+def _clean(value: object) -> str | None:
+    if not isinstance(value, str):
+        return None
+    value = value.strip()
+    return value or None