python-event-sourcery 0.4.0a3__tar.gz → 0.4.0a5__tar.gz

{python_event_sourcery-0.4.0a3 → python_event_sourcery-0.4.0a5}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: python-event-sourcery
-Version: 0.4.0a3
+Version: 0.4.0a5
 Summary: 
 License: MIT
 Author: Your Name

{python_event_sourcery-0.4.0a3 → python_event_sourcery-0.4.0a5}/event_sourcery/aggregate/repository.py

@@ -3,7 +3,13 @@ from contextlib import contextmanager
 from typing import Generic, TypeVar, cast
 
 from event_sourcery.aggregate import Aggregate
-from event_sourcery.event_store import Event, EventStore, Metadata, StreamId, StreamUUID
+from event_sourcery.event_store import (
+    Event,
+    EventStore,
+    StreamId,
+    StreamUUID,
+    WrappedEvent,
+)
 
 TAggregate = TypeVar("TAggregate", bound=Aggregate)
 TEvent = TypeVar("TEvent", bound=Event)
@@ -42,14 +48,14 @@ class Repository(Generic[TAggregate]):
         with aggregate.__persisting_changes__() as pending:
             start_from = old_version + 1
             events = [
-                Metadata.wrap(event, version)
+                WrappedEvent.wrap(event, version)
                 for version, event in enumerate(pending, start=start_from)
             ]
 
             if not events:
                 return
 
