GitHub

event_row

API reference for event_row.

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

TypeDefinitionDescription
Rowtype Row = Mapping[str, object]
Payloadtype Payload[R, K] = SetPayload[R] | PatchPayload[K] | RemovePayload[K]

What an EventRow event carries: a whole row, some of a row's non-key fields, or the removal of a row.

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.

ParameterTypeDescription
tagstr
keystr | KeyDeclaration
schemaS.StructSchema[R, object, object]
key_typetype[K] | None = None
patch_fieldstype[P] | None = None
errorS.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.

ParameterTypeDescription
rowEventRow[R, K, E, P]
setCallable[[R, K], Effect[object, E, RR]]
patchCallable[[K, P], Effect[object, E, RR]]
removeCallable[[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 handle

compaction

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.

ParameterTypeDescription
groupEventGroup[AnyEvent]
rowEventRow[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))