cannasage

Official Python SDK for the CannaSage Developer API. Async-first (httpx) with a sync compatibility wrapper.

Beta. This SDK is pre-1.0 and may change. Pin a specific version in production.

Install

pip install cannasage

Quick start (async)

import asyncio
from cannasage import AsyncCannaSageClient

async def main():
    async with AsyncCannaSageClient(api_key="csk_live_...") as cs:
        result = await cs.sops.list(category="ipm")
        print(result.data)

asyncio.run(main())

Quick start (sync)

from cannasage import CannaSageClient

cs = CannaSageClient(api_key="csk_live_...")
print(cs.sops.list(category="ipm").data)

The sync wrapper spawns a fresh asyncio event loop per call. If you're making many sequential calls, use AsyncCannaSageClient inside a single asyncio.run() block for better throughput.

Authentication

The OAuth client exchanges credentials lazily on the first request and caches the access token until ~1 minute before expiry.

Resources

Every method returns an ApiResponse with .data and .meta attributes.

Webhook signature verification

from fastapi import FastAPI, Request, HTTPException
from cannasage import verify_webhook_signature

app = FastAPI()
SECRET = "whsec_..."

@app.post("/webhooks/cannasage")
async def handle_webhook(request: Request):
    raw_body = await request.body()
    signature = request.headers.get("X-CannaSage-Signature", "")
    if not verify_webhook_signature(raw_body, signature, SECRET):
        raise HTTPException(status_code=401, detail="invalid signature")
    event = await request.json()
    # ... handle event
    return {"ok": True}

verify_webhook_signature uses hmac.compare_digest (constant-time) and never raises on mismatch — it returns bool.

Error handling

All HTTP errors raise CannaSageAPIError:

from cannasage import CannaSageAPIError

try:
    await cs.sops.get("missing")
except CannaSageAPIError as err:
    print(err.code, err.status, err.request_id)
    if err.code == "NOT_FOUND":
        ...

Retries, timeouts, idempotency

• Retries: up to 3 on 429 (rate limited) and 503 (overloaded). Retry-After is honoured with a 30s cap.
• Timeout: default 30s per request. Override via AsyncCannaSageClient(timeout_seconds=60).
• Idempotency: POST requests automatically receive a random Idempotency-Key header (forward-compatible — server support coming in a future release).

License

MIT — see LICENSE.

Links

• API reference
• Changelog
• Issues