logicblocks.event.projection
logicblocks.event.projection
Section titled “logicblocks.event.projection”InMemoryProjectionStorageAdapter
Section titled “InMemoryProjectionStorageAdapter”class InMemoryProjectionStorageAdapter[ItemQuery: Query = Lookup, CollectionQuery: Query = Search](
query_converter: Converter[Query, ResultSetTransformer[Projection[JsonValue, JsonValue]]] | None = None,
)
Bases: ProjectionStorageAdapter[ItemQuery, CollectionQuery]
A projection storage adapter that keeps projections in memory.
Projections are stored serialised to JSON values, so they are deserialised again on retrieval. Contents are lost when the adapter is discarded, which makes it suited to tests and prototyping.
Updating an existing projection replaces only its state and metadata.
Parameters:
query_converter(Converter[Query, ResultSetTransformer[Projection[JsonValue, JsonValue]]] | None) — Converts queries into transformers applied to the stored projections. Defaults to aDelegatingQueryConverterwith the default converters.
async def save(
*,
projection: Projection[JsonPersistable, JsonPersistable],
) -> None
find_one
Section titled “find_one”async def find_one[State: JsonPersistable = JsonValue, Metadata: JsonPersistable = JsonValue](
*,
lookup: ItemQuery,
state_type: type[State] = JsonValueType,
metadata_type: type[Metadata] = JsonValueType,
) -> Projection[State, Metadata] | None
find_many
Section titled “find_many”async def find_many[State: JsonPersistable = JsonValue, Metadata: JsonPersistable = JsonValue](
*,
search: CollectionQuery,
state_type: type[State] = JsonValueType,
metadata_type: type[Metadata] = JsonValueType,
) -> Sequence[Projection[State, Metadata]]
async def count(*, search: CollectionQuery) -> int
MissingHandlerBehaviour
Section titled “MissingHandlerBehaviour”class MissingHandlerBehaviour
Bases: StrEnum
What a projector does when it has no handler for an event.
Attributes:
RAISE— Raise aMissingProjectionHandlerError.IGNORE— Leave the state unchanged.
RAISE = 'raise'
IGNORE
Section titled “IGNORE”IGNORE = 'ignore'
MissingProjectionHandlerError
Section titled “MissingProjectionHandlerError”class MissingProjectionHandlerError(event: StoredEvent, projection_class: type)
Bases: Exception
Raised when a projector has no handler for an event it is applying.
Only raised when the projector’s missing_handler_behaviour is
MissingHandlerBehaviour.RAISE.
Parameters:
event(StoredEvent) — The event for which no handler was found.projection_class(type) — The projector class that was missing the handler.
PostgresProjectionStorageAdapter
Section titled “PostgresProjectionStorageAdapter”class PostgresProjectionStorageAdapter[ItemQuery: Query = Lookup, CollectionQuery: Query = Search](
*,
connection_source: postgres.ConnectionSource,
table_settings: postgres.TableSettings = postgres.TableSettings(table_name='projections'),
query_converter: postgres.QueryConverter | None = None,
)
Bases: ProjectionStorageAdapter[ItemQuery, CollectionQuery]
A projection storage adapter backed by a PostgreSQL table.
State, metadata and source are stored as jsonb. Saving upserts on
(name, id), replacing only the state and metadata of an existing
projection. Only log, category and stream source identifiers can be read
back.
When given ConnectionSettings, the adapter creates and owns a
connection pool, which must be opened with open before use and closed
with close afterwards. When given an existing pool, the caller
manages its lifecycle and open and close do nothing.
Parameters:
connection_source(postgres.ConnectionSource) — EitherConnectionSettingsor an existingAsyncConnectionPool.table_settings(postgres.TableSettings) — The table to store projections in. Defaults to a table namedprojections.query_converter(postgres.QueryConverter | None) — Converts queries into SQL. Defaults to aQueryConverterfortable_settingswith the default converters.
connection_pool
Section titled “connection_pool”connection_pool
table_settings
Section titled “table_settings”table_settings
query_converter
Section titled “query_converter”query_converter
async def open() -> None
Open the connection pool, if the adapter owns it.
async def close() -> None
Close the connection pool, if the adapter owns it.
async def save(
*,
projection: Projection[JsonPersistable, JsonPersistable],
) -> None
find_one
Section titled “find_one”async def find_one[State: JsonPersistable = JsonValue, Metadata: JsonPersistable = JsonValue](
*,
lookup: ItemQuery,
state_type: type[State] = JsonValueType,
metadata_type: type[Metadata] = JsonValueType,
) -> Projection[State, Metadata] | None
find_many
Section titled “find_many”async def find_many[State: JsonPersistable = JsonValue, Metadata: JsonPersistable = JsonValue](
*,
search: CollectionQuery,
state_type: type[State] = JsonValueType,
metadata_type: type[Metadata] = JsonValueType,
) -> Sequence[Projection[State, Metadata]]
async def count(*, search: CollectionQuery) -> int
ProjectionStorageAdapter
Section titled “ProjectionStorageAdapter”class ProjectionStorageAdapter[ItemQuery: Query = Lookup, CollectionQuery: Query = Search]
Bases: ABC
Abstract base class for projection storage backends.
Implement the abstract methods to provide a custom backend for use with
ProjectionStore. Projections are keyed by their name and id together.
Queries refer to the projection fields id, name, source, state
and metadata by path.
Type parameters:
ItemQuery(Query) — The query type accepted byfind_one. Defaults toLookup.CollectionQuery(Query) — The query type accepted byfind_manyandcount. Defaults toSearch.
async def save(
*,
projection: Projection[JsonPersistable, JsonPersistable],
) -> None
Insert a projection, or update it if it already exists.
A projection already exists if one with the same name and id is stored, in which case its state and metadata are replaced. State and metadata must be serialised to JSON values for storage.
Parameters:
projection(Projection[JsonPersistable, JsonPersistable]) — The projection to save.
find_one
Section titled “find_one”async def find_one[State: JsonPersistable = JsonValue, Metadata: JsonPersistable = JsonValue](
*,
lookup: ItemQuery,
state_type: type[State] = JsonValueType,
metadata_type: type[Metadata] = JsonValueType,
) -> Projection[State, Metadata] | None
Find the single projection matching a query.
Parameters:
lookup(ItemQuery) — The query identifying the projection.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.
Returns:
Projection[State, Metadata] | None— the matching projection, orNoneif there is no match.
Raises:
ValueError— If more than one projection matches.
find_many
Section titled “find_many”async def find_many[State: JsonPersistable = JsonValue, Metadata: JsonPersistable = JsonValue](
*,
search: CollectionQuery,
state_type: type[State] = JsonValueType,
metadata_type: type[Metadata] = JsonValueType,
) -> Sequence[Projection[State, Metadata]]
Find all projections matching a query.
Parameters:
search(CollectionQuery) — The query to match, including any sorting and paging.state_type(type[State]) — The type to deserialise each state into. Defaults to a JSON value.metadata_type(type[Metadata]) — The type to deserialise each metadata into. Defaults to a JSON value.
Returns:
Sequence[Projection[State, Metadata]]— the matching projections, possibly empty.
async def count(*, search: CollectionQuery) -> int
Count the projections matching a query.
Any paging in the query is applied too, so a paged query counts only that page.
Parameters:
search(CollectionQuery) — The query to match.
Returns:
int— the number of matching projections.
ProjectionStore
Section titled “ProjectionStore”class ProjectionStore(
adapter: ProjectionStorageAdapter,
logger: FilteringBoundLogger = default_logger,
)
Saves and retrieves projections using a storage adapter.
Parameters:
adapter(ProjectionStorageAdapter) — The storage adapter to persist projections with.logger(FilteringBoundLogger) — The logger to log operations to.
async def save(
*,
projection: Projection[JsonPersistable, JsonPersistable],
) -> None
Save a projection, inserting or updating it.
If a projection with the same name and id is already stored, its state and metadata are replaced.
Parameters:
projection(Projection[JsonPersistable, JsonPersistable]) — The projection to save.
locate
Section titled “locate”async def locate[State: JsonPersistable = JsonValue, Metadata: JsonPersistable = JsonValue](
*,
source: EventSourceIdentifier,
name: str,
state_type: type[State] = JsonValueType,
metadata_type: type[Metadata] = JsonValueType,
) -> Projection[State, Metadata] | None
Find a projection by its source and name.
Parameters:
source(EventSourceIdentifier) — The identifier of the event source the projection was projected from.name(str) — The projection name.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.
Returns:
Projection[State, Metadata] | None— the matching projection, orNoneif there is no match.
Raises:
ValueError— If more than one projection matches.
async def load[State: JsonPersistable = Mapping[str, Any], Metadata: JsonPersistable = Mapping[str, Any]](
*,
id: str,
name: str,
state_type: type[State],
metadata_type: type[Metadata],
) -> Projection[State, Metadata] | None
Load a projection by its id and name.
Parameters:
id(str) — The projection id.name(str) — The projection name.state_type(type[State]) — The type to deserialise the state into.metadata_type(type[Metadata]) — The type to deserialise the metadata into.
Returns:
Projection[State, Metadata] | None— the matching projection, orNoneif there is no match.
search
Section titled “search”async def search[State: JsonPersistable = JsonValue, Metadata: JsonPersistable = JsonValue](
*,
filters: Sequence[FilterClause],
sort: SortClause,
paging: PagingClause,
state_type: type[State] = JsonValueType,
metadata_type: type[Metadata] = JsonValueType,
) -> Sequence[Projection[State, Metadata]]
Find all projections matching the given clauses.
Parameters:
filters(Sequence[FilterClause]) — The filter clauses projections must match.sort(SortClause) — How to order the results.paging(PagingClause) — Which page of results to return.state_type(type[State]) — The type to deserialise each state into. Defaults to a JSON value.metadata_type(type[Metadata]) — The type to deserialise each metadata into. Defaults to a JSON value.
Returns:
Sequence[Projection[State, Metadata]]— the matching projections, possibly empty.
Projector
Section titled “Projector”class Projector[Identifier: EventSourceIdentifier, State, Metadata = JsonValue]
Bases: ABC
Base class for projectors, which fold events into a projection.
Subclass Projector and implement initial_state_factory,
initial_metadata_factory and id_factory, then add one handler method
per event name. Handlers are found by converting the event name to snake
case, so an event named profile-created is handled by
profile_created. Each handler takes the current state and the event and
returns the new state:
class ProfileProjector(Projector[StreamIdentifier, dict[str, str]]): def initial_state_factory(self) -> dict[str, str]: return {}
def initial_metadata_factory(self) -> JsonValue: return {}
def id_factory(self, state, source: StreamIdentifier) -> str: return source.stream
def profile_created(self, state, event): return {**state, "name": event.payload["name"]}Event names that convert to an existing projector method, such as
finalise-state, apply, project or id-factory, are routed to that
method as if it were a handler, so avoid them.
Type parameters:
Identifier(EventSourceIdentifier) — The type of event source identifier the projector projects from, for exampleStreamIdentifier.State— The type of the projection state.Metadata— The type of the projection metadata. Defaults toJsonValue.
Attributes:
name(str | None) — The projection name. Defaults toNone, in which caseprojection_namederives one from the class name.missing_handler_behaviour(MissingHandlerBehaviour) — What to do when an event has no handler. Defaults toMissingHandlerBehaviour.RAISE.
name: str | None = None
missing_handler_behaviour
Section titled “missing_handler_behaviour”missing_handler_behaviour: MissingHandlerBehaviour = MissingHandlerBehaviour.RAISE
initial_state_factory
Section titled “initial_state_factory”def initial_state_factory() -> State
Create the state to start from when no state is provided.
Returns:
State— the initial projection state.
initial_metadata_factory
Section titled “initial_metadata_factory”def initial_metadata_factory() -> Metadata
Create the metadata to start from when no metadata is provided.
Returns:
Metadata— the initial projection metadata.
id_factory
Section titled “id_factory”def id_factory(state: State, source: Identifier) -> str
Derive the projection id.
Called by project with the finalised state.
Parameters:
state(State) — The finalised projection state.source(Identifier) — The identifier of the event source being projected.
Returns:
str— the projection id.
update_metadata
Section titled “update_metadata”def update_metadata(
state: State,
metadata: Metadata,
event: StoredEvent,
) -> Metadata
Update the metadata after an event has been applied.
Called by project once per event, after the event’s handler. The
default implementation returns the metadata unchanged.
Parameters:
state(State) — The (unfinalised) state after applying the event.metadata(Metadata) — The current metadata.event(StoredEvent) — The event that was just applied.
Returns:
Metadata— the new metadata.
finalise_state
Section titled “finalise_state”def finalise_state(state: State) -> State
Transform the state once all events have been applied.
Override this for work, such as validation or normalisation, that
only needs doing once per projection rather than in every handler.
Called once at the end of each project call, including when the
source has no events, and before id_factory. The default
implementation returns the state unchanged.
The output becomes the starting state when a projection is resumed,
so it must not change what later handlers, update_metadata or
id_factory compute, and it must survive a round trip through the
projection store. See the README’s “Finalising State” section for
details.
Parameters:
state(State) — The state after all events have been applied.
Returns:
State— the finalised state.
projection_name
Section titled “projection_name”property projection_name
The name given to projections produced by this projector.
This is name if set, otherwise the class name with Projector
removed, in kebab case; for example ProfileProjector gives
profile.
def apply(*, event: StoredEvent[Any], state: State | None = None) -> State
Apply a single event to a state using the event’s handler.
Does not call update_metadata or finalise_state.
Parameters:
event(StoredEvent[Any]) — The event to apply.state(State | None) — The state to apply the event to. Defaults to the result ofinitial_state_factory.
Returns:
State— the new state, or the state unchanged if there is no handler andmissing_handler_behaviourisIGNORE.
Raises:
MissingProjectionHandlerError— If there is no handler for the event andmissing_handler_behaviourisRAISE.
project
Section titled “project”async def project(
*,
source: EventSource[Identifier, StoredEvent],
state: State | None = None,
metadata: Metadata | None = None,
) -> Projection[State, Metadata]
Project all events from an event source into a projection.
Applies each event in turn, calling update_metadata after each
one, then calls finalise_state and derives the id from the
finalised state using id_factory.
Parameters:
source(EventSource[Identifier, StoredEvent]) — The event source to read events from.state(State | None) — The state to start from, for example to resume a previous projection. Defaults to the result ofinitial_state_factory.metadata(Metadata | None) — The metadata to start from. Defaults to the result ofinitial_metadata_factory.
Returns:
Projection[State, Metadata]— the projection, namedprojection_name, with the source’s identifier as its source.
Raises:
MissingProjectionHandlerError— If an event has no handler andmissing_handler_behaviourisRAISE.