Skip to content

logicblocks.event.types

class Applier[V]

Bases: ABC

Abstract base class for transforming a value into a new value.

Type parameters:

  • V — The type of value transformed.
def apply(target: V) -> V

Apply the transformation to a target.

Parameters:

  • target (V) — The value to transform.

Returns:

  • V — the transformed value.
class Event

Bases: Protocol

Protocol for events that can be summarised for logging.

def summarise() -> JsonValue

Summarise the event, omitting its payload and metadata.

Returns:

class CategoryIdentifier(category: str)

Bases: EventSourceIdentifier

Identifies a category of streams.

Serialises to {"type": "category", "category": ...}.

Attributes:

  • category (str) — The category name.
category: str
def serialise(
    fallback: Callable[[object], JsonValue] = default_serialisation_fallback,
) -> JsonValue
class Converter[F, T]

Bases: ABC

Abstract base class for converting values of one type to another.

Type parameters:

  • F — The type converted from.
  • T — The type converted to.
def convert(item: F) -> T

Convert an item.

Parameters:

  • item (F) — The item to convert.

Returns:

  • T — the converted item.
class EventSourceIdentifier

Bases: Identifier, ABC

Base class for identifiers of a source of events.

Built-in subclasses are LogIdentifier, LogPartitionIdentifier, CategoryIdentifier, CategoryPartitionIdentifier and StreamIdentifier. Projections record the identifier of the source they were projected from.

type JsonArray = Sequence[JsonValue]

A JSON array: a sequence of JSON values.

type JsonLoggable = JsonValueSerialisable | JsonValue

A value that can be serialised to JSON, for example for logging.

type JsonObject = Mapping[str, JsonValue]

A JSON object: a mapping from string keys to JSON values.

type JsonPersistable = JsonValueConvertible | JsonValue

A value that can be stored as JSON and read back.

type JsonPrimitive = str | int | float | bool | None

A JSON primitive: a string, number, boolean or None.

type JsonValue = JsonObject | JsonArray | JsonPrimitive

Any JSON value: an object, array or primitive.

class JsonValueConvertible

Bases: JsonValueSerialisable, JsonValueDeserialisable, Protocol

Protocol for types that are JSON serialisable and deserialisable.

class JsonValueDeserialisable

Bases: Protocol

Protocol for classes that can deserialise instances from JSON.

@classmethod
def deserialise(
    value: JsonValue,
    fallback: Callable[[type[Any], JsonValue], Any],
) -> Self

Deserialise an instance from a JSON value.

Parameters:

  • value (JsonValue) — The JSON value to deserialise.
  • fallback (Callable[[type[Any], JsonValue], Any]) — Called with a target type and value to deserialise any nested value that cannot otherwise be deserialised.

Returns:

  • Self — the deserialised instance.
class JsonValueSerialisable

Bases: Protocol

Protocol for objects that can serialise themselves to a JSON value.

def serialise(fallback: Callable[[object], JsonValue]) -> JsonValue

Serialise the object to a JSON value.

Parameters:

  • fallback (Callable[[object], JsonValue]) — Called to serialise any nested value that is neither a JSON value nor JsonValueSerialisable.

Returns:

JsonValueType = JsonValue.__value__

The runtime value of the JsonValue alias.

Pass this where a type object is expected, for example as the state_type when loading a projection, to request an untyped JSON value.

class LogIdentifier

Bases: EventSourceIdentifier

Identifies the whole event log, across all categories and streams.

Serialises to {"type": "log"}.

def serialise(
    fallback: Callable[[object], JsonValue] = default_serialisation_fallback,
) -> JsonValue
class NewEvent[Name = str, Payload = JsonValue, Metadata = JsonValue](
    *,
    name: Name,
    payload: Payload,
    metadata: Metadata,
    observed_at: datetime | None = None,
    occurred_at: datetime | None = None,
    clock: Clock = SystemClock(),
)

Bases: JsonValueSerialisable

An event that has not yet been published to the event store.

Type parameters:

  • Name — The type of the event name. Defaults to str.
  • Payload — The type of the event payload. Defaults to JsonValue.
  • Metadata — The type of the event metadata. Defaults to JsonValue.

