eventsourcing 9.4.0a7__py3-none-any.whl → 9.4.0b1__py3-none-any.whl

eventsourcing/projection.py

@@ -40,45 +40,77 @@ class ApplicationSubscription(Iterator[tuple[DomainEventProtocol, Tracking]]):
         gt: int | None = None,
         topics: Sequence[str] = (),
     ):
+        """
+        Starts subscription to application's stored events using application's recorder.
+        """
         self.name = app.name
         self.recorder = app.recorder
         self.mapper = app.mapper
         self.subscription = self.recorder.subscribe(gt=gt, topics=topics)
 
+    def stop(self) -> None:
+        """
+        Stops the stored event subscription.
+        """
+        self.subscription.stop()
+
     def __enter__(self) -> Self:
+        """
+        Calls __enter__ on the stored event subscription.
+        """
         self.subscription.__enter__()
         return self
 
     def __exit__(self, *args: object, **kwargs: Any) -> None:
+        """
+        Calls __exit__ on the stored event subscription.
+        """
         self.subscription.__exit__(*args, **kwargs)
 
     def __iter__(self) -> Self:
         return self
 
     def __next__(self) -> tuple[DomainEventProtocol, Tracking]:
+        """
+        Returns the next stored event from the stored event subscription.
+        Constructs a tracking object that identifies the position of
+        the event in the application sequence, and reconstructs a domain
+        event object from the stored event object.
+        """
         notification = next(self.subscription)
         tracking = Tracking(self.name, notification.id)
         domain_event = self.mapper.to_domain_event(notification)
         return domain_event, tracking
 
     def __del__(self) -> None:
+        """
+        Stops the stored event subscription.
+        """
         self.stop()
 
-    def stop(self) -> None:
-        self.subscription.stop()
-
 
 class Projection(ABC, Generic[TTrackingRecorder]):
     name: str = ""
-    """Name of projection, used to pick prefixed environment variables."""
-    topics: Sequence[str] = ()
-    """Event topics, used to filter events in database."""
+    """
+    Name of projection, used to pick prefixed environment
+    variables and define database table names.
+    """
+    topics: tuple[str, ...] = ()
+    """
+    Filter events in database when subscribing to an application.
+    """
 
     def __init__(
         self,
-        tracking_recorder: TTrackingRecorder,
+        view: TTrackingRecorder,
     ):
-        self.tracking_recorder = tracking_recorder
+        """Initialises a projection instance."""
+        self._view = view
+
+    @property
+    def view(self) -> TTrackingRecorder:
+        """Materialised view of an event-sourced application."""
+        return self._view
 
     @singledispatchmethod
     @abstractmethod
