Metadata-Version: 2.5
Name: logicblocks.event.store
Version: 0.1.12a8
Summary: Eventing infrastructure for event sourced architectures.
Project-URL: Documentation, https://logicblocks.github.io/event.store/
Project-URL: Repository, https://github.com/logicblocks/event.store
Author-email: Toby Clemson <tobyclemson@gmail.com>, Jonas Svalin <jonassvalin@gmail.com>
License-Expression: MIT
License-File: LICENSE.md
Requires-Python: <4.0,>=3.13
Requires-Dist: aiologic>=0.15.0
Requires-Dist: psycopg[binary,pool]>=3.2.3
Requires-Dist: pyheck>=0.1.5
Requires-Dist: rich>=14.0.0
Requires-Dist: structlog>=25.1.0
Requires-Dist: uvloop>=0.22.1
Description-Content-Type: text/markdown

logicblocks.event.store
=======================

![PyPI - Version](https://img.shields.io/pypi/v/logicblocks.event.store)
![Python - Version](https://img.shields.io/pypi/pyversions/logicblocks.event.store)
[![Documentation](https://img.shields.io/github/actions/workflow/status/logicblocks/event.store/docs.yaml?branch=main&label=docs)](https://logicblocks.github.io/event.store/)
![CircleCI](https://img.shields.io/circleci/build/github/logicblocks/event.store)

Eventing infrastructure for event-sourced architectures.

Table of Contents
-----------------

- [Installation](#installation)
- [Usage](#usage)
- [Features](#features)
- [Documentation](#documentation)
- [Development](#development)
- [Contributing](#contributing)
- [License](#license)

Installation
------------

```shell
pip install logicblocks-event-store
```

Usage
-----

### Basic Example

<!-- --8<-- [start:basic-example] -->
```python
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](https://www.structlog.org/), 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:

```python
import logging

import structlog

structlog.configure(
    wrapper_class=structlog.make_filtering_bound_logger(logging.WARNING)
)
```
<!-- --8<-- [end:basic-example] -->

### 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](#basic-example):

```python
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
-------------

- [Documentation](https://logicblocks.github.io/event.store/)
- [API reference](https://logicblocks.github.io/event.store/reference/store/)

Development
-----------

This project uses [mise](https://mise.jdx.dev/) for tool management. To get
started:

```shell
mise install
mise run
```

See [CONTRIBUTING.md](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](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](CODE_OF_CONDUCT.md).

License
-------

Copyright &copy; 2025 LogicBlocks Maintainers

Distributed under the terms of the
[MIT License](http://opensource.org/licenses/MIT).