Parameters:

  • name (Name) — The event name.
  • payload (Payload) — The event payload.
  • metadata (Metadata) — The event metadata. Required; pass None if the event has no metadata.
  • observed_at (datetime | None) — When the event was observed. Defaults to the current time from clock, in UTC.
  • occurred_at (datetime | None) — When the event occurred. Defaults to observed_at.
  • clock (Clock) — The clock used to default observed_at.

Attributes:

  • name (Name) — The event name.
  • payload (Payload) — The event payload.
  • metadata (Metadata) — The event metadata.
  • observed_at (datetime) — When the event was observed.
  • occurred_at (datetime) — When the event occurred.
name: Name
payload: Payload
metadata: Metadata
observed_at: datetime
occurred_at: datetime
def serialise(
    fallback: Callable[[object], JsonValue] = default_serialisation_fallback,
) -> JsonValue

Serialise the event to a JSON value.

Timestamps are serialised as ISO 8601 strings.

Parameters:

  • fallback (Callable[[object], JsonValue]) — Called to serialise values that are neither JSON values nor JsonValueSerialisable. Defaults to raising a ValueError.

Returns:

  • JsonValue — a JSON object containing every field of the event.
def summarise()

Summarise the event as its name and timestamps only.

type Projectable = EventSourceIdentifier

The type of identifier a projection can be projected from.

class Projection[State = JsonValue, Metadata = JsonValue](
    *,
    id: str,
    name: str,
    source: Projectable,
    state: State,
    metadata: Metadata,
)

The result of projecting the events from an event source.

A projection is identified by its name and id together.

Type parameters:

  • State — The type of the projection state. Defaults to JsonValue.
  • Metadata — The type of the projection metadata. Defaults to JsonValue.

Attributes:

  • id (str) — The projection id, unique among projections with the same name.
  • name (str) — The projection name, typically shared by all projections produced by the same projector.
  • source (Projectable) — The identifier of the event source projected from.
  • state (State) — The projection state.
  • metadata (Metadata) — The projection metadata.
id: str
name: str
source: Projectable
state: State
metadata: Metadata
def serialise(
    fallback: Callable[[object], JsonValue] = default_serialisation_fallback,
) -> JsonValue

Serialise the projection to a JSON value.

Parameters:

  • fallback (Callable[[object], JsonValue]) — Called to serialise values that are neither JSON values nor JsonValueSerialisable. Defaults to raising a ValueError.

Returns:

  • JsonValue — a JSON object containing every field of the projection.
def summarise(
    fallback: Callable[[object], JsonValue] = default_serialisation_fallback,
) -> JsonValue

Summarise the projection, omitting its state and metadata.

Parameters:

  • fallback (Callable[[object], JsonValue]) — Called to serialise any value in the source that cannot otherwise be serialised.

Returns:

  • JsonValue — a JSON object containing the projection id, name and source.
class StoredEvent[Name = str, Payload = JsonValue, Metadata = JsonValue](
    id: str,
    name: Name,
    stream: str,
    category: str,
    position: int,
    sequence_number: int,
    payload: Payload,
    metadata: Metadata,
    observed_at: datetime,
    occurred_at: datetime,
)

Bases: JsonValueSerialisable, Event

An event that has been published to the event store.

Type parameters:

  • Name — The type of the event name. Defaults to str.
  • Payload — The type of the event payload. Defaults to JsonValue.
  • Metadata — The type of the event metadata. Defaults to JsonValue.

Attributes:

  • id (str) — The unique id assigned to the event by the store.
  • name (Name) — The event name.
  • stream (str) — The name of the stream the event belongs to.
  • category (str) — The name of the category the event’s stream belongs to.
  • position (int) — The event’s position within its stream, starting at 0.
  • sequence_number (int) — A number ordering the event across the whole log.
  • payload (Payload) — The event payload.
  • metadata (Metadata) — The event metadata.
  • observed_at (datetime) — When the event was observed.
  • occurred_at (datetime) — When the event occurred.
id: str
name: Name
stream: str
category: str
position: int
sequence_number: int
payload: Payload
metadata: Metadata
observed_at: datetime
occurred_at: datetime
def serialise(
    fallback: Callable[[object], JsonValue] = default_serialisation_fallback,
) -> JsonValue

