runnee 0.1.0__tar.gz

runnee-0.1.0/.gitignore

@@ -0,0 +1,13 @@
+.venv/
+__pycache__/
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+dist/
+build/
+*.egg-info/
+
+.env
+.env.*
+!.env.example
+coverage/

runnee-0.1.0/CHANGELOG.md

@@ -0,0 +1,9 @@
+# Changelog
+
+## 0.1.0 — Unreleased
+
+Explicit API-key constructor arguments are supported; existing configuration remains compatible.
+
+Initial remote-only Runnee Cloud client: execution, retained history, saved scripts and versions, encrypted secret management, usage, sandbox limits, public plan/health information and scoped telemetry. Includes typed errors, bounded responses, timeouts, cancellation, safe retries and pagination.
+
+No package has been published by this implementation. API-key issuance, account management, payment mutations and remote cancellation remain unavailable to SDK API keys.

runnee-0.1.0/CONTRIBUTING.md

@@ -0,0 +1,29 @@
+# Contributing
+
+Thank you for contributing to the official Runnee Cloud SDK. This repository contains the remote API client only. Keep runtime, infrastructure and customer data out of changes.
+
+## Local checks
+
+Use Python 3.11 or later in a virtual environment.
+
+```sh
+python -m venv .venv
+# Activate .venv using your shell.
+python -m pip install -e ".[dev]"
+python -m pytest
+python -m mypy
+python -m ruff check .
+python -m ruff format --check .
+python -m build
+python -m twine check dist/*
+```
+
+## Pull requests
+
+Add regression coverage for behavior changes. Keep public names compatible and document changes in CHANGELOG.md. Never commit real API keys, secret values, .env files or customer responses. Tests use synthetic keys and local HTTP mocks; they neither execute customer scripts nor require production credentials. Live API verification belongs in an isolated staging account.
+
+The checked-in openapi.json is the public API contract snapshot. Coordinate API changes with the platform maintainers, then update this snapshot, client types, validation and tests together. Do not add methods for unimplemented endpoints.
+
+## Releases and security
+
+Follow [RELEASING.md](RELEASING.md). Use semantic versioning; breaking public changes require a major release (during 0.x, a new minor release). Security reports follow [SECURITY.md](SECURITY.md), rather than public issue reports.

runnee-0.1.0/LICENSE

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

runnee-0.1.0/PKG-INFO

