Python Runtime Guide
For AI-assisted development, use the generated Assist contracts with the TeaQL Agent Kit Harness Engineering workflow.
The Python target generates models, typed Request classes, Q and E facades, relation loading,
aggregations and async persistence. Generated snake_case names come from centralized naming metadata;
templates never form plurals by appending s.
Start here
Use this sequence for a Python service:
- Python Quick Start — create the model, prepare an isolated package, initialize context, query and save.
- Python First Verification — prove context-only async execution, real SQLite persistence, loaded state and governance failures.
- Python Customization — install async providers, policy, validators and the two audit paths outside generated code.
- Python Business Scenarios — use relations, native statistics, expressions and optimistic mutations.
The public PyPI package name/version and generator target remain intentionally blank until publication. The Quick Start explains the clean-environment checks required once those coordinates exist.
Context-only async execution
Every execution method has exactly one caller-supplied argument:
orders = await (
Q.customer_orders()
.comment("Find orders awaiting review")
.purpose("Prepare the authorized review queue")
.execute_for_list(context)
)
The data service is injected while UserContext is initialized and resolved through its required
resources. Passing an old second service argument is invalid and raises Python's normal
TypeError. Missing context initialization fails closed.
Mutations follow the same context boundary:
order = await order.audit_as("Approve reviewed order").save(context)
Verified providers
| Database | Async driver observed in acceptance | Feature status |
|---|---|---|
| PostgreSQL | asyncpg 0.31.0 | PASS |
| MySQL | aiomysql 0.3.2 | PASS |
| SQLite | aiosqlite 0.22.1 | PASS |
The generated Feature passed dynamic filters, native aggregates, relation loading, exact Top-N, tenant-scoped versioned saves, stale-version rejection and dual audit events on all three providers.
Loaded values and expressions
The generated E facade distinguishes a field loaded with null from a field that was not selected.
This distinction is important for partial projections, fallbacks and list traversal. Regenerate and
run both compile and provider tests after changing projections or relations.