python-event-sourcery 0.5.2a0__tar.gz → 0.5.3a0__tar.gz

{python_event_sourcery-0.5.2a0 → python_event_sourcery-0.5.3a0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.3
 Name: python-event-sourcery
-Version: 0.5.2a0
+Version: 0.5.3a0
 Summary: A library for event-based systems in Python.
 License: MIT
 Author: Sebastian Buczyński

{python_event_sourcery-0.5.2a0 → python_event_sourcery-0.5.3a0}/event_sourcery/event_sourcing/__init__.py

@@ -1,7 +1,8 @@
 __all__ = [
     "Aggregate",
     "Repository",
+    "WrappedAggregate",
 ]
 
-from event_sourcery.event_sourcing.aggregate import Aggregate
+from event_sourcery.event_sourcing.aggregate import Aggregate, WrappedAggregate
 from event_sourcery.event_sourcing.repository import Repository

python_event_sourcery-0.5.3a0/event_sourcery/event_sourcing/aggregate.py

@@ -0,0 +1,123 @@
+import dataclasses
+from collections.abc import Iterator
+from contextlib import contextmanager
+from datetime import datetime
+from typing import ClassVar, Generic, TypeVar
+
+from event_sourcery import StreamCategory, StreamId
+from event_sourcery.event import Context, Event
+
+
+class Aggregate:
+    """
+    Base class for event-sourced aggregates.
+
+    Aggregates encapsulate domain logic and state changes as a sequence of events.
+    They are responsible for applying events to mutate their state and for emitting new
+    events that represent business-relevant changes.
+
+    The Aggregate base class provides mechanisms for tracking unpersisted changes and
+    for applying events in a consistent way.
+
+    Attributes:
+        category (ClassVar[StreamCategory]): StreamCategory for the aggregate type (group streams).
+        __changes__ (list[Event]): List of yet not persisted events.
+    """
+
+    category: ClassVar[StreamCategory]
+    _changes: list[Event]
+
+    @property
+    def __changes__(self) -> list[Event]:
+        return list(getattr(self, "_changes", []))
+
+    @contextmanager
+    def __persisting_changes__(self) -> Iterator[Iterator[Event]]:
+        """
+        Context manager for accessing and clearing unpersisted events.
+
+        Yields an iterator over all events that have been applied but not yet persisted.
+        After exiting the context, the list of unpersisted events is cleared.
+
+        Returns:
+            Iterator[Iterator[Event]]: Iterator over unpersisted events.
+        """
+        yield iter(self.__changes__)
+
+    def __apply__(self, event: Event) -> None:
+        """
+        Applies a single event to mutate the aggregate's state.
+
+        This method must be implemented by subclasses to define how each event type
+        changes the aggregate's state.
+
+        Args:
+            event (Event): The event to apply.
+        """
+        raise NotImplementedError
+
+    def _emit(self, event: Event) -> None:
+        """
+        Applies and tracks a new event as a pending change.
+
+        Calls __apply__ to mutate the aggregate's state and appends the event to the list
+        of unpersisted changes.
+
+        Args:
+            event (Event): The event to emit and track.
+        """
+        if not hasattr(self, "_changes"):
+            self._changes = []
+        self.__apply__(event)
+        self._changes.append(event)
+
+
+TAggregate = TypeVar("TAggregate", bound=Aggregate)
+TContext = TypeVar("TContext", bound=Context)
+
+
+@dataclasses.dataclass()
+class WrappedAggregate(Generic[TAggregate]):
+    """
+    Wraps an aggregate instance with stream-level metadata.
+
+    Provides access to the aggregate alongside information such as version,
+    timestamps, and whether the aggregate is newly created. Follows the same
+    wrapper pattern as ``WrappedEvent``.
+
+    Attributes:
+        aggregate: The aggregate instance.
+        stream_id: The stream identity (UUID + category).
+        context: The context passed for this operation, if any.
+        created_at: Timestamp of the first event in the stream.
+        updated_at: Timestamp of the last event in the stream.
+        stored_version: Number of events persisted before this session.
+    """
+
+    aggregate: TAggregate
+    stream_id: StreamId
+    context: Context = dataclasses.field(default_factory=Context)
+    stored_version: int = 0
+    created_at: datetime | None = None
+    updated_at: datetime | None = None
+
+    @property
+    def version(self) -> int:
+        """Current version of the aggregate, including pending events."""
+        return self.stored_version + len(getattr(self.aggregate, "__changes__", []))
+
+    @property
+    def is_new(self) -> bool:
+        """Whether the aggregate is newly created (no events existed before)."""
+        return self.stored_version == 0
+
+    def get_context(self, context_type: type[TContext]) -> TContext:
+        """Convert the stored context to a specific context type.
+
+        Args:
+            context_type: The target context class to validate against.
+
+        Returns:
+            An instance of *context_type* populated from the stored context data.
+        """
+        return context_type.model_validate(self.context.model_dump())

{python_event_sourcery-0.5.2a0 → python_event_sourcery-0.5.3a0}/event_sourcery/event_sourcing/repository.py

@@ -5,6 +5,7 @@ from typing import Generic, TypeVar, cast
 from event_sourcery import EventStore, StreamId, StreamUUID
 from event_sourcery.event import Context, Event, WrappedEvent
 from event_sourcery.event_sourcing import Aggregate
+from event_sourcery.event_sourcing.aggregate import WrappedAggregate
 
 TAggregate = TypeVar("TAggregate", bound=Aggregate)
 TEvent = TypeVar("TEvent", bound=Event)
@@ -28,13 +29,13 @@ class Repository(Generic[TAggregate]):
         uuid: StreamUUID,
         aggregate: TAggregate,
         context: Context | None = None,
-    ) -> Iterator[TAggregate]:
+    ) -> Iterator[WrappedAggregate[TAggregate]]:
         """
         Context manager for loading an aggregate instance.
 
         Loads the aggregate's event stream, replays events to reconstruct its state,
-        yields the aggregate for use, and persists any new events emitted during the
-        context.
+        yields a ``WrappedAggregate`` containing the aggregate and stream metadata,
+        and persists any new events emitted during the context.
 
         Args:
             uuid (StreamUUID): The unique identifier of the aggregate's stream.
@@ -42,33 +43,33 @@ class Repository(Generic[TAggregate]):
             context (Context | None): Optional context to attach to all emitted events.
 
         Yields:
-            TAggregate: The loaded and ready-to-use aggregate instance.
+            WrappedAggregate[TAggregate]: The aggregate wrapped with stream metadata.
         """
         stream_id = StreamId(uuid=uuid, name=uuid.name, category=aggregate.category)
