Metadata-Version: 2.4
Name: whodb-sdk
Version: 0.135.0
Summary: Official Python SDK for the WhoDB hosted platform — ontology, datasets, and sources as in-code function APIs
Author: Clidey, Inc.
License-Expression: Apache-2.0
Project-URL: Homepage, https://whodb.com
Project-URL: Repository, https://github.com/clidey/whodb
Keywords: whodb,ontology,data,sdk
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Requires-Python: >=3.10
Description-Content-Type: text/markdown
Requires-Dist: httpx>=0.27
Provides-Extra: dev
Requires-Dist: ruff==0.16.9; extra == "dev"

# whodb-sdk

Official Python SDK for the [WhoDB](https://whodb.com) hosted platform — your
ontology, datasets, sources, transforms, functions, and org administration as
in-code function APIs.

## Install

```bash
pip install whodb-sdk
```

Requires Python ≥ 3.10.

## Quickstart

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

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

## License

Apache-2.0