@@ -90,9 +122,6 @@ class Projection(ABC, Generic[TTrackingRecorder]):
         """
 
 
-TProjection = TypeVar("TProjection", bound=Projection[Any])
-
-
 TApplication = TypeVar("TApplication", bound=Application)
 
 
@@ -102,30 +131,40 @@ class ProjectionRunner(Generic[TApplication, TTrackingRecorder]):
         *,
         application_class: type[TApplication],
         projection_class: type[Projection[TTrackingRecorder]],
-        tracking_recorder_class: type[TTrackingRecorder] | None = None,
+        view_class: type[TTrackingRecorder],
         env: EnvType | None = None,
     ):
+        """
+        Constructs application from given application class with given environment.
+        Also constructs a materialised view from given class using an infrastructure
+        factory constructed with an environment named after the projection. Also
+        constructs a projection with the constructed materialised view object.
+        Starts a subscription to application and, in a separate event-processing
+        thread, calls projection's process_event() method for each event and tracking
+        object pair received from the subscription.
+        """
+        self._is_stopping = Event()
+
         self.app: TApplication = application_class(env)
 
-        projection_environment = self._construct_env(
-            name=projection_class.name or projection_class.__name__, env=env
-        )
-        self.projection_factory: InfrastructureFactory[TTrackingRecorder] = (
-            InfrastructureFactory.construct(env=projection_environment)
-        )
-        self.tracking_recorder: TTrackingRecorder = (
-            self.projection_factory.tracking_recorder(tracking_recorder_class)
+        self.view = (
+            InfrastructureFactory[TTrackingRecorder]
+            .construct(
+                env=self._construct_env(
+                    name=projection_class.name or projection_class.__name__, env=env
+                )
+            )
+            .tracking_recorder(view_class)
         )
 
         self.projection = projection_class(
-            tracking_recorder=self.tracking_recorder,
+            view=self.view,
         )
         self.subscription = ApplicationSubscription(
             app=self.app,
-            gt=self.tracking_recorder.max_tracking_id(self.app.name),
+            gt=self.view.max_tracking_id(self.app.name),
             topics=self.projection.topics,
         )
-        self._is_stopping = Event()
         self.thread_error: BaseException | None = None
         self.processing_thread = Thread(
             target=self._process_events_loop,
@@ -149,6 +188,9 @@ class ProjectionRunner(Generic[TApplication, TTrackingRecorder]):
         return Environment(name, _env)
 
     def stop(self) -> None:
+        """
+        Stops the application subscription, which will stop the event-processing thread.
+        """
         self._is_stopping.set()
         self.subscription.stop()
 
@@ -177,15 +219,23 @@ class ProjectionRunner(Generic[TApplication, TTrackingRecorder]):
                 )
 
             is_stopping.set()
-            subscription.subscription.stop()
+            subscription.stop()
 
     def run_forever(self, timeout: float | None = None) -> None:
+        """
+        Blocks until timeout, or until the runner is stopped or errors. Re-raises
+        any error otherwise exits normally
+        """
         if self._is_stopping.wait(timeout=timeout) and self.thread_error is not None:
             raise self.thread_error
 
-    def wait(self, notification_id: int, timeout: float = 1.0) -> None:
+    def wait(self, notification_id: int | None, timeout: float = 1.0) -> None:
+        """
+        Blocks until timeout, or until the materialised view has recorded a tracking
+        object that is greater than or equal to the given notification ID.
+        """
         try:
-            self.projection.tracking_recorder.wait(
+            self.projection.view.wait(
                 application_name=self.subscription.name,
                 notification_id=notification_id,
                 timeout=timeout,
@@ -199,8 +249,14 @@ class ProjectionRunner(Generic[TApplication, TTrackingRecorder]):
         return self
 
     def __exit__(self, *args: object, **kwargs: Any) -> None:
+        """
+        Calls stop() and waits for the event-processing thread to exit.
+        """
         self.stop()
         self.processing_thread.join()
 
     def __del__(self) -> None:
+        """
+        Calls stop().
+        """
         self.stop()

eventsourcing/sqlite.py

@@ -530,7 +530,11 @@ class SQLiteTrackingRecorder(SQLiteRecorder, TrackingRecorder):
             c.execute(self.select_max_tracking_id_statement, params)
             return c.fetchone()[0]
 
-    def has_tracking_id(self, application_name: str, notification_id: int) -> bool:
+    def has_tracking_id(
+        self, application_name: str, notification_id: int | None
+    ) -> bool:
+        if notification_id is None:
+            return True
         params = [application_name, notification_id]
         with self.datastore.transaction(commit=False) as c:
             c.execute(self.count_tracking_id_statement, params)

eventsourcing/system.py

@@ -17,9 +17,11 @@ from eventsourcing.application import (
     Application,
     NotificationLog,
     ProcessingEvent,
+    ProgrammingError,
     Section,
     TApplication,
 )
+from eventsourcing.dispatch import singledispatchmethod
 from eventsourcing.domain import DomainEventProtocol, MutableOrImmutableAggregate
 from eventsourcing.persistence import (
     IntegrityError,
@@ -196,7 +198,7 @@ class Follower(Application):
                 self.notify(processing_event.events)
                 self._notify(recordings)
 
-    @abstractmethod
+    @singledispatchmethod
     def policy(
         self,
         domain_event: DomainEventProtocol,
@@ -379,7 +381,7 @@ class System:
         return cls
 
     @property
-    def topic(self) -> str | None:
+    def topic(self) -> str:
         """
         Returns a topic to the system object, if constructed as a module attribute.
         """
@@ -389,6 +391,9 @@ class System:
             if value is self:
                 topic = module.__name__ + ":" + name
                 assert resolve_topic(topic) is self
+        if topic is None:
+            msg = "Unable to compute topic for system object: %s" % self
+            raise ProgrammingError(msg)
         return topic
 
 
@@ -423,6 +428,13 @@ class Runner(ABC):
         Returns an application instance for given application class.
         """
 