@@ -0,0 +1,113 @@
+Metadata-Version: 2.5
+Name: runnee
+Version: 0.1.0
+Summary: Official synchronous and asynchronous Python SDK for Runnee Cloud
+Project-URL: Homepage, https://runnee.cloud/docs#sdk
+Project-URL: Repository, https://github.com/Runnee-cloud/runnee-sdk-python
+Project-URL: Issues, https://github.com/Runnee-cloud/runnee-sdk-python/issues
+Author: Runnee
+License-Expression: MIT
+License-File: LICENSE
+Keywords: runnee,sdk,serverless
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Typing :: Typed
+Requires-Python: >=3.11
+Requires-Dist: httpx<1,>=0.27
+Provides-Extra: dev
+Requires-Dist: build>=1.2; extra == 'dev'
+Requires-Dist: mypy>=1.15; extra == 'dev'
+Requires-Dist: pytest-asyncio>=0.25; extra == 'dev'
+Requires-Dist: pytest>=8; extra == 'dev'
+Requires-Dist: ruff>=0.11; extra == 'dev'
+Requires-Dist: twine>=6; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# runnee
+
+Official synchronous and asynchronous Python SDK for Runnee Cloud. Remote execution only; no interpreter is distributed. Python 3.11+; one runtime dependency, HTTPX.
+
+## Installation
+
+Release candidate: registry commands apply after publication. Local installation from this repository: pip install .
+
+```sh
+pip install runnee
+uv add runnee
+```
+
+## Quickstart
+
+Create a dashboard API key with scripts:execute and set RUNNEE_API_KEY on your server.
+
+```python
+import os
+from runnee import Runnee
+
+with Runnee(api_key=os.environ["RUNNEE_API_KEY"]) as client:
+    result = client.execute(code="function main() { return 10 + 20; }", mode="dry-run")
+    if result["success"] and "executionResult" in result:
+        print(result["executionResult"].get("returnValue"))
+```
+
+```python
+import os
+import asyncio
+from runnee import AsyncRunnee
+
+
+async def main():
+    async with AsyncRunnee(api_key=os.environ["RUNNEE_API_KEY"]) as client:
+        result = await client.execute(code="function main() { return 30; }")
+        print(result)
+
+
+asyncio.run(main())
+```
+
+Use AsyncRunnee in FastAPI async routes; Runnee suits synchronous Flask/Django views and jobs. Clients own reusable connection pools; close them or use context managers.
+
+## Configuration
+
+Runnee(api_key=..., base_url="https://api.runnee.cloud", timeout=30, max_retries=2) and AsyncRunnee accept identical configuration. RUNNEE_BASE_URL is an optional fallback. timeout is seconds. HTTP requires loopback or explicit allow_insecure_http development use; redirects and environment proxy inheritance are disabled. Custom HTTPX transports support controlled testing.
+
+RequestOptions(timeout=..., max_retries=..., idempotency_key=..., cancel_event=..., on_response=...) supplies per-call behavior. Async client cancellation uses asyncio task cancellation. Sync cancel_event is checked between attempts and received response chunks; an in-flight socket can wait until its HTTPX timeout. Async timeout bounds the complete operation; sync uses the remaining budget for network timeouts and checks the deadline while receiving chunks and between attempts. A client timeout does not change the script execution budget.
+
+## API reference
+
+- execute(code=..., mode="dry-run", event=..., retain_source=False, script_name=..., secret_names=..., script_id=..., options=...)
+- executions.list(before=..., status=..., mode=...), get(id), iterate(...). Use for in sync or async for in async code. Pages contain at most20 items; history retention is3days.
+- scripts.list(), create(name=..., code=...), get(id), update(id,name=...,code=...,expected_version=...), delete(id), get_version(id,version), restore(id,version=...,expected_version=...), storage().
+- secrets.list(), get(name), create(name=...,value=...,allow_inline=False,script_ids=...), update(name,value=...,allow_inline=...,script_ids=...), delete(name).
+- usage.get(), summary(), history(days=7|30|90); sandbox.get(); billing.plans(); health.get().
+- telemetry.record_execution(input), record_event(input). External execution records consume quota.
+
+Async methods use the same names with await. Returned dictionaries follow API camelCase names and have generated TypedDict definitions in runnee.types. Arguments follow Python snake_case. SDK API-key issuance/revocation, account/payment mutations and remote execution cancellation are not supported.
+
+## Secret usage
+
+```python
+import os
+from runnee import Runnee
+
+with Runnee(api_key=os.environ["RUNNEE_API_KEY"]) as client:
+    client.secrets.create(name="EXTERNAL_API_KEY", value=os.environ["EXTERNAL_API_KEY"], allow_inline=True)
+    result = client.execute(
+        code='use("secrets"); function main() { return secrets.has("EXTERNAL_API_KEY"); }',
+        secret_names=["EXTERNAL_API_KEY"],
+    )
+    client.secrets.update("EXTERNAL_API_KEY", value=os.environ["REPLACEMENT_API_KEY"])
+    client.secrets.delete("EXTERNAL_API_KEY")
+```
+
+Metadata is readable with secrets:read; writes require secrets:write; grants require scripts:execute and secrets:use. Prefer script_ids policies over allow_inline; execute with script_id and the exact current saved source. Secrets remain inaccessible until explicitly named on an execution. Management responses never contain values. See SECURITY.md for disclosure boundaries.
+
+## Reliability and errors
+
+Read requests retry transient network failures and 429/500/502/503/504 with exponential jitter and Retry-After. Auth failures are never retried. Writes are not retried by default. Execute retries require an idempotency_key in RequestOptions. Reuse it after an uncertain network failure. Receipts expire after24hours and replay only summaries, not original output; HTTP409 can mean the original execution is pending. Inspect history before choosing a new key.
+
+RunneeError subclasses: RunneeAuthenticationError, RunneePermissionError, RunneeValidationError, RunneeRateLimitError, RunneeTimeoutError, RunneeNetworkError, RunneeServerError, RunneeConflictError, RunneeNotFoundError, RunneeResponseError, RunneeCancelledError. Errors expose status/request_id; RateLimit exposes retry_after seconds. Script failures return success=False instead of raising an HTTP exception.
+
+## Development
+
+pip install -e '.[dev]'; pytest; mypy; ruff check .; ruff format --check .; python -m build. CI tests supported Python versions and both clients. See CONTRIBUTING.md, CHANGELOG.md and RELEASING.md. MIT licensed. Publication is a separate approved release step.

runnee-0.1.0/README.md

