angzarr_client.builder¶

Fluent builders for commands and queries.

Classes¶

`CommandBuilder`	Fluent builder for constructing and executing commands.
`QueryBuilder`	Fluent builder for constructing and executing queries.

Module Contents¶

class angzarr_client.builder.CommandBuilder(client: angzarr_client.client.CommandHandlerClient, domain: str, root: uuid.UUID)¶

Fluent builder for constructing and executing commands.

Audit #67: root is required. The only path to an auto-generated UUID v4 is via command_new(), which materializes the UUID and passes it explicitly to the constructor. Aggregate roots are always client-assigned across all six languages (audit #20 convention).

with_correlation_id(id: str) → CommandBuilder¶: Set the correlation ID for request tracing.

with_sequence(seq: int) → CommandBuilder¶: Set the expected sequence number for optimistic locking.

with_merge_strategy(strategy: angzarr_client.proto.angzarr.MergeStrategy) → CommandBuilder¶

Set the merge strategy for conflict resolution.

Parameters:: strategy – MERGE_COMMUTATIVE (default) or MERGE_STRICT.

with_command(type_url: str, message: google.protobuf.message.Message) → CommandBuilder¶: Set the command type URL and message.

build() → angzarr_client.proto.angzarr.CommandBook¶: Build the CommandBook without executing.

execute(sync_mode: angzarr_client.proto.angzarr.SyncMode = SyncMode.SYNC_MODE_ASYNC) → angzarr_client.proto.angzarr.CommandResponse¶

Build and execute the command.

Parameters:: sync_mode – Execution mode (ASYNC, SIMPLE, or CASCADE). Defaults to ASYNC for fire-and-forget behavior.

class angzarr_client.builder.QueryBuilder(client: angzarr_client.client.QueryClient, domain: str, root: uuid.UUID | None = None)¶

Fluent builder for constructing and executing queries.

by_correlation_id(id: str) → QueryBuilder¶: Query by correlation ID instead of root.

edition(edition: str) → QueryBuilder¶: Query events from a specific edition.

with_edition¶

range(lower: int) → QueryBuilder¶

Query a range of sequences from lower (inclusive).

Last-selection-wins: clears any previously-set temporal selection so chained calls like .as_of_sequence(10).range(5) produce a Query with only the range. Mirrors Rust’s builder.rs:165 single-slot semantics (PARITY_AUDIT.md finding #23).

range_to(lower: int, upper: int) → QueryBuilder¶

Query a range of sequences with upper bound (inclusive).

Last-selection-wins (see range()).

as_of_sequence(seq: int) → QueryBuilder¶

Query state as of a specific sequence number.

Last-selection-wins: clears any previously-set range selection.

as_of_time(rfc3339: str) → QueryBuilder¶

Query state as of a specific timestamp (RFC3339 format).

Last-selection-wins: clears any previously-set range selection.

Audit finding #34 (Option B — raise immediately): a malformed rfc3339 string raises InvalidTimestampError synchronously rather than deferring to build(). Previously the failure was captured into a sticky _err field that survived subsequent last-call-wins setters, making qb.as_of_time(“bad”).as_of_sequence(5).build() raise the stale parse error. Mirrors Rust’s as_of_time(...) -> Result<Self> signature where the bad call short-circuits at the call site.

build() → angzarr_client.proto.angzarr.Query¶: Build the Query without executing.

get_event_book() → angzarr_client.proto.angzarr.EventBook¶: Execute the query and return a single EventBook.

get_events() → list[angzarr_client.proto.angzarr.EventBook]¶: Execute the query and return all matching EventBooks.

get_pages() → list[angzarr_client.proto.angzarr.EventPage]¶: Execute the query and return just the event pages.