+    def __enter__(self) -> Self:
+        self.start()
+        return self
+
+    def __exit__(self, *args: object, **kwargs: Any) -> None:
+        self.stop()
+
 
 class RunnerAlreadyStartedError(Exception):
     """
@@ -548,13 +560,6 @@ class SingleThreadedRunner(Runner, RecordingEventReceiver):
         assert isinstance(app, cls)
         return app
 
-    def __enter__(self) -> Self:
-        self.start()
-        return self
-
-    def __exit__(self, *args: object, **kwargs: Any) -> None:
-        self.stop()
-
 
 class NewSingleThreadedRunner(Runner, RecordingEventReceiver):
     """

eventsourcing/tests/application.py

@@ -34,7 +34,7 @@ class ExampleApplicationTestCase(TestCase):
     counts: ClassVar[dict[type[TestCase], int]] = {}
     expected_factory_topic: str
 
-    def test_example_application(self):
+    def test_example_application(self) -> None:
         app = BankAccounts(env={"IS_SNAPSHOTTING_ENABLED": "y"})
 
         self.assertEqual(get_topic(type(app.factory)), self.expected_factory_topic)
@@ -80,30 +80,32 @@ class ExampleApplicationTestCase(TestCase):
         # Take snapshot (specify version).
         app.take_snapshot(account_id, version=Aggregate.INITIAL_VERSION + 1)
 
+        assert app.snapshots is not None  # for mypy
         snapshots = list(app.snapshots.get(account_id))
         self.assertEqual(len(snapshots), 1)
         self.assertEqual(snapshots[0].originator_version, Aggregate.INITIAL_VERSION + 1)
 
-        from_snapshot = app.repository.get(
+        from_snapshot1: BankAccount = app.repository.get(
             account_id, version=Aggregate.INITIAL_VERSION + 2
         )
-        self.assertIsInstance(from_snapshot, BankAccount)
-        self.assertEqual(from_snapshot.version, Aggregate.INITIAL_VERSION + 2)
-        self.assertEqual(from_snapshot.balance, Decimal("35.00"))
+        self.assertIsInstance(from_snapshot1, BankAccount)
+        self.assertEqual(from_snapshot1.version, Aggregate.INITIAL_VERSION + 2)
+        self.assertEqual(from_snapshot1.balance, Decimal("35.00"))
 
         # Take snapshot (don't specify version).
         app.take_snapshot(account_id)
+        assert app.snapshots is not None  # for mypy
         snapshots = list(app.snapshots.get(account_id))
         self.assertEqual(len(snapshots), 2)
         self.assertEqual(snapshots[0].originator_version, Aggregate.INITIAL_VERSION + 1)
         self.assertEqual(snapshots[1].originator_version, Aggregate.INITIAL_VERSION + 3)
 
-        from_snapshot = app.repository.get(account_id)
-        self.assertIsInstance(from_snapshot, BankAccount)
-        self.assertEqual(from_snapshot.version, Aggregate.INITIAL_VERSION + 3)
-        self.assertEqual(from_snapshot.balance, Decimal("65.00"))
+        from_snapshot2: BankAccount = app.repository.get(account_id)
+        self.assertIsInstance(from_snapshot2, BankAccount)
+        self.assertEqual(from_snapshot2.version, Aggregate.INITIAL_VERSION + 3)
+        self.assertEqual(from_snapshot2.balance, Decimal("65.00"))
 
-    def test__put_performance(self):
+    def test__put_performance(self) -> None:
         app = BankAccounts()
 
         # Open an account.
@@ -113,7 +115,7 @@ class ExampleApplicationTestCase(TestCase):
         )
         account = app.get_account(account_id)
 
-        def put():
+        def put() -> None:
             # Credit the account.
             account.append_transaction(Decimal("10.00"))
             app.save(account)
@@ -125,14 +127,14 @@ class ExampleApplicationTestCase(TestCase):
         duration = timeit(put, number=self.timeit_number)
         self.print_time("store events", duration)
 
