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
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
Built Distribution
Filter files by name, interpreter, ABI, and platform.
If you're not sure about the file name format, learn more about wheel file names.
Copy a direct link to the current filters
File details
Details for the file logicblocks_event_store-0.1.12a2.tar.gz.
File metadata
- Download URL: logicblocks_event_store-0.1.12a2.tar.gz
- Upload date:
- Size: 74.5 kB
- Tags: Source
- Uploaded using 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}
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 |
61afc890f1af1421017cfa1465ca8a4e7b88ebf738e9e143e5a957546aca2be3
|
|
| MD5 |
47f10945c5889cb11bdeb9ae023394b3
|
|
| BLAKE2b-256 |
2a7e14858c105d2c422315bbeab26f95af7e94ec1b5795fba18def01c7c6b6f6
|
File details
Details for the file logicblocks_event_store-0.1.12a2-py3-none-any.whl.
File metadata
- Download URL: logicblocks_event_store-0.1.12a2-py3-none-any.whl
- Upload date:
- Size: 130.3 kB
- Tags: Python 3
- Uploaded using 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}
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 |
da4080184df020e2f550fe4f04dc1b11330e86c481b255848a9dd568bc7f4dbf
|
|
| MD5 |
a692e1f97508ca0409b3f580d0abf81f
|
|
| BLAKE2b-256 |
701203261739324e0d96d5090ff350a605be1c989d9e94245a4c0fd12ff45ec7
|
