Orbita Python

orbita-python is a synchronous Python client for Orbita. It connects to one load-balanced endpoint and leaves partition routing to the server, which is the same complete non-transactional posture supported by Orbita's generated stubs.

The package is pinned to the wire contract at orbita 0.2.0-dev@cb11cf03575e2c6e370fb83500038de45bd55e69. Generated code changes only when this repository deliberately advances that source pin.

Install

python -m pip install orbita-python

Use

from datetime import timedelta

import orbita

with orbita.Client(
    "http://127.0.0.1:7100",
    credential="tenant-secret",
) as client:
    catalog = client.keyspace("default")
    created = catalog.set(
        b"catalog/current",
        b"manifest-42",
        if_not_present=True,
        ttl=timedelta(minutes=5),
    )
    if not created.applied:
        print(f"already exists at version {created.current_version}")

Use an explicit http:// endpoint for plaintext h2c. Use https:// for TLS; pass tls_credentials=grpc.ssl_channel_credentials(...) when the endpoint needs custom trust roots or a client certificate.

The operator-facing API is separate:

from orbita.admin import AdminClient
from orbita.v1 import admin_pb2

with AdminClient(
    "http://127.0.0.1:7100",
    root_credential="root-secret",
) as admin:
    admin.create_keyspace(admin_pb2.CreateKeyspaceRequest(name="payments"))

API

Client.keyspace(name) returns a Keyspace with get, get_entry, set, delete, list_page, and pages. Keys and values are bytes. get returns None for a missing key, which keeps absence distinct from a stored b"".

Mutation conditions are keyword-only. set accepts if_not_present, if_version, and a datetime.timedelta TTL. delete accepts if_version. list_page returns one page, while pages carries the opaque cursor until the scan completes. Generated protobuf and gRPC modules live under orbita.v1.

Client.readiness() checks the connected node. An unready node is a successful response with ready=False, not an RPC error.

Failure Semantics

The clients retry only read-only calls that return UNAVAILABLE. They never retry a mutation because a lost reply can mean the mutation committed. In that case they raise AmbiguousMutationError; reconcile with a linearizable read before deciding whether to try again. The original grpc.RpcError is available as error.rpc_error.

A failed write condition is not an RPC error. Check applied and, when present, current_version.

Each list page is a consistent snapshot of one partition range. A multi-page scan is not a point-in-time snapshot. Versions are opaque compare-and-swap tokens, not per-key counters, and should not be compared across keys.

Compatibility

This prerelease supports the pinned KV, Health, and Admin contracts. It does not add watch, transactions, or client-side routing that the current server does not provide.

Development

python -m venv .venv
.venv/bin/pip install -e '.[dev]'
.venv/bin/ruff check .
.venv/bin/ruff format --check .
.venv/bin/mypy
.venv/bin/pytest

Regenerate the committed API from the pinned Orbita revision with:

PATH="$PWD/.venv/bin:$PATH" ./scripts/generate.sh