Metadata-Version: 2.4
Name: runta-sdk
Version: 0.1.1
Summary: Python SDK for Runta runtime management
Author: Runta
License-Expression: MIT
Requires-Python: >=3.10
Description-Content-Type: text/markdown
Requires-Dist: attrs>=22.2.0
Requires-Dist: httpx>=0.27
Provides-Extra: harbor
Requires-Dist: harbor>=0.15.0; python_version >= "3.12" and extra == "harbor"
Provides-Extra: dev
Requires-Dist: mkdocs-material; extra == "dev"
Requires-Dist: mkdocstrings[python]; extra == "dev"
Requires-Dist: openapi-python-client==0.29.0; python_version >= "3.11" and extra == "dev"
Requires-Dist: pytest>=8.0; extra == "dev"
Requires-Dist: pytest-asyncio>=0.23; extra == "dev"
Requires-Dist: ruamel-yaml; extra == "dev"
Requires-Dist: ruff; 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
data type field, see [`manual.md`](manual.md).

To render the local Python API docs:

```bash
uv run --extra dev mkdocs serve -a 127.0.0.1:8000
```

```python
import asyncio

from runta import AsyncRunta


async def main():
    async with AsyncRunta() 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()
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
defaults to `https://api.runta.me`; override it with `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://api.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://api.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-openapi/specs/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-openapi/specs/openapi.yaml ~/RuntaPythonSDK/contracts/runta-api.openapi.yaml
cd ~/RuntaPythonSDK
uv run python -m 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 python -m pytest --live
```

Local pytest loads `.env` automatically. The default local file uses:

```bash
RUNTA_ENDPOINT=http://127.0.0.1:8080
RUNTA_TOKEN=rt_your_token
```

Copy or edit `.env.example` for your local endpoint and token.

## Release

This repository publishes `runta-sdk` to PyPI from GitHub Releases.

1. Update `version` in `pyproject.toml`.
2. Run `uv run --extra dev python -m pytest`.
3. Run `rm -rf dist && uv build` and `uvx twine check dist/*`.
4. Commit the release change and create a GitHub Release whose tag is exactly
   `v{pyproject version}`, for example `v0.0.5`.

The `Publish SDK` workflow validates that the release tag matches
`pyproject.toml` and publishes the built distributions to PyPI with trusted
publishing.
