Skip to content

The whole library on one page

What each part of logicblocks.event.store does, how it works and how the parts fit together. Start with ten seconds, then zoom in as far as you need.

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

  1. typesNewEvent

    You describe what happened: a name, a payload and metadata.

  2. storeEventStore

    The store appends it to a stream, if your write condition still holds.

  3. typesStoredEvent

    It comes back as a fact with an id, a position and a sequence number.

  4. projectionProjector

    A projector folds a stream’s facts into state, one handler per event name.

  5. typesProjection

    The result is state you can use, with an id, a name and its source.

  6. projectionProjectionStore

    The 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 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.

BackgroundReact to events as they arrive
StateTurn events into answers
EventsAppend and read facts
PlumbingReading and storage machinery
FoundationsShared vocabulary
AlongsideFor your tests

depends on used byHover to preview, click to pin.

storelogicblocks.event.store

Appends 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.

Names you’ll use
  • EventStoreThe entry point: .log(), .category(), .stream()
  • EventStreamOne thing’s events. Publish and read. Also EventCategory and EventLog
  • conditionsposition_is, stream_is_empty, combined with & and |
  • retry_on_unmet_condition_errorRe-runs read, decide, publish after a conflict
  • InMemoryEventStorageAdapterFor tests. PostgresEventStorageAdapter for production
Depends on
Used by
Read more

Three things to notice:

  • Most code touches three packages. store, projection and types cover writing events, turning them into state and the values passed between the two. sources, persistence and query mostly 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

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

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.

NewEventEventStreamconditionsEventStorageAdapterStoredEventProjectorProjectionProjectionStoreSearchServiceManagerPollingServiceErrorHandlingServiceEventSubscriberEventBrokerEventSourceConsumerEventConsumerStateStoreProjectionEventProcessorStaticClockNewEventBuilderStoredEventBuilderMappingProjectionBuilder

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.

Three interchanges hold the library together:

  • EventStream is where writing meets projecting: you publish to a stream, and you project from it.
  • ProjectionStore is where on-demand and background projections meet: both save to it.
  • EventStorageAdapter is where tests meet production: swap the in-memory adapter for the Postgres one and nothing else changes.

04 · Zoom in

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.

ErrorHandlingServicerunsaccept(carts)createsconsume_all()events after checkpointprocess_eventsavecheckpointstate-changedServiceManagerstarts and stops it allEventBrokersingletonPollingServiceevery 200 msEventSubscribergroup cart-projectionEventSourceConsumersource: cartsProjectionEventProcessorwith CartProjectorProjectionStorecart-42 updatedEventCategorycartsEventConsumerStateStorelast_sequence_numberEventCategorycart-projection-state

The broker hands the carts category to the subscriber…

05 · 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…

You need
EventStoreEventStream.publishNewEvent

Get 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)]
)
Publishing to a stream →

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.

  1. Start here →
  2. Start here →
  3. Start here →
  4. Start here →
Packages in play
  • processing
  • projection
  • store
  • sources
  • persistence
  • types
  • query
  • utils
  • testing