@@ -0,0 +1,88 @@
+# runnee
+
+Official synchronous and asynchronous Python SDK for Runnee Cloud. Remote execution only; no interpreter is distributed. Python 3.11+; one runtime dependency, HTTPX.
+
+## Installation
+
+Release candidate: registry commands apply after publication. Local installation from this repository: pip install .
+
+```sh
+pip install runnee
+uv add runnee
+```
+
+## Quickstart
+
+Create a dashboard API key with scripts:execute and set RUNNEE_API_KEY on your server.
+
+```python
+import os
+from runnee import Runnee
+
+with Runnee(api_key=os.environ["RUNNEE_API_KEY"]) as client:
+    result = client.execute(code="function main() { return 10 + 20; }", mode="dry-run")
+    if result["success"] and "executionResult" in result:
+        print(result["executionResult"].get("returnValue"))
+```
+
+```python
+import os
+import asyncio
+from runnee import AsyncRunnee
+
+
+async def main():
+    async with AsyncRunnee(api_key=os.environ["RUNNEE_API_KEY"]) as client:
+        result = await client.execute(code="function main() { return 30; }")
+        print(result)
+
+
+asyncio.run(main())
+```
+
+Use AsyncRunnee in FastAPI async routes; Runnee suits synchronous Flask/Django views and jobs. Clients own reusable connection pools; close them or use context managers.
+
+## Configuration
+
+Runnee(api_key=..., base_url="https://api.runnee.cloud", timeout=30, max_retries=2) and AsyncRunnee accept identical configuration. RUNNEE_BASE_URL is an optional fallback. timeout is seconds. HTTP requires loopback or explicit allow_insecure_http development use; redirects and environment proxy inheritance are disabled. Custom HTTPX transports support controlled testing.
+
+RequestOptions(timeout=..., max_retries=..., idempotency_key=..., cancel_event=..., on_response=...) supplies per-call behavior. Async client cancellation uses asyncio task cancellation. Sync cancel_event is checked between attempts and received response chunks; an in-flight socket can wait until its HTTPX timeout. Async timeout bounds the complete operation; sync uses the remaining budget for network timeouts and checks the deadline while receiving chunks and between attempts. A client timeout does not change the script execution budget.
+
+## API reference
+
+- execute(code=..., mode="dry-run", event=..., retain_source=False, script_name=..., secret_names=..., script_id=..., options=...)
+- executions.list(before=..., status=..., mode=...), get(id), iterate(...). Use for in sync or async for in async code. Pages contain at most20 items; history retention is3days.
+- scripts.list(), create(name=..., code=...), get(id), update(id,name=...,code=...,expected_version=...), delete(id), get_version(id,version), restore(id,version=...,expected_version=...), storage().
+- secrets.list(), get(name), create(name=...,value=...,allow_inline=False,script_ids=...), update(name,value=...,allow_inline=...,script_ids=...), delete(name).
+- usage.get(), summary(), history(days=7|30|90); sandbox.get(); billing.plans(); health.get().
+- telemetry.record_execution(input), record_event(input). External execution records consume quota.
+
+Async methods use the same names with await. Returned dictionaries follow API camelCase names and have generated TypedDict definitions in runnee.types. Arguments follow Python snake_case. SDK API-key issuance/revocation, account/payment mutations and remote execution cancellation are not supported.
+
+## Secret usage
+
+```python
+import os
+from runnee import Runnee
+
+with Runnee(api_key=os.environ["RUNNEE_API_KEY"]) as client:
+    client.secrets.create(name="EXTERNAL_API_KEY", value=os.environ["EXTERNAL_API_KEY"], allow_inline=True)
+    result = client.execute(
+        code='use("secrets"); function main() { return secrets.has("EXTERNAL_API_KEY"); }',
+        secret_names=["EXTERNAL_API_KEY"],
+    )
+    client.secrets.update("EXTERNAL_API_KEY", value=os.environ["REPLACEMENT_API_KEY"])
+    client.secrets.delete("EXTERNAL_API_KEY")
+```
+
+Metadata is readable with secrets:read; writes require secrets:write; grants require scripts:execute and secrets:use. Prefer script_ids policies over allow_inline; execute with script_id and the exact current saved source. Secrets remain inaccessible until explicitly named on an execution. Management responses never contain values. See SECURITY.md for disclosure boundaries.
+
+## Reliability and errors
+
+Read requests retry transient network failures and 429/500/502/503/504 with exponential jitter and Retry-After. Auth failures are never retried. Writes are not retried by default. Execute retries require an idempotency_key in RequestOptions. Reuse it after an uncertain network failure. Receipts expire after24hours and replay only summaries, not original output; HTTP409 can mean the original execution is pending. Inspect history before choosing a new key.
+
+RunneeError subclasses: RunneeAuthenticationError, RunneePermissionError, RunneeValidationError, RunneeRateLimitError, RunneeTimeoutError, RunneeNetworkError, RunneeServerError, RunneeConflictError, RunneeNotFoundError, RunneeResponseError, RunneeCancelledError. Errors expose status/request_id; RateLimit exposes retry_after seconds. Script failures return success=False instead of raising an HTTP exception.
+
+## Development
+
+pip install -e '.[dev]'; pytest; mypy; ruff check .; ruff format --check .; python -m build. CI tests supported Python versions and both clients. See CONTRIBUTING.md, CHANGELOG.md and RELEASING.md. MIT licensed. Publication is a separate approved release step.

