python-event-sourcery 0.5.3a4__tar.gz → 0.6.0__tar.gz

{python_event_sourcery-0.5.3a4 → python_event_sourcery-0.6.0}/.github/workflows/main.yml

@@ -41,6 +41,12 @@ jobs:
           - 1113:1113
           - 2113:2113
 
+      rabbitmq:
+        image: rabbitmq:3.11.2
+        ports:
+          - '5672:5672'
+          - '15672:15672'
+
     steps:
     - uses: actions/checkout@v2
     - name: Install uv
@@ -48,11 +54,15 @@ jobs:
       with:
         python-version: ${{ matrix.python-version }}
         enable-cache: true
+    - name: Install poe
+      run: uv tool install poethepoet
     - name: Install deps
       run: uv sync --all-extras
     - name: Run linters
-      run: make lint
+      run: poe lint-fix
     - name: Build docs
       run: uv run --all-extras zensical build --clean
+    - name: Test docs code snippets
+      run: poe docs-test
     - name: Test with pytest
-      run: make test
+      run: poe test

{python_event_sourcery-0.5.3a4 → python_event_sourcery-0.6.0}/AGENTS.md

@@ -21,9 +21,10 @@ uv sync --all-extras   # install all deps (dev group is included by default)
 
 ```bash
 docker compose up -d   # required before tests (postgres, kurrentdb, rabbitmq)
-make test              # pytest with coverage (fail_under = 100)
-make lint              # ruff format + ruff check + mypy (must pass clean)
-make docs-serve        # docs live preview
+poe test              # pytest with coverage (fail_under = 100)
+poe lint-fix              # ruff format + ruff check + mypy (must pass clean)
+poe docs-test         # pytest docs/code/ — snippets embedded in docs must pass
+poe docs-serve        # docs live preview
 ```
 
 Run single tools via `uv run --all-extras <tool>`, e.g. `uv run --all-extras pytest tests/event_store -k django`.
@@ -34,12 +35,18 @@ Run single tools via `uv run --all-extras <tool>`, e.g. `uv run --all-extras pyt
 - New backend functionality goes through the shared test suite in `tests/`; use `not_implemented` / `skip_backend` markers for unsupported features.
 - Version bumps: `uv version --bump alpha` (CI autopublishes prereleases on push to main).
 
+## Tests
+
+See [`tests/AGENTS.md`](tests/AGENTS.md) for required TDD workflow and test style.
+
 ## Docs
 
-Changing public API or behavior may require updating `docs/` — pages embed runnable snippets from `docs/code/` (via `--8<--` includes). After touching docs code:
+Changing public API or behavior **requires** updating `docs/` and running docs tests —
+pages embed runnable snippets from `docs/code/` (via `--8<--` includes), and broken
+snippets go unnoticed without them. Docs tests need no docker services. After touching docs code:
 
 ```bash
