bkn-osdk 0.2.1__py3-none-any.whl

bkn_osdk/__init__.py

@@ -0,0 +1,122 @@
+# Copyright (c) 2026 OpenBKN. All rights reserved.
+# Licensed under the Apache License, Version 2.0. See the LICENSE file in the project root.
+
+"""bkn-osdk — a Python SDK for BKN, in two layers.
+
+**The platform layer** addresses the platform itself: any REST route by path
+(`call`, `request`) and any tool the deploy publishes by name (`call_tool`,
+`tool_catalog`). Every network, every capability, no generation — at the cost of
+shaping arguments yourself against what the catalog declares.
+
+**The ontology layer** addresses one knowledge network's ontology: classes
+generated from its schema, where `Order.total_amount` is a property this network
+really has and a typo is a type error rather than an empty result set.
+
+The layers are named for what they address, not for how they were built. Both
+run through the same credentials, the same transports and the same managed turn,
+so a script can drop to the platform layer for one call and come back up with
+its evidence still on one chain.
+
+A generated package imports from here and from nothing else, so a fix or a new
+operator reaches it through `pip install -U bkn-osdk` with no regeneration.
+
+Import is side-effect free: nothing resolves credentials or touches the network
+until a call is made.
+"""
+
+from __future__ import annotations
+
+from importlib.metadata import PackageNotFoundError
+from importlib.metadata import version as _version
+
+from . import oauth
+from .config import (
+    DEFAULT_TIMEOUT,
+    Context,
+    configure,
+    resolve_context,
+    session,
+)
+from .errors import (
+    AuthError,
+    BknError,
+    FormatVersionError,
+    HttpError,
+    InputError,
+    ObjectNotFound,
+    PlatformVersionError,
+    SchemaDriftError,
+    ToolError,
+)
+from .http import call, request
+from .identity import Me, me
+from .mcp import ToolResult, call_tool, tool_catalog
+from .metrics import Metric
+from .query import Comparison, Composite, Filter, ObjectSet, Page, Sort, to_condition
+from .schema import (
+    KnSchema,
+    MetricDef,
+    ObjectTypeDef,
+    PropertyDef,
+    RelationTypeDef,
+    fingerprint,
+)
+
+# Rebinds the `search` attribute from the submodule to the function it exports —
+# `bkn_osdk.search(kn_id, query)` is the surface, `bkn_osdk.search` the module is
+# an implementation detail. `import bkn_osdk.search` still resolves the module.
+from .search import search, search_instances
+from .subgraph import RelationPath
+from .types import ObjectType, Property, PropertyRef, Relation
+
+try:
+    __version__ = _version("bkn-osdk")
+except PackageNotFoundError:  # running from a source tree that was never installed
+    __version__ = "0.0.0.dev0"
+
+__all__ = [
+    "DEFAULT_TIMEOUT",
+    "AuthError",
+    "BknError",
+    "Comparison",
+    "Composite",
+    "Context",
+    "Filter",
+    "FormatVersionError",
+    "HttpError",
+    "InputError",
+    "KnSchema",
+    "Me",
+    "Metric",
+    "MetricDef",
+    "ObjectNotFound",
+    "ObjectSet",
+    "ObjectType",
+    "ObjectTypeDef",
+    "Page",
+    "PlatformVersionError",
+    "Property",
+    "PropertyDef",
+    "PropertyRef",
+    "Relation",
+    "RelationPath",
+    "RelationTypeDef",
+    "SchemaDriftError",
+    "Sort",
+    "ToolError",
+    "ToolResult",
+    "__version__",
+    "call",
+    "call_tool",
+    "configure",
+    "fingerprint",
+    "me",
+    "oauth",
+    "request",
+    "resolve_context",
+    "search",
+    "search_instances",
+    "session",
+    "to_condition",
+    "tool_catalog",
+]

bkn_osdk/auth.py

