angzarr_client.wrappers¶

User-facing wrappers around Angzarr framework proto types.

Each wrapper takes the underlying proto in its constructor and exposes domain accessors as methods. The raw proto is reachable via the Wrapped.proto() interface method (wrapper.proto()) when callers need direct field access.

Cover-bearing wrappers (Cover, EventBook, CommandBook, Query) inherit shared accessors from CoverBearer. Page wrappers (EventPage, CommandPage) and CommandResponse are not Cover-bearers and define their own surface.

Naming: wrapper class names shadow the proto type names. Internal code that wants the raw proto imports it from angzarr_client.proto.angzarr directly; user code reaches for the wrapper from angzarr_client.

Attributes¶

`T`
`UNKNOWN_DOMAIN`
`TYPE_URL_PREFIX`

Classes¶

`Wrapped`	Interface every angzarr wrapper implements.
`CoverBearer`	Shared accessors for proto types that carry a `Cover` field.
`Cover`	Wrapper for the `Cover` proto.
`EventBook`	Wrapper for the `EventBook` proto.
`CommandBook`	Wrapper for the `CommandBook` proto.
`Query`	Wrapper for the `Query` proto.
`EventPage`	Wrapper for the `EventPage` proto.
`CommandPage`	Wrapper for the `CommandPage` proto.
`CommandResponse`	Wrapper for the `CommandResponse` proto.

Module Contents¶

angzarr_client.wrappers.T¶

angzarr_client.wrappers.UNKNOWN_DOMAIN = 'unknown'¶

angzarr_client.wrappers.TYPE_URL_PREFIX = 'type.googleapis.com/'¶

class angzarr_client.wrappers.Wrapped¶

Bases: abc.ABC

Interface every angzarr wrapper implements.

Wrappers expose two surfaces:

Method-style accessors for common needs (e.g. Cover.domain()).
The raw proto for everything else, via proto().

Cross-language note: proto() is the documented escape hatch for callers that want direct proto field access (e.g. for serialization, for fields that don’t have a wrapper accessor, for proto-specific methods like HasField). Other languages will provide an equivalent method (e.g. Java Cover.proto()).

abstractmethod proto()¶: Return the wrapped proto message.

class angzarr_client.wrappers.CoverBearer¶

Bases: Wrapped

Shared accessors for proto types that carry a Cover field.

Subclasses set self._proto and override _cover_proto() to return the embedded Cover (or None if missing). The default implementation assumes self._proto is itself a Cover — only Cover relies on the default; the others override.

domain() → str¶: Get the domain, falling back to UNKNOWN_DOMAIN.

correlation_id() → str¶: Get the correlation_id, or empty string if missing.

has_correlation_id() → bool¶: True if a non-empty correlation_id is present.

root_uuid() → uuid.UUID | None¶: Extract the root UUID, or None if missing/malformed.

root_id_hex() → str¶: Root UUID as hex, or empty string if missing.

edition() → str | None¶: Edition name, or None when missing/empty.

routing_key() → str¶: Bus routing key (currently the domain).

cache_key() → str¶: Cache key derived from edition + domain + root.

class angzarr_client.wrappers.Cover(proto: angzarr_client.proto.angzarr.Cover)¶

Bases: CoverBearer

Wrapper for the Cover proto.

proto() → angzarr_client.proto.angzarr.Cover¶: Return the wrapped proto message.

class angzarr_client.wrappers.EventBook(proto: angzarr_client.proto.angzarr.EventBook)¶

Bases: CoverBearer

Wrapper for the EventBook proto.

proto() → angzarr_client.proto.angzarr.EventBook¶: Return the wrapped proto message.

cover() → Cover¶

The wrapped cover.

Always returns a Cover — when the underlying proto has no cover field set, the wrapper is built around the proto’s default-instance cover, so accessors like .domain() still work (returning the canonical empty responses, e.g. UNKNOWN_DOMAIN).

next_sequence() → int¶: Framework-precomputed next sequence number.

is_empty() → bool¶: True if there are no event pages.

pages() → list[EventPage]¶: All event pages, wrapped.

first_page() → EventPage | None¶: First event page, or None when empty.

last_page() → EventPage | None¶: Last event page, or None when empty.

class angzarr_client.wrappers.CommandBook(proto: angzarr_client.proto.angzarr.CommandBook)¶

Bases: CoverBearer

Wrapper for the CommandBook proto.

proto() → angzarr_client.proto.angzarr.CommandBook¶: Return the wrapped proto message.

cover() → Cover¶

The wrapped cover (always present; default-instance if not set).

See EventBook.cover() for the rationale.

pages() → list[CommandPage]¶: All command pages, wrapped.

first_command() → CommandPage | None¶: First command page, or None when empty.

command_sequence() → int¶: Sequence number of the first command page (0 when empty).

merge_strategy() → angzarr_client.proto.angzarr.MergeStrategy¶: Merge strategy of the first page; defaults to commutative.

class angzarr_client.wrappers.Query(proto: angzarr_client.proto.angzarr.Query)¶

Bases: CoverBearer

Wrapper for the Query proto.

proto() → angzarr_client.proto.angzarr.Query¶: Return the wrapped proto message.

cover() → Cover¶

The wrapped cover (always present; default-instance if not set).

See EventBook.cover() for the rationale.

class angzarr_client.wrappers.EventPage(proto: angzarr_client.proto.angzarr.EventPage)¶

Bases: Wrapped

Wrapper for the EventPage proto.

proto() → angzarr_client.proto.angzarr.EventPage¶: Return the wrapped proto message.

sequence_num() → int¶: Explicit sequence number, or 0 if not set.

header() → angzarr_client.proto.angzarr.PageHeader | None¶: The page header proto, or None if missing.

is_deferred() → bool¶: True if this page carries a deferred-sequence header.

type_url() → str | None¶: Event payload’s type URL, or None if missing.

payload() → bytes | None¶: Raw event payload bytes, or None if missing.

decode_typed(msg_class: type[T]) → T | None¶

Decode the event payload into msg_class, exact-match on type URL.

Returns None on missing event, type mismatch, or decode failure.

class angzarr_client.wrappers.CommandPage(proto: angzarr_client.proto.angzarr.CommandPage)¶

Bases: Wrapped

Wrapper for the CommandPage proto.

proto() → angzarr_client.proto.angzarr.CommandPage¶: Return the wrapped proto message.

sequence_num() → int¶: Explicit sequence number, or 0 if not set.

header() → angzarr_client.proto.angzarr.PageHeader | None¶: The page header proto, or None if missing.

is_deferred() → bool¶: True if this page carries a deferred-sequence header.

type_url() → str | None¶: Command payload’s type URL, or None if missing.

payload() → bytes | None¶: Raw command payload bytes, or None if missing.

merge_strategy() → angzarr_client.proto.angzarr.MergeStrategy¶: Per-page merge strategy.

class angzarr_client.wrappers.CommandResponse(proto: angzarr_client.proto.angzarr.CommandResponse)¶

Bases: Wrapped

Wrapper for the CommandResponse proto.

proto() → angzarr_client.proto.angzarr.CommandResponse¶: Return the wrapped proto message.

events_book() → EventBook | None¶: The wrapped events EventBook, or None if not set.

events() → list[EventPage]¶: All event pages from the response, wrapped.