logicblocks.event.processing
logicblocks.event.processing
Section titled “logicblocks.event.processing”EventConsumerStateConverter
Section titled “EventConsumerStateConverter”class EventConsumerStateConverter[E: Event]
Bases: ABC
Converts between events and the consumer state that tracks them.
Implementations define what state is recorded when an event is processed and how that state is turned into a query constraint that resumes consumption after the last processed event.
event_to_state
Section titled “event_to_state”def event_to_state(event: E) -> JsonObject
Return the consumer state to record for a processed event.
Parameters:
event(E) — The event that has been processed.
initial_state
Section titled “initial_state”def initial_state() -> JsonObject
Return the consumer state to use when no events are processed.
state_to_query_constraint
Section titled “state_to_query_constraint”def state_to_query_constraint(
state: JsonObject,
) -> constraints.QueryConstraint | None
Convert consumer state into a constraint for resuming consumption.
Parameters:
state(JsonObject) — The consumer state to convert.
Returns:
constraints.QueryConstraint | None— a constraint selecting events after those already processed, orNoneif all events should be consumed.
ContinueErrorHandler
Section titled “ContinueErrorHandler”class ContinueErrorHandler[T](value_factory: Callable[[BaseException], T])
Bases: ErrorHandler[T]
Error handler that decides to continue, returning a value.
Exceptions that are not Exception subclasses, such as
asyncio.CancelledError, are raised instead.
Parameters:
value_factory(Callable[[BaseException], T]) — Returns the value to continue with for an exception.
value_factory
Section titled “value_factory”value_factory: Callable[[BaseException], T]
handle
Section titled “handle”def handle(exception: BaseException) -> ErrorHandlerDecision[T]
ContinueErrorHandlerDecision
Section titled “ContinueErrorHandlerDecision”class ContinueErrorHandlerDecision[T](value: T)
Bases: ErrorHandlerDecision[T]
Decision to continue, returning a value in place of a result.
Attributes:
value(T) — The value to return.
value: T
DistributedEventBroker
Section titled “DistributedEventBroker”class DistributedEventBroker[E: Event](
event_subscriber_manager: EventSubscriberManager[E],
event_subscription_coordinator: EventSubscriptionCoordinator,
event_subscription_observer: EventSubscriptionObserver[E],
error_handler: ErrorHandler[NoneType] = RetryErrorHandler(),
)
Bases: EventBroker[E]
An event broker that coordinates event source allocation across nodes.
While running, the broker concurrently:
- maintains the registration of this node’s subscribers in shared state, sending heartbeats for healthy subscribers and purging stale ones, via the subscriber manager;
- competes for leadership and, while leader, distributes the event sources requested by each subscriber group across the live subscribers in that group, via the subscription coordinator;
- applies the resulting allocations to this node’s subscribers, calling
acceptandwithdrawas they change, via the subscription observer.
Subscribers are unregistered from shared state when execution ends.
Parameters:
event_subscriber_manager(EventSubscriberManager[E]) — Manages this node’s subscribers.event_subscription_coordinator(EventSubscriptionCoordinator) — Allocates event sources to subscribers when this node is leader.event_subscription_observer(EventSubscriptionObserver[E]) — Applies allocations to this node’s subscribers.error_handler(ErrorHandler[NoneType]) — The handler for errors raised during execution. Defaults to aRetryErrorHandler.
status
Section titled “status”property status: ProcessStatus
The combined status of the coordinator and observer.
register
Section titled “register”async def register(subscriber: EventSubscriber[E]) -> None
execute
Section titled “execute”async def execute() -> None
Run the broker until cancelled.
Errors are handled by the configured error handler.
DistributedEventBrokerSettings
Section titled “DistributedEventBrokerSettings”class DistributedEventBrokerSettings(
subscriber_manager_heartbeat_interval: timedelta = timedelta(seconds=10),
subscriber_manager_purge_interval: timedelta = timedelta(minutes=1),
subscriber_manager_subscriber_max_age: timedelta = timedelta(minutes=10),
coordinator_subscriber_max_time_since_last_seen: timedelta = timedelta(seconds=60),
coordinator_distribution_interval: timedelta = timedelta(seconds=20),
coordinator_leadership_max_duration: timedelta = timedelta(minutes=15),
coordinator_leadership_attempt_interval: timedelta = timedelta(seconds=5),
observer_synchronisation_interval: timedelta = timedelta(seconds=20),
)
Settings for a distributed event broker.
Attributes:
subscriber_manager_heartbeat_interval(timedelta) — How often heartbeats are sent for this node’s healthy subscribers.subscriber_manager_purge_interval(timedelta) — How often subscribers not seen recently are purged from shared state.subscriber_manager_subscriber_max_age(timedelta) — How long since last seen before a subscriber is purged.coordinator_subscriber_max_time_since_last_seen(timedelta) — How long since last seen before the coordinator stops allocating event sources to a subscriber.coordinator_distribution_interval(timedelta) — How often the leader redistributes event sources.coordinator_leadership_max_duration(timedelta) — The maximum time a node holds leadership before releasing it.coordinator_leadership_attempt_interval(timedelta) — How often a node that is not leader attempts to acquire leadership.observer_synchronisation_interval(timedelta) — How often allocations are synchronised to this node’s subscribers.
subscriber_manager_heartbeat_interval
Section titled “subscriber_manager_heartbeat_interval”subscriber_manager_heartbeat_interval: timedelta = timedelta(seconds=10)
subscriber_manager_purge_interval
Section titled “subscriber_manager_purge_interval”subscriber_manager_purge_interval: timedelta = timedelta(minutes=1)
subscriber_manager_subscriber_max_age
Section titled “subscriber_manager_subscriber_max_age”subscriber_manager_subscriber_max_age: timedelta = timedelta(minutes=10)
coordinator_subscriber_max_time_since_last_seen
Section titled “coordinator_subscriber_max_time_since_last_seen”coordinator_subscriber_max_time_since_last_seen: timedelta = timedelta(seconds=60)
coordinator_distribution_interval
Section titled “coordinator_distribution_interval”coordinator_distribution_interval: timedelta = timedelta(seconds=20)
coordinator_leadership_max_duration
Section titled “coordinator_leadership_max_duration”coordinator_leadership_max_duration: timedelta = timedelta(minutes=15)
coordinator_leadership_attempt_interval
Section titled “coordinator_leadership_attempt_interval”coordinator_leadership_attempt_interval: timedelta = timedelta(seconds=5)
observer_synchronisation_interval
Section titled “observer_synchronisation_interval”observer_synchronisation_interval: timedelta = timedelta(seconds=20)
ErrorHandler
Section titled “ErrorHandler”class ErrorHandler[T]
Bases: ABC
Base class for handlers deciding how to respond to an exception.
handle
Section titled “handle”def handle(exception: BaseException) -> ErrorHandlerDecision[T]
Decide how to respond to the given exception.
Parameters:
exception(BaseException) — The exception to handle.
Returns:
ErrorHandlerDecision[T]— the decision on how to respond.
ErrorHandlerDecision
Section titled “ErrorHandlerDecision”class ErrorHandlerDecision[T]
Base class for decisions made by an ErrorHandler.
Provides factory methods for each kind of decision.
exit_fatally
Section titled “exit_fatally”@staticmethod
def exit_fatally(*, exit_code: int = 1) -> ExitErrorHandlerDecision
Return a decision to exit the process.
Parameters:
exit_code(int) — The exit code to exit with.
raise_exception
Section titled “raise_exception”@staticmethod
def raise_exception(exception: BaseException) -> RaiseErrorHandlerDecision
Return a decision to raise an exception.
Parameters:
exception(BaseException) — The exception to raise.
continue_execution
Section titled “continue_execution”@staticmethod
def continue_execution[R](*, value: R) -> ContinueErrorHandlerDecision[R]
Return a decision to continue, returning a value as the result.
Parameters:
value(R) — The value to return.
retry_execution
Section titled “retry_execution”@staticmethod
def retry_execution(
*,
wait_before_retry: timedelta | None = None,
) -> RetryErrorHandlerDecision
Return a decision to retry the failed execution.
Parameters:
wait_before_retry(timedelta | None) — The time to wait before retrying. IfNone, retries immediately.
ErrorHandlingService
Section titled “ErrorHandlingService”class ErrorHandlingService[T = Any](
service: Service[T] | CallableServiceCallable[T] | None = None,
*,
callable: CallableServiceCallable[T] | None = None,
error_handler: ErrorHandler[T],
sleep: Callable[[float], Awaitable[None]] = asyncio.sleep,
)
Bases: Service[T]
Service that applies an error handler to a wrapped service.
Parameters:
service(Service[T] | CallableServiceCallable[T] | None) — The service to execute. Passing a bare callable is deprecated; wrap it in aCallableService.callable(CallableServiceCallable[T] | None) — Deprecated; useserviceinstead.error_handler(ErrorHandler[T]) — The error handler to apply to any exception raised.sleep(Callable[[float], Awaitable[None]]) — The function used to wait before retrying.
Raises:
TypeError— If neitherservicenorcallableis provided.
apply_error_handling
Section titled “apply_error_handling”@classmethod
async def apply_error_handling(
run: Callable[[], Awaitable[T]],
error_handler: ErrorHandler[T],
*,
sleep: Callable[[float], Awaitable[None]] = asyncio.sleep,
) -> T
Run a callable, responding to any exception as the handler decides.
Retry decisions run the callable again, after waiting if required;
continue decisions return their value; raise decisions raise their
exception; and exit decisions raise SystemExit.
Parameters:
run(Callable[[], Awaitable[T]]) — The callable to run.error_handler(ErrorHandler[T]) — Decides how to respond to each exception.sleep(Callable[[float], Awaitable[None]]) — The function used to wait before retrying.
Returns:
T— the result of the callable, or the value of a continue decision.
Raises:
SystemExit— If the handler decides to exit.ValueError— If the handler returns an unknown decision.
execute
Section titled “execute”async def execute() -> T
ErrorHandlingServiceMixin
Section titled “ErrorHandlingServiceMixin”class ErrorHandlingServiceMixin[T = Any](error_handler: ErrorHandler[T])
Bases: Service[T], ABC
Mixin applying error handling to a service’s _do_execute method.
Deprecated: use composition with ErrorHandlingService instead.
Parameters:
error_handler(ErrorHandler[T]) — The error handler to apply.
execute
Section titled “execute”async def execute() -> T
CallableService
Section titled “CallableService”class CallableService[T = Any](callable: CallableServiceCallable[T])
Bases: Service[T]
Service that executes an asynchronous callable.
Parameters:
callable(CallableServiceCallable[T]) — The zero-argument callable returning an awaitable result.
from_maybe_callable
Section titled “from_maybe_callable”@overload
@classmethod
def from_maybe_callable[S: Service](service_or_callable: S) -> S
@overload
@classmethod
def from_maybe_callable(
service_or_callable: CallableServiceCallable[T],
) -> Self
Wrap a callable as a service, passing services through unchanged.
Parameters:
service_or_callable(Service[Any] | CallableServiceCallable[T]) — A service, or a callable to wrap.
Returns:
- the service if one was given, otherwise a
CallableServicewrapping the callable.
execute
Section titled “execute”async def execute() -> T
EventBroker
Section titled “EventBroker”class EventBroker[E: Event]
Bases: Service[NoneType], Process, ABC
A long-running service that allocates event sources to subscribers.
Subscribers are registered with the broker, which then hands each of
them the event sources they requested, via EventSubscriber.accept,
while it executes. Brokers expose a ProcessStatus so their health can
be monitored.
Use make_event_broker to construct a broker of the required type.
register
Section titled “register”async def register(subscriber: EventSubscriber[E]) -> None
Register a subscriber to receive event sources from the broker.
Subscribers must be registered before the broker is executed, as the distributed broker never allocates sources to later ones.
Parameters:
subscriber(EventSubscriber[E]) — The subscriber to register.
EventBrokerType
Section titled “EventBrokerType”class EventBrokerType
Bases: ABC
Marker types selecting the broker strategy for make_event_broker.
Attributes:
Singleton(type[_SingletonEventBrokerType]) — Selects a broker that passes each registered subscriber on the local node the event sources it requested.Distributed(type[_DistributedEventBrokerType]) — Selects a broker that coordinates across nodes, sharing the requested event sources between the subscribers in each subscriber group.
Singleton
Section titled “Singleton”Singleton: type[_SingletonEventBrokerType]
Distributed
Section titled “Distributed”Distributed: type[_DistributedEventBrokerType]
EventConsumer
Section titled “EventConsumer”class EventConsumer
Bases: ABC
Base class for consumers that consume events from some source.
consume_all
Section titled “consume_all”async def consume_all() -> None
Consume all events currently available to this consumer.
DeferredFuture
Section titled “DeferredFuture”class DeferredFuture[T](name: str)
A handle to the future result of a service not yet scheduled.
Supports a subset of the asyncio.Future interface, delegating to the
underlying future once the service has been scheduled. It can be
awaited.
Parameters:
name(str) — The name of the service, used in error messages.
result
Section titled “result”def result() -> T
Return the result of the service.
Raises:
BaseException— Any exception raised by the service.asyncio.CancelledError— If the service was cancelled.RuntimeError— If the service has not been scheduled yet.asyncio.InvalidStateError— If the service has not finished.
exception
Section titled “exception”def exception() -> BaseException | None
Return the exception raised by the service, if any.
Raises:
RuntimeError— If the service has not been scheduled yet.asyncio.InvalidStateError— If the service has not finished.
def done() -> bool
Return whether the service has been scheduled and finished.
__await__
Section titled “__await__”def __await__()
EventConsumerState
Section titled “EventConsumerState”class EventConsumerState(state: JsonObject)
Bases: JsonValueConvertible
The persisted state of an event consumer.
Attributes:
state(JsonObject) — The state as produced by anEventConsumerStateConverter.
state: JsonObject
deserialise
Section titled “deserialise”@classmethod
def deserialise(
value: JsonValue,
fallback: Callable[[Any, JsonValue], Any] = default_deserialisation_fallback,
) -> Self
Deserialise consumer state from a JSON value.
For backwards compatibility, a top-level last_sequence_number is
merged into the state and a missing state is treated as empty.
Parameters:
value(JsonValue) — The JSON value to deserialise.fallback(Callable[[Any, JsonValue], Any]) — Called with the class and value if the value is not a valid consumer state.
Returns:
Self— the deserialised consumer state, or the result of the fallback.
serialise
Section titled “serialise”def serialise(
fallback: Callable[[object], JsonValue] = default_serialisation_fallback,
) -> JsonValue
EventConsumerStateStore
Section titled “EventConsumerStateStore”class EventConsumerStateStore[E: Event](
category: EventCategory,
converter: EventConsumerStateConverter[E],
persistence_interval: EventCount | None = EventCount(100),
)
Records and persists event consumer state in an event category.
State is held in memory per partition and persisted as state-changed
events in the stream named after the partition.
Parameters:
category(EventCategory) — The category in which to store consumer state.converter(EventConsumerStateConverter[E]) — Converts between events and consumer state.persistence_interval(EventCount | None) — The number of recorded events after whichsave_if_neededpersists state. IfNone,save_if_needednever saves.
record_processed
Section titled “record_processed”def record_processed(
event: E,
*,
extra_state: JsonObject | None = None,
partition: str = 'default',
) -> EventConsumerState
Record that an event has been processed.
The state is held in memory until saved.
Parameters:
event(E) — The processed event.extra_state(JsonObject | None) — Additional state to merge into the converted state.partition(str) — The partition to record the state against.
Returns:
EventConsumerState— the new consumer state.
def reset(*, extra_state: JsonObject | None = None, partition: str = 'default')
Reset a partition’s state to the converter’s initial state.
The reset state is held in memory only and is never saved.
Parameters:
extra_state(JsonObject | None) — Additional state to merge into the initial state.partition(str) — The partition to reset.
save_if_needed
Section titled “save_if_needed”async def save_if_needed(*, partition: str = 'default') -> None
Save a partition’s state if the persistence interval is reached.
Parameters:
partition(str) — The partition to save.
async def save(partition: str | None = None) -> None
Persist unsaved state.
Partitions with no state or no changes since the last save are skipped.
Parameters:
partition(str | None) — The partition to save. IfNone, all partitions with recorded state are saved.
Raises:
UnmetWriteConditionError— If the partition’s stream has been written to by another writer since it was last read.
async def load(*, partition: str = 'default') -> EventConsumerState | None
Load a partition’s state.
State held in memory is returned if present; otherwise the latest persisted state is read from the partition’s stream.
Parameters:
partition(str) — The partition to load.
Returns:
EventConsumerState | None— the consumer state, orNoneif there is none.
load_to_query_constraint
Section titled “load_to_query_constraint”async def load_to_query_constraint(
*,
partition: str = 'default',
) -> constraints.QueryConstraint | None
Load a partition’s state as a constraint for resuming consumption.
Parameters:
partition(str) — The partition to load.
Returns:
constraints.QueryConstraint | None— a constraint selecting events after those already processed, orNoneif there is no state or all events should be consumed.
EventCount
Section titled “EventCount”class EventCount
Bases: int
A count of events.
increment
Section titled “increment”def increment() -> Self
Return a new count one greater than this one.
EventProcessor
Section titled “EventProcessor”class EventProcessor[E: Event]
Bases: ABC
Base class for processors that handle events one at a time.
When used with an EventSourceConsumer, each event is acknowledged
automatically once process_event returns successfully.
process_event
Section titled “process_event”async def process_event(event: E) -> None
Process a single event.
Parameters:
event(E) — The event to process.
EventSourceConsumer
Section titled “EventSourceConsumer”class EventSourceConsumer[I: EventSourceIdentifier, E: Event](
*,
source: EventSource[I, E],
processor: SupportedProcessors[E],
state_store: EventConsumerStateStore[E],
logger: FilteringBoundLogger = default_logger,
save_state_after_consumption: bool = True,
)
Bases: EventConsumer
Consumes events from a single event source, tracking progress.
On each call to consume_all, the consumer loads its last recorded
state, iterates the source from that point onwards and passes events to
the processor, recording progress in the state store.
How events are acknowledged depends on the processor type:
EventProcessor: each event is acknowledged afterprocess_eventreturns, with state saved whenever the persistence interval is reached. Ifsave_state_after_consumptionisTrue, state is also saved once all events have been consumed.AutoCommitEventIteratorProcessor: each event is acknowledged when the processor requests the next event.ManagedEventIteratorProcessor: the processor acknowledges events and commits state itself via the provided manager.
Parameters:
source(EventSource[I, E]) — The event source to consume from.processor(SupportedProcessors[E]) — The processor to pass events to.state_store(EventConsumerStateStore[E]) — The store used to load and save consumer state.logger(FilteringBoundLogger) — The logger to use.save_state_after_consumption(bool) — Whether to force a save of consumer state after all events have been consumed. Only applies toEventProcessorprocessors.
consume_all
Section titled “consume_all”async def consume_all() -> None
Consume all events in the source after the last recorded position.
Raises:
TypeError— If the processor is not of a supported type.
EventBrokerStorageType
Section titled “EventBrokerStorageType”class EventBrokerStorageType
Bases: ABC
Marker types selecting the broker storage for make_event_broker.
Attributes:
InMemory(type[_InMemoryEventBrokerStorageType]) — Selects in-memory storage, suitable for tests and single process deployments.Postgres(type[_PostgresEventBrokerStorageType]) — Selects PostgreSQL storage, required by the distributed strategy to coordinate between nodes.
InMemory
Section titled “InMemory”InMemory: type[_InMemoryEventBrokerStorageType]
Postgres
Section titled “Postgres”Postgres: type[_PostgresEventBrokerStorageType]
InMemoryEventBrokerStorageTypeType
Section titled “InMemoryEventBrokerStorageTypeType”InMemoryEventBrokerStorageTypeType = type[_InMemoryEventBrokerStorageType]
PostgresEventBrokerStorageTypeType
Section titled “PostgresEventBrokerStorageTypeType”PostgresEventBrokerStorageTypeType = type[_PostgresEventBrokerStorageType]
EventSubscriber
Section titled “EventSubscriber”class EventSubscriber[E: Event]
Bases: ABC
A consumer of event sources allocated by an event broker.
Each subscriber declares the event sources it would like to consume via
subscription_requests. The broker then calls accept with each event
source allocated to the subscriber and withdraw with each event source
that is no longer allocated to it.
Subscribers sharing a group are treated as instances of the same logical consumer, so that a distributed broker can spread the requested event sources across them.
property group: str
The group to which the subscriber belongs.
property id: str
The ID of the subscriber, unique within its group.
property key: EventSubscriberKey
The key identifying the subscriber, from its group and ID.
subscription_requests
Section titled “subscription_requests”property subscription_requests: Sequence[EventSourceIdentifier]
The identifiers of the event sources the subscriber requests.
health
Section titled “health”def health() -> EventSubscriberHealth
Return the current health of the subscriber.
A distributed broker only sends heartbeats for healthy subscribers, so an unhealthy subscriber eventually stops receiving allocations.
Returns:
EventSubscriberHealth— the health of the subscriber.
accept
Section titled “accept”async def accept(source: EventSource[EventSourceIdentifier, E]) -> None
Accept an event source allocated to the subscriber.
Implementations should tolerate being passed a source they have already accepted, as some brokers reallocate sources periodically.
Parameters:
source(EventSource[EventSourceIdentifier, E]) — The event source allocated to the subscriber.
withdraw
Section titled “withdraw”async def withdraw(source: EventSource[EventSourceIdentifier, E]) -> None
Withdraw an event source no longer allocated to the subscriber.
Parameters:
source(EventSource[EventSourceIdentifier, E]) — The event source being revoked from the subscriber.
EventSubscriberHealth
Section titled “EventSubscriberHealth”class EventSubscriberHealth
Bases: StrEnum
The health of an event subscriber, as reported to the broker.
HEALTHY
Section titled “HEALTHY”HEALTHY = 'healthy'
UNHEALTHY
Section titled “UNHEALTHY”UNHEALTHY = 'unhealthy'
EventSubscriptionConsumer
Section titled “EventSubscriptionConsumer”class EventSubscriptionConsumer[E: Event](
group: str,
id: str,
subscription_requests: Sequence[EventSourceIdentifier],
delegate_factory: Callable[[EventSource[EventSourceIdentifier, Any]], EventConsumer],
logger: FilteringBoundLogger = default_logger,
)
Bases: EventConsumer, EventSubscriber[E]
An event subscriber that consumes from the sources it is allocated.
An event broker allocates sources to the subscriber via accept and
removes them via withdraw. Each accepted source is consumed by a
delegate consumer created by the delegate factory.
Parameters:
group(str) — The group the subscriber belongs to.id(str) — The unique identifier of the subscriber.subscription_requests(Sequence[EventSourceIdentifier]) — The identifiers of the event sources the subscriber requests.delegate_factory(Callable[[EventSource[EventSourceIdentifier, Any]], EventConsumer]) — Creates the consumer for an accepted source.logger(FilteringBoundLogger) — The logger to use.
property group: str
property id: str
health
Section titled “health”def health() -> EventSubscriberHealth
Return the health of the subscriber, which is always healthy.
subscription_requests
Section titled “subscription_requests”property subscription_requests: Sequence[EventSourceIdentifier]
accept
Section titled “accept”async def accept(source: EventSource[EventSourceIdentifier, E]) -> None
Accept a source, creating a delegate consumer for it.
If the source has already been accepted, the existing delegate consumer is retained.
Parameters:
source(EventSource[EventSourceIdentifier, E]) — The event source to accept.
withdraw
Section titled “withdraw”async def withdraw(source: EventSource[EventSourceIdentifier, E]) -> None
Withdraw a source, discarding its delegate consumer.
Withdrawing a source that has not been accepted logs a warning.
Parameters:
source(EventSource[EventSourceIdentifier, E]) — The event source to withdraw.
consume_all
Section titled “consume_all”async def consume_all() -> None
Consume all available events from each accepted source in turn.
ExecutionMode
Section titled “ExecutionMode”class ExecutionMode
Bases: Enum
Whether a ServiceManager waits for a service when starting.
Attributes:
FOREGROUND—ServiceManager.startwaits for the service to finish.BACKGROUND— The service runs withoutServiceManager.startwaiting for it.
FOREGROUND
Section titled “FOREGROUND”FOREGROUND = auto()
BACKGROUND
Section titled “BACKGROUND”BACKGROUND = auto()
ExitErrorHandler
Section titled “ExitErrorHandler”class ExitErrorHandler(
exit_code_factory: Callable[[BaseException], int] = default_exit_code_factory,
)
Bases: ErrorHandler[Any]
Error handler that decides to exit the process.
Parameters:
exit_code_factory(Callable[[BaseException], int]) — Returns the exit code for an exception. Defaults to always returning 1.
exit_code_factory
Section titled “exit_code_factory”exit_code_factory
handle
Section titled “handle”def handle(exception: BaseException) -> ErrorHandlerDecision[Any]
ExitErrorHandlerDecision
Section titled “ExitErrorHandlerDecision”class ExitErrorHandlerDecision(exit_code: int)
Bases: ErrorHandlerDecision[Any]
Decision to exit the process by raising SystemExit.
Attributes:
exit_code(int) — The exit code to exit with.
exit_code
Section titled “exit_code”exit_code: int
InMemoryLockManager
Section titled “InMemoryLockManager”class InMemoryLockManager
Bases: LockManager
Lock manager using asyncio locks, local to a single event loop.
try_lock
Section titled “try_lock”async def try_lock(lock_name: str) -> AsyncGenerator[Lock, None]
wait_for_lock
Section titled “wait_for_lock”async def wait_for_lock(
lock_name: str,
*,
timeout: timedelta | None = None,
) -> AsyncGenerator[Lock, None]
IsolationMode
Section titled “IsolationMode”class IsolationMode
Bases: Enum
Which thread and event loop a ServiceManager runs a service on.
Attributes:
MAIN_THREAD— The event loop that started the service manager.SHARED_THREAD— A separate thread and event loop shared by all services with this isolation mode.DEDICATED_THREAD— A separate thread and event loop for this service alone.
MAIN_THREAD
Section titled “MAIN_THREAD”MAIN_THREAD = auto()
SHARED_THREAD
Section titled “SHARED_THREAD”SHARED_THREAD = auto()
DEDICATED_THREAD
Section titled “DEDICATED_THREAD”DEDICATED_THREAD = auto()
class Lock(
name: str,
locked: bool,
timed_out: bool = False,
wait_time: timedelta = timedelta(seconds=0),
)
The outcome of an attempt to acquire a named lock.
Attributes:
name(str) — The name of the lock.locked(bool) — Whether the lock was acquired.timed_out(bool) — Whether the attempt timed out waiting for the lock.wait_time(timedelta) — How long was spent waiting for the lock.
name: str
locked
Section titled “locked”locked: bool
timed_out
Section titled “timed_out”timed_out: bool = False
wait_time
Section titled “wait_time”wait_time: timedelta = timedelta(seconds=0)
LockManager
Section titled “LockManager”class LockManager
Bases: ABC
Base class for managers of named mutual exclusion locks.
Both methods are asynchronous context managers yielding a Lock
describing whether the lock was acquired. If acquired, the lock is held
until the context exits.
try_lock
Section titled “try_lock”def try_lock(lock_name: str) -> AsyncGenerator[Lock, None]
Attempt to acquire a lock without waiting.
Parameters:
lock_name(str) — The name of the lock to acquire.
Yields:
AsyncGenerator[Lock, None]— the lock, withlockedset toFalseif it is already held.
wait_for_lock
Section titled “wait_for_lock”def wait_for_lock(
lock_name: str,
*,
timeout: timedelta | None = None,
) -> AsyncGenerator[Lock, None]
Wait to acquire a lock, optionally up to a timeout.
Parameters:
lock_name(str) — The name of the lock to acquire.timeout(timedelta | None) — The maximum time to wait. IfNone, waits indefinitely.
Yields:
AsyncGenerator[Lock, None]— the lock, withtimed_outset toTrueif the timeout elapsed before the lock was acquired.
OverrideRetryStrategyDecision
Section titled “OverrideRetryStrategyDecision”class OverrideRetryStrategyDecision[T](
error_handler_decision: ErrorHandlerDecision[T],
)
Bases: RetryStrategyDecision
Decision to use an error handler decision in place of retrying.
Attributes:
error_handler_decision(ErrorHandlerDecision[T]) — The error handler decision to use.
error_handler_decision
Section titled “error_handler_decision”error_handler_decision: ErrorHandlerDecision[T]
PollingService
Section titled “PollingService”class PollingService(
service: Service[Any] | CallableServiceCallable[Any] | None = None,
*,
callable: CallableServiceCallable[Any] | None = None,
poll_interval: timedelta = timedelta(milliseconds=200),
)
Bases: Service[Never]
Service that executes another service repeatedly, forever.
The poll interval is the delay between one execution finishing and the next starting. Any exception raised by the wrapped service stops polling and propagates.
Parameters:
service(Service[Any] | CallableServiceCallable[Any] | None) — The service to execute on each poll. Passing a bare callable is deprecated; wrap it in aCallableService.callable(CallableServiceCallable[Any] | None) — Deprecated; useserviceinstead.poll_interval(timedelta) — The delay between executions.
Raises:
TypeError— If neitherservicenorcallableis provided.
execute
Section titled “execute”async def execute() -> Never
PostgresLockManager
Section titled “PostgresLockManager”class PostgresLockManager(connection_settings: ConnectionSettings)
Bases: LockManager
Lock manager using PostgreSQL transaction-level advisory locks.
Each lock attempt opens a new connection, and the lock is held for the duration of that connection’s transaction.
Parameters:
connection_settings(ConnectionSettings) — The settings used to connect to PostgreSQL.
connection_settings
Section titled “connection_settings”connection_settings
try_lock
Section titled “try_lock”async def try_lock(lock_name: str) -> AsyncGenerator[Lock, None]
wait_for_lock
Section titled “wait_for_lock”async def wait_for_lock(
lock_name: str,
*,
timeout: timedelta | None = None,
) -> AsyncGenerator[Lock, None]
Process
Section titled “Process”class Process
Bases: ABC
Base class for processes that report a status.
status
Section titled “status”property status: ProcessStatus
The current status of the process.
ProcessStatus
Section titled “ProcessStatus”class ProcessStatus
Bases: StrEnum
The lifecycle status of a process.
INITIALISED
Section titled “INITIALISED”INITIALISED = 'initialised'
STARTING
Section titled “STARTING”STARTING = 'starting'
WAITING
Section titled “WAITING”WAITING = 'waiting'
RUNNING
Section titled “RUNNING”RUNNING = 'running'
STOPPING
Section titled “STOPPING”STOPPING = 'stopping'
STOPPED
Section titled “STOPPED”STOPPED = 'stopped'
ERRORED
Section titled “ERRORED”ERRORED = 'errored'
UNKNOWN
Section titled “UNKNOWN”UNKNOWN = 'unknown'
HasProcessStatus
Section titled “HasProcessStatus”class HasProcessStatus
Bases: Protocol
Protocol for objects that report a process status.
status
Section titled “status”property status: ProcessStatus
ProjectionEventProcessor
Section titled “ProjectionEventProcessor”class ProjectionEventProcessor[State: JsonPersistable = JsonValue, Metadata: JsonPersistable = JsonValue](
projector: Projector[StreamIdentifier, State, Metadata],
projection_store: ProjectionStore,
state_type: type[State] = JsonValueType,
metadata_type: type[Metadata] = JsonValueType,
)
Bases: EventProcessor[StoredEvent]
Event processor that updates projections as events are processed.
For each event, the processor locates the current projection for the event’s stream, applies the event using the projector and saves the updated projection.
Parameters:
projector(Projector[StreamIdentifier, State, Metadata]) — The projector used to apply events to projections.projection_store(ProjectionStore) — The store in which projections are kept.state_type(type[State]) — The type to deserialise projection state into.metadata_type(type[Metadata]) — The type to deserialise projection metadata into.
process_event
Section titled “process_event”async def process_event(event: StoredEvent) -> None
Apply the event to its stream’s projection and save the result.
Parameters:
event(StoredEvent) — The stored event to project.
RaiseErrorHandler
Section titled “RaiseErrorHandler”class RaiseErrorHandler(
exception_factory: Callable[[BaseException], BaseException] = default_exception_factory,
)
Bases: ErrorHandler[Any]
Error handler that decides to raise an exception.
Parameters:
exception_factory(Callable[[BaseException], BaseException]) — Returns the exception to raise for a handled exception. Defaults to returning the handled exception.
exception_factory
Section titled “exception_factory”exception_factory
handle
Section titled “handle”def handle(exception: BaseException) -> ErrorHandlerDecision[Any]
RaiseErrorHandlerDecision
Section titled “RaiseErrorHandlerDecision”class RaiseErrorHandlerDecision(exception: BaseException)
Bases: ErrorHandlerDecision[Any]
Decision to raise an exception.
Attributes:
exception(BaseException) — The exception to raise.
exception
Section titled “exception”exception: BaseException
RetryErrorHandler
Section titled “RetryErrorHandler”class RetryErrorHandler(retry_strategy: RetryStrategy | None = None)
Bases: ErrorHandler[Any]
Error handler that decides to retry the failed execution.
Exceptions that are not Exception subclasses, such as
asyncio.CancelledError, are raised instead.
Parameters:
retry_strategy(RetryStrategy | None) — Decides how to retry for each exception. IfNone, retries immediately.
handle
Section titled “handle”def handle(exception: BaseException) -> ErrorHandlerDecision[Any]
RetryErrorHandlerDecision
Section titled “RetryErrorHandlerDecision”class RetryErrorHandlerDecision(wait_before_retry: timedelta | None = None)
Bases: ErrorHandlerDecision[Any]
Decision to retry the failed execution.
Attributes:
wait_before_retry(timedelta | None) — The time to wait before retrying. IfNone, retries immediately.
wait_before_retry
Section titled “wait_before_retry”wait_before_retry: timedelta | None = None
RetryImmediatelyDecision
Section titled “RetryImmediatelyDecision”class RetryImmediatelyDecision
Bases: RetryStrategyDecision
Decision to retry without waiting.
RetryStrategyDecision
Section titled “RetryStrategyDecision”class RetryStrategyDecision
Base class for decisions made by a RetryStrategy.
Provides factory methods for each kind of decision.
retry_immediately
Section titled “retry_immediately”@staticmethod
def retry_immediately() -> RetryImmediatelyDecision
Return a decision to retry without waiting.
@staticmethod
def wait(duration: timedelta) -> WaitRetryStrategyDecision
Return a decision to wait before retrying.
Parameters:
duration(timedelta) — The time to wait before retrying.
override
Section titled “override”@staticmethod
def override[R](
error_handler_decision: ErrorHandlerDecision[R],
) -> OverrideRetryStrategyDecision[R]
Return a decision to use an error handler decision instead.
Allows a retry strategy to stop retrying, for example by raising or exiting.
Parameters:
error_handler_decision(ErrorHandlerDecision[R]) — The error handler decision to use.
Service
Section titled “Service”class Service[T = Any]
Bases: ABC
Base class for long-running or one-off units of work.
Services are typically registered with and run by a ServiceManager.
execute
Section titled “execute”async def execute() -> T
Run the service.
Returns:
T— the result of the service, if any.
ServiceManager
Section titled “ServiceManager”class ServiceManager
Registers, starts and stops a collection of services.
Services are registered with an execution mode and an isolation mode, and are all scheduled when the manager starts. The manager can be used as an asynchronous context manager, starting on entry and stopping on exit.
services
Section titled “services”property services: Mapping[str, ManagedServiceState[Any]]
The state of each registered service, keyed by name.
service
Section titled “service”def service(name: str) -> ManagedServiceState[Any] | None
Return the state of the named service, or None if not found.
Parameters:
name(str) — The name of the service.
register
Section titled “register”def register[T](
service: Service[T],
*,
name: str | None = None,
execution_mode: ExecutionMode = ExecutionMode.BACKGROUND,
isolation_mode: IsolationMode = IsolationMode.MAIN_THREAD,
) -> Self
Register a service to be run when the manager starts.
Parameters:
service(Service[T]) — The service to register.name(str | None) — The unique name of the service. Defaults to a random identifier.execution_mode(ExecutionMode) — Whetherstartwaits for the service to finish.isolation_mode(IsolationMode) — Which thread and event loop to run the service on.
Returns:
Self— this manager, for chaining.
Raises:
ValueError— If a service with the same name is already registered.
stop_on
Section titled “stop_on”def stop_on(signals: Sequence[int]) -> Self
Stop the manager when any of the given signals is received.
Signal handlers are installed on the event loop when the manager starts.
Parameters:
signals(Sequence[int]) — The signal numbers to stop on.
Returns:
Self— this manager, for chaining.
__aenter__
Section titled “__aenter__”async def __aenter__() -> Self
__aexit__
Section titled “__aexit__”async def __aexit__(
exc_type: type[BaseException] | None = None,
exc_value: BaseException | None = None,
traceback: TracebackType | None = None,
) -> bool
async def start() -> Self
Start all registered services.
Waits until all FOREGROUND services have finished; exceptions they
raise are not propagated but are available via each service’s
future. BACKGROUND services continue running after this returns.
Returns:
Self— this manager.
async def stop() -> Self
Cancel all running services and shut down their threads.
Returns:
Self— this manager.
ManagedServiceState
Section titled “ManagedServiceState”class ManagedServiceState[T]
Bases: ABC
The state of a service registered with a ServiceManager.
service
Section titled “service”property service: Service[T]
property name: str
execution_mode
Section titled “execution_mode”property execution_mode: ExecutionMode
isolation_mode
Section titled “isolation_mode”property isolation_mode: IsolationMode
service_status
Section titled “service_status”property service_status: ProcessStatus
The service’s status, or UNKNOWN if it does not report one.
future
Section titled “future”property future: DeferredFuture[T]
A future for the result of the service once it is scheduled.
StatusTrackingService
Section titled “StatusTrackingService”class StatusTrackingService[T = Any](service: Service[T])
Bases: Service[T]
Service that tracks the process status of a wrapped service.
The status is RUNNING while the wrapped service executes, STOPPED
once it returns or is cancelled, and ERRORED if it raises any other
exception.
Parameters:
service(Service[T]) — The service to execute and track.
status
Section titled “status”property status: ProcessStatus
execute
Section titled “execute”async def execute() -> T
DelegateServiceStatusTrackingMixin
Section titled “DelegateServiceStatusTrackingMixin”class DelegateServiceStatusTrackingMixin
Bases: ABC
Mixin reporting the status of the service held in _service.
The status is UNKNOWN if the service does not report one.
status
Section titled “status”property status: ProcessStatus
SingletonEventBroker
Section titled “SingletonEventBroker”class SingletonEventBroker[E: Event](
node_id: str,
event_subscriber_store: EventSubscriberStore[E],
event_source_factory: EventSourceFactory[E],
error_handler: ErrorHandler[NoneType] = RetryErrorHandler(),
logger: FilteringBoundLogger = default_logger,
distribution_interval: timedelta = timedelta(seconds=30),
)
Bases: EventBroker[E]
An event broker that allocates event sources on a single node.
While running, the broker repeatedly passes every registered subscriber each of the event sources it requested, waiting for the distribution interval between rounds. No coordination takes place between nodes, so each subscriber receives all of its requested event sources, and receives them again on every round. Sources are never withdrawn.
Parameters:
node_id(str) — The ID of the node on which the broker runs.event_subscriber_store(EventSubscriberStore[E]) — The store holding registered subscribers.event_source_factory(EventSourceFactory[E]) — The factory used to construct event sources from the subscribers’ requested identifiers.error_handler(ErrorHandler[NoneType]) — The handler for errors raised during execution. Defaults to aRetryErrorHandler.logger(FilteringBoundLogger) — The logger to use.distribution_interval(timedelta) — The time to wait between distribution rounds.
status
Section titled “status”property status: ProcessStatus
register
Section titled “register”async def register(subscriber: EventSubscriber[E]) -> None
execute
Section titled “execute”async def execute() -> None
Run the broker until cancelled, distributing event sources.
Errors are handled by the configured error handler.
SingletonEventBrokerSettings
Section titled “SingletonEventBrokerSettings”class SingletonEventBrokerSettings(
distribution_interval: timedelta = timedelta(seconds=60),
)
Settings for a singleton event broker.
Attributes:
distribution_interval(timedelta) — The time to wait between rounds of passing event sources to subscribers.
distribution_interval
Section titled “distribution_interval”distribution_interval: timedelta = timedelta(seconds=60)
SingletonEventBrokerTypeType
Section titled “SingletonEventBrokerTypeType”SingletonEventBrokerTypeType = type[_SingletonEventBrokerType]
DistributedEventBrokerTypeType
Section titled “DistributedEventBrokerTypeType”DistributedEventBrokerTypeType = type[_DistributedEventBrokerType]
TypeMappingErrorHandler
Section titled “TypeMappingErrorHandler”class TypeMappingErrorHandler[T](
type_mappings: TypeMappings[T] = MappingProxyType({}),
default_error_handler: ErrorHandler[T] = RaiseErrorHandler(),
)
Bases: ErrorHandler[T]
Error handler that delegates based on the type of the exception.
The most specific mapped type in the exception’s class hierarchy determines the handler used. Its callback is invoked before handling. Unmapped exceptions are passed to the default error handler.
Parameters:
type_mappings(TypeMappings[T]) — Error handling definitions keyed by exception type, typically built witherror_handler_type_mappings.default_error_handler(ErrorHandler[T]) — The handler for unmapped exceptions. Defaults to raising them.
type_mappings
Section titled “type_mappings”type_mappings
default_error_handler
Section titled “default_error_handler”default_error_handler
handle
Section titled “handle”def handle(exception: BaseException) -> ErrorHandlerDecision[T]
WaitRetryStrategyDecision
Section titled “WaitRetryStrategyDecision”class WaitRetryStrategyDecision(duration: timedelta)
Bases: RetryStrategyDecision
Decision to wait before retrying.
Attributes:
duration(timedelta) — The time to wait before retrying.
duration
Section titled “duration”duration: timedelta
determine_multi_process_status
Section titled “determine_multi_process_status”def determine_multi_process_status(*statuses: ProcessStatus) -> ProcessStatus
Combine the statuses of several processes into a single status.
UNKNOWN statuses are ignored. If all remaining statuses are the same,
that status is returned. Otherwise, in order of precedence: any
ERRORED gives ERRORED; any STOPPING or STOPPED gives
STOPPING; any STARTING gives STARTING; a mix of only RUNNING
and WAITING gives RUNNING; and a mix including INITIALISED gives
STARTING.
Parameters:
*statuses(ProcessStatus) — The statuses to combine.
Returns:
ProcessStatus— the combined status, orUNKNOWNif no known statuses are given.
exit_fatally_type_mapping
Section titled “exit_fatally_type_mapping”def exit_fatally_type_mapping(
types: Sequence[type[BaseException]],
exit_code_factory: Callable[[BaseException], int] = default_exit_code_factory,
callback: Callable[[BaseException], None] | None = None,
) -> ExitFatallyTypeMappingDict
Build an exit fatally type mapping for error_handler_type_mappings.
Parameters:
types(Sequence[type[BaseException]]) — The exception types to exit on.exit_code_factory(Callable[[BaseException], int]) — Returns the exit code for an exception. Defaults to always returning 1.callback(Callable[[BaseException], None] | None) — Called with the exception before exiting.
Returns:
ExitFatallyTypeMappingDict— the type mapping.
raise_exception_type_mapping
Section titled “raise_exception_type_mapping”def raise_exception_type_mapping(
types: Sequence[type[BaseException]],
exception_factory: Callable[[BaseException], BaseException],
callback: Callable[[BaseException], None] | None = None,
) -> RaiseExceptionTypeMappingDict
Build a raise exception type mapping.
For use with error_handler_type_mappings.
Parameters:
types(Sequence[type[BaseException]]) — The exception types to raise on.exception_factory(Callable[[BaseException], BaseException]) — Returns the exception to raise for a handled exception.callback(Callable[[BaseException], None] | None) — Called with the exception before raising.
Returns:
RaiseExceptionTypeMappingDict— the type mapping.
continue_execution_type_mapping
Section titled “continue_execution_type_mapping”def continue_execution_type_mapping[T](
types: Sequence[type[BaseException]],
value_factory: Callable[[BaseException], T],
callback: Callable[[BaseException], None] | None = None,
) -> ContinueExecutionTypeMappingDict[T]
Build a continue execution type mapping.
For use with error_handler_type_mappings.
Parameters:
types(Sequence[type[BaseException]]) — The exception types to continue on.value_factory(Callable[[BaseException], T]) — Returns the value to continue with for an exception.callback(Callable[[BaseException], None] | None) — Called with the exception before continuing.
Returns:
ContinueExecutionTypeMappingDict[T]— the type mapping.
retry_execution_type_mapping
Section titled “retry_execution_type_mapping”def retry_execution_type_mapping(
types: Sequence[type[BaseException]],
callback: Callable[[BaseException], None] | None = None,
retry_strategy: RetryStrategy | None = None,
) -> RetryExecutionTypeMappingDict
Build a retry execution type mapping.
For use with error_handler_type_mappings.
Parameters:
types(Sequence[type[BaseException]]) — The exception types to retry on.callback(Callable[[BaseException], None] | None) — Called with the exception before retrying.retry_strategy(RetryStrategy | None) — Decides how to retry for each exception. IfNone, retries immediately.
Returns:
RetryExecutionTypeMappingDict— the type mapping.
error_handler_type_mappings
Section titled “error_handler_type_mappings”def error_handler_type_mappings[T](
exit_fatally: ExitFatallyTypeMappingValue = None,
raise_exception: RaiseExceptionTypeMappingValue = None,
continue_execution: ContinueExecutionTypeMappingValue[T] = None,
retry_execution: RetryExecutionTypeMappingValue = None,
) -> TypeMappings[T]
Build type mappings for a TypeMappingErrorHandler.
Each argument is either a sequence of exception types, using the
default behaviour for that kind of handling, or a mapping produced by
the corresponding *_type_mapping function, except
continue_execution, which must be a mapping. If an exception type
appears under more than one argument, retry_execution takes
precedence, then continue_execution, raise_exception and finally
exit_fatally.
Parameters:
exit_fatally(ExitFatallyTypeMappingValue) — Exception types that should exit the process.raise_exception(RaiseExceptionTypeMappingValue) — Exception types that should be raised.continue_execution(ContinueExecutionTypeMappingValue[T]) — Exception types that should continue with a value, fromcontinue_execution_type_mapping.retry_execution(RetryExecutionTypeMappingValue) — Exception types that should be retried.
Returns:
TypeMappings[T]— the mapping from exception type to error handling definition.
make_event_broker
Section titled “make_event_broker”@overload
def make_event_broker(
node_id: str,
broker_type: DistributedEventBrokerTypeType,
storage_type: InMemoryEventBrokerStorageTypeType,
**kwargs: Unpack[InMemoryDistributedBrokerParams],
) -> EventBroker[StoredEvent]
@overload
def make_event_broker(
node_id: str,
broker_type: DistributedEventBrokerTypeType,
storage_type: PostgresEventBrokerStorageTypeType,
**kwargs: Unpack[PostgresDistributedBrokerParams],
) -> EventBroker[StoredEvent]
@overload
def make_event_broker(
node_id: str,
broker_type: SingletonEventBrokerTypeType,
storage_type: InMemoryEventBrokerStorageTypeType,
**kwargs: Unpack[InMemorySingletonBrokerParams],
) -> EventBroker[StoredEvent]
@overload
def make_event_broker(
node_id: str,
broker_type: SingletonEventBrokerTypeType,
storage_type: PostgresEventBrokerStorageTypeType,
**kwargs: Unpack[PostgresSingletonBrokerParams],
) -> EventBroker[StoredEvent]
Construct an event broker of the given type and storage.
The keyword arguments required depend on the combination of broker and storage type:
- in-memory storage requires
settingsandadapter; - Postgres storage requires
settings,connection_settingsandconnection_pool, and optionally acceptsadapter, defaulting to aPostgresEventStorageAdapterusingconnection_pool.
All combinations optionally accept an error_handler, defaulting to a
RetryErrorHandler that retries immediately and indefinitely.
Parameters:
node_id(str) — The ID of the node on which the broker runs.broker_type(SingletonEventBrokerTypeType | DistributedEventBrokerTypeType) — The broker strategy, one ofEventBrokerType.SingletonorEventBrokerType.Distributed.storage_type(InMemoryEventBrokerStorageTypeType | PostgresEventBrokerStorageTypeType) — The storage for broker state, one ofEventBrokerStorageType.InMemoryorEventBrokerStorageType.Postgres.**kwargs(Unpack[CombinedBrokerParams]) — The settings and dependencies for the chosen combination, wheresettingsmust be aSingletonEventBrokerSettingsorDistributedEventBrokerSettingsto matchbroker_type.
Returns:
EventBroker[StoredEvent]— the constructed, not yet running, event broker.
Raises:
ValueError— If the broker or storage type is not recognised.
make_event_store_subscriber
Section titled “make_event_store_subscriber”def make_event_store_subscriber[E: StoredEvent](
*,
subscriber_group: str,
subscriber_id: str | None = None,
subscription_request: EventSourceIdentifier,
subscriber_state_category: EventCategory,
subscriber_state_persistence_interval: EventCount = EventCount(100),
event_processor: EventProcessor[E],
logger: FilteringBoundLogger = default_logger,
save_state_after_consumption: bool = True,
) -> EventSubscriptionConsumer[E]
Create a subscriber that consumes stored events from the event store.
A convenience wrapper around make_subscriber that tracks progress by
the sequence number of the last processed event.
Parameters:
subscriber_group(str) — The group the subscriber belongs to. Subscribers in the same group share the work of consuming the requested sources.subscriber_id(str | None) — The unique identifier of the subscriber. Defaults to a random UUID.subscription_request(EventSourceIdentifier) — The identifier of the event source to subscribe to.subscriber_state_category(EventCategory) — The category in which to store subscriber state.subscriber_state_persistence_interval(EventCount) — The number of processed events after which subscriber state is saved.event_processor(EventProcessor[E]) — The processor to pass events to.logger(FilteringBoundLogger) — The logger to use.save_state_after_consumption(bool) — Whether to save subscriber state after all available events have been consumed.
Returns:
EventSubscriptionConsumer[E]— the subscription consumer.
make_in_memory_event_broker
Section titled “make_in_memory_event_broker”def make_in_memory_event_broker(
node_id: str,
settings: DistributedEventBrokerSettings,
adapter: EventStorageAdapter,
) -> EventBroker[StoredEvent]
Construct an in-memory distributed event broker.
Deprecated: use make_event_broker with EventBrokerType.Distributed
and EventBrokerStorageType.InMemory instead.
Parameters:
node_id(str) — The ID of the node on which the broker runs.settings(DistributedEventBrokerSettings) — The settings for the distributed broker.adapter(EventStorageAdapter) — The storage adapter from which event sources are read.
Returns:
EventBroker[StoredEvent]— the constructed event broker.
make_postgres_event_broker
Section titled “make_postgres_event_broker”def make_postgres_event_broker(
node_id: str,
connection_settings: ConnectionSettings,
connection_pool: AsyncConnectionPool[AsyncConnection],
settings: DistributedEventBrokerSettings,
) -> EventBroker[StoredEvent]
Construct a Postgres-backed distributed event broker.
Deprecated: use make_event_broker with EventBrokerType.Distributed
and EventBrokerStorageType.Postgres instead.
Parameters:
node_id(str) — The ID of the node on which the broker runs.connection_settings(ConnectionSettings) — The settings used to connect for locking.connection_pool(AsyncConnectionPool[AsyncConnection]) — The pool used for broker state and event storage.settings(DistributedEventBrokerSettings) — The settings for the distributed broker.
Returns:
EventBroker[StoredEvent]— the constructed event broker.
make_subscriber
Section titled “make_subscriber”def make_subscriber[E: Event](
*,
subscriber_group: str,
subscriber_id: str | None = None,
subscription_request: EventSourceIdentifier,
subscriber_state_category: EventCategory,
subscriber_state_persistence_interval: EventCount = EventCount(100),
subscriber_state_converter: EventConsumerStateConverter[E],
event_processor: EventProcessor[E],
logger: FilteringBoundLogger = default_logger,
save_state_after_consumption: bool = True,
) -> EventSubscriptionConsumer[E]
Create a subscriber that consumes events from the sources it is given.
The returned subscriber creates an EventSourceConsumer for each source
it accepts, all sharing a single EventConsumerStateStore.
Parameters:
subscriber_group(str) — The group the subscriber belongs to. Subscribers in the same group share the work of consuming the requested sources.subscriber_id(str | None) — The unique identifier of the subscriber. Defaults to a random UUID.subscription_request(EventSourceIdentifier) — The identifier of the event source to subscribe to.subscriber_state_category(EventCategory) — The category in which to store subscriber state.subscriber_state_persistence_interval(EventCount) — The number of processed events after which subscriber state is saved.subscriber_state_converter(EventConsumerStateConverter[E]) — The converter between events and subscriber state.event_processor(EventProcessor[E]) — The processor to pass events to.logger(FilteringBoundLogger) — The logger to use.save_state_after_consumption(bool) — Whether to save subscriber state after all available events have been consumed.
Returns:
EventSubscriptionConsumer[E]— the subscription consumer.
RetryStrategy
Section titled “RetryStrategy”class RetryStrategy[T]
Bases: ABC
Base class for strategies deciding how to retry after an exception.
Used by RetryErrorHandler.
calculate
Section titled “calculate”def calculate(exception: Exception) -> RetryStrategyDecision
Decide how to retry after the given exception.
Parameters:
exception(Exception) — The exception that caused the failure.
Returns:
RetryStrategyDecision— the retry decision.
ConstantRetryStrategy
Section titled “ConstantRetryStrategy”class ConstantRetryStrategy[T](time: timedelta)
Bases: RetryStrategy[T]
Retry strategy that always waits the same time before retrying.
Attributes:
time(timedelta) — The time to wait before each retry.
time: timedelta
calculate
Section titled “calculate”def calculate(exception: Exception) -> RetryStrategyDecision
IncludeExceptionsRetryStrategy
Section titled “IncludeExceptionsRetryStrategy”class IncludeExceptionsRetryStrategy[T](
delegate: RetryStrategy,
include_list: Sequence[type[Exception]],
)
Bases: RetryStrategy[T]
Applies a delegate strategy only to the listed exception types.
Exceptions not matching any of the listed types are retried immediately, rather than not retried.
Parameters:
delegate(RetryStrategy) — The strategy to apply to matching exceptions.include_list(Sequence[type[Exception]]) — The exception types to apply the delegate to, including their subclasses.
calculate
Section titled “calculate”def calculate(exception: Exception) -> RetryStrategyDecision
ExcludeExceptionsRetryStrategy
Section titled “ExcludeExceptionsRetryStrategy”class ExcludeExceptionsRetryStrategy[T](
delegate: RetryStrategy,
exclude_list: Sequence[type[Exception]],
)
Bases: RetryStrategy[T]
Applies a delegate strategy to all but the listed exception types.
Exceptions matching any of the listed types are retried immediately, rather than not retried.
Parameters:
delegate(RetryStrategy) — The strategy to apply to non-matching exceptions.exclude_list(Sequence[type[Exception]]) — The exception types not to apply the delegate to, including their subclasses.
calculate
Section titled “calculate”def calculate(exception: Exception) -> RetryStrategyDecision
logicblocks.event.processing.broker
Section titled “logicblocks.event.processing.broker”make_in_memory_distributed_event_broker
Section titled “make_in_memory_distributed_event_broker”def make_in_memory_distributed_event_broker(
node_id: str,
settings: DistributedEventBrokerSettings,
adapter: EventStorageAdapter,
error_handler: ErrorHandler[NoneType] = RetryErrorHandler(),
) -> EventBroker[StoredEvent]
Construct a distributed event broker with in-memory state.
Parameters:
node_id(str) — The ID of the node on which the broker runs.settings(DistributedEventBrokerSettings) — The settings for the broker.adapter(EventStorageAdapter) — The storage adapter from which event sources are read.error_handler(ErrorHandler[NoneType]) — The handler for errors raised during execution.
Returns:
EventBroker[StoredEvent]— the constructed event broker.
make_postgres_distributed_event_broker
Section titled “make_postgres_distributed_event_broker”def make_postgres_distributed_event_broker(
node_id: str,
connection_settings: ConnectionSettings,
connection_pool: AsyncConnectionPool[AsyncConnection],
settings: DistributedEventBrokerSettings,
adapter: EventStorageAdapter | None = None,
error_handler: ErrorHandler[NoneType] = RetryErrorHandler(),
) -> EventBroker[StoredEvent]
Construct a distributed event broker with Postgres-backed state.
Parameters:
node_id(str) — The ID of the node on which the broker runs.connection_settings(ConnectionSettings) — The settings used to connect for leadership locking.connection_pool(AsyncConnectionPool[AsyncConnection]) — The pool used for subscriber and subscription state, and for the default adapter.settings(DistributedEventBrokerSettings) — The settings for the broker.adapter(EventStorageAdapter | None) — The storage adapter from which event sources are read. Defaults to aPostgresEventStorageAdapteronconnection_pool.error_handler(ErrorHandler[NoneType]) — The handler for errors raised during execution.
Returns:
EventBroker[StoredEvent]— the constructed event broker.
make_in_memory_singleton_event_broker
Section titled “make_in_memory_singleton_event_broker”def make_in_memory_singleton_event_broker(
node_id: str,
settings: SingletonEventBrokerSettings,
adapter: EventStorageAdapter,
error_handler: ErrorHandler[NoneType] = RetryErrorHandler(),
) -> EventBroker[StoredEvent]
Construct a singleton event broker reading from the given adapter.
Parameters:
node_id(str) — The ID of the node on which the broker runs.settings(SingletonEventBrokerSettings) — The settings for the broker.adapter(EventStorageAdapter) — The storage adapter from which event sources are read.error_handler(ErrorHandler[NoneType]) — The handler for errors raised during execution.
Returns:
EventBroker[StoredEvent]— the constructed event broker.
make_postgres_singleton_event_broker
Section titled “make_postgres_singleton_event_broker”def make_postgres_singleton_event_broker(
node_id: str,
connection_settings: ConnectionSettings,
connection_pool: AsyncConnectionPool[AsyncConnection],
settings: SingletonEventBrokerSettings,
adapter: EventStorageAdapter | None = None,
error_handler: ErrorHandler[NoneType] = RetryErrorHandler(),
) -> EventBroker[StoredEvent]
Construct a singleton event broker backed by Postgres.
Parameters:
node_id(str) — The ID of the node on which the broker runs.connection_settings(ConnectionSettings) — The Postgres connection settings. Currently unused by the singleton broker.connection_pool(AsyncConnectionPool[AsyncConnection]) — The pool used to construct the default adapter.settings(SingletonEventBrokerSettings) — The settings for the broker.adapter(EventStorageAdapter | None) — The storage adapter from which event sources are read. Defaults to aPostgresEventStorageAdapteronconnection_pool.error_handler(ErrorHandler[NoneType]) — The handler for errors raised during execution.
Returns:
EventBroker[StoredEvent]— the constructed event broker.
logicblocks.event.processing.broker.strategies.distributed
Section titled “logicblocks.event.processing.broker.strategies.distributed”COORDINATOR_LOCK_NAME
Section titled “COORDINATOR_LOCK_NAME”COORDINATOR_LOCK_NAME = class_fullname(DefaultEventSubscriptionCoordinator)
DefaultEventSubscriberManager
Section titled “DefaultEventSubscriberManager”class DefaultEventSubscriberManager[E: Event](
node_id: str,
subscriber_store: EventSubscriberStore[E],
subscriber_state_store: EventSubscriberStateStore,
logger: FilteringBoundLogger = default_logger,
heartbeat_interval: timedelta = timedelta(seconds=10),
purge_interval: timedelta = timedelta(minutes=1),
subscriber_max_age: timedelta = timedelta(minutes=10),
)
Bases: EventSubscriberManager[E]
Registers subscribers, sends heartbeats and purges stale subscribers.
Only subscribers present when start is called are registered in shared
state; heartbeats are sent only for healthy subscribers.
Parameters:
node_id(str) — The ID of the node on which the manager runs.subscriber_store(EventSubscriberStore[E]) — The store of this node’s subscribers.subscriber_state_store(EventSubscriberStateStore) — The shared store of subscriber state.logger(FilteringBoundLogger) — The logger to use.heartbeat_interval(timedelta) — The time to wait between heartbeats.purge_interval(timedelta) — The time to wait between purges.subscriber_max_age(timedelta) — How long since last seen before any subscriber, on any node, is purged.
async def add(subscriber: EventSubscriber[E]) -> Self
async def start()
maintain
Section titled “maintain”async def maintain()
Run heartbeats and purges concurrently until cancelled.
async def stop()
register
Section titled “register”async def register()
Add each subscriber to the subscriber state store.
unregister
Section titled “unregister”async def unregister()
Remove each subscriber from the subscriber state store.
heartbeat
Section titled “heartbeat”async def heartbeat()
Periodically record healthy subscribers as seen, until cancelled.
Unhealthy subscribers are logged and not recorded.
async def purge()
Periodically purge stale subscribers, until cancelled.
DefaultEventSubscriptionCoordinator
Section titled “DefaultEventSubscriptionCoordinator”class DefaultEventSubscriptionCoordinator(
node_id: str,
lock_manager: LockManager,
subscriber_state_store: EventSubscriberStateStore,
subscription_state_store: EventSubscriptionStateStore,
logger: FilteringBoundLogger = default_logger,
subscriber_max_time_since_last_seen: timedelta = timedelta(seconds=60),
distribution_interval: timedelta = timedelta(seconds=20),
leadership_max_duration: timedelta = timedelta(minutes=15),
leadership_attempt_interval: timedelta = timedelta(seconds=5),
)
Bases: EventSubscriptionCoordinator
Coordinates allocation as the leader elected via a shared lock.
Nodes compete for the lock named by LOCK_NAME. The holder distributes
event sources at each distribution interval until its leadership
maximum duration elapses, then releases the lock and competes again.
Parameters:
node_id(str) — The ID of the node on which the coordinator runs.lock_manager(LockManager) — The lock manager used for leader election.subscriber_state_store(EventSubscriberStateStore) — The shared store of subscriber state.subscription_state_store(EventSubscriptionStateStore) — The shared store of subscription state.logger(FilteringBoundLogger) — The logger to use.subscriber_max_time_since_last_seen(timedelta) — How long since last seen before a subscriber is no longer allocated event sources.distribution_interval(timedelta) — The time to wait between distributions while leader.leadership_max_duration(timedelta) — The maximum time to hold leadership.leadership_attempt_interval(timedelta) — The time to wait between attempts to acquire leadership.
status
Section titled “status”property status: ProcessStatus
coordinate
Section titled “coordinate”async def coordinate() -> None
distribute
Section titled “distribute”async def distribute() -> None
Recalculate and store subscriptions for all live subscribers.
Subscriptions belonging to subscribers not seen recently are removed. Within each subscriber group, the target event sources are the longest set of subscription requests in the group; subscribers requesting anything else lose their subscription. Event sources not yet allocated to an eligible subscriber are spread round-robin across the eligible subscribers, and sources no longer requested are removed. All changes are applied to the subscription state store in a single call.
DefaultEventSubscriptionObserver
Section titled “DefaultEventSubscriptionObserver”class DefaultEventSubscriptionObserver[E: Event](
node_id: str,
subscriber_store: EventSubscriberStore[E],
subscription_state_store: EventSubscriptionStateStore,
event_source_factory: EventSourceFactory[E],
subscription_difference: EventSubscriptionDifference = EventSubscriptionDifference(),
logger: FilteringBoundLogger = default_logger,
synchronisation_interval: timedelta = timedelta(seconds=20),
)
Bases: EventSubscriptionObserver[E]
Periodically synchronises stored subscriptions to local subscribers.
Parameters:
node_id(str) — The ID of the node on which the observer runs.subscriber_store(EventSubscriberStore[E]) — The store of this node’s subscribers.subscription_state_store(EventSubscriptionStateStore) — The shared store of subscription state.event_source_factory(EventSourceFactory[E]) — The factory used to construct event sources from allocated identifiers.subscription_difference(EventSubscriptionDifference) — Calculates changes between subscription snapshots.logger(FilteringBoundLogger) — The logger to use.synchronisation_interval(timedelta) — The time to wait between synchronisations.
status
Section titled “status”property status: ProcessStatus
observe
Section titled “observe”async def observe()
synchronise
Section titled “synchronise”async def synchronise()
Apply changes in subscriptions since the last synchronisation.
Revoked event sources are withdrawn before newly allocated ones are accepted. Changes for subscribers not on this node are ignored.
EventSubscriberManager
Section titled “EventSubscriberManager”class EventSubscriberManager[E: Event]
Bases: ABC
Manages the registration of this node’s subscribers in shared state.
async def add(subscriber: EventSubscriber[E]) -> Self
Add a subscriber to be managed.
Returns:
Self— this manager, for chaining.
async def start() -> None
Register the managed subscribers in shared state.
maintain
Section titled “maintain”async def maintain() -> None
Keep the subscribers’ shared state current until cancelled.
async def stop() -> None
Unregister the managed subscribers from shared state.
EventSubscriberState
Section titled “EventSubscriberState”class EventSubscriberState(
group: str,
id: str,
node_id: str,
subscription_requests: Sequence[EventSourceIdentifier],
last_seen: datetime,
)
The shared record of a subscriber, as seen by the coordinator.
Attributes:
group(str) — The group the subscriber belongs to.id(str) — The ID of the subscriber within its group.node_id(str) — The ID of the node on which the subscriber runs.subscription_requests(Sequence[EventSourceIdentifier]) — The event sources the subscriber requests.last_seen(datetime) — When the subscriber was last registered or heartbeated.
group: str
id: str
node_id
Section titled “node_id”node_id: str
subscription_requests
Section titled “subscription_requests”subscription_requests: Sequence[EventSourceIdentifier]
last_seen
Section titled “last_seen”last_seen: datetime
property key: EventSubscriberKey
subscription_key
Section titled “subscription_key”property subscription_key: EventSubscriptionKey
EventSubscriberStateStore
Section titled “EventSubscriberStateStore”class EventSubscriberStateStore
Bases: ABC
Shared store of subscriber state used for distributed coordination.
async def add(subscriber: EventSubscriber[Any]) -> None
Record a subscriber as present on this node and seen now.
If the subscriber is already present, it is refreshed instead.
remove
Section titled “remove”async def remove(subscriber: EventSubscriber[Any]) -> None
Remove a subscriber’s state, if present.
async def list(
subscriber_group: str | None = None,
max_time_since_last_seen: timedelta | None = None,
) -> Sequence[EventSubscriberState]
List subscriber state, optionally filtered.
Parameters:
subscriber_group(str | None) — If given, only include subscribers in this group.max_time_since_last_seen(timedelta | None) — If given, only include subscribers seen more recently than this.
Returns:
Sequence[EventSubscriberState]— the matching subscriber states.
heartbeat
Section titled “heartbeat”async def heartbeat(subscriber: EventSubscriber[Any]) -> None
Record an existing subscriber as seen now.
Subscribers not already in the store are ignored.
async def purge(
max_time_since_last_seen: timedelta = timedelta(minutes=5),
) -> None
Remove all subscribers not seen within the given time.
EventSubscriptionChange
Section titled “EventSubscriptionChange”class EventSubscriptionChange(
group: str,
id: str,
event_source: EventSourceIdentifier,
)
The allocation or revocation of one event source for a subscriber.
group: str
id: str
event_source
Section titled “event_source”event_source: EventSourceIdentifier
property key: EventSubscriptionKey
subscriber_key
Section titled “subscriber_key”property subscriber_key: EventSubscriberKey
EventSubscriptionChangeset
Section titled “EventSubscriptionChangeset”class EventSubscriptionChangeset(
allocations: Set[EventSubscriptionChange],
revocations: Set[EventSubscriptionChange],
)
The event sources allocated and revoked between two snapshots.
allocations
Section titled “allocations”allocations: Set[EventSubscriptionChange]
revocations
Section titled “revocations”revocations: Set[EventSubscriptionChange]
EventSubscriptionCoordinator
Section titled “EventSubscriptionCoordinator”class EventSubscriptionCoordinator
Bases: Process, ABC
Allocates requested event sources to subscribers across nodes.
coordinate
Section titled “coordinate”async def coordinate() -> None
Coordinate event source allocation until cancelled.
EventSubscriptionDifference
Section titled “EventSubscriptionDifference”class EventSubscriptionDifference
Calculates per event source changes between subscription snapshots.
@staticmethod
def diff(
existing: Sequence[EventSubscriptionState],
updated: Sequence[EventSubscriptionState],
) -> EventSubscriptionChangeset
Calculate the event sources allocated and revoked.
Parameters:
existing(Sequence[EventSubscriptionState]) — The previous subscriptions.updated(Sequence[EventSubscriptionState]) — The current subscriptions.
Returns:
EventSubscriptionChangeset— the changeset, with an allocation for each event source present only inupdatedand a revocation for each event source present only inexisting, per subscription.
EventSubscriptionKey
Section titled “EventSubscriptionKey”class EventSubscriptionKey(group: str, id: str)
The unique identity of a subscription, matching its subscriber’s.
group: str
id: str
EventSubscriptionObserver
Section titled “EventSubscriptionObserver”class EventSubscriptionObserver[E: Event]
Bases: Process, ABC
Applies stored subscriptions to the subscribers on this node.
observe
Section titled “observe”async def observe() -> None
Synchronise subscriptions to subscribers until cancelled.
EventSubscriptionState
Section titled “EventSubscriptionState”class EventSubscriptionState(
group: str,
id: str,
node_id: str,
event_sources: Sequence[EventSourceIdentifier],
)
The event sources allocated to a subscriber.
Attributes:
group(str) — The group of the subscriber.id(str) — The ID of the subscriber within its group.node_id(str) — The ID of the node recorded against the subscription.event_sources(Sequence[EventSourceIdentifier]) — The event sources allocated to the subscriber.
group: str
id: str
node_id
Section titled “node_id”node_id: str
event_sources
Section titled “event_sources”event_sources: Sequence[EventSourceIdentifier]
property key: EventSubscriptionKey
subscriber_key
Section titled “subscriber_key”property subscriber_key: EventSubscriberKey
EventSubscriptionStateChange
Section titled “EventSubscriptionStateChange”class EventSubscriptionStateChange(
type: EventSubscriptionStateChangeType,
subscription: EventSubscriptionState,
)
A change to apply to the subscription state store.
type: EventSubscriptionStateChangeType
subscription
Section titled “subscription”subscription: EventSubscriptionState
EventSubscriptionStateChangeType
Section titled “EventSubscriptionStateChangeType”class EventSubscriptionStateChangeType
Bases: StrEnum
The kind of change to make to a stored subscription.
ADD = 'add'
REMOVE
Section titled “REMOVE”REMOVE = 'remove'
REPLACE
Section titled “REPLACE”REPLACE = 'replace'
EventSubscriptionStateStore
Section titled “EventSubscriptionStateStore”class EventSubscriptionStateStore
Bases: ABC
Shared store of subscriptions used for distributed coordination.
async def list() -> Sequence[EventSubscriptionState]
Return all subscriptions.
async def get(key: EventSubscriptionKey) -> EventSubscriptionState | None
Return the subscription with the given key, or None if absent.
async def add(subscription: EventSubscriptionState) -> None
Add a new subscription.
Raises:
ValueError— If a subscription with the same key already exists.
remove
Section titled “remove”async def remove(subscription: EventSubscriptionState) -> None
Remove an existing subscription.
Raises:
ValueError— If no subscription with the same key exists.
replace
Section titled “replace”async def replace(subscription: EventSubscriptionState) -> None
Replace the event sources of an existing subscription.
Raises:
ValueError— If no subscription with the same key exists.
async def apply(changes: Sequence[EventSubscriptionStateChange]) -> None
Apply a batch of additions, removals and replacements.
Parameters:
changes(Sequence[EventSubscriptionStateChange]) — The changes to apply, at most one per subscription key.
Raises:
ValueError— If more than one change targets the same key, or if any individual change is invalid.
InMemoryEventSubscriberStateStore
Section titled “InMemoryEventSubscriberStateStore”class InMemoryEventSubscriberStateStore(
node_id: str,
clock: Clock = SystemClock(),
)
Bases: EventSubscriberStateStore
An event subscriber state store holding state in memory.
Parameters:
node_id(str) — The ID of the node recorded against added subscribers.clock(Clock) — The clock used to timestamp subscribers.
node_id
Section titled “node_id”node_id
clock
subscribers
Section titled “subscribers”subscribers: list[EventSubscriberState]
async def add(subscriber: EventSubscriber[Any]) -> None
remove
Section titled “remove”async def remove(subscriber: EventSubscriber[Any]) -> None
async def list(
subscriber_group: str | None = None,
max_time_since_last_seen: timedelta | None = None,
) -> Sequence[EventSubscriberState]
heartbeat
Section titled “heartbeat”async def heartbeat(subscriber: EventSubscriber[Any]) -> None
async def purge(
max_time_since_last_seen: timedelta = timedelta(minutes=5),
) -> None
InMemoryEventSubscriptionStateStore
Section titled “InMemoryEventSubscriptionStateStore”class InMemoryEventSubscriptionStateStore(node_id: str)
Bases: EventSubscriptionStateStore
An event subscription state store holding state in memory.
Parameters:
node_id(str) — The node ID recorded against stored subscriptions, in place of the node ID on the given subscription.
node_id
Section titled “node_id”node_id
async def list() -> Sequence[EventSubscriptionState]
async def get(key: EventSubscriptionKey) -> EventSubscriptionState | None
async def add(subscription: EventSubscriptionState) -> None
remove
Section titled “remove”async def remove(subscription: EventSubscriptionState) -> None
replace
Section titled “replace”async def replace(subscription: EventSubscriptionState) -> None
async def apply(changes: Sequence[EventSubscriptionStateChange]) -> None
PostgresEventSubscriberStateStore
Section titled “PostgresEventSubscriberStateStore”class PostgresEventSubscriberStateStore(
*,
node_id: str,
connection_source: postgres.ConnectionSource,
clock: Clock = SystemClock(),
table_settings: postgres.TableSettings = postgres.TableSettings(table_name='subscribers'),
query_converter: postgres.QueryConverter | None = None,
)
Bases: EventSubscriberStateStore
An event subscriber state store persisting state in Postgres.
Parameters:
node_id(str) — The ID of the node recorded against added subscribers.connection_source(postgres.ConnectionSource) — The connection pool, or connection settings from which to create one.clock(Clock) — The clock used to timestamp subscribers.table_settings(postgres.TableSettings) — The settings of the table holding subscriber state.query_converter(postgres.QueryConverter | None) — The converter used to build list queries. Defaults to one with the default clause and query converters.
connection_pool
Section titled “connection_pool”connection_pool
node_id
Section titled “node_id”node_id
clock
table_settings
Section titled “table_settings”table_settings
query_converter
Section titled “query_converter”query_converter
async def add(subscriber: EventSubscriber[Any]) -> None
remove
Section titled “remove”async def remove(subscriber: EventSubscriber[Any]) -> None
async def list(
subscriber_group: str | None = None,
max_time_since_last_seen: timedelta | None = None,
) -> Sequence[EventSubscriberState]
heartbeat
Section titled “heartbeat”async def heartbeat(subscriber: EventSubscriber[Any]) -> None
async def purge(
max_time_since_last_seen: timedelta = timedelta(minutes=5),
) -> None
PostgresEventSubscriptionStateStore
Section titled “PostgresEventSubscriptionStateStore”class PostgresEventSubscriptionStateStore(
*,
node_id: str,
connection_source: postgres.ConnectionSource,
table_settings: postgres.TableSettings = postgres.TableSettings(table_name='subscriptions'),
query_converter: postgres.QueryConverter | None = None,
)
Bases: EventSubscriptionStateStore
An event subscription state store persisting state in Postgres.
get is not supported and raises NotImplementedError.
Parameters:
node_id(str) — The node ID recorded against stored subscriptions, in place of the node ID on the given subscription.connection_source(postgres.ConnectionSource) — The connection pool, or connection settings from which to create one.table_settings(postgres.TableSettings) — The settings of the table holding subscriptions.query_converter(postgres.QueryConverter | None) — The converter used to build list queries. Defaults to one with the default clause and query converters.
connection_pool
Section titled “connection_pool”connection_pool
node_id
Section titled “node_id”node_id
table_settings
Section titled “table_settings”table_settings
query_converter
Section titled “query_converter”query_converter
async def list() -> Sequence[EventSubscriptionState]
async def get(key: EventSubscriptionKey) -> EventSubscriptionState | None
async def add(subscription: EventSubscriptionState) -> None
remove
Section titled “remove”async def remove(subscription: EventSubscriptionState) -> None
replace
Section titled “replace”async def replace(subscription: EventSubscriptionState) -> None
async def apply(changes: Sequence[EventSubscriptionStateChange]) -> None
Apply a batch of changes using a single connection.
Raises:
ValueError— If more than one change targets the same key, or if any individual change is invalid.
logicblocks.event.processing.broker.subscribers
Section titled “logicblocks.event.processing.broker.subscribers”EventSubscriberStore
Section titled “EventSubscriberStore”class EventSubscriberStore[E: Event]
Bases: ABC
Holds the subscriber instances registered with a broker on a node.
async def add(subscriber: EventSubscriber[E]) -> None
Add a subscriber, replacing any existing one with the same key.
remove
Section titled “remove”async def remove(subscriber: EventSubscriber[E]) -> None
Remove a subscriber, if present.
async def get(key: EventSubscriberKey) -> EventSubscriber[E] | None
Return the subscriber with the given key, or None if absent.
async def list() -> Sequence[EventSubscriber[E]]
Return all subscribers in the store.
InMemoryEventSubscriberStore
Section titled “InMemoryEventSubscriberStore”class InMemoryEventSubscriberStore[E: Event]
Bases: EventSubscriberStore[E]
An event subscriber store holding subscribers in memory.
subscribers
Section titled “subscribers”subscribers: dict[EventSubscriberKey, EventSubscriber[E]]
async def add(subscriber: EventSubscriber[E]) -> None
remove
Section titled “remove”async def remove(subscriber: EventSubscriber[E]) -> None
async def get(key: EventSubscriberKey) -> EventSubscriber[E] | None
async def list() -> Sequence[EventSubscriber[E]]
logicblocks.event.processing.consumers
Section titled “logicblocks.event.processing.consumers”AutoCommitEventIteratorProcessor
Section titled “AutoCommitEventIteratorProcessor”class AutoCommitEventIteratorProcessor[E: Event]
Bases: ABC
Base class for processors that consume an iterator of events.
Each event is acknowledged, and the consumer state saved if needed, when the processor requests the next event from the iterator.
process
Section titled “process”async def process(events: EventIterator[E]) -> None
Process events from the provided iterator.
Parameters:
events(EventIterator[E]) — An asynchronous iterator over the events to process.
EventIterator
Section titled “EventIterator”type EventIterator[E: Event] = AsyncIterator[E]
EventProcessorManager
Section titled “EventProcessorManager”class EventProcessorManager[E: Event]
Bases: ABC
Allows a processor to control acknowledgement and state persistence.
Passed to a ManagedEventIteratorProcessor so that it can decide when
events count as processed and when consumer state is saved.
acknowledge
Section titled “acknowledge”def acknowledge(events: E | Sequence[E]) -> None
Record one or more events as processed.
Parameters:
events(E | Sequence[E]) — The event, or sequence of events, to acknowledge.
commit
Section titled “commit”async def commit(*, force: bool = False) -> None
Persist the consumer state for acknowledged events.
Parameters:
force(bool) — IfTrue, save the state regardless of the persistence interval. Otherwise, save only if the persistence interval has been reached.
ManagedEventIteratorProcessor
Section titled “ManagedEventIteratorProcessor”class ManagedEventIteratorProcessor[E: Event]
Bases: ABC
Base class for processors that manage acknowledgement themselves.
Events are not acknowledged automatically; the processor must use the provided manager to acknowledge events and commit state.
process
Section titled “process”async def process(
events: EventIterator[E],
manager: EventProcessorManager[E],
) -> None
Process events from the provided iterator.
Parameters:
events(EventIterator[E]) — An asynchronous iterator over the events to process.manager(EventProcessorManager[E]) — The manager used to acknowledge events and commit consumer state.
SupportedProcessors
Section titled “SupportedProcessors”type SupportedProcessors[E: Event] = EventProcessor[E] | AutoCommitEventIteratorProcessor[E] | ManagedEventIteratorProcessor[E]
StoredEventEventConsumerStateConverter
Section titled “StoredEventEventConsumerStateConverter”class StoredEventEventConsumerStateConverter
Bases: EventConsumerStateConverter[StoredEvent]
Tracks consumption of stored events by their sequence number.
State takes the form {"last_sequence_number": <int | None>}.
event_to_state
Section titled “event_to_state”def event_to_state(event: StoredEvent) -> JsonObject
initial_state
Section titled “initial_state”def initial_state() -> JsonObject
state_to_query_constraint
Section titled “state_to_query_constraint”def state_to_query_constraint(
state: JsonObject,
) -> constraints.QueryConstraint | None
logicblocks.event.processing.services
Section titled “logicblocks.event.processing.services”CallableServiceCallable
Section titled “CallableServiceCallable”type CallableServiceCallable[T] = Callable[[], Awaitable[T]]