Metadata-Version: 2.4
Name: cdbx-run
Version: 0.1.1
Summary: Python SDK for the cdbx Runner API — execute code in a secure sandbox
Project-URL: Homepage, https://cdbx.ai
Project-URL: Documentation, https://cdbx.ai/docs/how-to-use-cdbx/runner-api
License: MIT
Keywords: cdbx,code-execution,runner,sandbox,sdk
Requires-Python: >=3.9
Requires-Dist: requests>=2.28
Provides-Extra: dev
Requires-Dist: pytest-mock>=3.12; extra == 'dev'
Requires-Dist: pytest>=8.0; extra == 'dev'
Description-Content-Type: text/markdown

# cdbx-run

Python SDK for the [cdbx Runner API](https://cdbx.ai/docs/how-to-use-cdbx/runner-api) — execute code in a secure sandbox from any Python script or agent.

## Install

```bash
pip install cdbx-run
```

## Usage

```python
from cdbx_run import CdbxRunner

runner = CdbxRunner(api_key="cdbx_your_key_here")

result = runner.run(language="python", code='print("Hello, world!")')

print(result.stdout)   # "Hello, world!\n"
print(result.exit_code)  # 0
```

### Convenience function

```python
from cdbx_run import run

result = run("cdbx_your_key_here", language="python", code='print("Hello")')
```

### With stdin

```python
result = runner.run(
    language="python",
    code="name = input()\nprint(f'Hello, {name}!')",
    stdin="world",
)
```

### With timeout

```python
result = runner.run(
    language="python",
    code="import time; time.sleep(5)",
    timeout=3,  # seconds — capped by your tier
)
```

### As a context manager

```python
with CdbxRunner(api_key="cdbx_your_key_here") as runner:
    result = runner.run(language="go", code='package main\nimport "fmt"\nfunc main() { fmt.Println("Hello") }')
```

## Error handling

```python
from cdbx_run import CdbxRunner
from cdbx_run.errors import AuthError, QuotaExceededError, CdbxRunnerError

try:
    result = runner.run(language="python", code="...")
except AuthError:
    print("Invalid or missing API key")
except QuotaExceededError as e:
    print(f"Quota exceeded — retry after {e.retry_after}s")
except CdbxRunnerError as e:
    print(f"API error {e.status}: {e}")
```

## Rate limit info

```python
result = runner.run(language="python", code="...")

if result.rate_limit:
    print(f"{result.rate_limit.remaining} / {result.rate_limit.limit} executions remaining")
```

## Supported languages

30 languages including Python, JavaScript, TypeScript, Go, Rust, Java, C, C++, Ruby, PHP, Swift, and more. Full list in the [API docs](https://cdbx.ai/docs/how-to-use-cdbx/runner-api).

## API key

Generate a key at **cdbx.ai → Developer → API Keys**. Select the **Runner API** scope.

## License

MIT