-        old_version = self._load(stream_id, aggregate)
-        yield aggregate
-        self._save(aggregate, old_version, stream_id, context)
 
-    def _load(self, stream_id: StreamId, aggregate: TAggregate) -> int:
-        stream = self._event_store.load_stream(stream_id)
-        last_version = 0
-        for envelope in stream:
-            aggregate.__apply__(envelope.event)
-            last_version = cast(int, envelope.version)
+        wrapped = WrappedAggregate(
+            aggregate=aggregate,
+            stream_id=stream_id,
+            context=context or Context(),
+        )
+        self._load(wrapped)
+        yield wrapped
+        self._save(wrapped)
 
-        return last_version
+    def _load(self, wrapped: WrappedAggregate[TAggregate]) -> None:
+        stream = self._event_store.load_stream(wrapped.stream_id)
+        for envelope in stream:
+            wrapped.aggregate.__apply__(envelope.event)
+            wrapped.stored_version = cast(int, envelope.version)
+            if wrapped.created_at is None:
+                wrapped.created_at = envelope.created_at
+            wrapped.updated_at = envelope.created_at
 
-    def _save(
-        self,
-        aggregate: TAggregate,
-        old_version: int,
-        stream_id: StreamId,
-        context: Context | None = None,
-    ) -> None:
-        with aggregate.__persisting_changes__() as pending:
-            start_from = old_version + 1
+    def _save(self, wrapped: WrappedAggregate[TAggregate]) -> None:
+        with wrapped.aggregate.__persisting_changes__() as pending:
+            start_from = wrapped.stored_version + 1
             events = [
-                WrappedEvent.wrap(event, version, context=context)
+                WrappedEvent.wrap(event, version, context=wrapped.context)
                 for version, event in enumerate(pending, start=start_from)
             ]
 
@@ -77,6 +78,6 @@ class Repository(Generic[TAggregate]):
 
             self._event_store.append(
                 *events,
-                stream_id=stream_id,
-                expected_version=old_version,
+                stream_id=wrapped.stream_id,
+                expected_version=wrapped.stored_version,
             )

{python_event_sourcery-0.5.2a0 → python_event_sourcery-0.5.3a0}/pyproject.toml

@@ -3,7 +3,7 @@ name = "python-event-sourcery"
 requires-python = ">=3.10"
 
 [tool.poetry]
-version = "0.5.2a0"
+version = "0.5.3a0"
 description = "A library for event-based systems in Python."
 readme = "README.md"
 authors = [

python_event_sourcery-0.5.2a0/event_sourcery/event_sourcing/aggregate.py

@@ -1,67 +0,0 @@
-from collections.abc import Iterator
-from contextlib import contextmanager
-from typing import ClassVar
-
-from event_sourcery import StreamCategory
-from event_sourcery.event import Event
-
-
-class Aggregate:
-    """
-    Base class for event-sourced aggregates.
-
-    Aggregates encapsulate domain logic and state changes as a sequence of events.
-    They are responsible for applying events to mutate their state and for emitting new
-    events that represent business-relevant changes.
-
-    The Aggregate base class provides mechanisms for tracking unpersisted changes and
-    for applying events in a consistent way.
-
-    Attributes:
-        category (ClassVar[StreamCategory]): StreamCategory for the aggregate type (group streams).
-        _changes (list[Event]): List of yet not persisted events.
-    """
-
-    category: ClassVar[StreamCategory]
-    _changes: list[Event]
-
-    @contextmanager
-    def __persisting_changes__(self) -> Iterator[Iterator[Event]]:
-        """
-        Context manager for accessing and clearing unpersisted events.
-
-        Yields an iterator over all events that have been applied but not yet persisted.
-        After exiting the context, the list of unpersisted events is cleared.
-
-        Returns:
-            Iterator[Iterator[Event]]: Iterator over unpersisted events.
-        """
-        yield iter(getattr(self, "_changes", []))
-        self._changes = []
-
-    def __apply__(self, event: Event) -> None:
-        """
-        Applies a single event to mutate the aggregate's state.
-
-        This method must be implemented by subclasses to define how each event type
-        changes the aggregate's state.
-
-        Args:
-            event (Event): The event to apply.
-        """
-        raise NotImplementedError
-
-    def _emit(self, event: Event) -> None:
-        """
-        Applies and tracks a new event as a pending change.
-
-        Calls __apply__ to mutate the aggregate's state and appends the event to the list
-        of unpersisted changes.
-
-        Args:
-            event (Event): The event to emit and track.
-        """
-        if not hasattr(self, "_changes"):
-            self._changes = []
-        self.__apply__(event)
-        self._changes.append(event)