Examples, multi-tenant docs, alpha disclaimer

Co-Authored-By: Claude <noreply@anthropic.com>

Author: zeevdr

.github/workflows/ci.yml

@@ -5,6 +5,7 @@ on:
     branches: [main]
   pull_request:
     branches: [main]
+  workflow_call:
 
 jobs:
   lint:

README.md

@@ -8,6 +8,8 @@
 
 Python SDK for [OpenDecree](https://github.com/zeevdr/decree) — schema-driven configuration management.
 
+> **Alpha** — This SDK is under active development. APIs and behavior may change without notice between versions.
+
 ## Install
 
 ```bash
@@ -57,6 +59,18 @@ async with AsyncConfigClient("localhost:9090", subject="myapp") as client:
     retries = await client.get("tenant-id", "payments.retries", int)
 ```
 
+## Examples
+
+Runnable examples in the [`examples/`](examples/) directory:
+
+| Example | What it shows |
+|---------|--------------|
+| [quickstart](examples/quickstart/) | Context manager, typed `get()`, `set()` |
+| [async-client](examples/async-client/) | `async with`, `await`, `asyncio.gather()` |
+| [live-config](examples/live-config/) | `ConfigWatcher`, `@on_change`, `changes()` |
+| [fastapi-integration](examples/fastapi-integration/) | Async watcher as FastAPI lifespan dependency |
+| [error-handling](examples/error-handling/) | `RetryConfig`, `nullable=True`, error hierarchy |
+
 ## Documentation
 
 - [Quick Start](sdk/docs/quickstart.md)

examples/.gitignore

@@ -0,0 +1,4 @@
+.tenant-id
+__pycache__/
+*.pyc
+.venv/

examples/Makefile

@@ -0,0 +1,31 @@
+.PHONY: up setup test down clean help
+
+EXAMPLES := quickstart async-client live-config error-handling
+
+## up: Start the decree server (postgres + redis + migrations + service)
+up:
+	cd ../../decree && docker compose up -d --wait service
+
+## setup: Seed example schema, tenant, and config (writes .tenant-id)
+setup: up
+	python setup.py
+
+## test: Run all examples as smoke tests (run 'make setup' first)
+test:
+	@for dir in $(EXAMPLES); do \
+		echo "=== $$dir ==="; \
+		(cd $$dir && python -m pytest test_*.py -v) || exit 1; \
+	done
+
+## down: Stop the server and remove volumes
+down:
+	cd ../../decree && docker compose down -v
+
+## clean: Remove generated files
+clean:
+	rm -f .tenant-id
+	find . -type d -name __pycache__ -exec rm -rf {} + 2>/dev/null || true
+
+## help: Show this help
+help:
+	@grep -E '^## ' $(MAKEFILE_LIST) | sed 's/## //' | column -t -s ':'

examples/README.md

@@ -0,0 +1,63 @@
+# OpenDecree Python SDK Examples
+
+Runnable examples demonstrating the OpenDecree Python SDK.
+
+## Setup
+
+Start the decree server and seed example data:
+
+```bash
+# From this directory
+make setup
+```
+
+This starts PostgreSQL, Redis, and the decree server via Docker Compose,
+then creates an example schema, tenant, and initial config values.
+
+The tenant ID is written to `.tenant-id` — examples read it automatically.
+
+## Prerequisites
+
+```bash
+pip install opendecree
+```
+
+For the FastAPI example, also install:
+```bash
+pip install fastapi uvicorn
+```
+
+## Examples
+
+| Example | What it shows | Server required |
+|---------|--------------|-----------------|
+| [quickstart](quickstart/) | Context manager, typed `get()`, `set()` | Yes |
+| [async-client](async-client/) | `async with`, `await`, `asyncio.gather()` | Yes |
+| [live-config](live-config/) | `ConfigWatcher`, `@on_change` decorator, `changes()` iterator | Yes |
+| [fastapi-integration](fastapi-integration/) | `AsyncConfigWatcher` as FastAPI lifespan dependency | Yes |
+| [error-handling](error-handling/) | `RetryConfig`, `nullable=True`, error hierarchy | Yes |
+
+## Running an example
+
+```bash
+# After make setup:
+cd quickstart
+python main.py
+```
+
+Or run all examples as tests:
+
+```bash
+make test
+```
+
+## Teardown
+
+```bash
+make down
+```
+
+## Learn more
+
+- [Python SDK on PyPI](https://pypi.org/project/opendecree/)
+- [OpenDecree docs](https://github.com/zeevdr/decree)

examples/async-client/README.md

@@ -0,0 +1,28 @@
+# Async Client
+
+The same quickstart flow using `AsyncConfigClient` with `async`/`await`.
+
+## What it shows
+
+- `AsyncConfigClient` as an async context manager (`async with`)
+- `await client.get()` for non-blocking reads
+- `asyncio.gather()` for concurrent reads — faster than sequential
+- `await client.set_many()` for atomic multi-writes
+
+## Run
+
+```bash
+cd examples
+make setup
+cd async-client
+python main.py
+```
+
+## Next
+
+- [live-config](../live-config/) — async watcher with live updates
+- [fastapi-integration](../fastapi-integration/) — async client in a web app
+
+## Learn more
+
+- [Python SDK on PyPI](https://pypi.org/project/opendecree/)

examples/async-client/main.py

@@ -0,0 +1,78 @@
+#!/usr/bin/env python3
+"""Async Client: connect to OpenDecree using asyncio.
+
+Demonstrates the AsyncConfigClient — same API as ConfigClient but fully
+async. Uses `async with` for lifecycle and `await` for all operations.
+
+Run:
+    python main.py
+
+Requires a running decree server with seeded data (see ../README.md).
+"""
+
+import asyncio
+from datetime import timedelta
+from pathlib import Path
+
+from opendecree import AsyncConfigClient
+
+
+async def main() -> None:
+    tenant_id = get_tenant_id()
+
+    # Async context manager — closes the gRPC channel on exit.
+    async with AsyncConfigClient("localhost:9090", subject="async-example") as client:
+        # All operations are awaitable.
+        name = await client.get(tenant_id, "app.name")
+        print(f"app.name:          {name}")
+
+        debug = await client.get(tenant_id, "app.debug", bool)
+        print(f"app.debug:         {debug}")
+
+        rate_limit = await client.get(tenant_id, "server.rate_limit", int)
+        print(f"server.rate_limit: {rate_limit}")
+
+        timeout = await client.get(tenant_id, "server.timeout", timedelta)
+        print(f"server.timeout:    {timeout}")
+
+        fee_rate = await client.get(tenant_id, "payments.fee_rate", float)
+        print(f"payments.fee_rate: {fee_rate}")
+
+        # Concurrent reads with asyncio.gather — faster than sequential.
+        print("\nConcurrent reads:")
+        name, debug, rate_limit = await asyncio.gather(
+            client.get(tenant_id, "app.name"),
+            client.get(tenant_id, "app.debug", bool),
+            client.get(tenant_id, "server.rate_limit", int),
+        )
+        print(f"  app.name:          {name}")
+        print(f"  app.debug:         {debug}")
+        print(f"  server.rate_limit: {rate_limit}")
+
+        # Atomic multi-write.
+        await client.set_many(
+            tenant_id,
+            {"app.debug": "true", "server.rate_limit": "200"},
+            description="async example update",
+        )
+        print("\nUpdated app.debug=true, server.rate_limit=200")
+
+        debug = await client.get(tenant_id, "app.debug", bool)
+        rate_limit = await client.get(tenant_id, "server.rate_limit", int)
+        print(f"  app.debug:         {debug}")
+        print(f"  server.rate_limit: {rate_limit}")
+
+
+def get_tenant_id() -> str:
+    import os
+
+    if v := os.environ.get("TENANT_ID"):
+        return v
+    tenant_file = Path(__file__).parent.parent / ".tenant-id"
+    if tenant_file.exists():
+        return tenant_file.read_text().strip()
+    raise SystemExit("Set TENANT_ID env var or run 'make setup' from the examples directory")
+
+
+if __name__ == "__main__":
+    asyncio.run(main())

examples/async-client/test_async_client.py

@@ -0,0 +1,20 @@
+"""Smoke test for the async-client example."""
+
+import subprocess
+import sys
+
+import pytest
+
+
+@pytest.mark.example
+def test_async_client_runs() -> None:
+    """Verify the async-client example runs without errors."""
+    result = subprocess.run(
+        [sys.executable, "main.py"],
+        capture_output=True,
+        text=True,
+        timeout=30,
+    )
+    assert result.returncode == 0, f"stdout: {result.stdout}\nstderr: {result.stderr}"
+    assert "app.name:" in result.stdout
+    assert "Concurrent reads:" in result.stdout

examples/error-handling/README.md

@@ -0,0 +1,37 @@
+# Error Handling
+
+Retry configuration, nullable fields, and the typed error hierarchy.
+
+## What it shows
+
+- `RetryConfig` — customize retry attempts, backoff, and max delay
+- `nullable=True` — return `None` for missing values instead of raising
+- `set_null()` — explicitly null a field
+- Error hierarchy: `NotFoundError`, `InvalidArgumentError`, `DecreeError` base
+- Disabling retry with `retry=None`
+
+## Run
+
+```bash
+cd examples
+make setup
+cd error-handling
+python main.py
+```
+
+## Error types
+
+| Exception | When |
+|-----------|------|
+| `NotFoundError` | Field or tenant doesn't exist |
+| `InvalidArgumentError` | Value fails schema validation |
+| `LockedError` | Field is locked |
+| `ChecksumMismatchError` | Optimistic concurrency conflict |
+| `PermissionDeniedError` | Auth failure |
+| `UnavailableError` | Server unreachable (retryable) |
+| `TypeMismatchError` | SDK can't convert value to requested type |
+| `DecreeError` | Base class for all of the above |
+
+## Learn more
+
+- [Python SDK on PyPI](https://pypi.org/project/opendecree/)