The whole library on one page
The library is a set of building blocks for event sourcing in Python, built on asyncio. Each block does one job and depends only on the blocks beneath it, so you can start small and add more as you need them.
This page carries on with cart-42, the shopping cart from the
introduction to event sourcing. Each section goes a level deeper
than the one before, so stop whenever you’ve seen enough. Every package has its own colour, and
it’s the same colour in every diagram.
01 · Ten seconds
In ten seconds
Section titled “In ten seconds”- types
NewEventYou describe what happened: a name, a payload and metadata.
- store
EventStoreThe store appends it to a stream, if your write condition still holds.
- types
StoredEventIt comes back as a fact with an id, a position and a sequence number.
- projection
ProjectorA projector folds a stream’s facts into state, one handler per event name.
- types
ProjectionThe result is state you can use, with an id, a name and its source.
- projection
ProjectionStoreThe store keeps it so you can load and search it later.
Everything else in the library is about doing this safely when writers race, in the background as events arrive, across many processes, or quickly in your tests.
02 · One minute
The map
Section titled “The map”The library has nine packages in five layers. Each package depends only on packages in the layers below it, so the higher a package is, the more it does for you. Click a package to see what it’s for, the names you’ll use from it, and how it connects to the others.
depends on used byHover to preview, click to pin.
logicblocks.event.processingDoes work as events arrive, on one node or many.
A subscriber reads an event source and passes each event to your processor, saving a checkpoint as it goes. A broker decides which subscriber reads which source.
Services run all of this in the background, with polling, retries and clean shutdown.
EventProcessorYour code: process_event(event)ProjectionEventProcessorKeeps a projection store up to datemake_event_store_subscriberReads a source, calls the processor, checkpointsmake_event_brokerSingleton or distributed, in memory or PostgresServiceManagerRuns services. Also PollingService and ErrorHandlingService
logicblocks.event.projectionFolds events into state, and keeps that state.
A Projector is a fold. You give it an initial state and one handler per event name: item-added is handled by item_added. project() runs every event in a source through the handlers.
A ProjectionStore saves the result, loads it by id or source, and searches it with the query language.
ProjectorYour subclass: initial state, handlers, id_factoryProjectionStoresave, load, locate and searchInMemoryProjectionStorageAdapterFor tests. PostgresProjectionStorageAdapter for productionMissingHandlerBehaviourWhether events without a handler raise or are ignored
logicblocks.event.storeAppends events and reads them back.
An EventStore gives you the log, a category or a stream. None of these calls touch storage, and none of them need creating first.
publish appends events atomically, optionally guarded by a write condition. A storage adapter does the work: in memory for tests, Postgres for production.
EventStoreThe entry point: .log(), .category(), .stream()EventStreamOne thing’s events. Publish and read. Also EventCategory and EventLogconditionsposition_is, stream_is_empty, combined with & and |retry_on_unmet_condition_errorRe-runs read, decide, publish after a conflictInMemoryEventStorageAdapterFor tests. PostgresEventStorageAdapter for production
logicblocks.event.sourcesOne way to read events, wherever they come from.
An event source is anything you can read events from: a stream, a category, the whole log, or a list held in memory.
They all read the same way, with async for, read(), iterate() and latest(). Constraints such as sequence_number_after let a reader carry on from where it stopped.
EventSourceThe shared reading interfaceconstraintsFilters such as sequence_number_after(n)EventSourceFactoryBuilds a source from an identifier. Used by subscribersInMemoryEventSourceBase class for sources held in memory
logicblocks.event.persistencePlumbing shared by the storage adapters.
Converters translate queries and constraints into each backend’s language. The Postgres module holds connection settings and table settings.
You mostly touch it to connect to Postgres or to write your own adapter.
postgres.ConnectionSettingsHost, port, database and credentialspostgres.TableSettingsWhich table an adapter usesTypeRegistryConverterPicks the converter registered for a query, constraint or condition type
logicblocks.event.typesThe vocabulary every other package speaks.
Frozen dataclasses for the things the library passes around: the events you publish and read back, the identifiers that say where events live, and projections.
JSON protocols let your own payload and state classes be stored and read back.
NewEventAn event you are about to publishStoredEventAn event as recorded, with id, position and sequence numberStreamIdentifierSays where events live. Also CategoryIdentifier and LogIdentifierProjectionState folded from events, with an id, name, source and metadataJsonValueConvertibleImplement it to store your own types
logicblocks.event.queryDescribes searches without tying them to a database.
Queries are plain values: filters, a sort and a page. Each storage adapter translates them into its own language, such as SQL for Postgres or Python functions in memory.
FilterClauseAn Operator applied to a Path, such as state.dob ≥ 1990SortClauseSort by one or more fieldsKeySetPagingClausePaging that stays stable as data changes. Also OffsetPagingClauseLookupA query for one match. Search finds many
logicblocks.event.utilsClocks, so time can be controlled.
The library reads the time through a clock. It defaults to the system clock, and you can swap in a static clock to make timestamps predictable in tests.
ClockThe interface for reading the current timeSystemClockThe real time. The default everywhereStaticClockA fixed time you move on with set()
logicblocks.event.testingBuilders and random data for your tests.
Immutable builders make events and projections, filling every field you don’t set with random data. Combine them with the in-memory adapters and a static clock for fast, predictable tests.
NewEventBuilderBuilds NewEventsStoredEventBuilderBuilds StoredEvents, optionally .from_new_event()MappingProjectionBuilderBuilds Projections. Subclass BaseProjectionBuilder for your owndataRandom names, ids, payloads and timestamps
Three things to notice:
- Most code touches three packages.
store,projectionandtypescover writing events, turning them into state and the values passed between the two.sources,persistenceandquerymostly work behind the scenes. - Storage is always pluggable. The event store and the projection store both hand storage to an adapter: in memory for tests, Postgres for production, or your own.
- Processing builds on everything else. It is the one package that pulls the rest together, which is why it gets its own zoom-in below.
03 · Five minutes
The life of an event
Section titled “The life of an event”Follow one event, a grinder added to cart-42, from the moment you describe it to the moment it
changes an answer. The first four steps are always the same. Then pick a branch: work out the state
on demand when you need it, or keep it up to date in the background as events arrive. The
chips at the top light up the packages each step uses.
- processing
- projection
- store
- sources
- persistence
- types
- query
- utils
- testing
Describe what happened
An event is a frozen dataclass with a past-tense name, a JSON payload and metadata. metadata is required, so pass None when there is none.
observed_at defaults to now. occurred_at defaults to observed_at, so set it when you record something that happened earlier.
NewEvent- name
"item-added"- payload
{"sku": "grinder"}- metadata
{"actor": "customer-7"}- observed_at
2026-11-04 10:15:00+00:00- occurred_at
same as observed_at
defaulted for you
event = NewEvent( name="item-added", payload={"sku": "grinder"}, metadata={"actor": "customer-7"},)Point at a stream
The store hands you the log, a category or a stream. These are just addresses. Nothing is read or written yet, and nothing needs creating first.
The adapter decides where events are kept: in memory here, Postgres in production.
EventLog
carts
profiles
cart.identifier → StreamIdentifier(category="carts", stream="cart-42")
store = EventStore(adapters.InMemoryEventStorageAdapter())cart = store.stream(category="carts", stream="cart-42")Publish, if nothing has changed
You decided to add the grinder based on the cart as it was at position 1. A write condition makes the write depend on that still being true.
The adapter checks it while holding its write lock. If someone else got in first, publish raises UnmetWriteConditionError and writes nothing, so you can re-read and decide again.
position_is(1)1Other conditions: stream_is_empty(), NoCondition() (the default), and combinations with & and |.
latest = await cart.latest() # position 1stored = await cart.publish( events=[event], condition=conditions.position_is(latest.position),)It becomes a stored event
The adapter stores the event and gives it an id, its position in the stream and a sequence_number in the whole log. The timestamps you set are kept.
Positions start at 0 and have no gaps. Sequence numbers only ever increase, but they can have gaps.
StoredEvent- id
"0b6f9c2e-…"- category
"carts"- stream
"cart-42"- position
2- sequence_number
7- name
"item-added"- payload
{"sku": "grinder"}- metadata
{"actor": "customer-7"}- observed_at · occurred_at
as before
assigned by the storefrom the NewEvent
print(stored[0].position, stored[0].sequence_number)# 2 7Read the stream back
Streams, categories and the log are all event sources, so they read the same way: async for, read(), iterate() and latest().
A stream reads in position order. A category or the log reads in sequence number order.
- 0
item-added{"sku": "beans"} - 1
item-added{"sku": "mug"} - 2
item-added{"sku": "grinder"}
async for event in cart: print(event.position, event.name, event.payload)Fold it into state
A projector is a fold. project() starts from initial_state_factory, calls the handler named after each event (item-added → item_added), then calls finalise_state.
- start
{"items": {}} - + beans
{"items": {"beans": 1}} - + mug
{"items": {"beans": 1, "mug": 1}} - + grinder
{"items": {"beans": 1, "mug": 1, "grinder": 1}}
class CartProjector(Projector[StreamIdentifier, dict, dict]): def initial_state_factory(self): return {"items": {}, "status": "open"}
def item_added(self, state, event): sku = event.payload["sku"] state["items"][sku] = state["items"].get(sku, 0) + 1 return state # ...
projection = await CartProjector().project(source=cart)Get a projection
The result is a Projection: the state, plus what is needed to store and find it again. id_factory picks the id. The name comes from the class, so CartProjector gives cart.
Projection- id
"cart-42"- name
"cart"- source
StreamIdentifier("carts", "cart-42")- state
{"items": {…}, "status": "open"}- metadata
{}
worked out by the projector
print(projection.id, projection.name)# cart-42 cartSave it and search it
A ProjectionStore saves projections and finds them again by id, by source, or by searching. Searches are built from the query package’s clauses, which each adapter turns into its own query language.
| name | id | state.status |
|---|---|---|
| cart | cart-39 | open |
| cart | cart-42 | open |
| cart | cart-44 | open |
projections = ProjectionStore(InMemoryProjectionStorageAdapter())await projections.save(projection=projection)
open_carts = await projections.search( filters=[ FilterClause(Operator.EQUAL, Path("name"), "cart"), FilterClause(Operator.EQUAL, Path("state", "status"), "open"), ], sort=SortClause(fields=[SortField(Path("id"), SortOrder.ASC)]), paging=OffsetPagingClause(item_count=10),)A subscriber asks for the category
Rather than projecting on demand, you can keep projections up to date as events arrive. A subscriber asks for an event source, here the whole carts category, and names the processor to pass events to.
The broker hands each source to one subscriber in the group. With a distributed broker, that is one live instance across all your nodes.
carts) →
subscriber · cart-projection
The broker only allocates sources. It never reads events itself.
subscriber = make_event_store_subscriber( subscriber_group="cart-projection", subscription_request=CategoryIdentifier(category="carts"), subscriber_state_category=store.category(category="cart-projection-state"), event_processor=ProjectionEventProcessor( projector=CartProjector(), projection_store=projections ),)await broker.register(subscriber)Poll, from the last checkpoint
A PollingService calls subscriber.consume_all() every 200 ms by default. The subscriber loads its last checkpoint and reads only the events after it, using a sequence_number_after constraint.
- #4
cart-41 · checked-outalready processed - #6
cart-42 · item-addedalready processed - #7
cart-42 · item-added{"sku": "grinder"}
Numbers are sequence numbers across the category.
PollingService(service=CallableService(subscriber.consume_all))
# each poll reads only what's new, roughly:carts.iterate(constraints={constraints.sequence_number_after(6)})Process the event
ProjectionEventProcessor locates the stored projection for cart-42, applies the event with CartProjector and saves the result.
Or write your own EventProcessor and do anything in process_event: send an email, call an API, publish more events.
projection_store.locate(source=cart-42, name="cart")projector.project(state=stored state, source=just this event)projection_store.save(projection=…)
class ReceiptMailer(EventProcessor[StoredEvent]): async def process_event(self, event: StoredEvent) -> None: if event.name == "checked-out": await send_receipt(cart_id=event.stream)Record a checkpoint
The consumer records how far it got. Every 100 events, and at the end of each consume_all that processed events, it publishes the checkpoint as a state-changed event to the subscriber state category.
After a crash it carries on from the last save, so events since then are processed again. Make processors safe to repeat.
- 0
state-changed{"last_sequence_number": 4} - 1
state-changed{"last_sequence_number": 6} - 2
state-changed{"last_sequence_number": 7}
The checkpoint is itself just events in the store.
# stream "default" in category "cart-projection-state"NewEvent( name="state-changed", payload={"state": {"last_sequence_number": 7}}, metadata=None,)The metro map
Section titled “The metro map”Here’s another way to see how the parts fit together. Each everyday journey through the library is a line, and each class you meet along the way is a station. Where two lines share a station, the journeys meet, and that’s where the parts of the library connect.
Pick a line to follow one journey, or a station to see what it does. Big white stations are interchanges: the places where journeys share a class.
NewEventtypesWrite lineThe event you want to record: a name, a payload and metadata.
Read more →EventStreamstoreWrite lineProject lineOne thing’s events. Call publish() to append. It is also an event source you can read and project.
Read more →conditionsstoreWrite lineposition_is(), stream_is_empty() and their combinations make a publish conditional, for optimistic concurrency.
Read more →EventStorageAdapterstoreWrite lineTest lineWhere events are actually kept: InMemoryEventStorageAdapter for tests, PostgresEventStorageAdapter for production.
Read more →StoredEventtypesWrite lineThe recorded fact, with an id, a position in its stream and a sequence number in the log.
Read more →ProjectorprojectionProject lineFolds a source’s events into state, with one handler per event name.
Read more →ProjectiontypesProject lineThe folded state, with an id, a name, its source and metadata.
Read more →ProjectionStoreprojectionProject lineBackground lineSaves projections, then loads them by id, locates them by source or searches them.
Read more →SearchqueryProject lineFilters, a sort and a page, built from query clauses and translated by each adapter.
Read more →ServiceManagerprocessingBackground lineStarts and stops your long-running services, and can stop them on signals such as SIGTERM.
Read more →PollingServiceprocessingBackground lineRuns another service over and over, every 200 ms by default. Usually it calls subscriber.consume_all.
Read more →ErrorHandlingServiceprocessingBackground lineDecides what happens when a service raises: retry, continue, raise or exit.
Read more →EventSubscriberprocessingBackground lineAsks for an event source and passes its events to a processor. Build one with make_event_store_subscriber.
Read more →EventBrokerprocessingBackground lineDecides which subscriber consumes which source. Singleton for one process, distributed for many.
Read more →EventSourceConsumerprocessingBackground lineReads one source from its last checkpoint and passes each event to the processor.
Read more →EventConsumerStateStoreprocessingBackground lineSaves checkpoints as state-changed events, so a restarted process carries on where it left off.
Read more →ProjectionEventProcessorprocessingBackground lineApplies each event to the stored projection for its stream, then saves it.
Read more →StaticClockutilsTest lineA fixed time you control, for predictable timestamps.
Read more →NewEventBuildertestingTest lineBuilds NewEvents and fills every field you don’t set with random data.
Read more →StoredEventBuildertestingTest lineBuilds StoredEvents, ideal for unit-testing projectors and processors.
Read more →MappingProjectionBuildertestingTest lineBuilds Projections with random state. Subclass BaseProjectionBuilder for your own state.
Read more →Three interchanges hold the library together:
EventStreamis where writing meets projecting: you publish to a stream, and you project from it.ProjectionStoreis where on-demand and background projections meet: both save to it.EventStorageAdapteris where tests meet production: swap the in-memory adapter for the Postgres one and nothing else changes.
04 · Zoom in
Zoom in: processing
Section titled “Zoom in: processing”processing has the most moving parts, but they share out three jobs:
- who reads what: the broker;
- reading and remembering: subscribers, consumers and their checkpoints;
- keeping it all running: services.
Here they are, wired together for the cart-projection subscriber from the background branch above.
The broker hands the carts category to the subscriber…
- subscriber managerheartbeats
- coordinatorleader
- observerwatches subscriptions
- subscriber · cart-projectionconsuming carts
carts→ node-1cart-projection-stateshared checkpoint- subscriber managerheartbeats
- coordinatorwaiting
- observerwatches subscriptions
- subscriber · cart-projectionstandby
- subscribers
- subscriptions
- coordinator lock
The nodes never talk to each other. They only read and write this shared state.
05 · Find your way
Find your way
Section titled “Find your way”Pick what you’re trying to do to see the names you need, a minimal snippet and where to read more.
The snippets leave out imports and reuse cart, store and CartProjector from earlier on this
page.
I want to…
EventStoreEventStream.publishNewEventGet a stream from the store and publish to it. Every event in one publish is stored, or none of them are.
store = EventStore(adapters.InMemoryEventStorageAdapter())cart = store.stream(category="carts", stream="cart-42")
await cart.publish( events=[NewEvent(name="item-added", payload={"sku": "mug"}, metadata=None)])conditions.position_isretry_on_unmet_condition_errorUnmetWriteConditionErrorPublish on condition that the stream hasn’t moved since you read it. The decorator re-runs read, decide, publish when it has.
@retry_on_unmet_condition_error(tries=3)async def check_out(cart: EventStream) -> None: latest = await cart.latest() # ...decide, based on what you just read... await cart.publish( events=[NewEvent(name="checked-out", payload={}, metadata=None)], condition=conditions.position_is(latest.position if latest else None), )ProjectorProjectionWrite a projector with one handler per event name, then project the stream.
class CartProjector(Projector[StreamIdentifier, dict, dict]): def initial_state_factory(self): return {"items": {}, "status": "open"}
def initial_metadata_factory(self): return {}
def id_factory(self, state, source): return source.stream
def checked_out(self, state, event): return {**state, "status": "checked-out"}
projection = await CartProjector().project(source=cart)ProjectionStoreFilterClauseSortClauseOffsetPagingClauseSave projections to a projection store, then load them by id, locate them by source, or search them.
projections = ProjectionStore(InMemoryProjectionStorageAdapter())await projections.save(projection=projection)
checked_out = await projections.search( filters=[FilterClause(Operator.EQUAL, Path("state", "status"), "checked-out")], sort=SortClause(fields=[SortField(Path("id"), SortOrder.ASC)]), paging=OffsetPagingClause(item_count=20),)EventProcessormake_event_store_subscribermake_event_brokerServiceManagerPollingServiceWrite a processor, wrap it in a subscriber, register the subscriber with a broker, then run the broker and a poller as services.
class ReceiptMailer(EventProcessor[StoredEvent]): async def process_event(self, event: StoredEvent) -> None: if event.name == "checked-out": await send_receipt(cart_id=event.stream)
subscriber = make_event_store_subscriber( subscriber_group="receipts", subscription_request=CategoryIdentifier(category="carts"), subscriber_state_category=store.category(category="receipts-state"), event_processor=ReceiptMailer(),)broker = make_event_broker( node_id="node-1", broker_type=EventBrokerType.Singleton, storage_type=EventBrokerStorageType.InMemory, settings=SingletonEventBrokerSettings(), adapter=adapter,)await broker.register(subscriber)
services = ( ServiceManager() .register(broker) .register(PollingService(service=CallableService(subscriber.consume_all))))await services.start()ProjectionEventProcessorProjectorProjectionStoreUse the built-in processor that applies each event to the stored projection and saves it. Wire it up like any other processor.
subscriber = make_event_store_subscriber( subscriber_group="cart-projection", subscription_request=CategoryIdentifier(category="carts"), subscriber_state_category=store.category(category="cart-projection-state"), event_processor=ProjectionEventProcessor( projector=CartProjector(), projection_store=projections, ),)PostgresEventStorageAdapterPostgresProjectionStorageAdapterConnectionSettingsApply the repository’s SQL files with your own migration tooling, then swap the in-memory adapters for the Postgres ones. Nothing else changes.
connection_settings = ConnectionSettings( host="localhost", port=5432, dbname="shop", user="admin", password="secret")
store = EventStore( PostgresEventStorageAdapter(connection_source=connection_settings))projections = ProjectionStore( PostgresProjectionStorageAdapter(connection_source=connection_settings))EventBrokerType.DistributedDistributedEventBrokerSettingsEventBrokerStorageType.PostgresUse a distributed broker with Postgres storage. Each source is consumed by one live subscriber in its group, and moves elsewhere if that subscriber goes away.
broker = make_event_broker( node_id="node-1", broker_type=EventBrokerType.Distributed, storage_type=EventBrokerStorageType.Postgres, settings=DistributedEventBrokerSettings(), connection_settings=connection_settings, connection_pool=connection_pool,)ErrorHandlingServiceRetryErrorHandlerConstantRetryStrategyA polling service stops at its first exception. Wrap it so failures are retried after a pause.
retry_after_five_seconds = RetryErrorHandler( retry_strategy=ConstantRetryStrategy(time=timedelta(seconds=5)))
services = ServiceManager().register( ErrorHandlingService( service=PollingService(service=CallableService(subscriber.consume_all)), error_handler=retry_after_five_seconds, ))JsonValueSerialisableJsonValueDeserialisableGive your class serialise and deserialise methods. No base class is needed: the protocols are checked by shape.
@dataclass(frozen=True)class ItemAdded: sku: str
def serialise(self, fallback): return {"sku": self.sku}
@classmethod def deserialise(cls, value, fallback): return cls(sku=value["sku"])
await cart.publish( events=[NewEvent(name="item-added", payload=ItemAdded("mug"), metadata=None)])StoredEventBuilderInMemoryEventStorageAdapterStaticClockBuild the events you need and apply them directly. No store needed. For wider tests, use the in-memory adapters.
def test_checking_out_closes_the_cart(): event = StoredEventBuilder().with_name("checked-out").build()
state = CartProjector().apply( event=event, state={"items": {}, "status": "open"} )
assert state["status"] == "checked-out"Climb the ladder
Section titled “Climb the ladder”You don’t need everything at once. Most projects take up the library in this order, and each level adds to the one before it.
- processing
- projection
- store
- sources
- persistence
- types
- query
- utils
- testing