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

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

@@ -35,6 +35,10 @@ 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 **requires** updating `docs/` and running docs tests —

{python_event_sourcery-0.5.3a5 → 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.5.3a5 → python_event_sourcery-0.6.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: python-event-sourcery
-Version: 0.5.3a5
+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.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.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.3a5 → 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.3a5 → 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):
     """

{python_event_sourcery-0.5.3a5 → python_event_sourcery-0.6.0}/event_sourcery/_event_store/event/dto.py

@@ -1,10 +1,11 @@
 import dataclasses
 from dataclasses import dataclass
 from datetime import datetime, timezone
-from typing import Any, Generic, TypeAlias, TypeVar
+from typing import Any, ClassVar, Generic, TypeAlias, TypeVar, cast
 from uuid import UUID, uuid4
 
-from pydantic import BaseModel
+from pydantic import BaseModel, Field, PrivateAttr
+from typing_extensions import Self
 
 from event_sourcery._event_store.stream_id import StreamId
 from event_sourcery._event_store.tenant_id import DEFAULT_TENANT, TenantId
@@ -76,23 +77,66 @@ TEvent = TypeVar("TEvent", bound=Event)
 TContext = TypeVar("TContext", bound=BaseModel)
 
 
-class Context(BaseModel, extra="allow"):
-    """
-    Extensible context object for event metadata.
+class ContextComponent(BaseModel):
+    """A typed, independently owned part of an event context."""
 
-    Designed to carry correlation and causation identifiers, and can be extended
-    with additional metadata fields as needed. This allows for flexible propagation
-    of context information throughout event processing and handling pipelines.
+    __context_name__: ClassVar[str]
+
+
+TContextComponent = TypeVar("TContextComponent", bound=ContextComponent)
+
+
+class EventCorrelation(ContextComponent):
+    """Typed view of the root correlation and causation fields."""
+
+    correlation_id: UUID | None = None
+    causation_id: UUID | None = None
 
-    Attributes:
-        correlation_id (UUID | None): Identifier for correlating related events.
-        causation_id (UUID | None): Identifier for the cause of the event.
 
-    Additional fields can be added dynamically due to `extra="allow"`.
+class Context(BaseModel, extra="forbid"):
+    """Event metadata with fixed fields and independently typed components.
+
+    New writes may contain root correlation fields and registered component payloads.
+    Extra root fields in historical events are retained by the deserialization path
+    for backwards-compatible reads.
     """
 
     correlation_id: UUID | None = None
     causation_id: UUID | None = None
+    components: dict[str, dict[str, Any]] = Field(default_factory=dict)
+    _legacy_fields: dict[str, Any] = PrivateAttr(default_factory=dict)
+
+    def get(self, component_type: type[TContextComponent]) -> TContextComponent | None:
+        """Return a component validated as ``component_type`` when present."""
+        if component_type is EventCorrelation:
+            return cast(
+                TContextComponent,
+                EventCorrelation(
+                    correlation_id=self.correlation_id,
+                    causation_id=self.causation_id,
+                ),
+            )
+        payload = self.components.get(component_type.__context_name__)
+        return component_type.model_validate(payload) if payload is not None else None
+
+    def with_component(self, component: ContextComponent) -> Self:
+        """Return a copy with ``component`` added without mutating this context."""
+        if isinstance(component, EventCorrelation):
+            return self.model_copy(
+                update={
+                    "correlation_id": component.correlation_id,
+                    "causation_id": component.causation_id,
+                }
+            )
+
+        return self.model_copy(
+            update={
+                "components": {
+                    **self.components,
+                    component.__context_name__: component.model_dump(mode="json"),
+                }
+            }
+        )
 
 
 @dataclasses.dataclass()
@@ -139,7 +183,9 @@ class WrappedEvent(Generic[TEvent]):
         )
 
     def get_context(self, context_type: type[TContext]) -> TContext:
-        return context_type.model_validate(self.context.model_dump())
+        exclude = set() if "components" in context_type.model_fields else {"components"}
+        context = self.context.model_dump(exclude=exclude)
+        return context_type.model_validate({**context, **self.context._legacy_fields})
 
 
 @dataclasses.dataclass(frozen=True)

{python_event_sourcery-0.5.3a5 → python_event_sourcery-0.6.0}/event_sourcery/_event_store/event/serde.py

@@ -1,6 +1,6 @@
 import dataclasses
-from collections.abc import Mapping, Sequence
-from typing import cast
+from collections.abc import Mapping
+from typing import Any, cast
 
 from event_sourcery._event_store.event.dto import (
     Context,
@@ -23,13 +23,31 @@ class Serde:
         self.registry = registry
         self.encryption = encryption
 
+    def _deserialize_context(self, context: Mapping[str, Any]) -> Context:
+        field_names = {"correlation_id", "causation_id", "components"}
+        restored = Context(
+            correlation_id=context.get("correlation_id"),
+            causation_id=context.get("causation_id"),
+            components=context.get("components", {}),
+        )
+        restored._legacy_fields = {
+            name: value for name, value in context.items() if name not in field_names
+        }
+        return restored
+
+    def _serialize_context(self, context: Context) -> dict[str, Any]:
+        stored = context.model_dump(mode="json")
+        if not context.components:
+            del stored["components"]
+        return {**stored, **context._legacy_fields}
+
     def deserialize(self, event: RawEvent) -> WrappedEvent:
         event_as_dict = dataclasses.asdict(event)
         del event_as_dict["stream_id"]
         del event_as_dict["name"]
         data = cast(Mapping, event_as_dict.pop("data"))
         context = event_as_dict.pop("context", {})
-        event_as_dict["context"] = Context(**context)
+        event_as_dict["context"] = self._deserialize_context(context)
         event_type = self.registry.type_for_name(event.name)
 
         processed_data = self.encryption.decrypt(
@@ -43,9 +61,6 @@ class Serde:
             event=event_type(**processed_data),
         )
 
-    def deserialize_many(self, events: Sequence[RawEvent]) -> list[WrappedEvent]:
-        return [self.deserialize(event) for event in events]
-
     def deserialize_record(self, record: RecordedRaw) -> Recorded:
         return Recorded(
             wrapped_event=self.deserialize(record.entry),
@@ -66,10 +81,5 @@ class Serde:
             version=event.version,
             name=self.registry.name_for_type(type(event.event)),
             data=self.encryption.encrypt(event.event, stream_id),
-            context=event.context.model_dump(mode="json"),
+            context=self._serialize_context(event.context),
         )
-
-    def serialize_many(
-        self, events: Sequence[WrappedEvent], stream_id: StreamId
-    ) -> list[RawEvent]:
-        return [self.serialize(event, stream_id) for event in events]