-uv run --all-extras pytest docs/code   # snippets are real tests, must pass
-make lint-fix-docs                     # lint docs/code
+poe docs-test                         # snippets are real tests, must pass (enforced in CI)
+poe docs-lint-fix                     # lint docs/code
 uv run --all-extras zensical build --clean   # verify docs build
 ```

{python_event_sourcery-0.5.3a4 → python_event_sourcery-0.6.0}/CHANGELOG.md

@@ -1,5 +1,14 @@
 # Changelog
 
+## 0.6.0
+### Added
+- Typed, independently owned event context components with lazy access through `Context.get()`.
+- Context enrichers configured through `Backend.with_context_enrichers()`.
+- Optional `event_sourcery_otel` package for OpenTelemetry context propagation and parent-context activation.
+
+### Changed
+- **Breaking:** New `Context` values reject arbitrary root fields; add new context data with typed components.
+
 ## 0.5.2
 ### Changed
 - **Breaking:** `Repository.aggregate()` yields `WrappedAggregate` instead of `Aggregate` directly

python_event_sourcery-0.6.0/CONTRIBUTING.md

@@ -0,0 +1,54 @@
+# Basics
+
+## Prerequisites
+
+- docker + docker compose / any compatible replacement
+- uv
+- [poe](https://poethepoet.natn.io/)
+
+## Installation
+
+```bash
+uv sync --all-extras
+```
+
+## Running tests
+
+```bash
+docker compose up
+poe test
+```
+
+## Running linters
+
+```bash
+poe lint-fix
+```
+
+# Documentation
+
+First, `cd docs/documentation`
+
+## Testing docs code snippets
+
+Snippets embedded in docs pages (`docs/documentation/`) are real tests living in
+`docs/code/`. They must pass — otherwise the docs silently show broken code.
+No docker services required (they run on in-memory/SQLite backends):
+
+```bash
+poe docs-test        # or: uv run --all-extras pytest docs/code/
+poe docs-lint-fix    # ruff format + check for docs/code/
+```
+
+Run them whenever you change public API, behavior, or anything in `docs/code/`.
+
+## Serve docs with live preview
+
+```bash
+poe docs-serve
+```
+
+## Deploy docs to github pages
+
+Docs get auto deployed from main after each change.
+

{python_event_sourcery-0.5.3a4 → python_event_sourcery-0.6.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: python-event-sourcery
-Version: 0.5.3a4
+Version: 0.6.0
 Summary: A library for event-based systems in Python.
 Author-email: Sebastian Buczyński <nnplaya@gmail.com>, Łukasz Żukowski <lukasz.zukowski@gmail.com>
 License-Expression: MIT
@@ -13,6 +13,8 @@ Provides-Extra: django
 Requires-Dist: django<6,>=4; extra == 'django'
 Provides-Extra: kurrentdb
 Requires-Dist: kurrentdbclient>=1.0.6; extra == 'kurrentdb'
+Provides-Extra: otel
+Requires-Dist: opentelemetry-api<2,>=1; extra == 'otel'
 Provides-Extra: sqlalchemy
 Requires-Dist: sqlalchemy>=2.0; extra == 'sqlalchemy'
 Description-Content-Type: text/markdown

python_event_sourcery-0.6.0/docs/adr/20260926-typed-event-context-components-and-enrichers.md

@@ -0,0 +1,204 @@
+# Typed Event Context Components and Enrichers
+
+Date: 2026-09-26
+
+## Status
+
+Accepted
+
+Discussion: [GitHub issue #115](https://github.com/python-event-sourcery/python-event-sourcery/issues/115)
+
+## Problem Statement
+
+`Context` currently stores `correlation_id`, `causation_id`, and arbitrary extra
+fields. Applications can validate the complete context as their own `Context`
+subclass, but optional integrations cannot add strongly typed data without knowing
+that complete application-specific type.
+
+OpenTelemetry is the initial use case. Its integration needs to persist a typed
+propagation carrier alongside existing application context. The same mechanism may
+support request, tenant, authentication, and other integration-owned context data.
+
+Python cannot express an accumulated type such as `ApplicationContext &
+OpenTelemetryContext & RequestContext`. Each integration therefore needs to own and
+type only its part of the event context.
+
+## Decision
+
+### Context components
+
+Introduce a common Pydantic base for independently typed context components. Every
+component declares an explicit, stable wire name:
+
+```python
+class ContextComponent(BaseModel):
+    __context_name__: ClassVar[str]
+
+
+class OpenTelemetryCarrier(ContextComponent):
+    __context_name__ = "opentelemetry"
+
+    values: dict[str, str]
+```
+
+`Context` stores extension payloads in a dedicated `components` mapping. Its keys
+are component wire names and its values are JSON-compatible component payloads:
+
+```json
+{
+  "correlation_id": "...",
+  "causation_id": "...",
+  "components": {
+    "opentelemetry": {
+      "values": {
+        "traceparent": "00-...",
+        "tracestate": "..."
+      }
+    },
+    "application.request": {
+      "user_id": "123",
+      "request_id": "..."
+    }
+  }
+}
+```
+
+The mapping prevents duplicate components by construction and keeps new
+integration-owned data separate from root context fields.
+
+### Typed access and serialization
+
+`Context` exposes lazy typed access:
+
+```python
+otel = context.get(OpenTelemetryCarrier)
+# OpenTelemetryCarrier | None
+```
+
+`get()` derives the wire name from the requested component type, finds that
+payload in `components`, and validates it with `component_type.model_validate()`.
+`Context.with_component(component)` returns a new context containing the component
+payload; it does not mutate the existing context.
+
+`Serde` persists and restores `components` as raw JSON-compatible data. It does
+not eagerly materialize component classes. Consequently, this change does not add
+`ContextRegistry` or a generic registry abstraction: the caller supplies the
+component class when it requests a typed value. An event written with an optional
+integration can therefore be read and round-tripped by a process that does not
+install that integration.
+
+### Context enrichers
+
+An enricher declares the component type it owns and produces that component for an
+event when applicable:
+
+```python
+class EventContextEnricher(Protocol):
+    component_type: type[ContextComponent]
+
+    def enrich(
+        self,
+        context: Context,
+        *,
+        event: WrappedEvent,
+        stream_id: StreamId,
+    ) -> ContextComponent | None:
+        ...
+```
+
+Enrichers are configured through `Backend.with_context_enrichers()` and run in
+`EventStore._append()` after a `WrappedEvent` and its `Context` already exist, but
+before serialization:
+
+```text
+existing Context
+    -> context enrichers
+    -> Serde
+    -> StorageStrategy
+```
+
+An enricher returns only the component it owns. It does not replace or mutate the
+complete context. Enrichment happens once when a new event is written; it does not
+run during loading, replay, subscription processing, or outbox retries.
+
+A component already present on the incoming context is explicit and takes
+precedence over enricher output. Two enrichers declaring the same component are
+rejected by `with_context_enrichers()` before events can be appended.
+
+## Backward compatibility
+
+### Root correlation fields
+
+The existing `correlation_id` and `causation_id` fields remain at the context root.
+They are exposed through the component API as a special built-in
+`EventCorrelation` component:
+
+```python
+correlation = context.get(EventCorrelation)
+```
+
+`EventCorrelation` is a typed view over the existing root fields.
+`Context.with_component(EventCorrelation(...))` updates those root fields rather
+than adding a nested component key.
+
+### Existing API and stored events
+
+New `Context` values accept the root correlation fields and typed components. New
+integration data is added with `Context.with_component()` rather than arbitrary
+root fields:
+
+```python
+context = Context(correlation_id=...)
+context = context.with_component(RequestContext(user_id="123"))
+```
+
+Existing stored events remain readable without data migration. Historical root
+fields are retained when an event is deserialized, and existing whole-context
+validation remains available:
+
+```python
+wrapped_event.get_context(ApplicationContext)
+```
+
+If `ApplicationContext` declares `components`, it receives their raw payloads;
+otherwise `components` are excluded for compatibility with models using
+`extra="forbid"`. Unknown keys within persisted `components` remain opaque raw
+payloads, allowing processes without an optional integration to read and
+round-trip their events.
+
+This gives two compatible views:
+
+```text
+Legacy: validate the complete historical context as an application model
+Typed:  retrieve an independent component by its class
+```
+
+## OpenTelemetry application
+
+The optional `event_sourcery_otel` package defines an `OpenTelemetryCarrier` and
+an enricher without adding an OpenTelemetry dependency to the core package:
+
+```text
+current OpenTelemetry Context
+    -> propagator.inject()
+    -> OpenTelemetryCarrier
+    -> persisted event Context
+```
+
+The enricher only snapshots the active propagation context. Consumers can
+explicitly obtain or activate a persisted parent context through
+`get_parent_context()` and `use_parent_context()`. Creating spans and deciding
+their lifecycle remain application concerns.
+
+
+## Consequences
+
+- Integrations can own strongly typed context data independently.
+- Application-defined context and integration-defined components can coexist.
+- Existing root fields, custom context models, and stored events remain compatible.
+- Component validation happens lazily when code requests a component class.
+- `EventStore` gains a context enrichment step before serialization.
+- Stable component names become part of the persisted event format and must not be
+  changed without an explicit migration strategy.
+- New integration data cannot collide with legacy root fields because it is stored
+  under `components`.

python_event_sourcery-0.6.0/docs/code/test_context_enrichers.py

@@ -0,0 +1,40 @@
+from typing import ClassVar
+
+from event_sourcery import StreamId
+from event_sourcery.backend import InMemoryBackend
+from event_sourcery.event import Context, ContextComponent, Event, WrappedEvent
+
+
+def test_context_enrichers() -> None:
+    # --8<-- [start:context_enrichers_01]
+    class RequestContext(ContextComponent):
+        __context_name__: ClassVar[str] = "application.request"
+
+        request_id: str
+
+    class RequestContextEnricher:
+        component_type: type[ContextComponent] = RequestContext
+
+        def enrich(
+            self,
+            context: Context,
+            *,
+            event: WrappedEvent,
+            stream_id: StreamId,
+        ) -> RequestContext:
+            return RequestContext(request_id="request-123")
+
+    class InvoicePaid(Event):
+        invoice_number: str
+
+    backend = InMemoryBackend().with_context_enrichers(RequestContextEnricher())
+    event_store = backend.event_store
+    stream_id = StreamId(name="invoices/1003")
+
+    event_store.append(InvoicePaid(invoice_number="1003"), stream_id=stream_id)
+
+    recorded = event_store.load_stream(stream_id)[0]
+    assert recorded.context.get(RequestContext) == RequestContext(
+        request_id="request-123"
+    )
+    # --8<-- [end:context_enrichers_01]

{python_event_sourcery-0.5.3a4 → python_event_sourcery-0.6.0}/docs/code/test_get_started.py

@@ -14,10 +14,12 @@ def test_get_started():
         InvoicePaid(invoice_number="1003"),
         stream_id=StreamId(name="invoices/1003"),
     )
-
-    for recorded in event_store.load_stream(StreamId(name="invoices/1003")):
-        print(recorded.event, recorded.version)
     # --8<-- [end:get_started_01]
+    # --8<-- [start:get_started_02]
+    recorded_events = event_store.load_stream(StreamId(name="invoices/1003"))
+    for recorded in recorded_events:
+        print(recorded.event, recorded.version)
+    # --8<-- [end:get_started_02]
 
     events = event_store.load_stream(StreamId(name="invoices/1003"))
     assert len(events) == 1

python_event_sourcery-0.6.0/docs/code/test_otel.py

@@ -0,0 +1,38 @@
+from opentelemetry import trace
+
+from event_sourcery import StreamId
+from event_sourcery.backend import InMemoryBackend
+from event_sourcery.event import Event
+from event_sourcery_otel import OpenTelemetryContextEnricher, use_parent_context
+
+
+def test_otel_propagation() -> None:
+    # --8<-- [start:otel_01]
+    class InvoicePaid(Event):
+        invoice_number: str
+
+    backend = InMemoryBackend().with_context_enrichers(OpenTelemetryContextEnricher())
+    event_store = backend.event_store
+    stream_id = StreamId(name="invoices/1003")
+
+    span_context = trace.SpanContext(
+        trace_id=0x1234567890ABCDEF1234567890ABCDEF,
+        span_id=0x1234567890ABCDEF,
+        is_remote=False,
+        trace_flags=trace.TraceFlags(trace.TraceFlags.SAMPLED),
+        trace_state=trace.TraceState(),
+    )
+    with trace.use_span(trace.NonRecordingSpan(span_context), end_on_exit=False):
+        event_store.append(InvoicePaid(invoice_number="1003"), stream_id=stream_id)
+
+    recorded = event_store.load_stream(stream_id)[0]
+    # --8<-- [end:otel_01]
+
+    # --8<-- [start:otel_02]
+    with use_parent_context(recorded):
+        consume(recorded.event)
+    # --8<-- [end:otel_02]
+
+
+def consume(event: Event) -> None:
+    assert isinstance(event, Event)

{python_event_sourcery-0.5.3a4 → python_event_sourcery-0.6.0}/docs/get_started.md

@@ -16,7 +16,7 @@ pip install "python-event-sourcery[sqlalchemy]"
 
 The example below uses the in-memory backend, so you can run it right away, without setting up a database.
 
-Define an event by inheriting from the [Event] base class, then append it to a stream and read it back:
+Define an event by inheriting from the [Event] base class, then append it to a stream:
 
 ```python
 --8<--
