Core Concepts

Async execution model

All SDK operations are async. Wrap your code in an async def main() function and call asyncio.run(main()) to execute it:

import asyncio
from cacholong_sdk import connection, DnsZone

async def main():
    async with connection("https://api.cacholong.eu/api/v1/", "YOUR-API-KEY") as api:
        ctrl = DnsZone(api)
        async for zone in ctrl.fetch_all():
            print(zone["domain"])

asyncio.run(main())

If you are already inside an async context (e.g. FastAPI, an async task runner), you can await SDK calls directly without asyncio.run().

Connection as a context manager

connection is an async context manager built on jsonapi_client.Session. Use it with async with to ensure the HTTP session is properly opened and closed:

async with connection(api_uri, api_key) as api:
    ctrl = DnsZone(api)
    ...
# Session is closed here

Dict-style attribute access

Model attributes are accessed and set using dict-style syntax:

zone = await ctrl.fetch("ZONE-UUID")
print(zone["domain"])           # read
zone["domain"] = "new.example.com"  # write

Inspecting all available attributes

Use model.json to inspect the raw JSON:API attributes at runtime:

import json
zone = await ctrl.fetch("ZONE-UUID")
print(json.dumps(zone.json, indent=2))

For the full attribute reference for each resource, see the API documentation.