Python SDK

Use cuitty-persist from Python with sync and async APIs for records, events, and kv.

Installation

pip install cuitty-persist

Requires Python 3.10+. The package includes type stubs for full IDE support.

Basic usage

from cuitty_persist import create_store

store = create_store("my-app", adapter="sqlite", path="./data/my-app.db")

# Write a record
store.records.put("user:1", {"name": "Alice", "role": "admin"})

# Read it back
user = store.records.get("user:1")
print(user.value["name"])  # "Alice"

# List records
users = store.records.list(prefix="user:", limit=50)
for u in users:
    print(u.key, u.value["name"])

Async API

For asyncio applications, use the async variants. Every method has an async counterpart prefixed with a.

import asyncio
from cuitty_persist import create_store_async

async def main():
    store = await create_store_async(
        "my-app",
        adapter="sqlite",
        path="./data/my-app.db",
    )

    await store.records.aput("task:1", {
        "title": "Ship v0.1",
        "done": False,
    })

    task = await store.records.aget("task:1")
    print(task.value["title"])

    # Async iteration over events
    async for event in store.events.aiter(stream="deploy"):
        print(event.payload)

asyncio.run(main())

Events and KV

# Append an event
store.events.append("audit", {"action": "delete", "target": "user:99"})

# Read recent events
events = store.events.list(stream="audit", limit=10, order="desc")

# Key-value
store.kv.set("feature:beta", "enabled")
value = store.kv.get("feature:beta")  # "enabled"
store.kv.delete("feature:beta")

Enabling sync

from cuitty_persist import enable_sync

enable_sync(store, remote="https://sync.persist.one", strategy="last-write-wins")

The sync worker runs in a background thread for synchronous usage or as an asyncio task for async usage. It follows the same queue-based architecture as the TypeScript SDK.

Configuration via environment

export PERSIST_ADAPTER=sqlite
export PERSIST_PATH=./data/app.db
export PERSIST_SYNC_REMOTE=https://sync.persist.one

store = create_store("my-app")  # reads from environment