eventsourcing 9.4.4__tar.gz → 9.4.6__tar.gz

{eventsourcing-9.4.4 → eventsourcing-9.4.6}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.3
 Name: eventsourcing
-Version: 9.4.4
+Version: 9.4.6
 Summary: Event sourcing in Python
 License: BSD-3-Clause
 Keywords: event sourcing,event store,domain driven design,domain-driven design,ddd,cqrs,cqs
@@ -54,6 +54,8 @@ experience. Please [read the docs](https://eventsourcing.readthedocs.io/). See a
 
 *"a huge help and time saver"*
 
+[![Ask DeepWiki](https://deepwiki.com/badge.svg)](https://deepwiki.com/pyeventsourcing/eventsourcing)
+
 
 ## Installation
 
@@ -75,40 +77,44 @@ from eventsourcing.domain import Aggregate, event
 
 class Dog(Aggregate):
     @event('Registered')
-    def __init__(self, name):
+    def __init__(self, name: str) -> None:
         self.name = name
-        self.tricks = []
+        self.tricks: list[str] = []
 
     @event('TrickAdded')
-    def add_trick(self, trick):
+    def add_trick(self, trick: str) -> None:
         self.tricks.append(trick)
 ```
 
 Define application objects with the `Application` class.
 
 ```python
+from typing import Any
+from uuid import UUID
+
 from eventsourcing.application import Application
 
-class DogSchool(Application):
-    def register_dog(self, name):
+
+class DogSchool(Application[UUID]):
+    def register_dog(self, name: str) -> UUID:
         dog = Dog(name)
         self.save(dog)
         return dog.id
 
-    def add_trick(self, dog_id, trick):
-        dog = self.repository.get(dog_id)
+    def add_trick(self, dog_id: UUID, trick: str) -> None:
+        dog: Dog = self.repository.get(dog_id)
         dog.add_trick(trick)
         self.save(dog)
 
-    def get_dog(self, dog_id):
-        dog = self.repository.get(dog_id)
+    def get_dog(self, dog_id: UUID) -> dict[str, Any]:
+        dog: Dog = self.repository.get(dog_id)
         return {'name': dog.name, 'tricks': tuple(dog.tricks)}
 ```
 
 Write a test.
 
 ```python
-def test_dog_school():
+def test_dog_school() -> None:
     # Construct application object.
     school = DogSchool()
 
@@ -140,7 +146,7 @@ Configure the application to run with an SQLite database. Other persistence modu
 import os
 
 os.environ["PERSISTENCE_MODULE"] = 'eventsourcing.sqlite'
-os.environ["SQLITE_DBNAME"] = 'dog-school.db'
+os.environ["SQLITE_DBNAME"] = ':memory:'
 ```
 
 Run the test with SQLite.

{eventsourcing-9.4.4 → eventsourcing-9.4.6}/README.md

@@ -19,6 +19,8 @@ experience. Please [read the docs](https://eventsourcing.readthedocs.io/). See a
 
 *"a huge help and time saver"*
 
+[![Ask DeepWiki](https://deepwiki.com/badge.svg)](https://deepwiki.com/pyeventsourcing/eventsourcing)
+
 
 ## Installation
 
@@ -40,40 +42,44 @@ from eventsourcing.domain import Aggregate, event
 
 class Dog(Aggregate):
     @event('Registered')
-    def __init__(self, name):
+    def __init__(self, name: str) -> None:
         self.name = name
-        self.tricks = []
+        self.tricks: list[str] = []
 
     @event('TrickAdded')
-    def add_trick(self, trick):
+    def add_trick(self, trick: str) -> None:
         self.tricks.append(trick)
 ```
 
 Define application objects with the `Application` class.
 
 ```python
+from typing import Any
+from uuid import UUID
+
 from eventsourcing.application import Application
 
-class DogSchool(Application):
-    def register_dog(self, name):
+
+class DogSchool(Application[UUID]):
+    def register_dog(self, name: str) -> UUID:
         dog = Dog(name)
         self.save(dog)
         return dog.id
 
-    def add_trick(self, dog_id, trick):
-        dog = self.repository.get(dog_id)
+    def add_trick(self, dog_id: UUID, trick: str) -> None:
+        dog: Dog = self.repository.get(dog_id)
         dog.add_trick(trick)
         self.save(dog)
 
-    def get_dog(self, dog_id):
-        dog = self.repository.get(dog_id)
+    def get_dog(self, dog_id: UUID) -> dict[str, Any]:
+        dog: Dog = self.repository.get(dog_id)
         return {'name': dog.name, 'tricks': tuple(dog.tricks)}
 ```
 
 Write a test.
 
 ```python
-def test_dog_school():
+def test_dog_school() -> None:
     # Construct application object.
     school = DogSchool()
 
@@ -105,7 +111,7 @@ Configure the application to run with an SQLite database. Other persistence modu
 import os
 
 os.environ["PERSISTENCE_MODULE"] = 'eventsourcing.sqlite'
-os.environ["SQLITE_DBNAME"] = 'dog-school.db'
+os.environ["SQLITE_DBNAME"] = ':memory:'
 ```
 
 Run the test with SQLite.

{eventsourcing-9.4.4 → eventsourcing-9.4.6}/eventsourcing/application.py

@@ -22,14 +22,15 @@ from warnings import warn
 
 from eventsourcing.domain import (
     Aggregate,
+    BaseAggregate,
     CanMutateProtocol,
     CollectEventsProtocol,
     DomainEventProtocol,
     EventSourcingError,
     MutableOrImmutableAggregate,
     SDomainEvent,
-    Snapshot,
     SnapshotProtocol,
+    TAggregateID,
     TDomainEvent,
     TMutableOrImmutableAggregate,
     datetime_now_with_tzinfo,
@@ -70,7 +71,7 @@ class ProgrammingError(Exception):
 
 def project_aggregate(
     aggregate: TMutableOrImmutableAggregate | None,
-    domain_events: Iterable[DomainEventProtocol],
+    domain_events: Iterable[DomainEventProtocol[Any]],
 ) -> TMutableOrImmutableAggregate | None:
     """Projector function for aggregate projections, which works
     by successively calling aggregate mutator function mutate()
@@ -199,7 +200,7 @@ class LRUCache(Cache[S, T]):
         return evicted_key, evicted_value
 
 
-class Repository:
+class Repository(Generic[TAggregateID]):
     """Reconstructs aggregates from events in an
     :class:`~eventsourcing.persistence.EventStore`,
     possibly using snapshot store to avoid replaying
@@ -210,9 +211,9 @@ class Repository:
 
     def __init__(
         self,
-        event_store: EventStore,
+        event_store: EventStore[TAggregateID],
         *,
-        snapshot_store: EventStore | None = None,
+        snapshot_store: EventStore[TAggregateID] | None = None,
         cache_maxsize: int | None = None,
         fastforward: bool = True,
         fastforward_skipping: bool = False,
@@ -225,11 +226,13 @@ class Repository:
         :class:`~eventsourcing.persistence.EventStore` for aggregate
         :class:`~eventsourcing.domain.Snapshot` objects).
         """
-        self.event_store = event_store
-        self.snapshot_store = snapshot_store
+        self.event_store: EventStore[TAggregateID] = event_store
+        self.snapshot_store: EventStore[TAggregateID] | None = snapshot_store
 
         if cache_maxsize is None:
-            self.cache: Cache[UUID, MutableOrImmutableAggregate] | None = None
+            self.cache: (
+                Cache[TAggregateID, MutableOrImmutableAggregate[TAggregateID]] | None
+            ) = None
         elif cache_maxsize <= 0:
             self.cache = Cache()
         else:
@@ -240,14 +243,14 @@ class Repository:
 
         # Because fast-forwarding a cached aggregate isn't thread-safe.
         self._fastforward_locks_lock = Lock()
-        self._fastforward_locks_cache: LRUCache[UUID, Lock] = LRUCache(
+        self._fastforward_locks_cache: LRUCache[TAggregateID, Lock] = LRUCache(
             maxsize=self.FASTFORWARD_LOCKS_CACHE_MAXSIZE
         )
-        self._fastforward_locks_inuse: dict[UUID, tuple[Lock, int]] = {}
+        self._fastforward_locks_inuse: dict[TAggregateID, tuple[Lock, int]] = {}
 
     def get(
         self,
-        aggregate_id: UUID,
+        aggregate_id: TAggregateID,
         *,
         version: int | None = None,
         projector_func: ProjectorFunction[
@@ -310,7 +313,7 @@ class Repository:
 
     def _reconstruct_aggregate(
         self,
-        aggregate_id: UUID,
+        aggregate_id: TAggregateID,
         version: int | None,
         projector_func: ProjectorFunction[TMutableOrImmutableAggregate, TDomainEvent],
     ) -> TMutableOrImmutableAggregate:
@@ -350,11 +353,12 @@ class Repository:
 
         # Raise exception if "not found".
         if aggregate is None:
-            raise AggregateNotFoundError((aggregate_id, version))
+            msg = f"Aggregate {aggregate_id!r} version {version!r} not found."
+            raise AggregateNotFoundError(msg)
         # Return the aggregate.
         return aggregate
 
-    def _use_fastforward_lock(self, aggregate_id: UUID) -> Lock:
+    def _use_fastforward_lock(self, aggregate_id: TAggregateID) -> Lock:
         lock: Lock | None = None
         with self._fastforward_locks_lock:
             num_users = 0
@@ -369,7 +373,7 @@ class Repository:
             self._fastforward_locks_inuse[aggregate_id] = (lock, num_users)
             return lock
 
-    def _disuse_fastforward_lock(self, aggregate_id: UUID) -> None:
+    def _disuse_fastforward_lock(self, aggregate_id: TAggregateID) -> None:
         with self._fastforward_locks_lock:
             lock_, num_users = self._fastforward_locks_inuse[aggregate_id]
             num_users -= 1
@@ -379,7 +383,7 @@ class Repository:
             else:
                 self._fastforward_locks_inuse[aggregate_id] = (lock_, num_users)
 
-    def __contains__(self, item: UUID) -> bool:
+    def __contains__(self, item: TAggregateID) -> bool:
         """Tests to see if an aggregate exists in the repository."""
         try:
             self.get(aggregate_id=item)
@@ -409,7 +413,7 @@ class Section:
     """
 
     id: str | None
-    items: list[Notification]
+    items: Sequence[Notification]
     next_id: str | None
 
 
@@ -432,7 +436,7 @@ class NotificationLog(ABC):
         topics: Sequence[str] = (),
         *,
         inclusive_of_start: bool = True,
-    ) -> list[Notification]:
+    ) -> Sequence[Notification]:
         """Returns a selection of
         :class:`~eventsourcing.persistence.Notification` objects
         from the notification log.
@@ -518,7 +522,7 @@ class LocalNotificationLog(NotificationLog):
         topics: Sequence[str] = (),
         *,
         inclusive_of_start: bool = True,
-    ) -> list[Notification]:
+    ) -> Sequence[Notification]:
         """Returns a selection of
         :class:`~eventsourcing.persistence.Notification` objects
         from the notification log.
@@ -541,7 +545,7 @@ class LocalNotificationLog(NotificationLog):
         return f"{first_id},{last_id}"
 
 
-class ProcessingEvent:
+class ProcessingEvent(Generic[TAggregateID]):
     """Keeps together a :class:`~eventsourcing.persistence.Tracking`
     object, which represents the position of a domain event notification
     in the notification log of a particular application, and the
@@ -551,13 +555,17 @@ class ProcessingEvent:
     def __init__(self, tracking: Tracking | None = None):
         """Initialises the process event with the given tracking object."""
         self.tracking = tracking
-        self.events: list[DomainEventProtocol] = []
-        self.aggregates: dict[UUID, MutableOrImmutableAggregate] = {}
+        self.events: list[DomainEventProtocol[TAggregateID]] = []
+        self.aggregates: dict[
+            TAggregateID, MutableOrImmutableAggregate[TAggregateID]
+        ] = {}
         self.saved_kwargs: dict[Any, Any] = {}
 
     def collect_events(
         self,
-        *objs: MutableOrImmutableAggregate | DomainEventProtocol | None,
+        *objs: MutableOrImmutableAggregate[TAggregateID]
+        | DomainEventProtocol[TAggregateID]
+        | None,
         **kwargs: Any,
     ) -> None:
         """Collects pending domain events from the given aggregate."""
@@ -576,7 +584,9 @@ class ProcessingEvent:
 
     def save(
         self,
-        *aggregates: MutableOrImmutableAggregate | DomainEventProtocol | None,
+        *aggregates: MutableOrImmutableAggregate[TAggregateID]
+        | DomainEventProtocol[TAggregateID]
+        | None,
         **kwargs: Any,
     ) -> None:
         warn(
@@ -588,17 +598,22 @@ class ProcessingEvent:
         self.collect_events(*aggregates, **kwargs)
 
 
-class Application:
+class Application(Generic[TAggregateID]):
     """Base class for event-sourced applications."""
 
     name = "Application"
     env: ClassVar[dict[str, str]] = {}
     is_snapshotting_enabled: bool = False
-    snapshotting_intervals: ClassVar[dict[type[MutableOrImmutableAggregate], int]] = {}
+    snapshotting_intervals: ClassVar[
+        dict[type[MutableOrImmutableAggregate[Any]], int]
+    ] = {}
     snapshotting_projectors: ClassVar[
-        dict[type[MutableOrImmutableAggregate], ProjectorFunction[Any, Any]]
+        dict[
+            type[MutableOrImmutableAggregate[Any]],
+            ProjectorFunction[Any, Any],
+        ]
     ] = {}
-    snapshot_class: type[SnapshotProtocol] = Snapshot
+    snapshot_class: type[SnapshotProtocol[TAggregateID]] | None = None
     log_section_size = 10
     notify_topics: Sequence[str] = []
 
@@ -622,18 +637,18 @@ class Application:
         """
         self.env = self.construct_env(self.name, env)  # type: ignore[misc]
         self.factory = self.construct_factory(self.env)
-        self.mapper = self.construct_mapper()
+        self.mapper: Mapper[TAggregateID] = self.construct_mapper()
         self.recorder = self.construct_recorder()
-        self.events = self.construct_event_store()
-        self.snapshots: EventStore | None = None
+        self.events: EventStore[TAggregateID] = self.construct_event_store()
+        self.snapshots: EventStore[TAggregateID] | None = None
         if self.factory.is_snapshotting_enabled():
             self.snapshots = self.construct_snapshot_store()
-        self._repository = self.construct_repository()
+        self._repository: Repository[TAggregateID] = self.construct_repository()
         self._notification_log = self.construct_notification_log()
         self.closing = Event()
 
     @property
-    def repository(self) -> Repository:
+    def repository(self) -> Repository[TAggregateID]:
         """An application's repository reconstructs aggregates from stored events."""
         return self._repository
 
@@ -670,7 +685,7 @@ class Application:
         """
         return InfrastructureFactory.construct(env)
 
-    def construct_mapper(self) -> Mapper:
+    def construct_mapper(self) -> Mapper[TAggregateID]:
         """Constructs a :class:`~eventsourcing.persistence.Mapper`
         for use by the application.
         """
@@ -699,7 +714,7 @@ class Application:
         """
         return self.factory.application_recorder()
 
-    def construct_event_store(self) -> EventStore:
+    def construct_event_store(self) -> EventStore[TAggregateID]:
         """Constructs an :class:`~eventsourcing.persistence.EventStore`
         for use by the application to store and retrieve aggregate
         :class:`~eventsourcing.domain.AggregateEvent` objects.
@@ -709,8 +724,8 @@ class Application:
             recorder=self.recorder,
         )
 
-    def construct_snapshot_store(self) -> EventStore:
-        """Constructs an :class:`~eventsourcing.persistence.EventStore`
+    def construct_snapshot_store(self) -> EventStore[TAggregateID]:
+        """Constructs an :py:class:`~eventsourcing.persistence.EventStore`
         for use by the application to store and retrieve aggregate
         :class:`~eventsourcing.domain.Snapshot` objects.
         """
@@ -720,8 +735,8 @@ class Application:
             recorder=recorder,
         )
 
-    def construct_repository(self) -> Repository:
-        """Constructs a :class:`Repository` for use by the application."""
+    def construct_repository(self) -> Repository[TAggregateID]:
+        """Constructs a :py:class:`Repository` for use by the application."""
         cache_maxsize_envvar = self.env.get(self.AGGREGATE_CACHE_MAXSIZE)
         cache_maxsize = int(cache_maxsize_envvar) if cache_maxsize_envvar else None
         return Repository(
@@ -743,13 +758,15 @@ class Application:
 
     def save(
         self,
-        *objs: MutableOrImmutableAggregate | DomainEventProtocol | None,
+        *objs: MutableOrImmutableAggregate[TAggregateID]
+        | DomainEventProtocol[TAggregateID]
+        | None,
         **kwargs: Any,
-    ) -> list[Recording]:
+    ) -> list[Recording[TAggregateID]]:
         """Collects pending events from given aggregates and
         puts them in the application's event store.
         """
-        processing_event = ProcessingEvent()
+        processing_event: ProcessingEvent[TAggregateID] = ProcessingEvent()
         processing_event.collect_events(*objs, **kwargs)
         recordings = self._record(processing_event)
         self._take_snapshots(processing_event)
@@ -757,7 +774,9 @@ class Application:
         self.notify(processing_event.events)  # Deprecated.
         return recordings
 
-    def _record(self, processing_event: ProcessingEvent) -> list[Recording]:
+    def _record(
+        self, processing_event: ProcessingEvent[TAggregateID]
+    ) -> list[Recording[TAggregateID]]:
         """Records given process event in the application's recorder."""
         recordings = self.events.put(
             processing_event.events,
@@ -769,7 +788,7 @@ class Application:
                 self.repository.cache.put(aggregate_id, aggregate)
         return recordings
 
-    def _take_snapshots(self, processing_event: ProcessingEvent) -> None:
+    def _take_snapshots(self, processing_event: ProcessingEvent[TAggregateID]) -> None:
         # Take snapshots using IDs and types.
         if self.snapshots and self.snapshotting_intervals:
             for event in processing_event.events:
@@ -782,22 +801,21 @@ class Application:
                     try:
                         projector_func = self.snapshotting_projectors[type(aggregate)]
                     except KeyError:
+                        if not isinstance(event, CanMutateProtocol):
+                            msg = (
+                                f"Cannot take snapshot for {type(aggregate)} with "
+                                "default project_aggregate() function, because its "
+                                f"domain event {type(event)} does not implement "
+                                "the 'can mutate' protocol (see CanMutateProtocol)."
+                                f" Please define application class {type(self)}"
+                                " with class variable 'snapshotting_projectors', "
+                                f"to be a dict that has {type(aggregate)} as a key "
+                                "with the aggregate projector function for "
+                                f"{type(aggregate)} as the value for that key."
+                            )
+                            raise ProgrammingError(msg) from None
+
                         projector_func = project_aggregate
-                    if projector_func is project_aggregate and not isinstance(
-                        event, CanMutateProtocol
-                    ):
-                        msg = (
-                            f"Cannot take snapshot for {type(aggregate)} with "
-                            "default project_aggregate() function, because its "
-                            f"domain event {type(event)} does not implement "
-                            "the 'can mutate' protocol (see CanMutateProtocol)."
-                            f" Please define application class {type(self)}"
-                            " with class variable 'snapshotting_projectors', "
-                            f"to be a dict that has {type(aggregate)} as a key "
-                            "with the aggregate projector function for "
-                            f"{type(aggregate)} as the value for that key."
-                        )
-                        raise ProgrammingError(msg)
                     self.take_snapshot(
                         aggregate_id=event.originator_id,
                         version=event.originator_version,
@@ -806,11 +824,9 @@ class Application:
 
     def take_snapshot(
         self,
-        aggregate_id: UUID,
+        aggregate_id: TAggregateID,
         version: int | None = None,
-        projector_func: ProjectorFunction[
-            TMutableOrImmutableAggregate, TDomainEvent
-        ] = project_aggregate,
+        projector_func: ProjectorFunction[Any, Any] = project_aggregate,
     ) -> None:
         """Takes a snapshot of the recorded state of the aggregate,
         and puts the snapshot in the snapshot store.
@@ -824,14 +840,22 @@ class Application:
                 "application class."
             )
             raise AssertionError(msg)
-        aggregate = self.repository.get(
+        aggregate: BaseAggregate[TAggregateID] = self.repository.get(
             aggregate_id, version=version, projector_func=projector_func
         )
         snapshot_class = getattr(type(aggregate), "Snapshot", type(self).snapshot_class)
+        if snapshot_class is None:
+            msg = (
+                "Neither application nor aggregate have a snapshot class. "
+                f"Please either define a nested 'Snapshot' class on {type(aggregate)} "
+                f"or set class attribute 'snapshot_class' on {type(self)}."
+            )
+            raise AssertionError(msg)
+
         snapshot = snapshot_class.take(aggregate)
         self.snapshots.put([snapshot])
 
-    def notify(self, new_events: list[DomainEventProtocol]) -> None:
+    def notify(self, new_events: list[DomainEventProtocol[TAggregateID]]) -> None:
         """Deprecated.
 
         Called after new aggregate events have been saved. This
@@ -840,7 +864,7 @@ class Application:
         need to take action when new domain events have been saved.
         """
 
-    def _notify(self, recordings: list[Recording]) -> None:
+    def _notify(self, recordings: list[Recording[TAggregateID]]) -> None:
         """Called after new aggregate events have been saved. This
         method on this class doesn't actually do anything,
         but this method may be implemented by subclasses that
@@ -852,7 +876,7 @@ class Application:
         self.factory.close()
 
 
-TApplication = TypeVar("TApplication", bound=Application)
+TApplication = TypeVar("TApplication", bound=Application[Any])
 
 
 class AggregateNotFoundError(EventSourcingError):
@@ -877,7 +901,7 @@ class EventSourcedLog(Generic[TDomainEvent]):
 
     def __init__(
         self,
-        events: EventStore,
+        events: EventStore[Any],
         originator_id: UUID,
         logged_cls: type[TDomainEvent],  # TODO: Rename to 'event_class' in v10.
     ):