oblet 0.0.0

Python SDK for the oblet control plane.

oblet — Python SDK

The Python client SDK for the oblet control plane. It is a hand-written native surface over Buf-generated Connect plumbing, mirroring the Go reference SDK at pkg/client: one client per service, native parameter and result types, typed errors carrying the wire reason, point-in-time reads, and offline capability-token attenuation. Both a synchronous Client and an asyncio AsyncClient are provided over the same native types.

The package is self-contained — its own dependency closure, its own generated stubs committed under src/oblet/ — and extracts to a standalone repository by moving this directory.

Install

pip install oblet

Synchronous

import oblet

client = oblet.Client("https://control.example.com", token="<capability token>")

obj = client.object.head(oblet.object.HeadParams(workspace="ws", branch="main", key="doc.txt"))
print(obj.key, obj.size)

# Point-in-time read pinned to an audit leaf.
old = client.object.head(
    oblet.object.HeadParams(workspace="ws", branch="main", key="doc.txt"),
    oblet.CallOptions(at_leaf=42),
)

Asyncio

import oblet

client = await oblet.AsyncClient.connect("https://control.example.com", token="<capability token>")
obj = await client.object.head(oblet.object.HeadParams(workspace="ws", branch="main", key="doc.txt"))

AsyncClient is built through the await AsyncClient.connect(...) factory so the one-shot health ping can run; everything else mirrors Client.

Typed errors

try:
    client.object.head(oblet.object.HeadParams(workspace="ws", branch="main", key="missing"))
except oblet.PermissionDenied as err:
    print(err.reason)          # "pdp_denied"
except oblet.Error as err:     # base of every wire error
    print(oblet.reason_of(err))

Offline token attenuation

narrower = oblet.attenuate_token(token, ['resource == "doc1"'], ttl_seconds=3600, public_key=issuer_hex)

Layout

• src/oblet/ — the public package; __init__.py re-exports only.
• src/oblet/<service>/ — the native surface; the generated wire layer is the v1alpha1/ subpackage beneath it.
• tests/ — per-service tests against a real in-process Connect server, plus the conformance gates.

Development

make sdk-python-gen   # regenerate the wire layer from api/proto
make sdk-python       # ruff, pyright, pytest

See oblet-dev/design-docs/adr/0076-public-python-sdk.md for the design.