runnee-0.1.0/RELEASING.md

@@ -0,0 +1,31 @@
+# Releasing
+
+This repository is prepared for public release but no registry publication is implied by its presence. Never publish before the matching API and secrets features have passed staging verification. The SDK does not deploy or configure the service.
+
+## GitHub setup (maintainer)
+
+Create an empty **public** repository named runnee-sdk-python under `Runnee-cloud` (or update all repository URLs first). From the prepared SDK folder:
+
+```sh
+git init -b main
+git add .
+git commit -m "Initial public SDK release"
+git remote add origin https://github.com/Runnee-cloud/runnee-sdk-python.git
+git push -u origin main
+```
+
+Review `git diff --cached` before committing. Never upload the parent application repository. Enable GitHub private vulnerability reporting, dependency alerts and branch protection. Create the `pypi` GitHub Actions environment; restrict it to main and require a maintainer review if available for your account. The workflow only publishes when manually requested with publish=true on main. Ordinary pushes and tags run CI only. A manual run with publish=false builds downloadable artifacts without publishing.
+
+## Versioning
+
+Use semantic versioning. Update all version constants and CHANGELOG.md together. Search for the previous version in tracked files, including HTTP User-Agent strings; review the diff and regenerate distribution files. The workflow checks the expected version before building. Once published, treat versioned artifacts as immutable. After publication, tag the exact tested commit `vVERSION` and attach checksums and artifacts to a GitHub release.
+
+## PyPI
+
+1. Confirm `runnee` availability and ownership at https://pypi.org/project/runnee/. A 404 does not reserve the name. If unavailable, select another distribution name and update pyproject.toml and installation documentation consistently.
+2. Run the checks in CONTRIBUTING.md, `python -m build`, and `python -m twine check dist/*`. Inspect both the wheel and source archive.
+3. In your PyPI account, add a **pending publisher** for project `runnee`: owner `Runnee-cloud`, repository `runnee-sdk-python`, workflow `release.yml`, environment `pypi`. For an existing project, add the same configuration in its Publishing settings.
+4. Actions → Release → Run workflow on main; set the expected version and publish=true. Approve the pypi environment job. The workflow publishes the previously built distributions using OIDC; no PyPI token belongs in GitHub secrets.
+5. Verify in a clean environment using `pip install runnee==VERSION` and check sync and async imports. Also verify `uv add runnee==VERSION`.
+
+See [PyPI pending publishers](https://docs.pypi.org/trusted-publishers/creating-a-project-through-oidc/) and [publishing with OIDC](https://docs.pypi.org/trusted-publishers/using-a-publisher/).

runnee-0.1.0/SECURITY.md

@@ -0,0 +1,11 @@
+# Security policy
+
+Report vulnerabilities privately through GitHub private vulnerability reporting for the repository, when enabled. If unavailable, use the Runnee contact form and request a private security channel; do not post credentials or exploitable details publicly.
+
+API keys belong only on trusted servers. These SDKs execute code remotely and contain no interpreter. Requests use HTTPS by default, do not follow redirects, and do not log credentials or retain raw response bodies in exceptions. HTTP is limited to loopback unless explicitly enabled for development. Never disable TLS verification in production.
+
+Only the latest released minor version receives fixes while the SDK is pre-1.0. Dependencies should be patched promptly. Caller-provided transports are trusted code and must preserve authentication and TLS protections.
+
+Execution retries require an idempotency key. Receipt replays omit the original output, and a pending result is not evidence that execution failed. Client cancellation stops waiting; it does not guarantee remote cancellation.
+
+Secrets are encrypted by Runnee and granted explicitly to executions. Management returns metadata only. Do not put credentials in script source, events, telemetry, replies or errors. Redaction covers common accidental verbatim/encoded disclosure; it cannot stop an authorized malicious script from transforming or sending a secret to an external endpoint. Review secret-enabled scripts and narrow HTTP permissions. SDK request bodies necessarily contain values during create/rotate; configure application/APM instrumentation to omit them.

runnee-0.1.0/examples/async_quickstart.py

@@ -0,0 +1,13 @@
+import os
+import asyncio
+from runnee import AsyncRunnee
+
+
+async def main() -> None:
+    async with AsyncRunnee(api_key=os.environ["RUNNEE_API_KEY"]) as client:
+        result = await client.execute(code="function main(){return 10+20;}")
+        print(result)
+
+
+if __name__ == "__main__":
+    asyncio.run(main())

runnee-0.1.0/examples/quickstart.py

@@ -0,0 +1,6 @@
+import os
+from runnee import Runnee
+
+with Runnee(api_key=os.environ["RUNNEE_API_KEY"]) as client:
+    result = client.execute(code="function main(){return 10+20;}", mode="dry-run")
+    print(result)