Rows kept by events (Effect's eventlog/EventRow).
An EventRow is an event whose payload sets, patches or removes one
row of a table, identified by its key fields::
Grocery = event_row.make(
"grocery",
key="id",
schema=S.Struct(GroceryRow),
key_type=str,
patch_fields=GroceryPatch, # a total=False TypedDict of the non-key fields
)
log.write(Grocery, Grocery.set({"id": "g1", ...}).payload)
log.write(Grocery, Grocery.patch("g1", {"completed": True}).payload)key_type and patch_fields only type patch, remove and the
handler's callbacks (Python cannot derive them from the schema, as Effect
does); make checks patch_fields names exactly the non-key fields,
and patch raises EventRowPatchError for a key or unknown field.
handler turns three callbacks into the event's handler, resolving a
late entry against the newer ones already stored, so replicas applying
entries in any order converge to the fold of all entries in id order.
compaction drops the entries newer ones make redundant.
Types#
| Type | Definition | Description |
|---|---|---|
Row | type Row = Mapping[str, object] | |
Payload | type Payload[R, K] = SetPayload[R] | PatchPayload[K] | RemovePayload[K] | What an |
Classes#
Functions#
make#
make[R: Row, K = object, P: Row = Row, E = Never](tag, *, key, schema, key_type=None, patch_fields=None, error=None) -> EventRow[R, K, E, P]An event keeping rows of schema (Effect's EventRow.make).
key names the key field, or declares several; a missing key field
raises ValueError. A single named field is carried as its value,
a declaration as a mapping of its fields. key_type (that value's
type) and patch_fields (a TypedDict of exactly the non-key fields,
else ValueError) type the key and the patches.
| Parameter | Type | Description |
|---|---|---|
tag | str | |
key | str | KeyDeclaration | |
schema | S.StructSchema[R, object, object] | |
key_type | type[K] | None = None | |
patch_fields | type[P] | None = None | |
error | S.Codec[E, object, object, object] | None = None |
Returns EventRow[R, K, E, P]
def make[R: Row, K = object, P: Row = Row, E = Never](
tag: str,
*,
key: str | KeyDeclaration,
schema: S.StructSchema[R, object, object],
key_type: type[K] | None = None,
patch_fields: type[P] | None = None,
error: S.Codec[E, object, object, object] | None = None,
) -> EventRow[R, K, E, P]:
"""An event keeping rows of ``schema`` (Effect's ``EventRow.make``).
``key`` names the key field, or declares several; a missing key field
raises ``ValueError``. A single named field is carried as its value,
a declaration as a mapping of its fields. ``key_type`` (that value's
type) and ``patch_fields`` (a TypedDict of exactly the non-key fields,
else ``ValueError``) type the key and the patches."""
fields = cast("Mapping[str, _Codec]", schema.fields)
names = (key,) if isinstance(key, str) else key.fields
unknown = [name for name in names if name not in fields]
if not names or unknown:
raise ValueError(f"{tag!r} key fields must be fields of the schema, got {names!r}")
row_key = _scalar_key(key, fields[key]) if isinstance(key, str) else _declared_key(key, fields)
del key_type
patchable = frozenset(name for name in fields if name not in row_key.fields)
if patch_fields is not None:
declared = frozenset(cast("Mapping[str, object]", patch_fields.__annotations__))
if declared != patchable:
raise ValueError(
f"{tag!r} patch_fields must name the non-key fields {sorted(patchable)!r}, "
f"got {sorted(declared)!r}"
)
patch_schemas = {
name: _patch_field(codec) for name, codec in fields.items() if name in patchable
}
payload = S.Union(
_struct({"_tag": S.Literal("set"), "row": schema}),
_struct(
{
"_tag": S.Literal("patch"),
"key": row_key.schema,
"fields": _struct(patch_schemas, optional=True),
}
),
_struct({"_tag": S.Literal("remove"), "key": row_key.schema}),
)
def primary_key(p: Payload[R, K]) -> str:
return row_key.primary_key(p["row"] if p["_tag"] == "set" else row_key.to_values(p["key"]))
return EventRow(
tag,
primary_key,
cast("Any", payload),
S.Null,
cast("Any", S.Never if error is None else error),
key_fields=row_key.fields,
schema=schema,
_key=row_key,
_patchable=patchable,
)handler#
handler[R: Row, K, E, P: Row, RR = Never](row, *, set, patch, remove) -> Callable[[HandlerInput[Payload[R, K]]], Effect[None, E, RR]]The handler of row calling at most one callback per entry: the
entry's operation, minus what newer stored entries overwrite. A patch
left with no fields calls nothing.
| Parameter | Type | Description |
|---|---|---|
row | EventRow[R, K, E, P] | |
set | Callable[[R, K], Effect[object, E, RR]] | |
patch | Callable[[K, P], Effect[object, E, RR]] | |
remove | Callable[[K], Effect[object, E, RR]] |
Returns Callable[[HandlerInput[Payload[R, K]]], Effect[None, E, RR]]
def handler[R: Row, K, E, P: Row, RR = Never](
row: EventRow[R, K, E, P],
*,
set: Callable[[R, K], Effect[object, E, RR]],
patch: Callable[[K, P], Effect[object, E, RR]],
remove: Callable[[K], Effect[object, E, RR]],
) -> Callable[[HandlerInput[Payload[R, K]]], Effect[None, E, RR]]:
"""The handler of ``row`` calling at most one callback per entry: the
entry's operation, minus what newer stored entries overwrite. A patch
left with no fields calls nothing."""
decode = S.decode_unknown_effect(row.payload_codec)
key_from_row = row._key.from_row # pyright: ignore[reportPrivateUsage]
def run(op: _Op | None) -> Effect[object, E, RR]:
if op is None:
return succeed(None)
match op["_tag"]:
case "set":
return set(op["row"], cast("K", key_from_row(op["row"])))
case "patch":
fields = cast("P", op["fields"])
return patch(op["key"], fields) if fields else succeed(None)
case "remove":
return remove(op["key"])
def handle(options: HandlerInput[Payload[R, K]]) -> Effect[None, E, RR]:
conflicts = [c.payload for c in options.conflicts]
decoded: Effect[_Op, Never, Any] = decode(options.entry.payload).or_die()
return decoded.flat_map(lambda payload: run(_resolve(payload, conflicts))).as_void()
return handlecompaction#
compaction[R: Row, K, E, P: Row](group, row) -> Layer[Never, Never, Registry]Compact row's entries a remote sends: an entry is dropped when
newer ones of its key overwrite everything it writes. Undecodable
entries are kept.
The compactor opts into remote compaction (remote of
event_log.group_compaction); there it also keeps entries with fields
the row schema does not know.
| Parameter | Type | Description |
|---|---|---|
group | EventGroup[AnyEvent] | |
row | EventRow[R, K, E, P] |
Returns Layer[Never, Never, Registry]
def compaction[R: Row, K, E, P: Row](
group: EventGroup[AnyEvent], row: EventRow[R, K, E, P]
) -> Layer[Never, Never, Registry]:
"""Compact ``row``'s entries a remote sends: an entry is dropped when
newer ones of its key overwrite everything it writes. Undecodable
entries are kept.
The compactor opts into remote compaction (``remote`` of
``event_log.group_compaction``); there it also keeps entries with fields
the row schema does not know."""
event = group.events[row.tag]
decode = S.decode_unknown_effect(event.payload_codec)
decode_strict = S.decode_unknown_effect(to_codec_strict(event.payload))
def compact(
entries: Sequence[Entry], write: CompactWrite, /, *, remote: bool = False
) -> Effect[None]:
decode_payload = decode_strict if remote else decode
def body():
ops: dict[int, _Op] = {}
for entry in entries:
result = yield from decode_payload(entry.payload).exit()
if isinstance(result, Success):
ops[id(entry)] = result.value
shadowed = _shadowed(entries, ops)
kept = [entry for entry in entries if id(entry) not in shadowed]
yield from for_each(kept, lambda entry: write(entry, None))
return gen(body)
def register():
registry = yield from Registry()
yield from registry.register_compaction([row.tag], compact, remote=True)
return layer_effect_discard(gen(register))