Docs/Python SDK

Python SDK

First-party Python SDK for ContractGate — sync & async HTTP client, plus a pure-Python local validator for unit tests and pre-commit hooks.

Python 3.9+httpx async/syncMIT Licensev0.1.0RFC-005 · Accepted

¶Installation

Requires Python 3.9+. Runtime dependencies: httpx, PyYAML.

pip install contractgate

bash

Python 3.9+httpx ≥0.25,<1.0PyYAMLMIT License

¶Quick Start — HTTP Client (Sync)

Use Client to send events to the ContractGate gateway and inspect per-event results.

from contractgate import Client

cg = Client(base_url="https://gw.example.com", api_key="cg_live_...")

result = cg.ingest(
    contract_id="11111111-1111-1111-1111-111111111111",
    events=[
        {"user_id": "alice_01", "event_type": "click", "timestamp": 1712000000},
    ],
)

print(result.passed, "/", result.total, "events passed")
for r in result.results:
    if not r.passed:
        for v in r.violations:
            print(v.field, v.kind, v.message)

python

¶Quick Start — HTTP Client (Async)

AsyncClient is the async equivalent. It wraps httpx.AsyncClient and supports async with for lifecycle management.

import asyncio
from contractgate import AsyncClient

async def main():
    async with AsyncClient(base_url="...", api_key="...") as cg:
        result = await cg.ingest(contract_id="...", events=[...])

asyncio.run(main())

python

ℹ

Client and AsyncClient share the same transport layer and response models — they can never drift on header or auth shape.

¶Quick Start — Local Validator

A pure-Python port of the Rust validator — no network required. Useful in unit tests and pre-commit hooks.

from contractgate import Contract

contract = Contract.from_yaml(open("user_events.yaml").read())
compiled = contract.compile()

vr = compiled.validate({
    "user_id": "alice_01",
    "event_type": "click",
    "timestamp": 1712000000,
})
assert vr.passed, vr.violations

python

⚠

The local validator does not run RFC-004 PII transforms (mask, hash, drop, redact). It is read-only — pass/fail and violations only. The gateway's transformed_eventfield is the authoritative "what got stored" view.

¶Caveats

Local validator does not run PII transforms

The per-contract PII salt is server-side only and never returned in API responses (RFC-004). The local validator is for assert event_passes_contract(…)in user tests — not for replicating the gateway's storage path. Read transformed_event from each per-event result for the post-transform payload.

Audit honesty

Every per-event result carries the contract_version that actually matched the event (relevant under multi_stable_resolution: fallback). Surface it as-is — do not substitute the requested version.

Retries are off by default

Layer httpx.HTTPTransport(retries=) or tenacityif you need them. Avoid client-side retry on ingest to prevent double-write — use the gateway's quarantine replay endpoint instead.

httpx pin

httpx is pinned >=0.25,<1.0; the upper bound will widen once httpx 1.x ships and is tested.

Ready to integrate?

Get your API key and contract UUID from the Account page, then pip install contractgate.