logicblocks.event.types
logicblocks.event.types
Section titled “logicblocks.event.types”Applier
Section titled “Applier”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.
summarise
Section titled “summarise”def summarise() -> JsonValue
Summarise the event, omitting its payload and metadata.
Returns:
JsonValue— a JSON summary of the event.
CategoryIdentifier
Section titled “CategoryIdentifier”class CategoryIdentifier(category: str)
Bases: EventSourceIdentifier
Identifies a category of streams.
Serialises to {"type": "category", "category": ...}.
Attributes:
category(str) — The category name.
category
Section titled “category”category: str
serialise
Section titled “serialise”def serialise(
fallback: Callable[[object], JsonValue] = default_serialisation_fallback,
) -> JsonValue
Converter
Section titled “Converter”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.
convert
Section titled “convert”def convert(item: F) -> T
Convert an item.
Parameters:
item(F) — The item to convert.
Returns:
T— the converted item.
EventSourceIdentifier
Section titled “EventSourceIdentifier”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.
JsonArray
Section titled “JsonArray”type JsonArray = Sequence[JsonValue]
A JSON array: a sequence of JSON values.
JsonLoggable
Section titled “JsonLoggable”type JsonLoggable = JsonValueSerialisable | JsonValue
A value that can be serialised to JSON, for example for logging.
JsonObject
Section titled “JsonObject”type JsonObject = Mapping[str, JsonValue]
A JSON object: a mapping from string keys to JSON values.
JsonPersistable
Section titled “JsonPersistable”type JsonPersistable = JsonValueConvertible | JsonValue
A value that can be stored as JSON and read back.
JsonPrimitive
Section titled “JsonPrimitive”type JsonPrimitive = str | int | float | bool | None
A JSON primitive: a string, number, boolean or None.
JsonValue
Section titled “JsonValue”type JsonValue = JsonObject | JsonArray | JsonPrimitive
Any JSON value: an object, array or primitive.
JsonValueConvertible
Section titled “JsonValueConvertible”class JsonValueConvertible
Bases: JsonValueSerialisable, JsonValueDeserialisable, Protocol
Protocol for types that are JSON serialisable and deserialisable.
JsonValueDeserialisable
Section titled “JsonValueDeserialisable”class JsonValueDeserialisable
Bases: Protocol
Protocol for classes that can deserialise instances from JSON.
deserialise
Section titled “deserialise”@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.
JsonValueSerialisable
Section titled “JsonValueSerialisable”class JsonValueSerialisable
Bases: Protocol
Protocol for objects that can serialise themselves to a JSON value.
serialise
Section titled “serialise”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 norJsonValueSerialisable.
Returns:
JsonValue— the serialised JSON value.
JsonValueType
Section titled “JsonValueType”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.
LogIdentifier
Section titled “LogIdentifier”class LogIdentifier
Bases: EventSourceIdentifier
Identifies the whole event log, across all categories and streams.
Serialises to {"type": "log"}.
serialise
Section titled “serialise”def serialise(
fallback: Callable[[object], JsonValue] = default_serialisation_fallback,
) -> JsonValue
NewEvent
Section titled “NewEvent”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 tostr.Payload— The type of the event payload. Defaults toJsonValue.Metadata— The type of the event metadata. Defaults toJsonValue.
Parameters:
name(Name) — The event name.payload(Payload) — The event payload.metadata(Metadata) — The event metadata. Required; passNoneif the event has no metadata.observed_at(datetime | None) — When the event was observed. Defaults to the current time fromclock, in UTC.occurred_at(datetime | None) — When the event occurred. Defaults toobserved_at.clock(Clock) — The clock used to defaultobserved_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
Section titled “payload”payload: Payload
metadata
Section titled “metadata”metadata: Metadata
observed_at
Section titled “observed_at”observed_at: datetime
occurred_at
Section titled “occurred_at”occurred_at: datetime
serialise
Section titled “serialise”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 norJsonValueSerialisable. Defaults to raising aValueError.
Returns:
JsonValue— a JSON object containing every field of the event.
summarise
Section titled “summarise”def summarise()
Summarise the event as its name and timestamps only.
Projectable
Section titled “Projectable”type Projectable = EventSourceIdentifier
The type of identifier a projection can be projected from.
Projection
Section titled “Projection”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 toJsonValue.Metadata— The type of the projection metadata. Defaults toJsonValue.
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
Section titled “source”source: Projectable
state: State
metadata
Section titled “metadata”metadata: Metadata
serialise
Section titled “serialise”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 norJsonValueSerialisable. Defaults to raising aValueError.
Returns:
JsonValue— a JSON object containing every field of the projection.
summarise
Section titled “summarise”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.
StoredEvent
Section titled “StoredEvent”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 tostr.Payload— The type of the event payload. Defaults toJsonValue.Metadata— The type of the event metadata. Defaults toJsonValue.
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
Section titled “stream”stream: str
category
Section titled “category”category: str
position
Section titled “position”position: int
sequence_number
Section titled “sequence_number”sequence_number: int
payload
Section titled “payload”payload: Payload
metadata
Section titled “metadata”metadata: Metadata
observed_at
Section titled “observed_at”observed_at: datetime
occurred_at
Section titled “occurred_at”occurred_at: datetime
serialise
Section titled “serialise”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 norJsonValueSerialisable. Defaults to raising aValueError.
Returns:
JsonValue— a JSON object containing every field of the event.
summarise
Section titled “summarise”def summarise() -> JsonValue
Summarise the event, omitting its payload and metadata.
Returns:
JsonValue— a JSON object containing the event’s identifying fields and timestamps.
StreamIdentifier
Section titled “StreamIdentifier”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
Section titled “category”category: str
stream
Section titled “stream”stream: str
serialise
Section titled “serialise”def serialise(
fallback: Callable[[object], JsonValue] = default_serialisation_fallback,
) -> JsonValue
StringConvertible
Section titled “StringConvertible”class StringConvertible
Bases: StringSerialisable, StringDeserialisable, Protocol
Protocol for types that are string serialisable and deserialisable.
StringDeserialisable
Section titled “StringDeserialisable”class StringDeserialisable
Bases: Protocol
Protocol for classes that can deserialise instances from a string.
deserialise
Section titled “deserialise”@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.
StringLoggable
Section titled “StringLoggable”type StringLoggable = StringSerialisable | str
A value that can be serialised to a string, for example for logging.
StringPersistable
Section titled “StringPersistable”type StringPersistable = StringConvertible | str
A value that can be stored as a string and read back.
StringSerialisable
Section titled “StringSerialisable”class StringSerialisable
Bases: Protocol
Protocol for objects that can serialise themselves to a string.
serialise
Section titled “serialise”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
Section titled “default_deserialisation_fallback”default_deserialisation_fallback = raising_deserialisation_fallback
The deserialisation fallback used when none is given, which raises.
default_serialisation_fallback
Section titled “default_serialisation_fallback”default_serialisation_fallback = raising_serialisation_fallback
The serialisation fallback used when none is given, which raises.
deserialise_from_json_value
Section titled “deserialise_from_json_value”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 withklassandvaluewhen the value cannot otherwise be deserialised. Defaults to raising aValueError.
Returns:
T— the deserialised value.
deserialise_from_string
Section titled “deserialise_from_string”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 withklassandvaluewhen the value cannot otherwise be deserialised. Defaults to raising aValueError.
Returns:
T— the deserialised value.
deserialise_projection
Section titled “deserialise_projection”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 aValueError.metadata_fallback(Callable[[type[Metadata], object], Metadata]) — Called when the metadata cannot otherwise be deserialised. Defaults to raising aValueError.
Returns:
Projection[State, Metadata]— a copy of the projection with deserialised state and metadata.
is_json_array
Section titled “is_json_array”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]—Trueif the value is a sequence, other than a string or bytes, whose items are all JSON values, checked recursively.
is_json_object
Section titled “is_json_object”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]—Trueif the value is a mapping with string keys whose values are all JSON values, checked recursively.
is_json_primitive
Section titled “is_json_primitive”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]—Trueif the value is a string, number, boolean orNone.
is_json_value
Section titled “is_json_value”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]—Trueif the value is a JSON primitive, array or object, checked recursively.
raising_deserialisation_fallback
Section titled “raising_deserialisation_fallback”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.
raising_serialisation_fallback
Section titled “raising_serialisation_fallback”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.
serialise_projection
Section titled “serialise_projection”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 norJsonValueSerialisable. Defaults to raising aValueError.
Returns:
Projection[JsonValue, JsonValue]— a copy of the projection with JSON value state and metadata.
serialise_to_json_value
Section titled “serialise_to_json_value”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 aValueError.
Returns:
JsonValue— the serialised JSON value.
serialise_to_string
Section titled “serialise_to_string”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 aValueError.
Returns:
str— the serialised string.
str_serialisation_fallback
Section titled “str_serialisation_fallback”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.