Skip to content

logicblocks.event.sources

class ConstrainedEventSource[I: EventSourceIdentifier, E: Event](
    delegate: EventSource[I, E],
    constraints: Set[QueryConstraint],
)

Bases: EventSource[I, E]

An event source that applies a fixed set of constraints to a delegate.

Every call to iterate (and therefore read and async iteration) is forwarded to the delegate with the fixed constraints merged into any constraints supplied by the caller. latest is forwarded unconstrained.

Parameters:

  • delegate (EventSource[I, E]) — The event source to read events from.
  • constraints (Set[QueryConstraint]) — Query constraints applied to every iteration.
property identifier: I
async def latest() -> E | None
def iterate(
    *,
    constraints: Set[QueryConstraint] = frozenset(),
) -> AsyncIterator[E]
class EventSource[I: EventSourceIdentifier, E: Event]

Bases: ABC

Abstract base class for a readable source of events.

An event source is identified by an EventSourceIdentifier, such as a log, category or stream identifier, and provides access to the events it contains. Event sources are async iterable: iterating an event source directly is equivalent to calling iterate with no constraints.

Subclasses must implement identifier, latest and iterate.

property identifier: I

The identifier of this event source.

async def latest() -> E | None

Get the most recent event in the source.

Returns:

  • E | None — the latest event, or None if the source contains no events.
async def read(
    *,
    constraints: Set[QueryConstraint] = frozenset(),
) -> Sequence[E]

Read all events in the source into a sequence.

Parameters:

  • constraints (Set[QueryConstraint]) — Query constraints that each returned event must satisfy. Defaults to no constraints.

Returns:

  • Sequence[E] — the matching events, in the order produced by iterate.
def iterate(
    *,
    constraints: Set[QueryConstraint] = frozenset(),
) -> AsyncIterator[E]

Iterate over the events in the source.

Parameters:

  • constraints (Set[QueryConstraint]) — Query constraints that each yielded event must satisfy. Defaults to no constraints.

Returns:

  • AsyncIterator[E] — an async iterator over the matching events.
def __aiter__() -> AsyncIterator[E]
class EventSourceFactory[E: Event]

Bases: ABC

Abstract factory for constructing event sources from identifiers.

def construct[I: EventSourceIdentifier](identifier: I) -> EventSource[I, E]

Construct an event source for an identifier.

Parameters:

  • identifier (I) — The identifier of the event source to construct.

Returns:

  • EventSource[I, E] — an event source for the identifier.
class InMemoryEventSource[I: EventSourceIdentifier, E: Event](
    events: Sequence[E],
    identifier: I,
    constraint_converter: Converter[QueryConstraint, QueryConstraintCheck[E]] | None = None,
)

Bases: EventSource[I, E], ABC

Abstract event source backed by an in-memory sequence of events.

Events are yielded in the order of the supplied sequence. Each query constraint is converted into a predicate by the constraint converter and an event is yielded only if it satisfies all predicates. Subclasses must implement _get_default_constraint_converter to supply the converter used when none is provided.

Parameters:

  • events (Sequence[E]) — The events in the source, in order.
  • identifier (I) — The identifier of the source.
  • constraint_converter (Converter[QueryConstraint, QueryConstraintCheck[E]] | None) — Converts query constraints into predicates over events. Defaults to the subclass’s default converter.
property identifier: I
async def latest() -> E | None
async def iterate(
    *,
    constraints: Set[QueryConstraint] = frozenset(),
) -> AsyncIterator[E]

Query constraints for filtering the events read from an event source.

Constraints are declarative: each event source or storage adapter converts them into its own representation (for example, a predicate or a SQL clause) before applying them.

type QueryConstraintCheck[E: Event] = Callable[[E], bool]
class QueryConstraint

Bases: ABC

Base class for constraints restricting the events read from a source.

class SequenceNumberAfterConstraint(sequence_number: int)

Bases: QueryConstraint

Constraint matching events with a sequence number greater than a value.

Attributes:

  • sequence_number (int) — The exclusive lower bound on sequence number.
sequence_number: int
def sequence_number_after(sequence_number: int) -> QueryConstraint

Create a constraint matching events after a given sequence number.

Parameters:

  • sequence_number (int) — The exclusive lower bound on sequence number.

Returns:

  • QueryConstraint — a SequenceNumberAfterConstraint for the sequence number.