Pre-release
This release is a pre-release and may not be stable for production use.
logicblocks.event.store
Eventing infrastructure for event-sourced architectures.
Table of Contents
Installation
pip install logicblocks-event-store
Usage
Basic Example
import asyncio
from logicblocks.event.store import EventStore, adapters
from logicblocks.event.types import NewEvent, StreamIdentifier
from logicblocks.event.projection import Projector
class ProfileProjector(
Projector[StreamIdentifier, dict[str, str], dict[str, str]]
):
def initial_state_factory(self) -> dict[str, str]:
return {}
def initial_metadata_factory(self) -> dict[str, str]:
return {}
def id_factory(self, state, source: StreamIdentifier) -> str:
return source.stream
def profile_created(self, state, event):
state['name'] = event.payload['name']
state['email'] = event.payload['email']
return state
def date_of_birth_set(self, state, event):
state['dob'] = event.payload['dob']
return state
async def main():
adapter = adapters.InMemoryEventStorageAdapter()
store = EventStore(adapter)
stream = store.stream(category="profiles", stream="joe.bloggs")
# metadata is required; pass metadata=None when the event has no metadata
profile_created_event = NewEvent(name="profile-created",
payload={"name": "Joe Bloggs", "email": "joe.bloggs@example.com"},
metadata=None)
date_of_birth_set_event = NewEvent(name="date-of-birth-set", payload={"dob": "1992-07-10"},
metadata={"actor": "user-123"})
await stream.publish(
events=[
profile_created_event
])
await stream.publish(
events=[
date_of_birth_set_event
]
)
projector = ProfileProjector()
projection = await projector.project(source=stream)
profile = projection.state
asyncio.run(main())
# profile == {
# "name": "Joe Bloggs",
# "email": "joe.bloggs@example.com",
# "dob": "1992-07-10"
# }
Features
- Event modelling:
- Log / category / stream based: events are grouped into logs of categories of streams.
- Arbitrary payloads and metadata: events can have arbitrary payloads and metadata limited only by what the underlying storage backend can support.
- Bi-temporality support: events included timestamps for both the time the event occurred and the time the event was recorded in the log.
- Event storage:
- Immutable and append only: the event store is modelled as an append-only log of immutable events.
- Consistency guarantees: concurrent stream updates can optionally be handled with optimistic concurrency control.
- Write conditions: an extensible write condition system allows pre-conditions to be evaluated before publish.
- Ordering guarantees: event writes are serialised (at log level by default, but customisable) to guarantee consistent ordering at scan time.
asynciosupport: the event store is implemented usingasyncioand can be used in cooperative multitasking applications.
- Storage adapters:
- Storage adapter abstraction: adapters are provided for different storage
backends, currently including:
- an in-memory implementation for testing and experimentation; and
- a PostgreSQL backed implementation for production use.
- Extensible to other backends: the storage adapter abstract base class is designed to be relatively easily implemented to support other storage backends.
- Storage adapter abstraction: adapters are provided for different storage
backends, currently including:
- Projections:
- Reduction: event sequences can be reduced to a single value, a projection, using a projector.
- Metadata: projections have metadata for keeping track of things like update timestamps, versions, etc.
- Storage: a general purpose projection store allows easy management of projections for the majority of use cases, utilising the same adapter architecture as the event store, with a rich and customisable query language providing store search.
- Snapshotting: coming soon.
- Types:
- Type hints: includes type hints for all public classes and functions.
- Value types: includes serialisable value types for identifiers, events and projections.
- Pydantic support: coming soon.
- Testing utilities:
- Builders: includes builders for events to simplify testing.
- Data generators: includes random data generators for events and event attributes.
- Storage adapter tests: includes tests for storage adapters to ensure consistency across implementations.
Documentation
Development
This project uses mise for tool management. To get started:
mise install
mise run
See CONTRIBUTING.md for detailed development instructions.
Contributing
Bug reports and pull requests are welcome on GitHub at https://github.com/logicblocks/event.store.
See CONTRIBUTING.md for guidelines on:
- Reporting bugs and requesting features
- Setting up your development environment
- Running tests and code quality checks
- Submitting pull requests
This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the code of conduct.
License
Copyright © 2025 LogicBlocks Maintainers
Distributed under the terms of the MIT License.
1 maintainer
Release files for logicblocks.event.store 0.1.12a3
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | |
|---|---|---|---|
| logicblocks_event_store-0.1.12a3.tar.gz | 74.5 kB | Details |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Reset |
|---|---|---|---|---|
| logicblocks_event_store-0.1.12a3-py3-none-any.whl | Python 3 | none | any | Details |
Total release size: 204.8 kB
Release files / logicblocks_event_store-0.1.12a3.tar.gz
| Download URL | logicblocks_event_store-0.1.12a3.tar.gz |
|---|---|
| Size | 74.5 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
9e54e9eecd0154f6eb348edfda5b6aed10e10d39ad3fb1bf4d081e20a3446073
|
|
BLAKE2b-256 checksum How to use checksums |
e51de2ef33495ed4a234418b05e5cf979ab4e77a35109175a21dfe6dd38fa86c
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
uv/0.9.14 {"installer":{"name":"uv","version":"0.9.14","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"24.04","id":"noble","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}
|
Release files / logicblocks_event_store-0.1.12a3-py3-none-any.whl
| Download URL | logicblocks_event_store-0.1.12a3-py3-none-any.whl |
|---|---|
| Size | 130.3 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
851d046e06eeefc2ded8aae864c1c9809d9b0490d5081564b03992650829d07e
|
|
BLAKE2b-256 checksum How to use checksums |
d6dc355c625b15ad10a38912d62208d5dc967fb811d326b9f815455e64017557
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
uv/0.9.14 {"installer":{"name":"uv","version":"0.9.14","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"24.04","id":"noble","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}
|
