toondb

Official Python SDK for communicating with a TOONDB instance.

Overview

toondb provides a clean client for:

• service health checks
• collection management
• CRUD operations
• schema updates
• TOON dumps
• bridge-compatible action execution

TOONDB Instance Setup

To create and run a TOONDB database instance, use the main TOONDB project:

github.com/lythelab/toondb

This SDK assumes you already have a running TOONDB service URL and credentials.

Requirements

• Python >= 3.7
• requests library

Installation

pip install toondb

Quick Start

from toondb import ToonDBClient

client = ToonDBClient(
    base_url="https://your-toondb-service-url",
    username="your-username",
    password="your-password",
)

health = client.health()
print(health)

Configuration

Explicit configuration

from toondb import ToonDBClient

client = ToonDBClient(
    base_url="https://example.toondb.io",
    username="vin",
    password="vin123"
)

Environment fallback If omitted in the constructor options, the SDK auto-loads values from environment variables:

• TOONDB_URL
• TOONDB_USER
• TOONDB_PASS

# works if env vars are set
client = ToonDBClient()

API Reference

Health

• health()

Collection operations

• create_collection(collection, schema)
• update_collection_schema(collection, schema)
• dump(collection) -> returns TOON dump array/string depending on server response

Document operations

• insert(collection, doc)
• find(collection, filter=None)
• update(collection, filter, patch)
• delete(collection, filter)

Bridge-compatible operations

• bridge(request)
• execute(action, payload=None)
• shutdown()

Supported bridge actions:

• create_collection
• insert
• update
• update_schema
• find
• delete
• dump
• shutdown

Usage Example (CRUD)

# Create a collection with a schema
client.create_collection("users", {
    "fields": { "name": "string", "age": "number", "active": "boolean" },
    "indexed_fields": ["name"]
})

# Insert a document
client.insert("users", { "name": "milo", "age": 7, "active": True })

# Find documents matching criteria
found = client.find("users", {
    "conditions": [{"field": "name", "op": "eq", "value": "milo"}]
})

# Update matching documents
client.update(
    "users",
    {"conditions": [{"field": "name", "op": "eq", "value": "milo"}]},
    {"age": 8}
)

# Dump the collection
toon_dump = client.dump("users")
print(toon_dump)

Error Handling

The SDK raises typed exceptions appropriately:

• ToonDBAuthError for auth failures (HTTP 401)
• ToonDBResponseError for other API/server response failures
• ToonDBNetworkError for transport/network failures or timeouts

from toondb import ToonDBAuthError, ToonDBNetworkError

try:
    client.health()
except ToonDBAuthError:
    print("Invalid credentials")
except ToonDBNetworkError:
    print("Network issue")
except Exception as err:
    print(err)

Development

Run tests:

pytest tests/

Run smoke example: (In PowerShell you would use $env:TOONDB_URL=... but below is standard Unix style)

TOONDB_URL=http://127.0.0.1:6767 TOONDB_USER=vin TOONDB_PASS=vin123 python examples/smoke.py

Smoke script location:
examples/smoke.py

Contributing

Please see:
CONTRIBUTING.md