-    def test__get_performance_with_snapshotting_enabled(self):
+    def test__get_performance_with_snapshotting_enabled(self) -> None:
         print()
         self._test_get_performance(is_snapshotting_enabled=True)
 
-    def test__get_performance_without_snapshotting_enabled(self):
+    def test__get_performance_without_snapshotting_enabled(self) -> None:
         self._test_get_performance(is_snapshotting_enabled=False)
 
-    def _test_get_performance(self, *, is_snapshotting_enabled: bool):
+    def _test_get_performance(self, *, is_snapshotting_enabled: bool) -> None:
         app = BankAccounts(
             env={"IS_SNAPSHOTTING_ENABLED": "y" if is_snapshotting_enabled else "n"}
         )
@@ -143,7 +145,7 @@ class ExampleApplicationTestCase(TestCase):
             email_address="alice@example.com",
         )
 
-        def read():
+        def read() -> None:
             # Get the account.
             app.get_account(account_id)
 
@@ -158,7 +160,7 @@ class ExampleApplicationTestCase(TestCase):
             test_label = "get without snapshotting"
         self.print_time(test_label, duration)
 
-    def print_time(self, test_label, duration):
+    def print_time(self, test_label: str, duration: float) -> None:
         cls = type(self)
         if cls not in self.started_ats:
             self.started_ats[cls] = datetime.now()
@@ -176,8 +178,8 @@ class ExampleApplicationTestCase(TestCase):
         )
 
         if self.counts[cls] == 3:
-            duration = datetime.now() - cls.started_ats[cls]
-            print(f"{cls.__name__: <29} timeit duration: {duration}")
+            cls_duration = datetime.now() - cls.started_ats[cls]
+            print(f"{cls.__name__: <29} timeit duration: {cls_duration}")
             sys.stdout.flush()
 
 
@@ -199,7 +201,7 @@ class BankAccounts(Application):
         super().register_transcodings(transcoder)
         transcoder.register(EmailAddressAsStr())
 
-    def open_account(self, full_name, email_address):
+    def open_account(self, full_name: str, email_address: str) -> UUID:
         account = BankAccount.open(
             full_name=full_name,
             email_address=email_address,
@@ -218,7 +220,7 @@ class BankAccounts(Application):
 
     def get_account(self, account_id: UUID) -> BankAccount:
         try:
-            aggregate = self.repository.get(account_id)
+            aggregate: BankAccount = self.repository.get(account_id)
         except AggregateNotFoundError:
             raise self.AccountNotFoundError(account_id) from None
         else:
@@ -230,7 +232,7 @@ class BankAccounts(Application):
 
 
 class ApplicationTestCase(TestCase):
-    def test_name(self):
+    def test_name(self) -> None:
         self.assertEqual(Application.name, "Application")
 
         class MyApplication1(Application):
@@ -243,7 +245,7 @@ class ApplicationTestCase(TestCase):
 
         self.assertEqual(MyApplication2.name, "MyBoundedContext")
 
-    def test_resolve_persistence_topics(self):
+    def test_resolve_persistence_topics(self) -> None:
         # None specified.
         app = Application()
         self.assertIsInstance(app.factory, InfrastructureFactory)
@@ -279,7 +281,7 @@ class ApplicationTestCase(TestCase):
             "eventsourcing.application:Application",
         )
 
-    def test_save_returns_recording_event(self):
+    def test_save_returns_recording_event(self) -> None:
         app = Application()
 
         recordings = app.save()
@@ -301,7 +303,9 @@ class ApplicationTestCase(TestCase):
         self.assertEqual(recordings[0].notification.id, 3)
         self.assertEqual(recordings[1].notification.id, 4)
 
-    def test_take_snapshot_raises_assertion_error_if_snapshotting_not_enabled(self):
+    def test_take_snapshot_raises_assertion_error_if_snapshotting_not_enabled(
+        self,
+    ) -> None:
         app = Application()
         with self.assertRaises(AssertionError) as cm:
             app.take_snapshot(uuid4())
@@ -314,12 +318,13 @@ class ApplicationTestCase(TestCase):
             "application class.",
         )
 
