whodb-sdk 0.127.0__tar.gz

whodb_sdk-0.127.0/PKG-INFO

@@ -0,0 +1,83 @@
+Metadata-Version: 2.4
+Name: whodb-sdk
+Version: 0.127.0
+Summary: Official Python SDK for the WhoDB hosted platform — ontology, datasets, and sources as in-code function APIs
+Author: Clidey, Inc.
+License: 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
+
+# whodb-sdk
+
+Official Python SDK for the [WhoDB](https://whodb.com) hosted platform — your
+ontology, datasets, and sources 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()
+
+# Iterate everything, page by page:
+for page in users.list(page_size=500).pages():
+    print(len(page.rows))
+
+# 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

whodb_sdk-0.127.0/README.md

@@ -0,0 +1,63 @@
+# whodb-sdk
+
+Official Python SDK for the [WhoDB](https://whodb.com) hosted platform — your
+ontology, datasets, and sources 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()
+
+# Iterate everything, page by page:
+for page in users.list(page_size=500).pages():
+    print(len(page.rows))
+
+# 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

whodb_sdk-0.127.0/pyproject.toml

@@ -0,0 +1,30 @@
+[build-system]
+requires = ["setuptools>=68"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "whodb-sdk"
+version = "0.127.0"
+description = "Official Python SDK for the WhoDB hosted platform — ontology, datasets, and sources as in-code function APIs"
+readme = "README.md"
+license = { text = "Apache-2.0" }
+requires-python = ">=3.10"
+dependencies = ["httpx>=0.27"]
+authors = [{ name = "Clidey, Inc." }]
+keywords = ["whodb", "ontology", "data", "sdk"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+]
+
+[project.urls]
+Homepage = "https://whodb.com"
+Repository = "https://github.com/clidey/whodb"
+
+[tool.setuptools.packages.find]
+where = ["src"]

whodb_sdk-0.127.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

whodb_sdk-0.127.0/src/whodb/__init__.py

@@ -0,0 +1,50 @@
+"""Official Python SDK for the WhoDB hosted platform.
+
+```python
+from whodb import WhoDB
+
+whodb = WhoDB(api_key=os.environ["WHODB_API_KEY"])
+user = whodb.ontology("User").get("u_123")
+```
+"""
+
+from ._auth import CliCredentials, StaticCredentials
+from ._errors import (
+    AuthError,
+    CliCredentialsError,
+    NotFoundError,
+    PlatformError,
+    TransportCapabilityError,
+    ValidationError,
+    WhoDBError,
+    WhoDBVersionError,
+)
+from ._pagination import ListCall, Page
+from ._version import SDK_VERSION
+from .client import DEFAULT_HOST, AsyncWhoDB, WhoDB
+from .dataset import DatasetHandle
+from .ontology import OntologyHandle
+from .source import SourceHandle
+
+__version__ = SDK_VERSION
+
+__all__ = [
+    "WhoDB",
+    "AsyncWhoDB",
+    "DEFAULT_HOST",
+    "OntologyHandle",
+    "DatasetHandle",
+    "SourceHandle",
+    "ListCall",
+    "Page",
+    "WhoDBError",
+    "AuthError",
+    "NotFoundError",
+    "ValidationError",
+    "WhoDBVersionError",
+    "CliCredentialsError",
+    "TransportCapabilityError",
+    "PlatformError",
+    "StaticCredentials",
+    "CliCredentials",
+]

whodb_sdk-0.127.0/src/whodb/_async_ontology.py

@@ -0,0 +1,173 @@
+"""Async twin of OntologyHandle. Same behavior, awaitable surface."""
+
+from __future__ import annotations
+
+import json
+from typing import Any, AsyncIterator, Awaitable, Callable, Optional
+
+from ._errors import NotFoundError, ValidationError
+from ._generated import operations as ops
+from ._hydrate import hydrate_rows, property_types_of
+from ._manifest_check import warn_if_flagged
+from .ontology import _DEFAULT_PAGE_SIZE, _to_record_inputs
+
+
+class AsyncOntologyHandle:
+    """Awaitable handle for one ontology entity, addressed by apiName."""
+
+    def __init__(
+        self,
+        execute: Callable[[ops.Request], Awaitable[Any]],
+        project_id: Callable[[], Awaitable[str]],
+        api_name: str,
+    ):
+        self._execute = execute
+        self._project_id = project_id
+        self._api_name = api_name
+        self._entity_cache: Optional[dict] = None
+
+    async def entity_meta(self) -> dict:
+        """Resolve and cache the entity metadata backing this handle."""
+        if self._entity_cache is not None:
+            return self._entity_cache
+        warn_if_flagged("OntologyEntities")
+        entities = await self._execute(
+            ops.ontology_entities_request({"projectId": await self._project_id()})
+        )
+        entity = next((e for e in entities or [] if e.get("apiName") == self._api_name), None)
+        if entity is None:
+            raise NotFoundError(f'ontology entity "{self._api_name}" not found in this project')
+        self._entity_cache = entity
+        return entity
+
+    async def get(self, pk: Any) -> Optional[dict]:
+        """Fetch a single record by primary key, or None when absent."""
+        entity = await self.entity_meta()
+        primary_key = entity.get("primaryKey")
+        if not primary_key:
+            raise ValidationError(
+                f'entity "{self._api_name}" has no primary key — use list() with a where filter'
+            )
+        warn_if_flagged("OntologyQuery")
+        result = await self._execute(
+            ops.ontology_query_request(
+                {
+                    "projectId": await self._project_id(),
+                    "input": {
+                        "entity": self._api_name,
+                        "whereJson": json.dumps({primary_key: {"eq": str(pk)}}),
+                        "pageSize": 1,
+                        "offset": 0,
+                    },
+                }
+            )
+        )
+        rows, _ = hydrate_rows(result, property_types_of(entity))
+        return rows[0] if rows else None
+
+    async def list(
+        self,
+        where: Optional[dict] = None,
+        sort: Optional[list[dict]] = None,
+        page_size: int = _DEFAULT_PAGE_SIZE,
+        page_offset: int = 0,
+    ) -> list[dict]:
+        """List one page of records with optional filter/sort."""
+        entity = await self.entity_meta()
+        warn_if_flagged("OntologyQuery")
+        result = await self._execute(
+            ops.ontology_query_request(
+                {
+                    "projectId": await self._project_id(),
+                    "input": {
+                        "entity": self._api_name,
+                        "whereJson": json.dumps(where) if where else None,
+                        "sort": sort,
+                        "pageSize": page_size,
+                        "offset": page_offset,
+                    },
+                }
+            )
+        )
+        rows, _ = hydrate_rows(result, property_types_of(entity))
+        return rows
+
+    async def pages(
+        self, where: Optional[dict] = None, page_size: int = _DEFAULT_PAGE_SIZE
+    ) -> AsyncIterator[list[dict]]:
+        """Iterate every page until a short page signals the end."""
+        offset = 0
+        while True:
+            rows = await self.list(where=where, page_size=page_size, page_offset=offset)
+            yield rows
+            if len(rows) < page_size:
+                return
+            offset += page_size
+
+    async def create(self, values: dict[str, Any]) -> None:
+        """Insert one record."""
+        entity = await self.entity_meta()
+        warn_if_flagged("OntologyAddRow")
+        await self._execute(
+            ops.ontology_add_row_request(
+                {
+                    "projectId": await self._project_id(),
+                    "entityId": entity["id"],
+                    "values": _to_record_inputs(values),
+                }
+            )
+        )
+
+    async def create_many(self, rows: list[dict[str, Any]], idempotency_key: Optional[str] = None) -> dict:
+        """Insert many records with optional idempotency key."""
+        entity = await self.entity_meta()
+        warn_if_flagged("OntologyAddRows")
+        return await self._execute(
+            ops.ontology_add_rows_request(
+                {
+                    "projectId": await self._project_id(),
+                    "entityId": entity["id"],
+                    "rows": [{"values": _to_record_inputs(row)} for row in rows],
+                    "idempotencyKey": idempotency_key,
+                }
+            )
+        )
+
+    async def update(self, pk: Any, values: dict[str, Any]) -> None:
+        """Update one record identified by primary key."""
+        entity = await self.entity_meta()
+        primary_key = entity.get("primaryKey")
+        if not primary_key:
+            raise ValidationError(
+                f'entity "{self._api_name}" has no primary key — updates are not supported'
+            )
+        warn_if_flagged("OntologyUpdateRow")
+        await self._execute(
+            ops.ontology_update_row_request(
+                {
+                    "projectId": await self._project_id(),
+                    "entityId": entity["id"],
+                    "values": _to_record_inputs({**values, primary_key: str(pk)}),
+                    "updatedColumns": list(values.keys()),
+                }
+            )
+        )
+
+    async def delete(self, pk: Any) -> None:
+        """Delete one record identified by primary key."""
+        entity = await self.entity_meta()
+        primary_key = entity.get("primaryKey")
+        if not primary_key:
+            raise ValidationError(
+                f'entity "{self._api_name}" has no primary key — deletes are not supported'
+            )
+        warn_if_flagged("OntologyDeleteRow")
+        await self._execute(
+            ops.ontology_delete_row_request(
+                {
+                    "projectId": await self._project_id(),
+                    "entityId": entity["id"],
+                    "values": _to_record_inputs({primary_key: str(pk)}),
+                }
+            )
+        )

whodb_sdk-0.127.0/src/whodb/_auth.py

@@ -0,0 +1,122 @@
+"""Credential providers, mirrored from the TypeScript SDK's auth.ts."""
+
+from __future__ import annotations
+
+import json
+import subprocess
+from datetime import datetime, timedelta, timezone
+from typing import Callable, Optional, Protocol
+
+from ._errors import AuthError, CliCredentialsError
+
+_CLI_REFRESH_SKEW = timedelta(seconds=60)
+
+
+class CredentialProvider(Protocol):
+    """Yields a bearer credential; refresh() runs once after a 401."""
+
+    def token(self) -> str: ...
+
+    def refresh(self) -> None: ...
+
+    def defaults(self) -> dict:
+        """Workspace defaults carried by the credential source, if any."""
+        ...
+
+
+class StaticCredentials:
+    """Static API-key or raw-token credentials (production/headless usage)."""
+
+    def __init__(self, value: str):
+        self._value = value
+
+    def token(self) -> str:
+        """Return the configured credential."""
+        return self._value
+
+    def refresh(self) -> None:
+        """Static credentials cannot refresh; no-op."""
+
+    def defaults(self) -> dict:
+        """Static credentials carry no workspace defaults."""
+        return {}
+
+
+class CallbackCredentials:
+    """Caller-managed token callback."""
+
+    def __init__(self, callback: Callable[[], str]):
+        self._callback = callback
+
+    def token(self) -> str:
+        """Return a token from the caller's callback."""
+        return self._callback()
+
+    def refresh(self) -> None:
+        """The callback is consulted every call; nothing to invalidate."""
+
+    def defaults(self) -> dict:
+        """Callback credentials carry no workspace defaults."""
+        return {}
+
+
+class CliCredentials:
+    """CLI credentials: exec `whodb auth print-token` and cache until expiry.
+
+    The gcloud-ADC pattern for local development — requires the whodb CLI on
+    PATH and a prior `whodb login`.
+    """
+
+    def __init__(self, command: str = "whodb"):
+        self._command = command
+        self._cached: Optional[dict] = None
+
+    def _exec(self) -> dict:
+        try:
+            completed = subprocess.run(
+                [self._command, "auth", "print-token", "--format", "json"],
+                capture_output=True,
+                timeout=15,
+                check=False,
+            )
+        except FileNotFoundError as exc:
+            raise CliCredentialsError(
+                "whodb CLI not found — install it or set WHODB_API_KEY"
+            ) from exc
+        if completed.returncode != 0:
+            detail = completed.stderr.decode(errors="replace").strip()
+            raise CliCredentialsError(f"whodb auth print-token failed: {detail}")
+        try:
+            return json.loads(completed.stdout)
+        except json.JSONDecodeError as exc:
+            raise CliCredentialsError("whodb auth print-token returned invalid JSON") from exc
+
+    def _is_fresh(self, entry: dict) -> bool:
+        expires_at = entry.get("expires_at")
+        if not expires_at:
+            return False  # no expiry info — re-exec every call
+        expiry = datetime.fromisoformat(expires_at.replace("Z", "+00:00"))
+        return expiry - datetime.now(timezone.utc) > _CLI_REFRESH_SKEW
+
+    def token(self) -> str:
+        """Return a fresh access token, re-execing the CLI near expiry."""
+        if self._cached is None or not self._is_fresh(self._cached):
+            self._cached = self._exec()
+        token = self._cached.get("access_token")
+        if not token:
+            raise AuthError("whodb CLI returned an empty access token")
+        return token
+
+    def refresh(self) -> None:
+        """Drop the cached token so the next call re-execs the CLI."""
+        self._cached = None
+
+    def defaults(self) -> dict:
+        """Return the CLI's saved host/org/project defaults."""
+        if self._cached is None:
+            self._cached = self._exec()
+        return {
+            "host": self._cached.get("host"),
+            "org_id": self._cached.get("org_id"),
+            "project_id": self._cached.get("project_id"),
+        }

whodb_sdk-0.127.0/src/whodb/_errors.py

@@ -0,0 +1,57 @@
+"""Error taxonomy for the whodb SDK, mirrored across all SDK languages."""
+
+from __future__ import annotations
+
+
+class WhoDBError(Exception):
+    """Base class for all errors raised by the whodb SDK."""
+
+
+class AuthError(WhoDBError):
+    """Authentication failed: missing, invalid, expired, or revoked credentials."""
+
+
+class NotFoundError(WhoDBError):
+    """The requested resource does not exist or the caller cannot see it."""
+
+
+class ValidationError(WhoDBError):
+    """The request was rejected as invalid before execution."""
+
+
+class WhoDBVersionError(WhoDBError):
+    """This SDK release targets an older platform API; upgrade the package."""
+
+
+class CliCredentialsError(WhoDBError):
+    """The whodb CLI credential helper is unavailable or not logged in."""
+
+
+class TransportCapabilityError(WhoDBError):
+    """An operation is not available over the current transport (e.g. IPC)."""
+
+
+class PlatformError(WhoDBError):
+    """Any other platform-reported error, carrying the GraphQL error code."""
+
+    def __init__(self, message: str, code: str):
+        super().__init__(message)
+        self.code = code
+
+
+def map_graphql_errors(errors: list[dict]) -> WhoDBError:
+    """Map a GraphQL errors array to the SDK error taxonomy.
+
+    The first error decides the type; its code is preserved on PlatformError
+    for callers that need to branch on specifics.
+    """
+    first = errors[0] if errors else {"message": "unknown platform error"}
+    code = (first.get("extensions") or {}).get("code", "")
+    message = first.get("message", "unknown platform error")
+    if code in ("UNAUTHENTICATED", "FORBIDDEN"):
+        return AuthError(message)
+    if code == "NOT_FOUND":
+        return NotFoundError(message)
+    if code in ("BAD_USER_INPUT", "GRAPHQL_VALIDATION_FAILED"):
+        return ValidationError(message)
+    return PlatformError(message, code)

whodb_sdk-0.127.0/src/whodb/_generated/__init__.py

@@ -0,0 +1,2 @@
+# GENERATED by sdk/tools/generate-core.mjs — DO NOT EDIT (manifest 4b84678f5fe7)
+"""Generated wire core for the whodb SDK. Do not import directly."""

whodb_sdk-0.127.0/src/whodb/_generated/hydration.py

@@ -0,0 +1,34 @@
+# GENERATED by sdk/tools/generate-core.mjs — DO NOT EDIT (manifest 4b84678f5fe7)
+"""Column-type → coercion kind rules shared across all SDK languages."""
+
+HYDRATION_RULES = {
+    "int": "int",
+    "integer": "int",
+    "bigint": "int",
+    "smallint": "int",
+    "int2": "int",
+    "int4": "int",
+    "int8": "int",
+    "serial": "int",
+    "bigserial": "int",
+    "float": "float",
+    "float4": "float",
+    "float8": "float",
+    "double": "float",
+    "double precision": "float",
+    "real": "float",
+    "numeric": "float",
+    "decimal": "float",
+    "bool": "bool",
+    "boolean": "bool",
+    "timestamp": "timestamp",
+    "timestamptz": "timestamp",
+    "timestamp with time zone": "timestamp",
+    "timestamp without time zone": "timestamp",
+    "datetime": "timestamp",
+    "date": "date",
+    "json": "json",
+    "jsonb": "json"
+}
+
+HYDRATION_DEFAULT = "string"