@@ -24,6 +24,16 @@ docs/code/test_get_started.py:get_started_01
 --8<--
 ```
 
+## Reading events
+
+Events from a given stream can be read back at once:
+
+```python
+--8<--
+docs/code/test_get_started.py:get_started_02
+--8<--
+```
+
 Output:
 
 ```

{python_event_sourcery-0.5.3a4 → python_event_sourcery-0.6.0}/docs/index.md

@@ -1,3 +1,7 @@
 # Python Event Sourcery
 
 A library for event-based systems in Python. For event sourcing, CQRS, and event-driven architectures.
+
+## What's first?
+
+- **[Get started guide](get_started.md)** - try out the library in 5 minutes

python_event_sourcery-0.6.0/docs/recipes/context_enrichment.md

@@ -0,0 +1,17 @@
+# Enrich event context
+
+A context enricher adds a typed component immediately before an event is
+serialized. Configure enrichers on the backend before accessing its event store.
+The original event context is not mutated.
+
+```python
+--8<--
+docs/code/test_context_enrichers.py:context_enrichers_01
+--8<--
+```
+
+Pass multiple enrichers to `with_context_enrichers()` in their execution order.
+Each enricher may return `None` when it has no component to add for an event.
+If two enrichers declare the same component, `with_context_enrichers()` raises
+`ConflictingContextComponent`. A component explicitly supplied with the event
+takes precedence over enricher output.