Serialise the event to a JSON value.

Timestamps are serialised as ISO 8601 strings.

Parameters:

  • fallback (Callable[[object], JsonValue]) — Called to serialise values that are neither JSON values nor JsonValueSerialisable. Defaults to raising a ValueError.

Returns:

  • JsonValue — a JSON object containing every field of the event.
def summarise() -> JsonValue

Summarise the event, omitting its payload and metadata.

Returns:

  • JsonValue — a JSON object containing the event’s identifying fields and timestamps.
class StreamIdentifier(category: str, stream: str)

Bases: EventSourceIdentifier

Identifies a single stream within a category.

Serialises to {"type": "stream", "category": ..., "stream": ...}.

Attributes:

  • category (str) — The name of the category the stream belongs to.
  • stream (str) — The stream name.
category: str
stream: str
def serialise(
    fallback: Callable[[object], JsonValue] = default_serialisation_fallback,
) -> JsonValue
class StringConvertible

Bases: StringSerialisable, StringDeserialisable, Protocol

Protocol for types that are string serialisable and deserialisable.

class StringDeserialisable

Bases: Protocol

Protocol for classes that can deserialise instances from a string.

@classmethod
def deserialise(value: str, fallback: Callable[[type[Any], str], Any]) -> Self

Deserialise an instance from a string.

Parameters:

  • value (str) — The string to deserialise.
  • fallback (Callable[[type[Any], str], Any]) — Called with a target type and value to deserialise any nested value that cannot otherwise be deserialised.

Returns:

  • Self — the deserialised instance.
type StringLoggable = StringSerialisable | str

A value that can be serialised to a string, for example for logging.

type StringPersistable = StringConvertible | str

A value that can be stored as a string and read back.

class StringSerialisable

Bases: Protocol

Protocol for objects that can serialise themselves to a string.

def serialise(fallback: Callable[[object], str]) -> str

Serialise the object to a string.

Parameters:

  • fallback (Callable[[object], str]) — Called to serialise any nested value that cannot otherwise be serialised.

Returns:

  • str — the serialised string.
default_deserialisation_fallback = raising_deserialisation_fallback

The deserialisation fallback used when none is given, which raises.

default_serialisation_fallback = raising_serialisation_fallback

The serialisation fallback used when none is given, which raises.

def deserialise_from_json_value[T](
    klass: type[T],
    value: object,
    fallback: Callable[[type[T], object], T] = default_deserialisation_fallback,
) -> T

Deserialise a JSON value to a given type.

Supports None, the primitive types str, int, float and bool, sequence and mapping types (including parameterised ones such as list[int] or Mapping[str, int]), JsonValueType and JsonValueDeserialisable classes. For parameterised sequences and mappings, each item is checked against the item type but the value is returned as is.

Parameters:

  • klass (type[T]) — The type to deserialise to.
  • value (object) — The value to deserialise.
  • fallback (Callable[[type[T], object], T]) — Called with klass and value when the value cannot otherwise be deserialised. Defaults to raising a ValueError.

Returns:

  • T — the deserialised value.
def deserialise_from_string[T](
    klass: type[T],
    value: object,
    fallback: Callable[[type[T], object], T] = default_deserialisation_fallback,
) -> T

Deserialise a string to a given type.

Strings are returned as is for str and its subclasses, and passed to the deserialise method of JsonValueDeserialisable classes. Anything else is passed to fallback.

Parameters:

  • klass (type[T]) — The type to deserialise to.
  • value (object) — The value to deserialise.
  • fallback (Callable[[type[T], object], T]) — Called with klass and value when the value cannot otherwise be deserialised. Defaults to raising a ValueError.

Returns:

  • T — the deserialised value.
def deserialise_projection[State: JsonPersistable = JsonValue, Metadata: JsonPersistable = JsonValue](
    projection: Projection[JsonValue, JsonValue],
    state_type: type[State] = JsonValueType,
    metadata_type: type[Metadata] = JsonValueType,
    state_fallback: Callable[[type[State], object], State] = _state_deserialisation_fallback,
    metadata_fallback: Callable[[type[Metadata], object], Metadata] = _metadata_deserialisation_fallback,
) -> Projection[State, Metadata]

