Skip to main content

Python Business Scenarios

Read the generated Q.py, requests/*_request.py, models/*.py, and E.py for the exact API. The generator uses centralized snake_case plural names—for example order_statuses(), never a guessed order_statuss().

Filter and paginate asynchronously​

result = await (
    Q.customer_orders()
    .comment("Find matching orders")
    .with_order_number_containing("WEB-")
    .order_by_id_ascending()
    .offset(0)
    .limit(20)
    .purpose("Prepare the authorized order review page")
    .execute_for_list(ctx)
)

purpose() returns an executable wrapper. The wrapper, not the ordinary Request, exposes execute_for_list(ctx), execute_for_one(ctx), and entity-returning variants. Every execution method accepts exactly one runtime argument: ctx.

Select children​

request = (
    Q.customer_orders()
    .comment("Load orders and their first lines")
    .select_order_line_list_with(
        Q.order_lines().order_by_id_ascending().limit(3)
    )
)
orders = await request.purpose(
    "Display the authorized order summary"
).execute_entities_for_list(ctx)

The child Request is still a builder and does not execute independently. The SQL runtime implements per-parent Top-N with a partition/window plan.

Native statistics​

facet = await (
    Q.customer_orders()
    .comment("Group authorized order totals by status")
    .group_by_status()
    .count_as("recordCount")
    .sum_total_amount_as("totalAmount")
    .purpose("Build the status facet")
    .execute_for_list(ctx)
)

COUNT, SUM and GROUP BY remain database-native. Keep the same normalized filter on rows, count, facets and totals.

Create and save​

order = (
    Q.customer_orders()
    .comment("Create a validated order")
    .purpose("Persist an authorized checkout")
    .new_entity(ctx)
)
order.update_order_number("WEB-10001")
await order.audit_as("Create validated checkout order").save(ctx)

Loaded entities retain their optimistic version. A stale update is rejected rather than silently overwriting the current row. mark_as_deleted() marks a generated entity for audited deletion.

Expressions and loaded state​

The generated E facade distinguishes loaded null from not loaded. Use it for safe expression evaluation, fallback, list size and traversal rather than reading a partial projection as though all fields were fetched.

Failure checklist​

  • A second execution argument is always wrong and should raise TypeError.
  • Missing dataService in UserContext fails closed.
  • Unknown JSON fields and unsupported operators must be rejected before Request construction.
  • Save requires audit_as.
  • Regenerate stale archives before investigating a missing or misspelled API.
  • Run compileall/pytest and the selected async provider integration after regeneration.