Metadata-Version: 2.4
Name: oblet
Version: 0.0.0
Summary: Python SDK for the oblet control plane.
Project-URL: Homepage, https://oblet.dev
Project-URL: Source, https://github.com/oblet-dev/oblet
Author: Miyelani, Inc.
License-Expression: Apache-2.0
License-File: LICENSE
Requires-Python: >=3.10
Requires-Dist: biscuit-python<0.4,>=0.3
Requires-Dist: connect-python<0.10,>=0.9.0
Requires-Dist: cryptography>=44
Requires-Dist: protobuf>=5
Requires-Dist: pyhpke<0.7,>=0.6.4
Description-Content-Type: text/markdown

<!--
SPDX-FileCopyrightText: 2026 Miyelani, Inc.
SPDX-License-Identifier: Apache-2.0
-->

# 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

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

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

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

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