Skip to main content
Pre-release

This release is a pre-release and may not be stable for production use.

logicblocks.event.store

PyPI - Version Python - Version Documentation CircleCI

Eventing infrastructure for event-sourced architectures.

Table of Contents

Installation

pip install logicblocks-event-store

Usage

Basic Example

import asyncio

from logicblocks.event.projection import Projector
from logicblocks.event.store import EventStore, adapters
from logicblocks.event.types import JsonValue, NewEvent, StreamIdentifier


class ProfileProjector(Projector[StreamIdentifier, dict[str, str]]):
    def initial_state_factory(self) -> dict[str, str]:
        return {}

    def initial_metadata_factory(self) -> JsonValue:
        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)

    print(projection.state)
    # {'name': 'Joe Bloggs', 'email': 'joe.bloggs@example.com',
    #  'dob': '1992-07-10'}


asyncio.run(main())

Projector takes the source identifier type, the state type and, optionally, the type of the projection's own metadata, which defaults to JsonValue. The projection's metadata is separate from the metadata on each event.

The library logs through structlog, so running the example also prints debug and info lines for each publish and read. To show only warnings and above, configure structlog before running it:

import logging

import structlog

structlog.configure(
    wrapper_class=structlog.make_filtering_bound_logger(logging.WARNING)
)

Finalising State

Override finalise_state to do work once per projection rather than in every event handler, for example validation or normalisation. Handlers can then make cheap, unvalidated changes and leave the expensive work to the end. This example extends the ProfileProjector from the basic example:

class ValidatedProfileProjector(ProfileProjector):
    def finalise_state(self, state: dict[str, str]) -> dict[str, str]:
        if "email" not in state:
            raise ValueError("profile has no email")
        return {**state, "email": state["email"].strip()}

finalise_state is called once at the end of each project() call, after all events are applied and before id_factory derives the projection id, including when the source has no events. Keep in mind that:

  • with ProjectionEventProcessor, which projects one event at a time, it runs once per processed event, so the saving comes from multi-event folds such as rebuilds;
  • its output becomes the starting state when a projection is resumed, either directly via state= or, with ProjectionEventProcessor, as the state reloaded from the projection store (the processor passes state=None for a stream's first event, when nothing is stored yet). So it must not change what later handlers, update_metadata or id_factory compute. Validation and recomputing derived fields are fine; lossy normalisation, such as clamping or truncation, isn't;
  • its output must survive a round trip through the projection store, and it must not change fields id_factory uses for projections that are already stored, otherwise those projections need rebuilding;
  • update_metadata and apply() see unfinalised state;
  • handlers mustn't rely on coercion or defaults that validation would apply;
  • handlers are found by converting the event name to snake case, and nothing stops that matching a projector method. An event named finalise-state is routed to finalise_state as if it were a handler and fails with a TypeError. Other method names clash the same way: apply and project also raise a TypeError, and id-factory silently replaces the state with the projection id. Avoid event names that convert to projector methods;
  • subclasses that override project() must call finalise_state themselves.

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.
    • asyncio support: the event store is implemented using asyncio and 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.
  • 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.

Metadata

Release files for logicblocks.event.store 0.1.12a8

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for logicblocks.event.store 0.1.12a8
File Size Uploaded Provenance Actions
logicblocks_event_store-0.1.12a8.tar.gz 108.4 kB Without provenance Details for logicblocks_event_store-0.1.12a8.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for logicblocks.event.store 0.1.12a8
File Interpreter ABI Platform Actions
logicblocks_event_store-0.1.12a8-py3-none-any.whl Python 3 none any Details for logicblocks_event_store-0.1.12a8-py3-none-any.whl

Total release size: 279.5 kB

Release files / logicblocks_event_store-0.1.12a8.tar.gz

Download URL logicblocks_event_store-0.1.12a8.tar.gz
Size 108.4 kB
Tags Source
SHA-256 checksum
How to use checksums
5ee2fe220d5e1d749dde7401432a1cf619bc2958ce82a59e44bb48bb9ca5fceb
BLAKE2b-256 checksum
How to use checksums
3c78126980d144803dd45412eb292bc4f364665d0acf3acb7280dbfb483584e3
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.12a8-py3-none-any.whl

Download URL logicblocks_event_store-0.1.12a8-py3-none-any.whl
Size 171.1 kB
Tags Python 3
SHA-256 checksum
How to use checksums
7af5ecf314d2231e81c444152bb38244cff1cea025cad9d7b7df4de8c0ab1574
BLAKE2b-256 checksum
How to use checksums
15d19749f0fa237b305f6247c1ea0adcb938c857a867abeec2c0e4167728e8ef
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}

Security for logicblocks.event.store 0.1.12a8

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

No provenance found

None of the files in this release were uploaded with provenance metadata.

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Release history Release notifications | RSS feed

This release
Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page