@@ -0,0 +1,199 @@
+# Copyright (c) 2026 OpenBKN. All rights reserved.
+# Licensed under the Apache License, Version 2.0. See the LICENSE file in the project root.
+
+"""Keeping a stored session alive for the length of a Python process.
+
+Access tokens on this platform are short-lived, so a long-running script that
+resolved its credentials from `~/.bkn` goes stale mid-run and starts getting
+401s. The `openbkn` CLI solves that by refreshing on a 401 and persisting; this
+side does the same exchange, in memory.
+
+**The one time this writes to the store** is refresh-token rotation. Where the
+authorization server returns a *new* refresh token, the old one is spent — so
+keeping the new one to ourselves would strand the CLI with a dead credential and
+force a re-login. Writing it back is what preserves the CLI's session, not a
+land-grab on a file it owns; where no new token comes back, nothing is written.
+
+Refresh applies only to credentials that came from the store. An explicit
+`token=` or `BKN_TOKEN` is the caller's to manage, and an AppKey has no refresh
+at all — its 401 means re-issue.
+"""
+
+from __future__ import annotations
+
+import threading
+import urllib.parse
+from dataclasses import dataclass
+
+import httpx
+
+from . import oauth
+from .config import Context, StoredCredential, TokenHolder, write_refreshed_token
+from .errors import BknError
+
+__all__ = ["can_refresh", "refreshed_token", "token_for"]
+
+#: An app's token set is renewed this long before it expires, so a request does
+#: not set off with a token that dies in flight.
+REFRESH_WINDOW_SECONDS = 60.0
+
+TOKEN_PATH = "/oauth2/token"
+
+_lock = threading.Lock()
+#: (base URL, user id) -> the freshest access token this process has obtained.
+_fresh: dict[tuple[str, str], str] = {}
+
+
+@dataclass(frozen=True)
+class _Tokens:
+    access_token: str
+    refresh_token: str | None
+
+
+def can_refresh(ctx: Context) -> bool:
+    """Whether a 401 for this context is worth a refresh attempt."""
+    return ctx.credential is not None or ctx.app_tokens is not None
+
+
+def token_for(ctx: Context) -> str:
+    """The token to send: whatever this process last refreshed, else the stored one.
+
+    Without this, every request after the first expiry would pay for its own
+    refresh round trip.
+    """
+    if ctx.app_tokens is not None:
+        return _app_token(ctx, ctx.app_tokens)
+    credential = ctx.credential
+    if credential is None:
+        return ctx.token
+    with _lock:
+        return _fresh.get((credential.base_url, credential.user_id), ctx.token)
+
+
+def refreshed_token(ctx: Context, used: str) -> str | None:
+    """Exchange the refresh token for a fresh access token, or None if that fails.
+
+    `used` is the token that just came back 401; if another thread refreshed in
+    the meantime, its result is returned instead of a second exchange.
+    """
+    if ctx.app_tokens is not None:
+        return _app_refreshed(ctx, ctx.app_tokens, used)
+    credential = ctx.credential
+    if credential is None:
+        return None
+
+    key = (credential.base_url, credential.user_id)
+    with _lock:
+        current = _fresh.get(key)
+        if current is not None and current != used:
+            return current
+
+    tokens = _exchange(credential, ctx.insecure, ctx.timeout)
+    if tokens is None:
+        return None
+
+    with _lock:
+        _fresh[key] = tokens.access_token
+
+    if tokens.refresh_token and tokens.refresh_token != credential.refresh_token:
+        # Rotation: the stored refresh token is now spent. Hand the replacement
+        # back to the store, or the next `openbkn` command has no way in.
+        write_refreshed_token(
+            credential.base_url,
+            credential.user_id,
+            access_token=tokens.access_token,
+            refresh_token=tokens.refresh_token,
+        )
+    return tokens.access_token
+
+
+def _app_token(ctx: Context, holder: TokenHolder) -> str:
+    """The holder's access token, renewed first if it is about to expire.
+
+    The lock is held across the renewal so threads arriving together wait for
+    one refresh and then all read its result.
+    """
+    with holder.lock:
+        if holder.tokens.expires_within(REFRESH_WINDOW_SECONDS):
+            renewed = _renew(ctx, holder)
+            if renewed is not None:
+                return renewed
+        return holder.tokens.access_token
+
+
+def _app_refreshed(ctx: Context, holder: TokenHolder, used: str) -> str | None:
+    """Refresh after a 401 on `used`, unless another thread already replaced it."""
+    with holder.lock:
+        current = holder.tokens.access_token
+        if current != used:
+            return current
+        return _renew(ctx, holder)
+
+
+def _renew(ctx: Context, holder: TokenHolder) -> str | None:
+    """Run the refresh grant for a holder (lock held); None when it fails.
+
+    A failed grant is not raised: the caller falls back to the request's own 401,
+    which `http.py` annotates with the sign-in-again hint. `on_refresh` runs after
+    the holder is updated, and its exceptions are deliberately *not* caught — an
+    app that cannot save a rotated refresh token wants to know before it loses it.
+    """
+    tokens = holder.tokens
+    if not tokens.refresh_token:
+        return None
+    try:
+        renewed = oauth.refresh(
+            ctx.base_url,
+            tokens,
+            client_id=holder.client_id,
+            insecure=ctx.insecure,
+            timeout=ctx.timeout,
+        )
+    except BknError:
+        return None
+    holder.tokens = renewed
+    if holder.on_refresh is not None:
+        holder.on_refresh(renewed)
+    return renewed.access_token
+
+
+def _exchange(credential: StoredCredential, insecure: bool, timeout: float) -> _Tokens | None:
+    """The RFC 6749 refresh grant, against a public client with no secret.
+
+    A failure returns None rather than raising, so the caller surfaces the
+    original 401 — which carries the platform's own next-step hint — instead of
+    a second error about the refresh.
+    """
+    body = urllib.parse.urlencode(
+        {
+            "grant_type": "refresh_token",
+            "refresh_token": credential.refresh_token,
+            "client_id": credential.client_id,
+        }
+    )
+    try:
+        with httpx.Client(verify=not insecure, timeout=timeout) as client:
+            response = client.post(
+                f"{credential.base_url}{TOKEN_PATH}",
+                content=body,
+                headers={
+                    "content-type": "application/x-www-form-urlencoded",
+                    "accept": "application/json",
+                },
+            )
+        if response.is_error:
+            return None
+        payload = response.json()
+    except (httpx.HTTPError, ValueError):
+        return None
+
+    access = payload.get("access_token") if isinstance(payload, dict) else None
+    if not isinstance(access, str) or not access:
+        return None
+    rotated = payload.get("refresh_token") if isinstance(payload, dict) else None
+    return _Tokens(access, rotated if isinstance(rotated, str) and rotated else None)
+
+
+def _reset_for_tests() -> None:
+    with _lock:
+        _fresh.clear()

bkn_osdk/codegen/__init__.py

@@ -0,0 +1,11 @@
+# Copyright (c) 2026 OpenBKN. All rights reserved.
+# Licensed under the Apache License, Version 2.0. See the LICENSE file in the project root.
+
+"""The generator: a pure `schema -> file tree` function plus its CLI shell.
+
+Ships in the same distribution as the runtime but is imported only by the
+`bkn-osdk` console script, so it costs an installed consumer nothing at runtime.
+
+The core must stay pure — no HTTP, no filesystem — so that the CLI shell, the
+test shell, and a future server-side wheel builder can all drive it.
+"""