{python_event_sourcery-0.5.3a4 → python_event_sourcery-0.6.0}/docs/recipes/integrate.md

@@ -61,6 +61,7 @@ docs/code/test_recipes.py:integrate_sql_02
 
 You can now use [EventStore] to load events from a stream or append new events.
 
+
 [Backend]: ../reference/event_store/backend/Backend.md
 [EventStore]: ../reference/event_store/EventStore.md
 [SQLAlchemy]: ../reference/backends/sqlalchemy.md

python_event_sourcery-0.6.0/docs/recipes/opentelemetry.md

@@ -0,0 +1,25 @@
+# OpenTelemetry context propagation
+
+Install the optional integration:
+
+```bash
+pip install "python-event-sourcery[otel]"
+```
+
+Configure its enricher before accessing the event store. It persists the active
+OpenTelemetry propagation context; it does not create or end spans.
+
+```python
+--8<--
+docs/code/test_otel.py:otel_01
+--8<--
+```
+
+When consuming a recorded event, explicitly activate its propagated parent
+context before starting application work or a consumer span:
+
+```python
+--8<--
+docs/code/test_otel.py:otel_02
+--8<--
+```

python_event_sourcery-0.6.0/docs/reference/event_store/event/ContextComponent.md

@@ -0,0 +1 @@
+::: event_sourcery.event.ContextComponent

