whodb-sdk

Official Python SDK for the WhoDB hosted platform — your ontology, datasets, sources, transforms, functions, and org administration as in-code function APIs.

Install

pip install whodb-sdk

Requires Python ≥ 3.10.

Quickstart

import os
from whodb import WhoDB

# Production: API key (create one in org settings → API keys).
whodb = WhoDB(api_key=os.environ["WHODB_API_KEY"])

# Local development: zero config — reuses your `whodb login` session.
# whodb = WhoDB()

users = whodb.ontology("User")

user = users.get("u_123")
active = users.list(where={"status": {"eq": "active"}}, page_size=100).all()
users.create({"email": "a@b.co"})
users.create_many(rows, idempotency_key="import-42")
users.update("u_123", {"plan": "pro"})
orders = users.follow_link("u_123", "orders").all()

# Behavior-managed workflow:
order = whodb.ontology("Order")
capabilities = order.capabilities("order_123")
order.preview_action("approve", "order_123", {"note": "Looks good"})
order.action(
    "approve", "order_123", {"note": "Looks good"},
    expected_version=capabilities.get("recordVersion"),
    idempotency_key="approve-order-123",
)
history = order.action_executions("order_123")

# Iterate everything, page by page:
for page in users.list(page_size=500).pages():
    print(len(page.rows))

# Datasets, transforms, functions:
kpis = whodb.dataset("weekly_kpis").rows()
rollup = whodb.transform("nightly-rollup")
run = rollup.run()
rollup.wait(run["id"], timeout_ms=300_000)
fn = whodb.function("normalize")
fn.promote("v1")  # snapshot + set active production version
result = fn.execute({"name": "Ada"})
versions = whodb.versions().list("function", fn.meta()["id"])

# Org administration (requires org manage rights):
sa = whodb.service_accounts().create("ci-deployer")
raw_key = whodb.service_accounts().create_key(sa["id"])["rawKey"]  # shown once — store it securely
whodb.sharing().share("ont_...", "organization")

# Async client:
from whodb import AsyncWhoDB
awhodb = AsyncWhoDB(api_key=os.environ["WHODB_API_KEY"])
user = await awhodb.ontology("User").get("u_123")

Authentication

Credential precedence: constructor args (api_key= / token= / credentials=) → WHODB_API_KEY env var → the whodb CLI's stored login. Workspace (org= / project=) is optional with an API key; pass project= when the key has access to more than one project.

Inside a WhoDB Function, WhoDB() auto-detects the runtime and needs no configuration at all.

Typed clients

whodb sdk generate --language python --out whodb_gen/

License

Apache-2.0