# Code Sandbox Python SDK

Use the Code Sandbox API to run code in 10+ languages from Python.

## Install

```bash
pip install code-sandbox-sdk
```

Or from source in this repo:

```bash
pip install -e packages/python-sdk
```

## Usage

**Cloud (API key required):**

```python
from code_sandbox import Client

client = Client(api_key="your-api-key")

# Execute code
result = client.execute(language="python", code="print(2 + 2)")
print(result.stdout)   # 4
print(result.success)  # True
print(result.exit_code)  # 0

# List runtimes
for r in client.runtimes():
    print(r.language, r.version)
```

**Local Piston (no API key):**

```python
from code_sandbox import create_local_client

client = create_local_client(base_url="http://localhost:2000/api/v2")
result = client.execute(language="python", code="print(2 + 2)")
print(result.stdout)   # 4
# If nothing prints, check result.success, result.error, result.stderr
```

**Troubleshooting local Piston:** If `result.stdout` is empty, always check `result.error` and `result.stderr` — they will show the real error (e.g. "runtime is unknown" means you need to install the Python runtime inside the Piston container using the [Piston CLI](https://github.com/engineer-man/piston#cli)). Run the test script: `python test_local.py` (from this package directory) to see success/stdout/stderr/error.

## API

- **Client(api_key, base_url=None)** – Create a client. `base_url` defaults to `http://localhost:3001`.
- **create_local_client(base_url=None)** – Create a client for local Piston (Docker). No API key required.
- **client.execute(language, code, stdin=None, version=None)** – Run code. Returns an **ExecuteResult** with `success`, `stdout`, `stderr`, `exit_code`, `run_time_ms`, `error`, `compile_output`.
- **client.runtimes()** – List supported languages and versions. Returns a list of **Runtime** objects with `language`, `version`, `aliases`.

## Publishing to PyPI

For maintainers: to upload a new version to PyPI, build and upload with:

```bash
pip install build twine
python -m build
twine upload dist/* -u __token__ -p <PYPI_API_TOKEN>
```

**PyPI API token (for later reference; keep secure, do not commit to a public repo):**

```
pypi-AgEIcHlwaS5vcmcCJDNmM2ZlNmFmLTYxYmItNGRmYS04NDJlLWI2NzY1YWJlNjI5ZgACKlszLCJlMWZjMmY1NS05NGE0LTRmZDMtYTY0OS05MTdjMzRlMTQ4NDkiXQAABiBsLP17pnp737nYcpNRSdYRDWF8IB6vXD4BqqmjFOVRLw
```

Or set `TWINE_USERNAME=__token__` and `TWINE_PASSWORD` to the token above when running `twine upload dist/*`.
