# zrok Python SDK

The zrok Python SDK (`zrok2` on PyPI) provides a high-level interface for the zrok API and a lower-level
auto-generated REST client.

## Package structure

- **`src/zrok/`** — hand-written SDK modules: `share`, `access`, `name`, `listing`, `status`, `environment`, etc.
- **`src/zrok_api/`** — auto-generated OpenAPI client (do not edit by hand; regenerate with `bin/generate_rest.sh` from repo root)
- **`tests/`** — unit tests (mocked, no live services required)
- **`tests/integration/`** — integration tests (requires a running `zrok2` instance)
- **`examples/`** — runnable examples (http-server, pastebin, notebook proxy)

## Requirements

- Python >3.10 (3.12+ recommended for faster installs and broader wheel availability)
- Runtime dependencies are declared in `src/requirements.txt`
- Test dependencies are declared in `src/test-requirements.txt`

## Development setup

Create a virtual environment and install the SDK in editable mode with test extras:

```bash
python3 -m venv .venv
source .venv/bin/activate
pip install -e src/[test]
```

This installs the SDK, its runtime dependencies, `pytest`, and `pytest-cov`.

For the full test-requirements (includes `flake8`, `mypy`, `tox`):

```bash
pip install -r src/test-requirements.txt
```

## Regenerating the API client

`src/zrok_api/` is generated by the repo's REST generation script. Run this from the `zrok` repository root:

```bash
./bin/generate_rest.sh
```

This regenerates all REST clients/servers (including the Python client) from the modular OpenAPI sources.

## Running tests

### Unit tests

Unit tests mock the API and need no live infrastructure:

```bash
pytest src/ -v
```

Lint with flake8 (uses the `.flake8` config in this directory):

```bash
flake8 .
```

### Integration tests

Integration tests run against a live `zrok2` instance. They require two environment variables:

| Variable | Description |
| --- | --- |
| `ZROK2_API_ENDPOINT` | Controller URL, e.g. `http://zrok.example.com:18080` |
| `ZROK2_ADMIN_TOKEN` | Admin secret from the controller config |

The instance must have been bootstrapped with `zrok2-bootstrap.bash` (which creates the required
`public` namespace with `--open`).

```bash
ZROK2_API_ENDPOINT='http://localhost:18080' \
ZROK2_ADMIN_TOKEN='<token>' \
pytest tests/integration/ -v --tb=short
```

The easiest way to get a local instance is the
[Docker self-hosting guide](https://docs.zrok.io/docs/self-hosting/deployment/docker/).
To build from your local source instead of pulling release images, use the build overlay:

```bash
cd docker/compose/zrok2-instance
cp .env.example .env
# edit .env to set secrets (see the self-hosting guide for details)
COMPOSE_FILE=compose.yml:compose.build.yml \
  docker compose up -d --build --wait

# To tear down and remove all state (required before re-creating):
COMPOSE_FILE=compose.yml:compose.build.yml docker compose down -v
```

Or use the Linux package test harness (builds and installs packages, bootstraps all services):

```bash
bash nfpm/dangerous.linux.test.bash --keep
```

## CI

- **`ci-build.yml`** — runs unit tests and flake8 across Python 3.10–3.13
- **`integration-tests.yml`** — builds from source with Docker Compose, runs integration tests
- **`build-wheels.yml`** — builds and publishes to PyPI on release tags