Deserialise a projection’s state and metadata to the given types.

Uses deserialise_from_json_value for both state and metadata.

Parameters:

  • projection (Projection[JsonValue, JsonValue]) — The projection with JSON value state and metadata.
  • state_type (type[State]) — The type to deserialise the state into. Defaults to a JSON value.
  • metadata_type (type[Metadata]) — The type to deserialise the metadata into. Defaults to a JSON value.
  • state_fallback (Callable[[type[State], object], State]) — Called when the state cannot otherwise be deserialised. Defaults to raising a ValueError.
  • metadata_fallback (Callable[[type[Metadata], object], Metadata]) — Called when the metadata cannot otherwise be deserialised. Defaults to raising a ValueError.

Returns:

  • Projection[State, Metadata] — a copy of the projection with deserialised state and metadata.
def is_json_array(value: Any) -> TypeGuard[JsonArray]

Check whether a value is a JSON array.

Parameters:

  • value (Any) — The value to check.

Returns:

  • TypeGuard[JsonArray] — True if the value is a sequence, other than a string or bytes, whose items are all JSON values, checked recursively.
def is_json_object(value: Any) -> TypeGuard[JsonObject]

Check whether a value is a JSON object.

Parameters:

  • value (Any) — The value to check.

Returns:

  • TypeGuard[JsonObject] — True if the value is a mapping with string keys whose values are all JSON values, checked recursively.
def is_json_primitive(value: Any) -> TypeGuard[JsonPrimitive]

Check whether a value is a JSON primitive.

Parameters:

  • value (Any) — The value to check.

Returns:

  • TypeGuard[JsonPrimitive] — True if the value is a string, number, boolean or None.
def is_json_value(value: Any) -> TypeGuard[JsonValue]

Check whether a value is a JSON value.

Parameters:

  • value (Any) — The value to check.

Returns:

  • TypeGuard[JsonValue] — True if the value is a JSON primitive, array or object, checked recursively.
def raising_deserialisation_fallback[T](klass: type[T], value: object) -> T

Deserialisation fallback that rejects every value.

Parameters:

  • klass (type[T]) — The type that the value could not be deserialised to.
  • value (object) — The value that could not be deserialised.

Raises:

  • ValueError — Always.
def raising_serialisation_fallback(value: object) -> Any

Serialisation fallback that rejects every value.

Parameters:

  • value (object) — The value that could not be serialised.

Raises:

  • ValueError — Always.
def serialise_projection(
    projection: Projection[JsonPersistable, JsonPersistable],
    fallback: Callable[[object], JsonValue] = default_serialisation_fallback,
) -> Projection[JsonValue, JsonValue]

Serialise a projection’s state and metadata to JSON values.

Parameters:

  • projection (Projection[JsonPersistable, JsonPersistable]) — The projection to serialise.
  • fallback (Callable[[object], JsonValue]) — Called to serialise values that are neither JSON values nor JsonValueSerialisable. Defaults to raising a ValueError.

Returns:

def serialise_to_json_value(
    value: object,
    fallback: Callable[[object], JsonValue] = default_serialisation_fallback,
) -> JsonValue

Serialise a value to a JSON value.

JsonValueSerialisable values are serialised using their serialise method, JSON values are returned unchanged and anything else is passed to fallback.

Parameters:

  • value (object) — The value to serialise.
  • fallback (Callable[[object], JsonValue]) — Called with any value that cannot otherwise be serialised. Defaults to raising a ValueError.

Returns:

def serialise_to_string(
    value: object,
    fallback: Callable[[object], str] = default_serialisation_fallback,
) -> str

Serialise a value to a string.

StringSerialisable values are serialised using their serialise method, strings are returned unchanged and anything else is passed to fallback.

Parameters:

  • value (object) — The value to serialise.
  • fallback (Callable[[object], str]) — Called with any value that cannot otherwise be serialised. Defaults to raising a ValueError.

Returns:

  • str — the serialised string.
def str_serialisation_fallback(value: object) -> str

Serialisation fallback that converts the value using str.

Useful for logging, where a lossy representation is acceptable.

Parameters:

  • value (object) — The value that could not otherwise be serialised.

Returns:

  • str — the value as a string.