eventsourcing 9.4.0b3__tar.gz → 9.4.1__tar.gz

{eventsourcing-9.4.0b3 → eventsourcing-9.4.1}/PKG-INFO

@@ -1,33 +1,32 @@
 Metadata-Version: 2.3
 Name: eventsourcing
-Version: 9.4.0b3
+Version: 9.4.1
 Summary: Event sourcing in Python
-License: BSD 3-Clause
+License: BSD-3-Clause
 Keywords: event sourcing,event store,domain driven design,domain-driven design,ddd,cqrs,cqs
 Author: John Bywater
 Author-email: john.bywater@appropriatesoftware.net
-Requires-Python: >=3.9, !=2.7.*, !=3.0.*, !=3.1.*, !=3.2.*, !=3.3.*, !=3.4.*, !=3.5.*, !=3.6.*, !=3.7.*, !=3.8.*
-Classifier: Development Status :: 4 - Beta
+Requires-Python: >=3.9.2
+Classifier: Development Status :: 5 - Production/Stable
 Classifier: Intended Audience :: Developers
 Classifier: Intended Audience :: Education
 Classifier: Intended Audience :: Science/Research
 Classifier: License :: OSI Approved :: BSD License
-Classifier: License :: Other/Proprietary License
 Classifier: Operating System :: OS Independent
-Classifier: Programming Language :: Python
 Classifier: Programming Language :: Python :: 3
 Classifier: Programming Language :: Python :: 3.10
 Classifier: Programming Language :: Python :: 3.11
 Classifier: Programming Language :: Python :: 3.12
 Classifier: Programming Language :: Python :: 3.13
 Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python
 Classifier: Topic :: Software Development :: Libraries :: Python Modules
 Provides-Extra: crypto
 Provides-Extra: cryptography
 Provides-Extra: postgres
-Requires-Dist: cryptography (>=44.0,<44.1) ; extra == "cryptography"
-Requires-Dist: psycopg[pool] (<=3.2.99999) ; extra == "postgres"
-Requires-Dist: pycryptodome (>=3.22,<3.23) ; extra == "crypto"
+Requires-Dist: cryptography (>=44.0,<45.0) ; extra == "cryptography"
+Requires-Dist: psycopg[pool] (>=3.2,<3.3) ; extra == "postgres"
+Requires-Dist: pycryptodome (>=3.22,<4.0) ; extra == "crypto"
 Requires-Dist: typing_extensions
 Project-URL: Homepage, https://github.com/pyeventsourcing/eventsourcing
 Project-URL: Repository, https://github.com/pyeventsourcing/eventsourcing
@@ -43,7 +42,10 @@ Description-Content-Type: text/markdown
 
 # Event Sourcing in Python
 
