zrok/sdk/python/README.md

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:

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):

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:

./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:

pytest src/ -v

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

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).

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. To build from your local source instead of pulling release images, use the build overlay:

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 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