-    def test_application_with_cached_aggregates_and_fastforward(self):
+    def test_application_with_cached_aggregates_and_fastforward(self) -> None:
         app = Application(env={"AGGREGATE_CACHE_MAXSIZE": "10"})
 
         aggregate = Aggregate()
         app.save(aggregate)
         # Should not put the aggregate in the cache.
+        assert app.repository.cache is not None  # for mypy
         with self.assertRaises(KeyError):
             self.assertEqual(aggregate, app.repository.cache.get(aggregate.id))
 
@@ -339,7 +344,7 @@ class ApplicationTestCase(TestCase):
         app.repository.get(aggregate.id)
         self.assertEqual(aggregate, app.repository.cache.get(aggregate.id))
 
-    def test_application_fastforward_skipping_during_contention(self):
+    def test_application_fastforward_skipping_during_contention(self) -> None:
         app = Application(
             env={
                 "AGGREGATE_CACHE_MAXSIZE": "10",
@@ -354,18 +359,18 @@ class ApplicationTestCase(TestCase):
         stopped = Event()
 
         # Trigger, save, get, check.
-        def trigger_save_get_check():
+        def trigger_save_get_check() -> None:
             while not stopped.is_set():
                 try:
-                    aggregate = app.repository.get(aggregate_id)
+                    aggregate: Aggregate = app.repository.get(aggregate_id)
                     aggregate.trigger_event(Aggregate.Event)
                     saved_version = aggregate.version
                     try:
                         app.save(aggregate)
                     except IntegrityError:
                         continue
-                    cached_version = app.repository.get(aggregate_id).version
-                    if saved_version > cached_version:
+                    cached: Aggregate = app.repository.get(aggregate_id)
+                    if saved_version > cached.version:
                         print(f"Skipped fast-forwarding at version {saved_version}")
                         stopped.set()
                     if aggregate.version % 1000 == 0:
@@ -384,7 +389,7 @@ class ApplicationTestCase(TestCase):
             self.fail("Didn't skip fast forwarding before test timed out...")
         executor.shutdown()
 
-    def test_application_fastforward_blocking_during_contention(self):
+    def test_application_fastforward_blocking_during_contention(self) -> None:
         app = Application(
             env={
                 "AGGREGATE_CACHE_MAXSIZE": "10",
@@ -398,18 +403,18 @@ class ApplicationTestCase(TestCase):
         stopped = Event()
 
         # Trigger, save, get, check.
-        def trigger_save_get_check():
+        def trigger_save_get_check() -> None:
             while not stopped.is_set():
                 try:
-                    aggregate = app.repository.get(aggregate_id)
+                    aggregate: Aggregate = app.repository.get(aggregate_id)
                     aggregate.trigger_event(Aggregate.Event)
                     saved_version = aggregate.version
                     try:
                         app.save(aggregate)
                     except IntegrityError:
                         continue
-                    cached_version = app.repository.get(aggregate_id).version
-                    if saved_version > cached_version:
+                    cached: Aggregate = app.repository.get(aggregate_id)
+                    if saved_version > cached.version:
                         print(f"Skipped fast-forwarding at version {saved_version}")
                         stopped.set()
                     if aggregate.version % 1000 == 0:
@@ -429,7 +434,7 @@ class ApplicationTestCase(TestCase):
             self.fail("Wrongly skipped fast forwarding")
         executor.shutdown()
 
-    def test_application_with_cached_aggregates_not_fastforward(self):
+    def test_application_with_cached_aggregates_not_fastforward(self) -> None:
         app = Application(
             env={
                 "AGGREGATE_CACHE_MAXSIZE": "10",
@@ -439,11 +444,12 @@ class ApplicationTestCase(TestCase):
         aggregate = Aggregate()
         app.save(aggregate)
         # Should put the aggregate in the cache.
+        assert app.repository.cache is not None  # for mypy
         self.assertEqual(aggregate, app.repository.cache.get(aggregate.id))
         app.repository.get(aggregate.id)
         self.assertEqual(aggregate, app.repository.cache.get(aggregate.id))
 
-    def test_application_with_deepcopy_from_cache_arg(self):
+    def test_application_with_deepcopy_from_cache_arg(self) -> None:
         app = Application(
             env={
                 "AGGREGATE_CACHE_MAXSIZE": "10",
@@ -452,14 +458,15 @@ class ApplicationTestCase(TestCase):
         aggregate = Aggregate()
         app.save(aggregate)
         self.assertEqual(aggregate.version, 1)
-        aggregate = app.repository.get(aggregate.id)
-        aggregate.version = 101
+        reconstructed: Aggregate = app.repository.get(aggregate.id)
+        reconstructed.version = 101
+        assert app.repository.cache is not None  # for mypy
         self.assertEqual(app.repository.cache.get(aggregate.id).version, 1)
-        aggregate = app.repository.get(aggregate.id, deepcopy_from_cache=False)
-        aggregate.version = 101
+        cached: Aggregate = app.repository.get(aggregate.id, deepcopy_from_cache=False)
+        cached.version = 101
         self.assertEqual(app.repository.cache.get(aggregate.id).version, 101)
 
-    def test_application_with_deepcopy_from_cache_attribute(self):
+    def test_application_with_deepcopy_from_cache_attribute(self) -> None:
         app = Application(
             env={
                 "AGGREGATE_CACHE_MAXSIZE": "10",
@@ -468,15 +475,16 @@ class ApplicationTestCase(TestCase):
         aggregate = Aggregate()
         app.save(aggregate)
         self.assertEqual(aggregate.version, 1)
-        aggregate = app.repository.get(aggregate.id)
-        aggregate.version = 101
+        reconstructed: Aggregate = app.repository.get(aggregate.id)
+        reconstructed.version = 101
+        assert app.repository.cache is not None  # for mypy
         self.assertEqual(app.repository.cache.get(aggregate.id).version, 1)
         app.repository.deepcopy_from_cache = False
-        aggregate = app.repository.get(aggregate.id)
-        aggregate.version = 101
+        cached: Aggregate = app.repository.get(aggregate.id)
+        cached.version = 101
         self.assertEqual(app.repository.cache.get(aggregate.id).version, 101)
 
-    def test_application_log(self):
+    def test_application_log(self) -> None:
         # Check the old 'log' attribute presents the 'notification log' object.
         app = Application()
 
@@ -486,6 +494,6 @@ class ApplicationTestCase(TestCase):
 
         self.assertEqual(1, len(w))
         self.assertIs(w[-1].category, DeprecationWarning)
-        self.assertEqual(
-            "'log' is deprecated, use 'notifications' instead", w[-1].message.args[0]
+        self.assertIn(
+            "'log' is deprecated, use 'notifications' instead", str(w[-1].message)
         )

eventsourcing/tests/domain.py

@@ -2,6 +2,7 @@ from __future__ import annotations
 
 from dataclasses import dataclass
 from decimal import Decimal
+from typing import cast
 from uuid import uuid4
 
 from eventsourcing.domain import Aggregate, AggregateCreated, AggregateEvent
@@ -59,6 +60,7 @@ class BankAccount(Aggregate):
         if self.balance + amount < -self.overdraft_limit:
             raise InsufficientFundsError({"account_id": self.id})
 
+    @dataclass(frozen=True)
     class TransactionAppended(AggregateEvent):
         """
         Domain event for when transaction
@@ -67,11 +69,11 @@ class BankAccount(Aggregate):
 
         amount: Decimal
 
-        def apply(self, account: BankAccount) -> None:
+        def apply(self, aggregate: Aggregate) -> None:
             """
             Increments the account balance.
             """
-            account.balance += self.amount
+            cast(BankAccount, aggregate).balance += self.amount
 
     def set_overdraft_limit(self, overdraft_limit: Decimal) -> None:
         """
@@ -93,8 +95,8 @@ class BankAccount(Aggregate):
 
         overdraft_limit: Decimal
 
-        def apply(self, account: BankAccount):
-            account.overdraft_limit = self.overdraft_limit
+        def apply(self, aggregate: Aggregate) -> None:
+            cast(BankAccount, aggregate).overdraft_limit = self.overdraft_limit
 
     def close(self) -> None:
         """
@@ -107,8 +109,8 @@ class BankAccount(Aggregate):
         Domain event for when account is closed.
         """
 
-        def apply(self, account: BankAccount):
-            account.is_closed = True
+        def apply(self, aggregate: Aggregate) -> None:
+            cast(BankAccount, aggregate).is_closed = True
 
 
 class AccountClosedError(Exception):