-            self._event_store.publish(
+            self._event_store.append(
                 *events,
                 stream_id=stream_id,
                 expected_version=old_version,

{python_event_sourcery-0.4.0a3 → python_event_sourcery-0.4.0a5}/event_sourcery/event_store/__init__.py

@@ -9,7 +9,7 @@ __all__ = [
     "ExplicitVersioning",
     "InMemoryBackendFactory",
     "Listener",
-    "Metadata",
+    "WrappedEvent",
     "NO_VERSIONING",
     "Position",
     "RawEvent",
@@ -31,11 +31,11 @@ from event_sourcery.event_store.event import (
     Entry,
     Event,
     EventRegistry,
-    Metadata,
     Position,
     RawEvent,
     Recorded,
     RecordedRaw,
+    WrappedEvent,
 )
 from event_sourcery.event_store.event_store import EventStore
 from event_sourcery.event_store.factory import (

{python_event_sourcery-0.4.0a3 → python_event_sourcery-0.4.0a5}/event_sourcery/event_store/dispatcher.py

@@ -3,14 +3,14 @@ from collections.abc import Callable
 
 from event_sourcery.event_store.event import (
     Event,
-    Metadata,
     Position,
     RecordedRaw,
     Serde,
+    WrappedEvent,
 )
 from event_sourcery.event_store.stream_id import StreamId
 
-Listener = Callable[[Metadata, StreamId, Position | None], None]
+Listener = Callable[[WrappedEvent, StreamId, Position | None], None]
 
 
 class Dispatcher:
@@ -22,10 +22,10 @@ class Dispatcher:
         for raw in raws:
             record = self._serde.deserialize_record(raw)
             for event_type, listeners in self._listeners.items():
-                if not isinstance(record.metadata.event, event_type):
+                if not isinstance(record.wrapped_event.event, event_type):
                     continue
                 for listener in listeners:
-                    listener(record.metadata, record.stream_id, record.position)
+                    listener(record.wrapped_event, record.stream_id, record.position)
 
     def register(self, listener: Listener, to: type[Event]) -> None:
         self._listeners[to].add(listener)

{python_event_sourcery-0.4.0a3 → python_event_sourcery-0.4.0a5}/event_sourcery/event_store/event/__init__.py

@@ -3,7 +3,7 @@ __all__ = [
     "Entry",
     "Event",
     "EventRegistry",
-    "Metadata",
+    "WrappedEvent",
     "Position",
     "RawEvent",
     "Recorded",
@@ -16,11 +16,11 @@ from event_sourcery.event_store.event.dto import (
     Context,
     Entry,
     Event,
-    Metadata,
     Position,
     RawEvent,
     Recorded,
     RecordedRaw,
+    WrappedEvent,
 )
 from event_sourcery.event_store.event.registry import EventRegistry
 from event_sourcery.event_store.event.serde import Serde

{python_event_sourcery-0.4.0a3 → python_event_sourcery-0.4.0a5}/event_sourcery/event_store/event/dto.py

@@ -27,6 +27,15 @@ class RecordedRaw(BaseModel):
 
 
 class Event(BaseModel, extra="forbid"):
+    """Base class for all events.
+
+    Example usage:
+    ```
+    class OrderCancelled(Event):
+        order_id: OrderId
+    ```
+    """
+
     __registry__: ClassVar = EventRegistry()
 
     def __init_subclass__(cls, **kwargs: Any) -> None:
@@ -41,7 +50,21 @@ class Context(BaseModel, extra="allow"):
     causation_id: UUID | None = None
 
 
-class Metadata(BaseModel, Generic[TEvent], extra="forbid"):
+class WrappedEvent(BaseModel, Generic[TEvent], extra="forbid"):
+    """Wrapper for events with all relevant metadata.
+
+    Returned from EventStore when loading events from a stream.
+
+    Example usage:
+    ```
+    class OrderCancelled(Event):
+        order_id: OrderId
+
+    event = OrderCancelled(order_id=OrderId("#123"))
+    wrapped_event = WrappedEvent.wrap(event, version=1)
+    ```
+    """
+
     event: TEvent
     version: int | None
     uuid: UUID = Field(default_factory=uuid4)
@@ -49,12 +72,12 @@ class Metadata(BaseModel, Generic[TEvent], extra="forbid"):
     context: Context = Field(default_factory=Context)
 
     @classmethod
-    def wrap(cls, event: TEvent, version: int | None) -> "Metadata[TEvent]":
-        return Metadata[TEvent](event=event, version=version)
+    def wrap(cls, event: TEvent, version: int | None) -> "WrappedEvent[TEvent]":
+        return WrappedEvent[TEvent](event=event, version=version)
 
 
 class Entry(BaseModel):
-    metadata: Metadata
+    wrapped_event: WrappedEvent
     stream_id: StreamId
 
 

{python_event_sourcery-0.4.0a3 → python_event_sourcery-0.4.0a5}/event_sourcery/event_store/event/registry.py

@@ -18,11 +18,18 @@ def event_name(cls: type) -> str:
 
 
 class EventRegistry:
+    """Keeps mappings between event types and their names.
+
+    Normally, there is no need to use it directly. If one needs to have multiple
+    registries or wants more granular control, they can pass an instance
+    of EventRegistry to BackendFactory."""
+
     def __init__(self) -> None:
         self._types_to_names: dict[type[Event], str] = {}
         self._names_to_types: dict[str, type[Event]] = {}
 
     def add(self, event: type["Event"]) -> type["Event"]:
+        """Add event subclass to the registry."""
         if event in self._types_to_names:
             raise DuplicatedEvent(f"Duplicated Event detected! {event}")
 

{python_event_sourcery-0.4.0a3 → python_event_sourcery-0.4.0a5}/event_sourcery/event_store/event/serde.py

@@ -4,10 +4,10 @@ from typing import cast
 
 from event_sourcery.event_store.event.dto import (
     Event,
-    Metadata,
     RawEvent,
     Recorded,
     RecordedRaw,
+    WrappedEvent,
 )
 from event_sourcery.event_store.event.registry import EventRegistry
 from event_sourcery.event_store.stream_id import StreamId
@@ -17,27 +17,27 @@ from event_sourcery.event_store.stream_id import StreamId
 class Serde:
     registry: EventRegistry
 
-    def deserialize(self, event: RawEvent) -> Metadata:
+    def deserialize(self, event: RawEvent) -> WrappedEvent:
         event_as_dict = dict(event)
         del event_as_dict["stream_id"]
         del event_as_dict["name"]
         data = cast(Mapping, event_as_dict.pop("data"))
         event_type = self.registry.type_for_name(event.name)
-        return Metadata[event_type](  # type: ignore
+        return WrappedEvent[event_type](  # type: ignore
             **event_as_dict,
             event=event_type(**data),
         )
 
     def deserialize_record(self, record: RecordedRaw) -> Recorded:
         return Recorded(
-            metadata=self.deserialize(record.entry),
+            wrapped_event=self.deserialize(record.entry),
             stream_id=record.entry.stream_id,
             position=record.position,
         )
 
     def serialize(
         self,
-        event: Metadata,
+        event: WrappedEvent,
         stream_id: StreamId,
     ) -> RawEvent:
         model = cast(Event, event.event)

python_event_sourcery-0.4.0a5/event_sourcery/event_store/event_store.py

@@ -0,0 +1,202 @@
+from collections.abc import Sequence
+from functools import singledispatchmethod
+from typing import cast
+
+from event_sourcery.event_store.event import (
+    Event,
+    Position,
+    RawEvent,
+    Serde,
+    WrappedEvent,
+)
+from event_sourcery.event_store.interfaces import StorageStrategy
+from event_sourcery.event_store.stream_id import StreamId
+from event_sourcery.event_store.versioning import (
+    NO_VERSIONING,
+    ExplicitVersioning,
+    Versioning,
+)
+
+
+class EventStore:
+    """API for working with events."""
+
+    def __init__(self, storage_strategy: StorageStrategy, serde: Serde) -> None:
+        self._storage_strategy = storage_strategy
+        self._serde = serde
+
+    def load_stream(
+        self,
+        stream_id: StreamId,
+        start: int | None = None,
+        stop: int | None = None,
+    ) -> Sequence[WrappedEvent]:
+        """Loads events from a given stream.
+
+        Examples:
+            >>> load_stream(stream_id=StreamId(name="not_existing_stream"))
+            []
+            >>> load_stream(stream_id=StreamId(name="existing_stream"))
+            [WrappedEvent(..., version=1), ..., WrappedEvent(..., version=3)]
+            >>> load_stream(stream_id=StreamId(name="existing_stream"), start=2, stop=3)
+            [WrappedEvent(..., version=2)]
+
+        Args:
+            stream_id: The stream identifier to load events from.
+            start: The stream version to start loading from (including).
+            stop: The stream version to stop loading at (excluding).
+
+        Returns:
+            A sequence of events or empty list if the stream doesn't exist.
+        """
+        events = self._storage_strategy.fetch_events(stream_id, start=start, stop=stop)
+        return self._deserialize_events(events)
+
+    @singledispatchmethod
+    def append(
+        self,
+        first: WrappedEvent,
+        *events: WrappedEvent,
+        stream_id: StreamId,
+        expected_version: int | Versioning = 0,
+    ) -> None:
+        """Appends events to a stream with a given ID.
+
+        Implements optimistic locking to ensure stream wasn't modified since last read.
+        To use it, pass the expected version of the stream.
+
+        Examples:
+            >>> append(WrappedEvent(...), stream_id=StreamId())
+            None
+            >>> append(WrappedEvent(...), stream_id=StreamId(), expected_version=1)
+            None
+
+        Args:
+            first: The first event to append (WrappedEvent or Event).
+            *events: The rest of the events to append (same type as first argument).
+            stream_id: The stream identifier to append events to.
+            expected_version: The expected version of the stream
+
+        Returns:
+            None
+        """
+        self._append(
+            stream_id=stream_id,
+            events=(first, *events),
+            expected_version=expected_version,
+        )
+
+    @append.register
+    def _append_events(
+        self,
+        *events: Event,
+        stream_id: StreamId,
+        expected_version: int | Versioning = 0,
+    ) -> None:
+        wrapped_events = self._wrap_events(expected_version, events)
+        self.append(
+            *wrapped_events,
+            stream_id=stream_id,
+            expected_version=expected_version,
+        )
+
+    @singledispatchmethod
+    def _wrap_events(
+        self,
+        expected_version: int,
+        events: Sequence[Event],
+    ) -> Sequence[WrappedEvent]:
+        return [
+            WrappedEvent.wrap(event=event, version=version)
+            for version, event in enumerate(events, start=expected_version + 1)
+        ]
+
+    @_wrap_events.register
+    def _wrap_events_versioning(
+        self, expected_version: Versioning, events: Sequence[Event]
+    ) -> Sequence[WrappedEvent]:
+        return [WrappedEvent.wrap(event=event, version=None) for event in events]
+
+    def _append(
+        self,
+        stream_id: StreamId,
+        events: Sequence[WrappedEvent],
+        expected_version: int | Versioning,
+    ) -> None:
+        new_version = events[-1].version
+        versioning: Versioning
+        if expected_version is not NO_VERSIONING:
+            versioning = ExplicitVersioning(
+                expected_version=cast(int, expected_version),
+                initial_version=cast(int, new_version),
+            )
+        else:
+            versioning = NO_VERSIONING
+
+        self._storage_strategy.insert_events(
+            stream_id=stream_id,
+            versioning=versioning,
+            events=self._serialize_events(events, stream_id),
+        )
+
+    def delete_stream(self, stream_id: StreamId) -> None:
+        """Deletes a stream with a given ID.
+
+        If a stream does not exist, this method does nothing.
+
+        Examples:
+            >>> delete_stream(StreamId())
+            None
+            >>> delete_stream(StreamId(name="not_existing_stream"))
+            None
+
+        Args:
+            stream_id: The stream identifier to delete.
+
+        Returns:
+            None
+        """
+        self._storage_strategy.delete_stream(stream_id)
+
+    def save_snapshot(self, stream_id: StreamId, snapshot: WrappedEvent) -> None:
+        """Saves a snapshot of the stream.
+
+        Examples:
+            >>> save_snapshot(StreamId(), WrappedEvent(...))
+            None
+            >>> save_snapshot(StreamId(name="not_existing_stream"), WrappedEvent(...))
+            None
+
+        Args:
+            stream_id: The stream identifier to save the snapshot.
+            snapshot: The snapshot to save.
+
+        Returns:
+            None
+        """
+
+        serialized = self._serde.serialize(event=snapshot, stream_id=stream_id)
+        self._storage_strategy.save_snapshot(serialized)
+
+    def _deserialize_events(self, events: list[RawEvent]) -> list[WrappedEvent]:
+        return [self._serde.deserialize(e) for e in events]
+
+    def _serialize_events(
+        self,
+        events: Sequence[WrappedEvent],
+        stream_id: StreamId,
+    ) -> list[RawEvent]:
+        return [self._serde.serialize(event=e, stream_id=stream_id) for e in events]
+
+    @property
+    def position(self) -> Position | None:
+        """Returns the current position of the event store.
+
+        Examples:
+            >>> position
+            None  # nothing was saved yet
+            >>> position
+            Position(15)  # Some events were saved
+
+        """
+        return self._storage_strategy.current_position

{python_event_sourcery-0.4.0a3 → python_event_sourcery-0.4.0a5}/event_sourcery/event_store/factory.py

@@ -38,6 +38,8 @@ class TransactionalBackend(Backend):
 
 
 class BackendFactory(abc.ABC):
+    """Abstract base class to configure EventStore."""
+
     @abc.abstractmethod
     def build(self) -> Backend:
         pass

{python_event_sourcery-0.4.0a3 → python_event_sourcery-0.4.0a5}/event_sourcery/event_store/in_memory.py

@@ -298,6 +298,8 @@ class Config(BaseModel):
 
 @dataclass(repr=False)
 class InMemoryBackendFactory(BackendFactory):
+    """Lightweight in-memory backend factory for testing and development."""
+
     serde = Serde(Event.__registry__)
 
     _config: Config = field(default_factory=Config)

{python_event_sourcery-0.4.0a3 → python_event_sourcery-0.4.0a5}/event_sourcery/event_store/outbox.py

@@ -19,7 +19,7 @@ class Outbox:
             with entry as raw_record:
                 event = self._serde.deserialize(raw_record.entry)
                 record = Recorded(
-                    metadata=event,
+                    wrapped_event=event,
                     stream_id=raw_record.entry.stream_id,
                     position=raw_record.position,
                 )

{python_event_sourcery-0.4.0a3 → python_event_sourcery-0.4.0a5}/event_sourcery/read_model/projector.py

@@ -1,10 +1,10 @@
 from collections.abc import Callable
 from typing import TypeAlias
 
-from event_sourcery.event_store import Event, EventStore, Metadata, StreamId
+from event_sourcery.event_store import Event, EventStore, StreamId, WrappedEvent
 from event_sourcery.read_model.cursors_dao import CursorsDao
 
-ReadModel: TypeAlias = Callable[[Metadata, StreamId], None]
+ReadModel: TypeAlias = Callable[[WrappedEvent, StreamId], None]
 
 
 class Projector:
@@ -23,38 +23,38 @@ class Projector:
         self._cursors_dao = cursors_dao
         self._read_model = read_model
 
-    def project(self, metadata: Metadata[Event], stream_id: StreamId) -> None:
-        if metadata.version is None:
+    def project(self, wrapped_event: WrappedEvent[Event], stream_id: StreamId) -> None:
+        if wrapped_event.version is None:
             raise self.CantProjectUnversionedEvent
 
         try:
             self._cursors_dao.increment(
-                name=self._name, stream_id=stream_id, version=metadata.version
+                name=self._name, stream_id=stream_id, version=wrapped_event.version
             )
-            self._read_model(metadata, stream_id)
+            self._read_model(wrapped_event, stream_id)
         except self._cursors_dao.StreamNotTracked:
             self._cursors_dao.put_at(
-                name=self._name, stream_id=stream_id, version=metadata.version
+                name=self._name, stream_id=stream_id, version=wrapped_event.version
             )
             missed_events = self._event_store.load_stream(
-                stream_id=stream_id, stop=metadata.version
+                stream_id=stream_id, stop=wrapped_event.version
             )
             for event in missed_events:
                 self._read_model(event, stream_id)
 
-            self._read_model(metadata, stream_id)
+            self._read_model(wrapped_event, stream_id)
         except self._cursors_dao.BehindStream as exc:
             self._cursors_dao.move_to(
-                name=self._name, stream_id=stream_id, version=metadata.version
+                name=self._name, stream_id=stream_id, version=wrapped_event.version
             )
             missed_events = self._event_store.load_stream(
                 stream_id=stream_id,
                 start=exc.current_version + 1,
-                stop=metadata.version,
+                stop=wrapped_event.version,
             )
             for event in missed_events:
                 self._read_model(event, stream_id)
 
-            self._read_model(metadata, stream_id)
+            self._read_model(wrapped_event, stream_id)
         except self._cursors_dao.AheadOfStream:
             return

{python_event_sourcery-0.4.0a3 → python_event_sourcery-0.4.0a5}/event_sourcery_sqlalchemy/cursors_dao.py

@@ -38,7 +38,7 @@ class SqlAlchemyCursorsDao(CursorsDao):
             .values({ProjectorCursor.version: version})
         )
         result = self._session.execute(update_stmt)
-        if result.rowcount == 1:  # type: ignore
+        if result.rowcount == 1:
             return
         else:
             current_version = self._current_version(name, stream_id)

{python_event_sourcery-0.4.0a3 → python_event_sourcery-0.4.0a5}/event_sourcery_sqlalchemy/event_store.py

@@ -155,7 +155,7 @@ class SqlAlchemyStorageStrategy(StorageStrategy):
             )
             result = self._session.execute(bump_version_stmt)
 
-            if result.rowcount != 1:  # type: ignore
+            if result.rowcount != 1:
                 # optimistic lock failed
                 raise ConcurrentStreamWriteError
 

{python_event_sourcery-0.4.0a3 → python_event_sourcery-0.4.0a5}/pyproject.toml

@@ -1,6 +1,6 @@
 [tool.poetry]
 name = "python-event-sourcery"
-version = "0.4.0a3"
+version = "0.4.0a5"
 description = ""
 authors = ["Your Name <you@example.com>"]
 license = "MIT"
@@ -26,6 +26,7 @@ pytest-cov = "*"
 pytest-django = {version = "*"}
 mkdocs-material = "^8.3.9"
 psycopg2-binary = "^2.9.3"
+mkdocstrings = {version = "*", extras = ["python"]}
 
 [tool.poetry.extras]
 sqlalchemy = ["SQLAlchemy"]

python_event_sourcery-0.4.0a3/event_sourcery/event_store/event_store.py

@@ -1,129 +0,0 @@
-from collections.abc import Sequence
-from functools import singledispatchmethod
-from typing import cast
-
-from event_sourcery.event_store.event import Event, Metadata, Position, RawEvent, Serde
-from event_sourcery.event_store.interfaces import StorageStrategy
-from event_sourcery.event_store.stream_id import StreamId
-from event_sourcery.event_store.versioning import (
-    NO_VERSIONING,
-    ExplicitVersioning,
-    Versioning,
-)
-
-
-class EventStore:
-    def __init__(self, storage_strategy: StorageStrategy, serde: Serde) -> None:
-        self._storage_strategy = storage_strategy
-        self._serde = serde
-
-    def load_stream(
-        self,
-        stream_id: StreamId,
-        start: int | None = None,
-        stop: int | None = None,
-    ) -> Sequence[Metadata]:
-        events = self._storage_strategy.fetch_events(stream_id, start=start, stop=stop)
-        return self._deserialize_events(events)
-
-    @singledispatchmethod
-    def append(
-        self,
-        first: Metadata,
-        *events: Metadata,
-        stream_id: StreamId,
-        expected_version: int | Versioning = 0,
-    ) -> None:
-        self._append(
-            stream_id=stream_id,
-            events=(first, *events),
-            expected_version=expected_version,
-        )
-
-    @append.register
-    def _append_events(
-        self,
-        *events: Event,
-        stream_id: StreamId,
-        expected_version: int | Versioning = 0,
-    ) -> None:
-        wrapped_events = self._wrap_events(expected_version, events)
-        self.append(
-            *wrapped_events,
-            stream_id=stream_id,
-            expected_version=expected_version,
-        )
-
-    @singledispatchmethod
-    def _wrap_events(
-        self,
-        expected_version: int,
-        events: Sequence[Event],
-    ) -> Sequence[Metadata]:
-        return [
-            Metadata.wrap(event=event, version=version)
-            for version, event in enumerate(events, start=expected_version + 1)
-        ]
-
-    @_wrap_events.register
-    def _wrap_events_versioning(
-        self, expected_version: Versioning, events: Sequence[Event]
-    ) -> Sequence[Metadata]:
-        return [Metadata.wrap(event=event, version=None) for event in events]
-
-    @singledispatchmethod
-    def publish(
-        self,
-        first: Metadata,
-        *events: Metadata,
-        stream_id: StreamId,
-        expected_version: int | Versioning = 0,
-    ) -> None:
-        self._append(
-            stream_id=stream_id,
-            events=(first, *events),
-            expected_version=expected_version,
-        )
-
-    def _append(
-        self,
-        stream_id: StreamId,
-        events: Sequence[Metadata],
-        expected_version: int | Versioning,
-    ) -> None:
-        new_version = events[-1].version
-        versioning: Versioning
-        if expected_version is not NO_VERSIONING:
-            versioning = ExplicitVersioning(
-                expected_version=cast(int, expected_version),
-                initial_version=cast(int, new_version),
-            )
-        else:
-            versioning = NO_VERSIONING
-
-        self._storage_strategy.insert_events(
-            stream_id=stream_id,
-            versioning=versioning,
-            events=self._serialize_events(events, stream_id),
-        )
-
-    def delete_stream(self, stream_id: StreamId) -> None:
-        self._storage_strategy.delete_stream(stream_id)
-
-    def save_snapshot(self, stream_id: StreamId, snapshot: Metadata) -> None:
-        serialized = self._serde.serialize(event=snapshot, stream_id=stream_id)
-        self._storage_strategy.save_snapshot(serialized)
-
-    def _deserialize_events(self, events: list[RawEvent]) -> list[Metadata]:
-        return [self._serde.deserialize(e) for e in events]
-
-    def _serialize_events(
-        self,
-        events: Sequence[Metadata],
-        stream_id: StreamId,
-    ) -> list[RawEvent]:
-        return [self._serde.serialize(event=e, stream_id=stream_id) for e in events]
-
-    @property
-    def position(self) -> Position | None:
-        return self._storage_strategy.current_position