-A library for event sourcing in Python.
+This project is a comprehensive Python library for implementing event sourcing, a design pattern where all
+changes to application state are stored as a sequence of events. This library provides a solid foundation
+for building event-sourced applications in Python, with a focus on reliability, performance, and developer
+experience. Please [read the docs](https://eventsourcing.readthedocs.io/). See also [extension projects](https://github.com/pyeventsourcing).
 
 *"totally amazing and a pleasure to use"*
 
@@ -51,8 +53,6 @@ A library for event sourcing in Python.
 
 *"a huge help and time saver"*
 
-Please [read the docs](https://eventsourcing.readthedocs.io/). See also [extension projects](https://github.com/pyeventsourcing).
-
 
 ## Installation
 

{eventsourcing-9.4.0b3 → eventsourcing-9.4.1}/README.md

@@ -8,7 +8,10 @@
 
 # Event Sourcing in Python
 
-A library for event sourcing in Python.
+This project is a comprehensive Python library for implementing event sourcing, a design pattern where all
+changes to application state are stored as a sequence of events. This library provides a solid foundation
+for building event-sourced applications in Python, with a focus on reliability, performance, and developer
+experience. Please [read the docs](https://eventsourcing.readthedocs.io/). See also [extension projects](https://github.com/pyeventsourcing).
 
 *"totally amazing and a pleasure to use"*
 
@@ -16,8 +19,6 @@ A library for event sourcing in Python.
 
 *"a huge help and time saver"*
 
-Please [read the docs](https://eventsourcing.readthedocs.io/). See also [extension projects](https://github.com/pyeventsourcing).
-
 
 ## Installation
 

{eventsourcing-9.4.0b3 → eventsourcing-9.4.1}/eventsourcing/domain.py

@@ -943,12 +943,20 @@ class MetaAggregate(EventsourcingType, Generic[TAggregate], type):
         }
 
         # Create the event class object.
-        return cast("type[CanMutateAggregate]", type(name, bases, event_cls_dict))
+        _new_class = type(name, bases, event_cls_dict)
+        return cast("type[CanMutateAggregate]", _new_class)
 
     def __call__(
         cls: MetaAggregate[TAggregate], *args: Any, **kwargs: Any
     ) -> TAggregate:
+        if cls is BaseAggregate:
+            msg = "BaseAggregate class cannot be instantiated directly"
+            raise TypeError(msg)
         created_event_classes = _created_event_classes[cls]
+        # Here, unlike when calling _create(), we don't have a given event class,
+        # so we need to check that there is one "created" event class to use here.
+        # We don't check this in __init_subclass__ to allow for alternatives that
+        # can be selected by developers by calling _create(event_class=...).
         if len(created_event_classes) > 1:
             msg = (
                 f"{cls.__qualname__} can't decide which of many "
@@ -975,10 +983,9 @@ class MetaAggregate(EventsourcingType, Generic[TAggregate], type):
         event_class: type[CanInitAggregate],
         **kwargs: Any,
     ) -> TAggregate:
+        # Just define method signature for the __call__() method.
         raise NotImplementedError  # pragma: no cover
 
-    _created_event_class: type[CanInitAggregate]
-
 
 class BaseAggregate(metaclass=MetaAggregate):
     """Base class for aggregates."""
@@ -1141,13 +1148,22 @@ class BaseAggregate(metaclass=MetaAggregate):
         return f"{type(self).__name__}({', '.join(attrs)})"
 
     def __init_subclass__(
-        cls: type[BaseAggregate], *, created_event_name: str | None = None
+        cls: type[BaseAggregate], *, created_event_name: str = ""
     ) -> None:
         """
         Initialises aggregate subclass by defining __init__ method and event classes.
         """
         super().__init_subclass__()
 
+        # Ensure we aren't defining another instance of the same class,
+        # because annotations can get confused when using singledispatchmethod
+        # during class definition e.g. on an aggregate projector function.
+        _module = importlib.import_module(cls.__module__)
+        if cls.__name__ in _module.__dict__:
+            msg = f"Name '{cls.__name__}' already defined in '{cls.__module__}' module"
+            raise ProgrammingError(msg)
+
+        # Get the class annotations.
         class_annotations = cls.__dict__.get("__annotations__", {})
         try:
             class_annotations.pop("id")
@@ -1155,6 +1171,11 @@ class BaseAggregate(metaclass=MetaAggregate):
         except KeyError:
             pass
 
+        if "id" in cls.__dict__:
+            msg = f"Setting attribute 'id' on class '{cls.__name__}' is not allowed"
+            raise ProgrammingError(msg)
+
+        # Process the class as a dataclass, if there are annotations.
         if (
             class_annotations
             or cls in _annotations_mention_id
@@ -1162,6 +1183,29 @@ class BaseAggregate(metaclass=MetaAggregate):
         ):
             dataclasses.dataclass(eq=False, repr=False)(cls)
 
+        # Remember if __init__ mentions ID.
+        for param_name in inspect.signature(cls.__init__).parameters:
+            if param_name == "id":
+                _init_mentions_id.add(cls)
+                break
+
+        # Analyse __init__ attribute, to get __init__ method and @event decorator.
+        init_attr: FunctionType | CommandMethodDecorator | None = cls.__dict__.get(
+            "__init__"
+        )
+        if init_attr is None:
+            # No method, no decorator.
+            init_method: CallableType | None = None
+            init_decorator: CommandMethodDecorator | None = None
+        elif isinstance(init_attr, CommandMethodDecorator):
+            # Method decorated with @event.
+            init_method = init_attr.decorated_func
+            init_decorator = init_attr
+        else:
+            # Undecorated __init__ method.
+            init_decorator = None
+            init_method = init_attr
+
         # Identify or define a base event class for this aggregate.
         base_event_name = "Event"
         base_event_cls: type[CanMutateAggregate]
@@ -1175,142 +1219,150 @@ class BaseAggregate(metaclass=MetaAggregate):
             )
             setattr(cls, base_event_name, base_event_cls)
 
-        # Make sure all events defined on aggregate subclass the base event class.
+        # Ensure all events defined on this class are subclasses of base event class.
+        created_event_classes: dict[str, type[CanInitAggregate]] = {}
         for name, value in tuple(cls.__dict__.items()):
             if name == base_event_name:
                 # Don't subclass the base event class again.
                 continue
             if name.lower() == name:
-                # Don't subclass lowercase named attributes that have classes.
+                # Don't subclass lowercase named attributes.
                 continue
-            if (
-                isinstance(value, type)
-                and issubclass(value, AggregateEvent)
-                and not issubclass(value, base_event_cls)
-            ):
-                sub_class = cls._define_event_class(name, (value, base_event_cls), None)
-                setattr(cls, name, sub_class)
-        created_event_classes: dict[str, type[CanInitAggregate]] = {
-            name: value
-            for name, value in cls.__dict__.items()
-            if isinstance(value, type) and issubclass(value, CanInitAggregate)
-        }
-        # Analyse the __init__ attribute.
-        init_attr: FunctionType | CommandMethodDecorator | None = cls.__dict__.get(
-            "__init__"
-        )
-        if init_attr is None:
-            init_decorator: CommandMethodDecorator | None = None
-            init_method: CallableType | None = None
-        elif isinstance(init_attr, CommandMethodDecorator):
-            init_decorator = init_attr
-            init_method = init_attr.decorated_func
-        else:
-            init_decorator = None
-            init_method = init_attr
+            if isinstance(value, type) and issubclass(value, CanMutateAggregate):
+                if not issubclass(value, base_event_cls):
+                    event_class = cls._define_event_class(
+                        name, (value, base_event_cls), None
+                    )
+                    setattr(cls, name, event_class)
+                else:
+                    event_class = value
+
+                # Remember all "created" event classes defined on this class.
+                if issubclass(event_class, CanInitAggregate):
+                    created_event_classes[name] = event_class
 
         # Identify or define the aggregate's "created" event class.
         created_event_class: type[CanInitAggregate] | None = None
 
-        # Does class have an init method decorated with a CommandMethodDecorator?
+        # Analyse __init__ method decorator.
         if init_decorator:
 
-            # Disallow using both 'created_event_name' and decorator on __init__.
-            if created_event_name:
-                msg = "Can't use both 'created_event_name' and decorator on __init__"
-                raise TypeError(msg)
-
-            # Does the decorator specify a "created" event class?
+            # Does the decorator specify an event class?
             if init_decorator.given_event_cls:
-                created_event_class = cast(
-                    "type[CanInitAggregate]", init_decorator.given_event_cls
-                )
-
-            # Does the decorator specify a "created" event name?
-            elif init_decorator.event_cls_name:
-                created_event_name = init_decorator.event_cls_name
-
-            # Disallow using decorator on __init__ without event spec.
-            else:
-                msg = "Decorator on __init__ has neither event name nor class"
-                raise TypeError(msg)
-
-        # Check if init mentions ID.
-        for param_name in inspect.signature(cls.__init__).parameters:
-            if param_name == "id":
-                _init_mentions_id.add(cls)
-                break
 
-        if created_event_class:
-            # Check specified "created" event class can init aggregate.
-            if not issubclass(created_event_class, CanInitAggregate):
-                msg = (
-                    f"{created_event_class} not subclass of {CanInitAggregate.__name__}"
-                )
-                raise TypeError(msg)
+                # Disallow conflicts between 'created_event_name' and given class.
+                if (
+                    created_event_name
+                    and created_event_name != init_decorator.given_event_cls.__name__
+                ):
+                    msg = (
+                        "Given 'created_event_name' conflicts "
+                        "with decorator on __init__"
+                    )
+                    raise TypeError(msg)
 
-            for sub_class in created_event_classes.values():
-                if issubclass(sub_class, created_event_class):
-                    # We just subclassed the created event class, so reassign it.
-                    created_event_class = sub_class
+                # Check given event class can init aggregate.
+                if not issubclass(init_decorator.given_event_cls, CanInitAggregate):
+                    msg = (
+                        f"class '{init_decorator.given_event_cls.__name__}' "
+                        f'not a "created" event class'
+                    )
+                    raise TypeError(msg)
 
-        # Is a "created" event class already defined that matches the name?
-        elif created_event_name and created_event_name in created_event_classes:
-            created_event_class = created_event_classes[created_event_name]
+                # Have we already subclassed the given event class?
+                for sub_class in created_event_classes.values():
+                    if issubclass(sub_class, init_decorator.given_event_cls):
+                        created_event_class = sub_class
+                        break
+                else:
+                    created_event_class = init_decorator.given_event_cls
 
-        # If there is only one class defined, then use it.
-        elif len(created_event_classes) == 1 and not created_event_name:
-            created_event_class = next(iter(created_event_classes.values()))
+            # Does the decorator specify an event name?
+            elif init_decorator.event_cls_name:
+                # Disallow conflicts between 'created_event_name' and given name.
+                if (
+                    created_event_name
+                    and created_event_name != init_decorator.event_cls_name
+                ):
+                    msg = (
+                        "Given 'created_event_name' conflicts "
+                        "with decorator on __init__"
+                    )
+                    raise TypeError(msg)
 
-        # If there are no "created" event classes already defined, or a name is
-        # specified that hasn't matched, then define a "created" event class.
-        elif len(created_event_classes) == 0 or created_event_name:
+                created_event_name = init_decorator.event_cls_name
 
-            # Decide the base classes for the new "created" event class.
-            if created_event_name and len(created_event_classes) == 1:
-                base_created_event_cls = next(iter(created_event_classes.values()))
+            # Disallow using decorator on __init__ without event name or class.
             else:
-                # TODO: This could probably be improved.
-                # Look for first class in MRO that has one specified "created" class.
-                for base_cls in cls.__mro__:
-                    if (
-                        base_cls in _created_event_classes
-                        and len(_created_event_classes[base_cls]) == 1
-                    ):
-                        base_created_event_cls = _created_event_classes[base_cls][0]
-                        break
-                else:  # pragma: no cover
-                    # TODO: Write a test to cover this.
-                    msg = (
-                        "Can't find base aggregate class with "
-                        "a specified 'created' event class"
+                msg = "@event decorator on __init__ has neither event name nor class"
+                raise TypeError(msg)
+
+        # Do we need to define a created event class?
+        if not created_event_class:
+            # If we have a "created" event class that matches the name, then use it.
+            if created_event_name in created_event_classes:
+                created_event_class = created_event_classes[created_event_name]
+            # Otherwise, if we have no name and only one class defined, then use it.
+            elif not created_event_name and len(created_event_classes) == 1:
+                created_event_class = next(iter(created_event_classes.values()))
+
+            # Otherwise, if there are no "created" events, or a name is
+            # specified that hasn't matched, then define a "created" event class.
+            elif len(created_event_classes) == 0 or created_event_name:
+                # Decide the base "created" event class.
+
+                try:
+                    # Look for a base class with the same name.
+                    base_created_event_cls = cast(
+                        "type[CanInitAggregate]",
+                        getattr(cls, created_event_name),
                     )
-                    raise TypeError(msg)
+                except AttributeError:
+                    # Look for base class with one nominated "created" event.
+                    for base_cls in cls.__mro__:
+                        if (
+                            base_cls in _created_event_classes
+                            and len(_created_event_classes[base_cls]) == 1
+                        ):
+                            base_created_event_cls = _created_event_classes[base_cls][0]
+                            break
+                    else:
+                        msg = (
+                            "Can't identify suitable base class for "
+                            f"\"created\" event class on class '{cls.__name__}'"
+                        )
+                        raise TypeError(msg) from None
 
-            if not created_event_name:
-                created_event_name = base_created_event_cls.__name__
+                if not created_event_name:
+                    created_event_name = base_created_event_cls.__name__
 
-            # Disallow init method from having variable params if
-            # we are using it to define a "created" event class.
-            if init_method:
-                _raise_type_error_if_func_has_variable_params(init_method)
+                # Disallow init method from having variable params, because
+                # we are using it to define a "created" event class.
+                if init_method:
+                    _raise_type_error_if_func_has_variable_params(init_method)
 
-            # Define a "created" event class for this aggregate.
-            if issubclass(base_created_event_cls, base_event_cls):
                 # Don't subclass from base event class twice.
-                bases: tuple[type[CanMutateAggregate], ...] = (base_created_event_cls,)
-            else:
-                bases = (base_created_event_cls, base_event_cls)
-            created_event_class = cast(
-                "type[CanInitAggregate]",
-                cls._define_event_class(
-                    created_event_name,
-                    bases,
-                    init_method,
-                ),
-            )
-            # Set the event class as an attribute of the aggregate class.
-            setattr(cls, created_event_name, created_event_class)
+                assert isinstance(base_created_event_cls, type), base_created_event_cls
+                assert not issubclass(
+                    base_created_event_cls, base_event_cls
+                ), base_created_event_cls
+
+                # Define "created" event class.
+                assert created_event_name
+                assert issubclass(base_created_event_cls, CanInitAggregate)
+                created_event_class_bases = (base_created_event_cls, base_event_cls)
+                created_event_class = cast(
+                    "type[CanInitAggregate]",
+                    cls._define_event_class(
+                        created_event_name,
+                        created_event_class_bases,
+                        init_method,
+                    ),
+                )
+                # Set the event class as an attribute of the aggregate class.
+                setattr(cls, created_event_name, created_event_class)
+
+        assert created_event_class or len(created_event_classes) > 1
 
         if created_event_class:
             _created_event_classes[cls] = [created_event_class]
@@ -1318,16 +1370,18 @@ class BaseAggregate(metaclass=MetaAggregate):
             # Prepare to disallow ambiguity of choice between created event classes.
             _created_event_classes[cls] = list(created_event_classes.values())
 
-        # Prepare the subsequent event classes.
+        # Find and analyse any @event decorators.
         for attr_name, attr_value in tuple(cls.__dict__.items()):
             event_decorator: CommandMethodDecorator | None = None
 
-            if isinstance(attr_value, CommandMethodDecorator):
-                event_decorator = attr_value
-                if event_decorator.decorated_func.__name__ == "__init__":
-                    continue
+            # Ignore a decorator on the __init__ method.
+            if isinstance(attr_value, CommandMethodDecorator) and (
+                attr_value.decorated_func.__name__ == "__init__"
+            ):
+                continue
 
-            elif isinstance(attr_value, property) and isinstance(
+            # Handle @property.setter decorator on top of @event decorator.
+            if isinstance(attr_value, property) and isinstance(
                 attr_value.fset, CommandMethodDecorator
             ):
                 event_decorator = attr_value.fset
@@ -1355,6 +1409,9 @@ class BaseAggregate(metaclass=MetaAggregate):
                     )
                     raise TypeError(msg)
 
+            elif isinstance(attr_value, CommandMethodDecorator):
+                event_decorator = attr_value
+
             if event_decorator is not None:
                 if event_decorator.given_event_cls:
                     # Check this is not a "created" event class.
@@ -1404,7 +1461,7 @@ class BaseAggregate(metaclass=MetaAggregate):
                     "type[DecoratorEvent]", event_cls
                 )
 
-        # Check any create_id method defined on this class is static or class method.
+        # Check any create_id() method defined on this class is static or class method.
         if "create_id" in cls.__dict__ and not isinstance(
             cls.__dict__["create_id"], (staticmethod, classmethod)
         ):
@@ -1419,7 +1476,7 @@ class BaseAggregate(metaclass=MetaAggregate):
             if param.kind in [param.KEYWORD_ONLY, param.POSITIONAL_OR_KEYWORD]:
                 _create_id_param_names[cls].append(name)
 
-        # Define event classes for all events on bases.
+        # Define event classes for all events on all bases if not defined on this class.
         for aggregate_base_class in cls.__bases__:
             for name, value in aggregate_base_class.__dict__.items():
                 if (
@@ -1428,10 +1485,10 @@ class BaseAggregate(metaclass=MetaAggregate):
                     and name not in cls.__dict__
                     and name.lower() != name
                 ):
-                    sub_class = cls._define_event_class(
+                    event_class = cls._define_event_class(
                         name, (base_event_cls, value), None
                     )
-                    setattr(cls, name, sub_class)
+                    setattr(cls, name, event_class)
 
 
 class Aggregate(BaseAggregate):

{eventsourcing-9.4.0b3 → eventsourcing-9.4.1}/eventsourcing/postgres.py

@@ -766,6 +766,10 @@ class PostgresFactory(InfrastructureFactory[PostgresTrackingRecorder]):
                 "in environment with key "
                 f"'{self.POSTGRES_DBNAME}'"
             )
+            # TODO: Indicate both keys here, also for other environment variables.
+            # ) + " or ".join(
+            #   [f"'{key}'" for key in self.env.create_keys(self.POSTGRES_DBNAME)]
+            # )
             raise OSError(msg)
 
         host = self.env.get(self.POSTGRES_HOST)

{eventsourcing-9.4.0b3 → eventsourcing-9.4.1}/eventsourcing/projection.py

@@ -2,19 +2,22 @@ from __future__ import annotations
 
 import contextlib
 import os
+import threading
 import weakref
 from abc import ABC, abstractmethod
 from collections.abc import Iterator, Sequence
 from threading import Event, Thread
 from traceback import format_exc
-from typing import TYPE_CHECKING, Any, Generic, TypeVar
+from typing import TYPE_CHECKING, Any, ClassVar, Generic, TypeVar
 from warnings import warn
 
-from eventsourcing.application import Application
+from eventsourcing.application import Application, ProcessingEvent
 from eventsourcing.dispatch import singledispatchmethod
 from eventsourcing.domain import DomainEventProtocol
 from eventsourcing.persistence import (
     InfrastructureFactory,
+    IntegrityError,
+    ProcessRecorder,
     Tracking,
     TrackingRecorder,
     TTrackingRecorder,
@@ -43,7 +46,7 @@ class ApplicationSubscription(Iterator[tuple[DomainEventProtocol, Tracking]]):
         topics: Sequence[str] = (),
     ):
         """
-        Starts subscription to application's stored events using application's recorder.
+        Starts a subscription to application's recorder.
         """
         self.name = app.name
         self.recorder = app.recorder
@@ -51,7 +54,7 @@ class ApplicationSubscription(Iterator[tuple[DomainEventProtocol, Tracking]]):
         self.subscription = self.recorder.subscribe(gt=gt, topics=topics)
 
     def stop(self) -> None:
-        """Stops the stored event subscription."""
+        """Stops the subscription to the application's recorder."""
         self.subscription.stop()
 
     def __enter__(self) -> Self:
@@ -67,10 +70,11 @@ class ApplicationSubscription(Iterator[tuple[DomainEventProtocol, Tracking]]):
         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.
+        """Returns the next stored event from subscription to the application's
+        recorder. Constructs a tracking object that identifies the position of
+        the event in the application sequence. Constructs a domain event object
+        from the stored event object using the application's mapper. Returns a
+        tuple of the domain event object and the tracking object.
         """
         notification = next(self.subscription)
         tracking = Tracking(self.name, notification.id)
@@ -79,7 +83,8 @@ class ApplicationSubscription(Iterator[tuple[DomainEventProtocol, Tracking]]):
 
     def __del__(self) -> None:
         """Stops the stored event subscription."""
-        self.stop()
+        with contextlib.suppress(AttributeError):
+            self.stop()
 
 
 class Projection(ABC, Generic[TTrackingRecorder]):
@@ -90,14 +95,18 @@ class Projection(ABC, Generic[TTrackingRecorder]):
     """
     topics: tuple[str, ...] = ()
     """
-    Filter events in database when subscribing to an application.
+    Event topics, used to filter events in database when subscribing to an application.
     """
 
+    def __init_subclass__(cls, **kwargs: Any) -> None:
+        if "name" not in cls.__dict__:
+            cls.name = cls.__name__
+
     def __init__(
         self,
         view: TTrackingRecorder,
     ):
-        """Initialises a projection instance."""
+        """Initialises the view property with the given view argument."""
         self._view = view
 
     @property
@@ -113,63 +122,130 @@ class Projection(ABC, Generic[TTrackingRecorder]):
         """Process a domain event and track it."""
 
 
+class EventSourcedProjection(Application, ABC):
+    """Extends the :py:class:`~eventsourcing.application.Application` class
+    by using a process recorder as its application recorder, and by
+    processing domain events through its :py:func:`policy` method.
+    """
+
+    topics: ClassVar[Sequence[str]] = ()
+
+    def __init__(self, env: EnvType | None = None) -> None:
+        super().__init__(env)
+        self.recorder: ProcessRecorder
+        self.processing_lock = threading.Lock()
+
+    def construct_recorder(self) -> ProcessRecorder:
+        """Constructs and returns a :class:`~eventsourcing.persistence.ProcessRecorder`
+        for the application to use as its application recorder.
+        """
+        return self.factory.process_recorder()
+
+    def process_event(
+        self, domain_event: DomainEventProtocol, tracking: Tracking
+    ) -> None:
+        """Calls :func:`~eventsourcing.system.Follower.policy` method with
+        the given :class:`~eventsourcing.domain.AggregateEvent` and a
+        new :class:`~eventsourcing.application.ProcessingEvent` created from
+        the given :class:`~eventsourcing.persistence.Tracking` object.
+
+        The policy will collect any new aggregate events on the process
+        event object.
+
+        After the policy method returns, the process event object will
+        then be recorded by calling
+        :func:`~eventsourcing.application.Application.record`, which
+        will return new notifications.
+
+        After calling
+        :func:`~eventsourcing.application.Application.take_snapshots`,
+        the new notifications are passed to the
+        :func:`~eventsourcing.application.Application.notify` method.
+        """
+        processing_event = ProcessingEvent(tracking=tracking)
+        self.policy(domain_event, processing_event)
+        try:
+            recordings = self._record(processing_event)
+        except IntegrityError:
+            if self.recorder.has_tracking_id(
+                tracking.application_name,
+                tracking.notification_id,
+            ):
+                pass
+            else:
+                raise
+        else:
+            self._take_snapshots(processing_event)
+            self.notify(processing_event.events)
+            self._notify(recordings)
+
+    @singledispatchmethod
+    def policy(
+        self,
+        domain_event: DomainEventProtocol,
+        processing_event: ProcessingEvent,
+    ) -> None:
+        """Abstract domain event processing policy method. Must be
+        implemented by event processing applications. When
+        processing the given domain event, event processing
+        applications must use the :func:`~ProcessingEvent.collect_events`
+        method of the given :py:class:`~ProcessingEvent` object (not
+        the application's :func:`~eventsourcing.application.Application.save`
+        method) so that the new domain events will be recorded atomically
+        and uniquely with tracking information about the position of the processed
+        event in its application sequence.
+        """
+
+
 TApplication = TypeVar("TApplication", bound=Application)
+TEventSourcedProjection = TypeVar(
+    "TEventSourcedProjection", bound=EventSourcedProjection
+)
 
 
-class ProjectionRunner(Generic[TApplication, TTrackingRecorder]):
+class BaseProjectionRunner(Generic[TApplication]):
     def __init__(
         self,
         *,
+        projection: EventSourcedProjection | Projection[Any],
         application_class: type[TApplication],
-        projection_class: type[Projection[TTrackingRecorder]],
-        view_class: type[TTrackingRecorder],
+        tracking_recorder: TrackingRecorder,
+        topics: Sequence[str],
         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.
-        """
+    ) -> None:
+        self._projection = projection
         self._is_interrupted = Event()
         self._has_called_stop = False
 
+        # Construct the application.
         self.app: TApplication = application_class(env)
 
-        self.view = (
-            InfrastructureFactory[TTrackingRecorder]
-            .construct(
-                env=self._construct_env(
-                    name=projection_class.name or projection_class.__name__, env=env
-                )
-            )
-            .tracking_recorder(view_class)
-        )
+        self._tracking_recorder = tracking_recorder
 
-        self.projection = projection_class(
-            view=self.view,
-        )
-        self.subscription = ApplicationSubscription(
+        # Subscribe to the application.
+        self._subscription = ApplicationSubscription(
             app=self.app,
-            gt=self.view.max_tracking_id(self.app.name),
-            topics=self.projection.topics,
+            gt=self._tracking_recorder.max_tracking_id(self.app.name),
+            topics=topics,
         )
+
+        # Start a thread to stop the subscription when the runner is interrupted.
         self._thread_error: BaseException | None = None
         self._stop_thread = Thread(
             target=self._stop_subscription_when_stopping,
             kwargs={
-                "subscription": self.subscription,
+                "subscription": self._subscription,
                 "is_stopping": self._is_interrupted,
             },
         )
         self._stop_thread.start()
+
+        # Start a thread to iterate over the subscription.
         self._processing_thread = Thread(
             target=self._process_events_loop,
             kwargs={
-                "subscription": self.subscription,
-                "projection": self.projection,
+                "subscription": self._subscription,
+                "projection": self._projection,
                 "is_stopping": self._is_interrupted,
                 "runner": weakref.ref(self),
             },
@@ -180,7 +256,8 @@ class ProjectionRunner(Generic[TApplication, TTrackingRecorder]):
     def is_interrupted(self) -> Event:
         return self._is_interrupted
 
-    def _construct_env(self, name: str, env: EnvType | None = None) -> Environment:
+    @staticmethod
+    def _construct_env(name: str, env: EnvType | None = None) -> Environment:
         """Constructs environment from which projection will be configured."""
         _env: dict[str, str] = {}
         _env.update(os.environ)
@@ -210,10 +287,11 @@ class ProjectionRunner(Generic[TApplication, TTrackingRecorder]):
     @staticmethod
     def _process_events_loop(
         subscription: ApplicationSubscription,
-        projection: Projection[TrackingRecorder],
+        projection: EventSourcedProjection | Projection[Any],
         is_stopping: Event,
         runner: weakref.ReferenceType[ProjectionRunner[Application, TrackingRecorder]],
     ) -> None:
+        """Iterates over the subscription and calls process_event()."""
         try:
             with subscription:
                 for domain_event, tracking in subscription:
@@ -250,8 +328,8 @@ class ProjectionRunner(Generic[TApplication, TTrackingRecorder]):
         object that is greater than or equal to the given notification ID.
         """
         try:
-            self.projection.view.wait(
-                application_name=self.subscription.name,
+            self._tracking_recorder.wait(
+                application_name=self.app.name,
                 notification_id=notification_id,
                 timeout=timeout,
                 interrupt=self._is_interrupted,
@@ -287,3 +365,64 @@ class ProjectionRunner(Generic[TApplication, TTrackingRecorder]):
         """Calls stop()."""
         with contextlib.suppress(AttributeError):
             self.stop()
+
+
+class ProjectionRunner(
+    BaseProjectionRunner[TApplication], Generic[TApplication, TTrackingRecorder]
+):
+    def __init__(
+        self,
+        *,
+        application_class: type[TApplication],
+        projection_class: type[Projection[TTrackingRecorder]],
+        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.
+        """
+        # Construct the materialised view using an infrastructure factory.
+        self.view = (
+            InfrastructureFactory[TTrackingRecorder]
+            .construct(env=self._construct_env(name=projection_class.name, env=env))
+            .tracking_recorder(view_class)
+        )
+
+        # Construct the projection using the materialised view.
+        self.projection = projection_class(view=self.view)
+
+        super().__init__(
+            projection=self.projection,
+            application_class=application_class,
+            tracking_recorder=self.view,
+            topics=self.projection.topics,
+            env=env,
+        )
+
+
+class EventSourcedProjectionRunner(
+    BaseProjectionRunner[TApplication], Generic[TApplication, TEventSourcedProjection]
+):
+    def __init__(
+        self,
+        *,
+        application_class: type[TApplication],
+        projection_class: type[TEventSourcedProjection],
+        env: EnvType | None = None,
+    ):
+        self.projection: TEventSourcedProjection = projection_class(
+            env=self._construct_env(name=projection_class.name, env=env)
+        )
+
+        super().__init__(
+            projection=self.projection,
+            application_class=application_class,
+            tracking_recorder=self.projection.recorder,
+            topics=self.projection.topics,
+            env=env,
+        )

{eventsourcing-9.4.0b3 → eventsourcing-9.4.1}/eventsourcing/sqlite.py

@@ -472,6 +472,7 @@ class SQLiteApplicationRecorder(
     def subscribe(
         self, gt: int | None = None, topics: Sequence[str] = ()
     ) -> Subscription[ApplicationRecorder]:
+        """This method is not implemented on this class."""
         msg = f"The {type(self).__qualname__} recorder does not support subscriptions"
         raise NotImplementedError(msg)
 

{eventsourcing-9.4.0b3 → eventsourcing-9.4.1}/eventsourcing/system.py

@@ -6,26 +6,25 @@ import traceback
 from abc import ABC, abstractmethod
 from collections import defaultdict
 from queue import Full, Queue
+from types import FrameType, ModuleType
 from typing import TYPE_CHECKING, Any, ClassVar, Optional, Union, cast
 
+from eventsourcing.projection import EventSourcedProjection
+
 if TYPE_CHECKING:
     from collections.abc import Iterable, Iterator, Sequence
-    from types import FrameType, ModuleType
 
     from typing_extensions import Self
 
 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,
     Mapper,
     Notification,
     ProcessRecorder,
@@ -52,29 +51,25 @@ class RecordingEvent:
 ConvertingJob = Optional[Union[RecordingEvent, list[Notification]]]
 
 
-class Follower(Application):
-    """Extends the :class:`~eventsourcing.application.Application` class
-    by using a process recorder as its application recorder, by keeping
-    track of the applications it is following, and pulling and processing
-    new domain event notifications through its :func:`policy` method.
+class Follower(EventSourcedProjection):
+    """Extends the :class:`~eventsourcing.projection.EventSourcedProjection` class
+    by pulling notification objects from its notification log readers, by converting
+    the notification objects to domain events and tracking objects and by processing
+    the reconstructed domain event objects.
     """
 
-    follow_topics: ClassVar[Sequence[str]] = []
     pull_section_size = 10
 
+    def __init_subclass__(cls, **kwargs: Any) -> None:
+        super().__init_subclass__(**kwargs)
+        # for backwards compatibility, set "topics" if has "follow_topics".
+        cls.topics = getattr(cls, "follow_topics", cls.topics)
+
     def __init__(self, env: EnvType | None = None) -> None:
         super().__init__(env)
         self.readers: dict[str, NotificationLogReader] = {}
         self.mappers: dict[str, Mapper] = {}
-        self.recorder: ProcessRecorder
         self.is_threading_enabled = False
-        self.processing_lock = threading.Lock()
-
-    def construct_recorder(self) -> ProcessRecorder:
-        """Constructs and returns a :class:`~eventsourcing.persistence.ProcessRecorder`
-        for the application to use as its application recorder.
-        """
-        return self.factory.process_recorder()
 
     def follow(self, name: str, log: NotificationLog) -> None:
         """Constructs a notification log reader and a mapper for
@@ -107,6 +102,12 @@ class Follower(Application):
             ):
                 self.process_event(domain_event, tracking)
 
+    def process_event(
+        self, domain_event: DomainEventProtocol, tracking: Tracking
+    ) -> None:
+        with self.processing_lock:
+            super().process_event(domain_event, tracking)
+
     def pull_notifications(
         self,
         leader_name: str,
@@ -121,15 +122,15 @@ class Follower(Application):
         return self.readers[leader_name].select(
             start=start,
             stop=stop,
-            topics=self.follow_topics,
+            topics=self.topics,
             inclusive_of_start=inclusive_of_start,
         )
 
     def filter_received_notifications(
         self, notifications: list[Notification]
     ) -> list[Notification]:
-        if self.follow_topics:
-            return [n for n in notifications if n.topic in self.follow_topics]
+        if self.topics:
+            return [n for n in notifications if n.topic in self.topics]
         return notifications
 
     def convert_notifications(
@@ -151,64 +152,6 @@ class Follower(Application):
             processing_jobs.append((domain_event, tracking))
         return processing_jobs
 
-    # @retry(IntegrityError, max_attempts=50000, wait=0.01)
-    def process_event(
-        self, domain_event: DomainEventProtocol, tracking: Tracking
-    ) -> None:
-        """Calls :func:`~eventsourcing.system.Follower.policy` method with
-        the given :class:`~eventsourcing.domain.AggregateEvent` and a
-        new :class:`~eventsourcing.application.ProcessingEvent` created from
-        the given :class:`~eventsourcing.persistence.Tracking` object.
-
-        The policy will collect any new aggregate events on the process
-        event object.
-
-        After the policy method returns, the process event object will
-        then be recorded by calling
-        :func:`~eventsourcing.application.Application.record`, which
-        will return new notifications.
-
-        After calling
-        :func:`~eventsourcing.application.Application.take_snapshots`,
-        the new notifications are passed to the
-        :func:`~eventsourcing.application.Application.notify` method.
-        """
-        processing_event = ProcessingEvent(tracking=tracking)
-        with self.processing_lock:
-            self.policy(domain_event, processing_event)
-            try:
-                recordings = self._record(processing_event)
-            except IntegrityError:
-                if self.recorder.has_tracking_id(
-                    tracking.application_name,
-                    tracking.notification_id,
-                ):
-                    pass
-                else:
-                    raise
-            else:
-                self._take_snapshots(processing_event)
-                self.notify(processing_event.events)
-                self._notify(recordings)
-
-    @singledispatchmethod
-    def policy(
-        self,
-        domain_event: DomainEventProtocol,
-        processing_event: ProcessingEvent,
-    ) -> None:
-        """Abstract domain event processing policy method. Must be
-        implemented by event processing applications. When
-        processing the given domain event, event processing
-        applications must use the :func:`~ProcessingEvent.collect_events`
-        method of the given process event object (instead of
-        the application's :func:`~eventsourcing.application.Application.save`
-        method) to collect pending events from changed aggregates,
-        so that the new domain events will be recorded atomically
-        with tracking information about the position of the given
-        domain event's notification.
-        """
-
 
 class RecordingEventReceiver(ABC):
     """Abstract base class for objects that may receive recording events."""
@@ -279,8 +222,8 @@ class System:
         pipes: Iterable[Iterable[type[Application]]],
     ):
         # Remember the caller frame's module, so that we might identify a topic.
-        caller_frame = cast("FrameType", inspect.currentframe()).f_back
-        module = cast("ModuleType", inspect.getmodule(caller_frame))
+        caller_frame = cast(FrameType, inspect.currentframe()).f_back
+        module = cast(ModuleType, inspect.getmodule(caller_frame))
         type(self).__caller_modules[id(self)] = module  # noqa: SLF001
 
         # Build nodes and edges.
@@ -629,9 +572,9 @@ class NewSingleThreadedRunner(Runner, RecordingEventReceiver):
                                 follower = self.apps[follower_name]
                                 assert isinstance(follower, Follower)
                                 if (
-                                    follower.follow_topics
+                                    follower.topics
                                     and recording.notification.topic
-                                    not in follower.follow_topics
+                                    not in follower.topics
                                 ):
                                     continue
                                 follower.process_event(
@@ -1076,9 +1019,8 @@ class ConvertingThread(threading.Thread):
                     recording_event = recording_event_or_notifications
                     for recording in recording_event.recordings:
                         if (
-                            self.follower.follow_topics
-                            and recording.notification.topic
-                            not in self.follower.follow_topics
+                            self.follower.topics
+                            and recording.notification.topic not in self.follower.topics
                         ):
                             continue
                         tracking = Tracking(

eventsourcing-9.4.1/eventsourcing/tests/__init__.py

@@ -0,0 +1,3 @@
+import warnings
+
+warnings.resetwarnings()  # VS Code unittest runner somehow adds warning filters :-/

{eventsourcing-9.4.0b3 → eventsourcing-9.4.1}/eventsourcing/tests/persistence.py

@@ -450,8 +450,8 @@ class ApplicationRecorderTestCase(TestCase, ABC, Generic[_TApplicationRecorder])
         num_writers = 10
         num_writes_per_writer = 100
         num_events_per_write = 100
-        reader_sleep = 0.0
-        writer_sleep = 0.0
+        reader_sleep = 0.0001
+        writer_sleep = 0.0001
 
         def insert_events() -> None:
             thread_id = get_ident()

{eventsourcing-9.4.0b3 → eventsourcing-9.4.1}/pyproject.toml

@@ -1,16 +1,21 @@
-[tool.poetry]
-name = "eventsourcing"
-version = "9.4.0b3"
+[build-system]
+requires = ["poetry-core>=1.0.0"]
+build-backend = "poetry.core.masonry.api"
 
+[project]
+name = "eventsourcing"
+version = "9.4.1"
 description = "Event sourcing in Python"
+license = "BSD-3-Clause"
+readme = "README.md"
+requires-python = ">=3.9.2"
 authors = [
-    "John Bywater <john.bywater@appropriatesoftware.net>",
+    { "name" = "John Bywater", "email" = "john.bywater@appropriatesoftware.net" },
 ]
-license = "BSD 3-Clause"
 classifiers = [
 #    "Development Status :: 3 - Alpha",
-    "Development Status :: 4 - Beta",
-#    "Development Status :: 5 - Production/Stable",
+#    "Development Status :: 4 - Beta",
+    "Development Status :: 5 - Production/Stable",
     "Intended Audience :: Developers",
     "Intended Audience :: Education",
     "Intended Audience :: Science/Research",
@@ -25,10 +30,6 @@ classifiers = [
     "Programming Language :: Python",
     "Topic :: Software Development :: Libraries :: Python Modules",
 ]
-readme = "README.md"
-homepage = "https://github.com/pyeventsourcing/eventsourcing"
-repository = "https://github.com/pyeventsourcing/eventsourcing"
-include = ["eventsourcing/py.typed"]
 keywords=[
     "event sourcing",
     "event store",
@@ -38,18 +39,21 @@ keywords=[
     "cqrs",
     "cqs",
 ]
+dependencies = [
+  "typing_extensions",
+]
 
-[tool.poetry.dependencies]
-python = ">=3.9,<4.0,!=3.9.0,!=3.9.1"
-typing_extensions = "*"
-pycryptodome = { version = "~3.22", optional = true }
-cryptography = { version = "~44.0", optional = true }
-psycopg = { version = "<=3.2.99999", optional = true, extras=["pool"]}
+[project.optional-dependencies]
+crypto = ["pycryptodome>=3.22,<4.0"]
+cryptography = ["cryptography>=44.0,<45.0"]
+postgres = ["psycopg[pool]>=3.2,<3.3"]
 
-[tool.poetry.extras]
-crypto = ["pycryptodome"]
-cryptography = ["cryptography"]
-postgres = ["psycopg"]
+[project.urls]
+homepage = "https://github.com/pyeventsourcing/eventsourcing"
+repository = "https://github.com/pyeventsourcing/eventsourcing"
+
+[tool.poetry]
+include = ["eventsourcing/py.typed"]
 
 [tool.poetry.group.dev.dependencies]
 black = { version = "*", allow-prereleases = true }
@@ -57,7 +61,6 @@ coverage = "^7.2.7"
 isort = "*"
 mypy = "*"
 ruff = "*"
-psycopg = { version = "<=3.2.99999", extras = ["pool"] }
 psycopg-binary = "*"
 pyright = "*"
 
@@ -68,11 +71,6 @@ pydantic = { version = "~2.9"}
 autodoc_pydantic = "*"
 orjson = { version = "~3.10.11"}
 
-
-[build-system]
-requires = ["poetry-core>=1.0.0"]
-build-backend = "poetry.core.masonry.api"
-
 [tool.black]
 line-length = 88
 target-version = ["py39"]
@@ -177,6 +175,7 @@ ignore = [
     "C901",  # is too complex
     "TD002",  # Missing author in TODO
     "TD003",  # Missing issue line for this TODO
+    "TC006",  # Add quotes to type expression in `typing.cast()`
     "PLR0915",  # Too many statements
     "PLR0912", # Too many branches
     "S101", # Use of `assert` detected
@@ -200,6 +199,10 @@ dummy-variable-rgx = "^(_+|(_+[a-zA-Z0-9_]*[a-zA-Z0-9]+?))$"
 "*/sqlite.py" = [
     "S608",  # Possible SQL injection vector through string-based query construction
 ]
+"examples/shopstandard/domain.py" = [
+    "A002",
+]
+
 [tool.ruff.lint.flake8-type-checking]
 runtime-evaluated-base-classes = ["pydantic.BaseModel"]