python_event_sourcery-0.6.0/docs/reference/event_store/event/EventContextEnricher.md

@@ -0,0 +1 @@
+::: event_sourcery.event.EventContextEnricher

python_event_sourcery-0.6.0/docs/reference/event_store/event/EventCorrelation.md

@@ -0,0 +1 @@
+::: event_sourcery.event.EventCorrelation

python_event_sourcery-0.6.0/docs/reference/otel/OpenTelemetryCarrier.md

@@ -0,0 +1 @@
+::: event_sourcery_otel.OpenTelemetryCarrier

python_event_sourcery-0.6.0/docs/reference/otel/OpenTelemetryContextEnricher.md

@@ -0,0 +1 @@
+::: event_sourcery_otel.OpenTelemetryContextEnricher

python_event_sourcery-0.6.0/docs/reference/otel/get_parent_context.md

@@ -0,0 +1 @@
+::: event_sourcery_otel.get_parent_context

python_event_sourcery-0.6.0/docs/reference/otel/use_parent_context.md

@@ -0,0 +1 @@
+::: event_sourcery_otel.use_parent_context

{python_event_sourcery-0.5.3a4 → python_event_sourcery-0.6.0}/event_sourcery/_event_store/backend.py

@@ -14,6 +14,7 @@ from event_sourcery._event_store.event.encryption import (
 from event_sourcery._event_store.event.registry import EventRegistry
 from event_sourcery._event_store.event.serde import Serde
 from event_sourcery._event_store.event_store import (
+    EventContextEnricher,
     EventStore,
     StorageStrategy,
 )
@@ -36,7 +37,7 @@ from event_sourcery._event_store.subscription.interfaces import (
     SubscriptionStrategy,
 )
 from event_sourcery._event_store.tenant_id import DEFAULT_TENANT, TenantId
-from event_sourcery.exceptions import NoProviderConfigured
+from event_sourcery.exceptions import ConflictingContextComponent, NoProviderConfigured
 
 T = TypeVar("T")
 T_co = TypeVar("T_co", covariant=True)
@@ -107,6 +108,10 @@ class _Container:
         return new
 
 
+class ContextEnrichers(tuple[EventContextEnricher, ...]):
+    pass
+
+
 class Backend(_Container):
     """
     Dependency Injection container for Event Sourcery components.
@@ -140,9 +145,11 @@ class Backend(_Container):
         self[StorageStrategy] = not_configured(
             "Use one of pyES backends: SQLAlchemy, Django or KurrentDB",
         )
+        self[ContextEnrichers] = ContextEnrichers()
         self[EventStore] = lambda c: EventStore(
             storage_strategy=c[StorageStrategy],
             serde=c[Serde],
+            context_enrichers=c[ContextEnrichers],
         )
         self[Outbox] = lambda c: Outbox(
             strategy=c[OutboxStorageStrategy],
@@ -206,6 +213,16 @@ class Backend(_Container):
         )
         return self
 
+    def with_context_enrichers(self, *enrichers: EventContextEnricher) -> Self:
+        names = set[str]()
+        for enricher in enrichers:
+            name = enricher.component_type.__context_name__
+            if name in names:
+                raise ConflictingContextComponent(name)
+            names.add(name)
+        self[ContextEnrichers] = ContextEnrichers(enrichers)
+        return self
+
 
 class TransactionalBackend(Backend):
     """