Skip to content

logicblocks.event.projection

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:

async def save(
    *,
    projection: Projection[JsonPersistable, JsonPersistable],
) -> None
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
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
class MissingHandlerBehaviour

Bases: StrEnum

What a projector does when it has no handler for an event.

Attributes:

  • RAISE — Raise a MissingProjectionHandlerError.
  • IGNORE — Leave the state unchanged.
RAISE = 'raise'
IGNORE = 'ignore'
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.
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) — Either ConnectionSettings or an existing AsyncConnectionPool.
  • table_settings (postgres.TableSettings) — The table to store projections in. Defaults to a table named projections.
  • query_converter (postgres.QueryConverter | None) — Converts queries into SQL. Defaults to a QueryConverter for table_settings with the default converters.
connection_pool
table_settings
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
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
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
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 by find_one. Defaults to Lookup.
  • CollectionQuery (Query) — The query type accepted by find_many and count. Defaults to Search.
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:

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, or None if there is no match.

Raises:

  • ValueError — If more than one projection matches.
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.
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:

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, or None if 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, or None if there is no match.
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.
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 example StreamIdentifier.
  • State — The type of the projection state.
  • Metadata — The type of the projection metadata. Defaults to JsonValue.

Attributes:

  • name (str | None) — The projection name. Defaults to None, in which case projection_name derives one from the class name.
  • missing_handler_behaviour (MissingHandlerBehaviour) — What to do when an event has no handler. Defaults to MissingHandlerBehaviour.RAISE.
name: str | None = None
missing_handler_behaviour: MissingHandlerBehaviour = MissingHandlerBehaviour.RAISE
def initial_state_factory() -> State

Create the state to start from when no state is provided.

Returns:

  • State — the initial projection state.
def initial_metadata_factory() -> Metadata

Create the metadata to start from when no metadata is provided.

Returns:

  • Metadata — the initial projection metadata.
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.
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.
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.
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 of initial_state_factory.

Returns:

  • State — the new state, or the state unchanged if there is no handler and missing_handler_behaviour is IGNORE.

Raises:

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 of initial_state_factory.
  • metadata (Metadata | None) — The metadata to start from. Defaults to the result of initial_metadata_factory.

Returns:

  • Projection[State, Metadata] — the projection, named projection_name, with the source’s identifier as its source.

Raises: