eventsourcing 9.2.21__py3-none-any.whl → 9.3.0__py3-none-any.whl

eventsourcing/__init__.py

@@ -1 +1 @@
-__version__ = "9.2.21"
+__version__ = "9.3.0dev0"

eventsourcing/application.py

@@ -1,3 +1,5 @@
+from __future__ import annotations
+
 import os
 from abc import ABC, abstractmethod
 from copy import deepcopy
@@ -5,8 +7,10 @@ from dataclasses import dataclass
 from itertools import chain
 from threading import Event, Lock
 from typing import (
+    TYPE_CHECKING,
     Any,
     Callable,
+    ClassVar,
     Dict,
     Generic,
     Iterable,
@@ -17,16 +21,10 @@ from typing import (
     Tuple,
     Type,
     TypeVar,
-    Union,
     cast,
 )
-from uuid import UUID
 from warnings import warn
 
-# For backwards compatibility of import statements...
-from eventsourcing.domain import LogEvent  # noqa: F401
-from eventsourcing.domain import TLogEvent  # noqa: F401
-from eventsourcing.domain import create_utc_datetime_now  # noqa: F401
 from eventsourcing.domain import (
     Aggregate,
     CanMutateProtocol,
@@ -39,6 +37,7 @@ from eventsourcing.domain import (
     SnapshotProtocol,
     TDomainEvent,
     TMutableOrImmutableAggregate,
+    create_utc_datetime_now,
 )
 from eventsourcing.persistence import (
     ApplicationRecorder,
@@ -55,6 +54,9 @@ from eventsourcing.persistence import (
 )
 from eventsourcing.utils import Environment, EnvType, strtobool
 
+if TYPE_CHECKING:  # pragma: nocover
+    from uuid import UUID
+
 ProjectorFunction = Callable[
     [Optional[TMutableOrImmutableAggregate], Iterable[TDomainEvent]],
     Optional[TMutableOrImmutableAggregate],
@@ -67,9 +69,9 @@ MutatorFunction = Callable[
 
 
 def project_aggregate(
-    aggregate: Optional[TMutableOrImmutableAggregate],
+    aggregate: TMutableOrImmutableAggregate | None,
     domain_events: Iterable[DomainEventProtocol],
-) -> Optional[TMutableOrImmutableAggregate]:
+) -> TMutableOrImmutableAggregate | None:
     """
     Projector function for aggregate projections, which works
     by successively calling aggregate mutator function mutate()
@@ -89,13 +91,12 @@ class Cache(Generic[S, T]):
     def __init__(self) -> None:
         self.cache: Dict[S, Any] = {}
 
-    def get(self, key: S, evict: bool = False) -> T:
+    def get(self, key: S, *, evict: bool = False) -> T:
         if evict:
             return self.cache.pop(key)
-        else:
-            return self.cache[key]
+        return self.cache[key]
 
-    def put(self, key: S, value: T) -> Optional[T]:
+    def put(self, key: S, value: T) -> T | None:
         if value is not None:
             self.cache[key] = value
         return None
@@ -130,7 +131,7 @@ class LRUCache(Cache[S, T]):
             None,
         ]  # initialize by pointing to self
 
-    def get(self, key: S, evict: bool = False) -> T:
+    def get(self, key: S, *, evict: bool = False) -> T:
         with self.lock:
             link = self.cache.get(key)
             if link is not None:
@@ -151,10 +152,9 @@ class LRUCache(Cache[S, T]):
                     self.full = self.cache.__len__() >= self.maxsize
 
                 return result
-            else:
-                raise KeyError
+            raise KeyError
 
-    def put(self, key: S, value: T) -> Optional[Any]:
+    def put(self, key: S, value: T) -> Any | None:
         evicted_key = None
         evicted_value = None
         with self.lock:
@@ -213,8 +213,9 @@ class Repository:
     def __init__(
         self,
         event_store: EventStore,
-        snapshot_store: Optional[EventStore] = None,
-        cache_maxsize: Optional[int] = None,
+        *,
+        snapshot_store: EventStore | None = None,
+        cache_maxsize: int | None = None,
         fastforward: bool = True,
         fastforward_skipping: bool = False,
         deepcopy_from_cache: bool = True,
@@ -231,7 +232,7 @@ class Repository:
         self.snapshot_store = snapshot_store
 
         if cache_maxsize is None:
-            self.cache: Optional[Cache[UUID, MutableOrImmutableAggregate]] = None
+            self.cache: Cache[UUID, MutableOrImmutableAggregate] | None = None
         elif cache_maxsize <= 0:
             self.cache = Cache()
         else:
@@ -250,7 +251,8 @@ class Repository:
     def get(
         self,
         aggregate_id: UUID,
-        version: Optional[int] = None,
+        *,
+        version: int | None = None,
         projector_func: ProjectorFunction[
             TMutableOrImmutableAggregate, TDomainEvent
         ] = project_aggregate,
@@ -289,9 +291,8 @@ class Repository:
                                     aggregate, cast(Iterable[TDomainEvent], new_events)
                                 )
                                 if _aggregate is None:
-                                    raise AggregateNotFound(aggregate_id)
-                                else:
-                                    aggregate = _aggregate
+                                    raise AggregateNotFoundError(aggregate_id)
+                                aggregate = _aggregate
                             finally:
                                 fastforward_lock.release()
                     finally:
@@ -310,10 +311,10 @@ class Repository:
     def _reconstruct_aggregate(
         self,
         aggregate_id: UUID,
-        version: Optional[int],
+        version: int | None,
         projector_func: ProjectorFunction[TMutableOrImmutableAggregate, TDomainEvent],
     ) -> TMutableOrImmutableAggregate:
-        gt: Optional[int] = None
+        gt: int | None = None
 
         if self.snapshot_store is not None:
             # Try to get a snapshot.
@@ -338,7 +339,7 @@ class Repository:
         )
 
         # Reconstruct the aggregate from its events.
-        initial: Optional[TMutableOrImmutableAggregate] = None
+        initial: TMutableOrImmutableAggregate | None = None
         aggregate = projector_func(
             initial,
             chain(
@@ -349,10 +350,9 @@ class Repository:
 
         # Raise exception if "not found".
         if aggregate is None:
-            raise AggregateNotFound((aggregate_id, version))
-        else:
-            # Return the aggregate.
-            return aggregate
+            raise AggregateNotFoundError((aggregate_id, version))
+        # Return the aggregate.
+        return aggregate
 
     def _use_fastforward_lock(self, aggregate_id: UUID) -> Lock:
         with self._fastforward_locks_lock:
@@ -386,7 +386,7 @@ class Repository:
         """
         try:
             self.get(aggregate_id=item)
-        except AggregateNotFound:
+        except AggregateNotFoundError:
             return False
         else:
             return True
@@ -412,9 +412,9 @@ class Section:
     :param Optional[str] next_id: section ID of the following section
     """
 
-    id: Optional[str]
+    id: str | None
     items: List[Notification]
-    next_id: Optional[str]
+    next_id: str | None
 
 
 class NotificationLog(ABC):
@@ -435,7 +435,7 @@ class NotificationLog(ABC):
         self,
         start: int,
         limit: int,
-        stop: Optional[int] = None,
+        stop: int | None = None,
         topics: Sequence[str] = (),
     ) -> List[Notification]:
         """
@@ -495,8 +495,8 @@ class LocalNotificationLog(NotificationLog):
         notifications = self.select(start, limit)
 
         # Get next section ID.
-        actual_section_id: Optional[str]
-        next_id: Optional[str]
+        actual_section_id: str | None
+        next_id: str | None
         if len(notifications):
             last_notification_id = notifications[-1].id
             actual_section_id = self.format_section_id(
@@ -523,7 +523,7 @@ class LocalNotificationLog(NotificationLog):
         self,
         start: int,
         limit: int,
-        stop: Optional[int] = None,
+        stop: int | None = None,
         topics: Sequence[str] = (),
     ) -> List[Notification]:
         """
@@ -532,16 +532,17 @@ class LocalNotificationLog(NotificationLog):
         from the notification log.
         """
         if limit > self.section_size:
-            raise ValueError(
+            msg = (
                 f"Requested limit {limit} greater than section size {self.section_size}"
             )
+            raise ValueError(msg)
         return self.recorder.select_notifications(
             start=start, limit=limit, stop=stop, topics=topics
         )
 
     @staticmethod
     def format_section_id(first_id: int, last_id: int) -> str:
-        return "{},{}".format(first_id, last_id)
+        return f"{first_id},{last_id}"
 
 
 class ProcessingEvent:
@@ -552,7 +553,7 @@ class ProcessingEvent:
     new domain events that result from processing that notification.
     """
 
-    def __init__(self, tracking: Optional[Tracking] = None):
+    def __init__(self, tracking: Tracking | None = None):
         """
         Initialises the process event with the given tracking object.
         """
@@ -563,7 +564,7 @@ class ProcessingEvent:
 
     def collect_events(
         self,
-        *objs: Optional[Union[MutableOrImmutableAggregate, DomainEventProtocol]],
+        *objs: MutableOrImmutableAggregate | DomainEventProtocol | None,
         **kwargs: Any,
     ) -> None:
         """
@@ -572,7 +573,7 @@ class ProcessingEvent:
         for obj in objs:
             if obj is None:
                 continue
-            elif isinstance(obj, DomainEventProtocol):
+            if isinstance(obj, DomainEventProtocol):
                 self.events.append(obj)
             else:
                 if isinstance(obj, CollectEventsProtocol):
@@ -584,7 +585,7 @@ class ProcessingEvent:
 
     def save(
         self,
-        *aggregates: Optional[Union[MutableOrImmutableAggregate, DomainEventProtocol]],
+        *aggregates: MutableOrImmutableAggregate | DomainEventProtocol | None,
         **kwargs: Any,
     ) -> None:
         warn(
@@ -596,31 +597,12 @@ class ProcessingEvent:
         self.collect_events(*aggregates, **kwargs)
 
 
-class ProcessEvent(ProcessingEvent):
-    """Deprecated, use :class:`ProcessingEvent` instead.
-
-    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
-    new domain events that result from processing that notification.
-    """
-
-    def __init__(self, tracking: Optional[Tracking] = None):
-        warn(
-            "'ProcessEvent' is deprecated, use 'ProcessingEvent' instead",
-            DeprecationWarning,
-            stacklevel=2,
-        )
-
-        super().__init__(tracking)
-
-
 class RecordingEvent:
     def __init__(
         self,
         application_name: str,
         recordings: List[Recording],
-        previous_max_notification_id: Optional[int],
+        previous_max_notification_id: int | None,
     ):
         self.application_name = application_name
         self.recordings = recordings
@@ -633,13 +615,13 @@ class Application:
     """
 
     name = "Application"
-    env: EnvType = {}
+    env: ClassVar[Dict[str, str]] = {}
     is_snapshotting_enabled: bool = False
-    snapshotting_intervals: Optional[
-        Dict[Type[MutableOrImmutableAggregate], int]
+    snapshotting_intervals: ClassVar[
+        Dict[Type[MutableOrImmutableAggregate], int] | None
     ] = None
-    snapshotting_projectors: Optional[
-        Dict[Type[MutableOrImmutableAggregate], ProjectorFunction[Any, Any]]
+    snapshotting_projectors: ClassVar[
+        Dict[Type[MutableOrImmutableAggregate], ProjectorFunction[Any, Any]] | None
     ] = None
     snapshot_class: Type[SnapshotProtocol] = Snapshot
     log_section_size = 10
@@ -654,7 +636,7 @@ class Application:
         if "name" not in cls.__dict__:
             cls.name = cls.__name__
 
-    def __init__(self, env: Optional[EnvType] = None) -> None:
+    def __init__(self, env: EnvType | None = None) -> None:
         """
         Initialises an application with an
         :class:`~eventsourcing.persistence.InfrastructureFactory`,
@@ -664,20 +646,36 @@ class Application:
         a :class:`~eventsourcing.application.Repository`, and
         a :class:`~eventsourcing.application.LocalNotificationLog`.
         """
-        self.env = self.construct_env(self.name, env)
+        self.env = self.construct_env(self.name, env)  # type: ignore[misc]
         self.factory = self.construct_factory(self.env)
         self.mapper = self.construct_mapper()
         self.recorder = self.construct_recorder()
         self.events = self.construct_event_store()
-        self.snapshots: Optional[EventStore] = None
+        self.snapshots: EventStore | None = None
         if self.factory.is_snapshotting_enabled():
             self.snapshots = self.construct_snapshot_store()
-        self.repository = self.construct_repository()
-        self.notification_log = self.construct_notification_log()
+        self._repository = self.construct_repository()
+        self._notification_log = self.construct_notification_log()
         self.closing = Event()
-        self.previous_max_notification_id: Optional[
-            int
-        ] = self.recorder.max_notification_id()
+        self.previous_max_notification_id: int | None = (
+            self.recorder.max_notification_id()
+        )
+
+    @property
+    def repository(self) -> Repository:
+        """
+        An application's repository reconstructs aggregates from stored events.
+        """
+        return self._repository
+
+    @property
+    def notification_log(self) -> LocalNotificationLog:
+        """
+        An application's notification log presents all the aggregate events
+        of an application in the order they were recorded as a sequence of event
+        notifications.
+        """
+        return self._notification_log
 
     @property
     def log(self) -> LocalNotificationLog:
@@ -686,9 +684,9 @@ class Application:
             DeprecationWarning,
             stacklevel=2,
         )
-        return self.notification_log
+        return self._notification_log
 
-    def construct_env(self, name: str, env: Optional[EnvType] = None) -> Environment:
+    def construct_env(self, name: str, env: EnvType | None = None) -> Environment:
         """
         Constructs environment from which application will be configured.
         """
@@ -767,10 +765,7 @@ class Application:
         Constructs a :class:`Repository` for use by the application.
         """
         cache_maxsize_envvar = self.env.get(self.AGGREGATE_CACHE_MAXSIZE)
-        if cache_maxsize_envvar:
-            cache_maxsize = int(cache_maxsize_envvar)
-        else:
-            cache_maxsize = None
+        cache_maxsize = int(cache_maxsize_envvar) if cache_maxsize_envvar else None
         return Repository(
             event_store=self.events,
             snapshot_store=self.snapshots,
@@ -792,7 +787,7 @@ class Application:
 
     def save(
         self,
-        *objs: Optional[Union[MutableOrImmutableAggregate, DomainEventProtocol]],
+        *objs: MutableOrImmutableAggregate | DomainEventProtocol | None,
         **kwargs: Any,
     ) -> List[Recording]:
         """
@@ -830,40 +825,39 @@ class Application:
                 except KeyError:
                     continue
                 interval = self.snapshotting_intervals.get(type(aggregate))
-                if interval is not None:
-                    if event.originator_version % interval == 0:
-                        projector_func: ProjectorFunction[
-                            MutableOrImmutableAggregate, DomainEventProtocol
-                        ]
-                        if (
-                            self.snapshotting_projectors
-                            and type(aggregate) in self.snapshotting_projectors
-                        ):
-                            projector_func = self.snapshotting_projectors[
-                                type(aggregate)
-                            ]
-                        else:
-                            projector_func = project_aggregate
-                        if (
-                            not isinstance(event, CanMutateProtocol)
-                            and projector_func is project_aggregate
-                        ):
-                            raise ProgrammingError(
-                                (
-                                    "Aggregate projector function not found. Please set "
-                                    "snapshotting_projectors on application class."
-                                )
-                            )
-                        self.take_snapshot(
-                            aggregate_id=event.originator_id,
-                            version=event.originator_version,
-                            projector_func=projector_func,
+                if interval is not None and event.originator_version % interval == 0:
+                    if (
+                        self.snapshotting_projectors
+                        and type(aggregate) in self.snapshotting_projectors
+                    ):
+                        projector_func = self.snapshotting_projectors[type(aggregate)]
+                    else:
+                        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,
+                        projector_func=projector_func,
+                    )
 
     def take_snapshot(
         self,
         aggregate_id: UUID,
-        version: Optional[int] = None,
+        version: int | None = None,
         projector_func: ProjectorFunction[
             TMutableOrImmutableAggregate, TDomainEvent
         ] = project_aggregate,
@@ -873,19 +867,20 @@ class Application:
         and puts the snapshot in the snapshot store.
         """
         if self.snapshots is None:
-            raise AssertionError(
+            msg = (
                 "Can't take snapshot without snapshots store. Please "
                 "set environment variable IS_SNAPSHOTTING_ENABLED to "
                 "a true value (e.g. 'y'), or set 'is_snapshotting_enabled' "
                 "on application class, or set 'snapshotting_intervals' on "
                 "application class."
             )
-        else:
-            aggregate = self.repository.get(
-                aggregate_id, version=version, projector_func=projector_func
-            )
-            snapshot = type(self).snapshot_class.take(aggregate)
-            self.snapshots.put([snapshot])
+            raise AssertionError(msg)
+        aggregate = self.repository.get(
+            aggregate_id, version=version, projector_func=projector_func
+        )
+        snapshot_class = getattr(type(aggregate), "Snapshot", type(self).snapshot_class)
+        snapshot = snapshot_class.take(aggregate)
+        self.snapshots.put([snapshot])
 
     def notify(self, new_events: List[DomainEventProtocol]) -> None:
         """
@@ -913,13 +908,23 @@ class Application:
 TApplication = TypeVar("TApplication", bound=Application)
 
 
-class AggregateNotFound(EventSourcingError):
+class AggregateNotFoundError(EventSourcingError):
     """
     Raised when an :class:`~eventsourcing.domain.Aggregate`
     object is not found in a :class:`Repository`.
     """
 
 
+class AggregateNotFound(AggregateNotFoundError):  # noqa: N818
+    def __init__(self, *args: Any, **kwargs: Any) -> None:
+        warn(
+            "AggregateNotFound is deprecated, use AggregateNotFoundError instead",
+            DeprecationWarning,
+            stacklevel=2,
+        )
+        super().__init__(*args, **kwargs)
+
+
 class EventSourcedLog(Generic[TDomainEvent]):
     """
     Constructs a sequence of domain events, like an aggregate.
@@ -939,15 +944,15 @@ class EventSourcedLog(Generic[TDomainEvent]):
         self,
         events: EventStore,
         originator_id: UUID,
-        logged_cls: Type[TDomainEvent],  # Todo: Rename to 'event_class' in v10.
+        logged_cls: Type[TDomainEvent],  # TODO: Rename to 'event_class' in v10.
     ):
         self.events = events
         self.originator_id = originator_id
-        self.logged_cls = logged_cls  # Todo: Rename to 'event_class' in v10.
+        self.logged_cls = logged_cls  # TODO: Rename to 'event_class' in v10.
 
     def trigger_event(
         self,
-        next_originator_version: Optional[int] = None,
+        next_originator_version: int | None = None,
         **kwargs: Any,
     ) -> TDomainEvent:
         """
@@ -961,8 +966,8 @@ class EventSourcedLog(Generic[TDomainEvent]):
 
     def _trigger_event(
         self,
-        logged_cls: Optional[Type[T]],
-        next_originator_version: Optional[int] = None,
+        logged_cls: Type[T] | None,
+        next_originator_version: int | None = None,
         **kwargs: Any,
     ) -> T:
         """
@@ -975,15 +980,14 @@ class EventSourcedLog(Generic[TDomainEvent]):
             else:
                 next_originator_version = last_logged.originator_version + 1
 
-        logged_event = logged_cls(  # type: ignore
+        return logged_cls(  # type: ignore
             originator_id=self.originator_id,
             originator_version=next_originator_version,
             timestamp=create_utc_datetime_now(),
             **kwargs,
         )
-        return logged_event
 
-    def get_first(self) -> Optional[TDomainEvent]:
+    def get_first(self) -> TDomainEvent | None:
         """
         Selects the first logged event.
         """
@@ -992,7 +996,7 @@ class EventSourcedLog(Generic[TDomainEvent]):
         except StopIteration:
             return None
 
-    def get_last(self) -> Optional[TDomainEvent]:
+    def get_last(self) -> TDomainEvent | None:
         """
         Selects the last logged event.
         """
@@ -1003,10 +1007,11 @@ class EventSourcedLog(Generic[TDomainEvent]):
 
     def get(
         self,
-        gt: Optional[int] = None,
-        lte: Optional[int] = None,
+        *,
+        gt: int | None = None,
+        lte: int | None = None,
         desc: bool = False,
-        limit: Optional[int] = None,
+        limit: int | None = None,
     ) -> Iterator[TDomainEvent]:
         """
         Selects a range of logged events with limit,

eventsourcing/cipher.py

@@ -1,12 +1,17 @@
+from __future__ import annotations
+
 import os
 from base64 import b64decode, b64encode
+from typing import TYPE_CHECKING
 
 from Crypto.Cipher import AES
 from Crypto.Cipher._mode_gcm import GcmMode
 from Crypto.Cipher.AES import key_size
 
 from eventsourcing.persistence import Cipher
-from eventsourcing.utils import Environment
+
+if TYPE_CHECKING:  # pragma: nocover
+    from eventsourcing.utils import Environment
 
 
 class AESCipher(Cipher):
@@ -31,9 +36,8 @@ class AESCipher(Cipher):
     @staticmethod
     def check_key_size(num_bytes: int) -> None:
         if num_bytes not in AESCipher.KEY_SIZES:
-            raise ValueError(
-                "Invalid key size: {} not in {}".format(num_bytes, AESCipher.KEY_SIZES)
-            )
+            msg = f"Invalid key size: {num_bytes} not in {AESCipher.KEY_SIZES}"
+            raise ValueError(msg)
 
     @staticmethod
     def random_bytes(num_bytes: int) -> bytes:
@@ -47,7 +51,8 @@ class AESCipher(Cipher):
         """
         cipher_key = environment.get(self.CIPHER_KEY)
         if not cipher_key:
-            raise EnvironmentError(f"'{self.CIPHER_KEY}' not set in env")
+            msg = f"'{self.CIPHER_KEY}' not in env"
+            raise OSError(msg)
         key = b64decode(cipher_key.encode("utf8"))
         AESCipher.check_key_size(len(key))
         self.key = key
@@ -64,11 +69,8 @@ class AESCipher(Cipher):
         encrypted = result[0]
         tag = result[1]
 
-        # Combine with nonce.
-        ciphertext = nonce + tag + encrypted
-
         # Return ciphertext.
-        return ciphertext
+        return nonce + tag + encrypted
 
     def construct_cipher(self, nonce: bytes) -> GcmMode:
         cipher = AES.new(
@@ -85,11 +87,13 @@ class AESCipher(Cipher):
         # Split out the nonce, tag, and encrypted data.
         nonce = ciphertext[:12]
         if len(nonce) != 12:
-            raise ValueError("Damaged cipher text: invalid nonce length")
+            msg = "Damaged cipher text: invalid nonce length"
+            raise ValueError(msg)
 
         tag = ciphertext[12:28]
         if len(tag) != 16:
-            raise ValueError("Damaged cipher text: invalid tag length")
+            msg = "Damaged cipher text: invalid tag length"
+            raise ValueError(msg)
         encrypted = ciphertext[28:]
 
         # Construct AES cipher, with old nonce.
@@ -99,5 +103,6 @@ class AESCipher(Cipher):
         try:
             plaintext = cipher.decrypt_and_verify(encrypted, tag)
         except ValueError as e:
-            raise ValueError("Cipher text is damaged: {}".format(e))
+            msg = f"Cipher text is damaged: {e}"
+            raise ValueError(msg) from None
         return plaintext