eventsourcing 9.4.6__py3-none-any.whl → 9.5.0a0__py3-none-any.whl

eventsourcing/domain.py

@@ -32,6 +32,7 @@ from warnings import warn
 
 from eventsourcing.utils import (
     TopicError,
+    construct_topic,
     get_method_name,
     get_topic,
     register_topic,
@@ -369,7 +370,7 @@ class CanInitAggregate(CanMutateAggregate[TAggregateID]):
 
         # Pick out event attributes for the aggregate base class init method.
         self_dict = self._as_dict()
-        base_kwargs = _filter_kwargs_for_method_params(
+        base_kwargs = filter_kwargs_for_method_params(
             self_dict, type(agg).__base_init__
         )
 
@@ -378,7 +379,7 @@ class CanInitAggregate(CanMutateAggregate[TAggregateID]):
         agg.__base_init__(**base_kwargs)
 
         # Pick out event attributes for aggregate subclass class init method.
-        init_kwargs = _filter_kwargs_for_method_params(self_dict, type(agg).__init__)
+        init_kwargs = filter_kwargs_for_method_params(self_dict, type(agg).__init__)
 
         # Provide the aggregate id, if the __init__ method expects it.
         if aggregate_class in _init_mentions_id:
@@ -459,7 +460,7 @@ class LogEvent(DomainEvent):
     """
 
 
-def _filter_kwargs_for_method_params(
+def filter_kwargs_for_method_params(
     kwargs: dict[str, Any], method: Callable[..., Any]
 ) -> dict[str, Any]:
     names = _spec_filter_kwargs_for_method_params(method)
@@ -472,8 +473,14 @@ def _spec_filter_kwargs_for_method_params(method: Callable[..., Any]) -> set[str
     return set(method_signature.parameters)
 
 
+class AbstractDCBEvent:
+    pass
+
+
 if TYPE_CHECKING:
-    EventSpecType = Union[str, type[CanMutateAggregate[Any]]]
+    EventSpecType = Union[  # noqa: PYI055
+        str, type[CanMutateAggregate[Any]], type[AbstractDCBEvent]
+    ]
 
 CallableType = Callable[..., None]
 DecoratableType = Union[CallableType, property]
@@ -488,7 +495,9 @@ class CommandMethodDecorator:
         event_topic: str | None = None,
     ):
         self.is_name_inferred_from_method = False
-        self.given_event_cls: type[CanMutateAggregate[Any]] | None = None
+        self.given_event_cls: (
+            type[CanMutateAggregate[Any] | AbstractDCBEvent] | None
+        ) = None
         self.event_cls_name: str | None = None
         self.decorated_property: property | None = None
         self.is_property_setter = False
@@ -505,9 +514,13 @@ class CommandMethodDecorator:
 
         # Event class has been specified.
         elif isinstance(event_spec, type) and issubclass(
-            event_spec, CanMutateAggregate
+            event_spec, (CanMutateAggregate, AbstractDCBEvent)
         ):
-            if event_spec in _given_event_classes:
+            # Guard against associating more than one method body with any given class.
+            if (
+                issubclass(event_spec, CanMutateAggregate)
+                and event_spec in _given_event_classes
+            ):
                 name = event_spec.__name__
                 msg = f"{name} event class used in more than one decorator"
                 raise TypeError(msg)
@@ -551,6 +564,10 @@ class CommandMethodDecorator:
             # Remember the decorated obj as the decorated method.
             self.decorated_func = decorated_obj
 
+            if self.decorated_func.__name__ == "_":
+                underscore_method_decorators.append(
+                    (construct_topic(self.decorated_func), self)
+                )
             # If necessary, derive an event class name from the method.
             if not self.given_event_cls and not self.event_cls_name:
                 original_method_name = self.decorated_func.__name__
@@ -608,6 +625,10 @@ class CommandMethodDecorator:
         self, instance: BaseAggregate[Any] | None, owner: type[BaseAggregate[Any]]
     ) -> BoundCommandMethodDecorator | UnboundCommandMethodDecorator | property | Any:
         """Descriptor protocol for getting decorated method or property."""
+        if self.decorated_func.__name__ == "_":
+            msg = "Underscore 'non-command' methods cannot be used to trigger events."
+            raise ProgrammingError(msg)
+
         # If we are decorating a property, then delegate to the property's __get__.
         if self.decorated_property:
             return self.decorated_property.__get__(instance, owner)
@@ -620,6 +641,12 @@ class CommandMethodDecorator:
         if instance:
             return BoundCommandMethodDecorator(self, instance)
 
+        if "SPHINX_BUILD" in os.environ:  # pragma: no cover
+            # Sphinx hack: use the original function when sphinx is running so that the
+            # documentation ends up with the correct function signatures.
+            # See 'SPHINX_BUILD' in conf.py.
+            return self.decorated_func
+
         # Return an "unbound" command method decorator if we have no instance.
         return UnboundCommandMethodDecorator(self)
 
@@ -639,7 +666,7 @@ def event(arg: TDecoratableType, /) -> TDecoratableType:
 
 @overload
 def event(
-    arg: type[CanMutateAggregate[Any]], /
+    arg: type[CanMutateAggregate[Any] | AbstractDCBEvent], /
 ) -> Callable[[TDecoratableType], TDecoratableType]:
     """Signature for calling ``@event`` decorator with event class."""
 
@@ -720,7 +747,10 @@ def event(
     if (
         arg is None
         or isinstance(arg, str)
-        or (isinstance(arg, type) and issubclass(arg, CanMutateAggregate))
+        or (
+            isinstance(arg, type)
+            and issubclass(arg, (CanMutateAggregate, AbstractDCBEvent))
+        )
     ):
         event_spec = arg
 
@@ -773,14 +803,22 @@ class UnboundCommandMethodDecorator:
         )
 
 
+class CanTriggerEvent(Protocol):
+    def trigger_event(
+        self,
+        event_class: type[Any],
+        **kwargs: Any,
+    ) -> None:
+        pass  # pragma: no cover
+
+
 class BoundCommandMethodDecorator:
-    """Binds a CommandMethodDecorator with an aggregate instance so calls to
-    decorated command methods can be intercepted and will trigger an event.
+    """Binds a CommandMethodDecorator with an object instance that can trigger
+    events, so that calls to decorated command methods can be intercepted and
+    will trigger a "decorated func caller" event.
     """
 
-    def __init__(
-        self, event_decorator: CommandMethodDecorator, aggregate: BaseAggregate[Any]
-    ):
+    def __init__(self, event_decorator: CommandMethodDecorator, obj: CanTriggerEvent):
         """:param CommandMethodDecorator event_decorator:
         :param Aggregate aggregate:
         """
@@ -790,29 +828,41 @@ class BoundCommandMethodDecorator:
         self.__qualname__ = event_decorator.decorated_func.__qualname__
         self.__annotations__ = event_decorator.decorated_func.__annotations__
         self.__doc__ = event_decorator.decorated_func.__doc__
-        self.aggregate = aggregate
+        self.obj = obj
 
     def trigger(self, *args: Any, **kwargs: Any) -> None:
         kwargs = _coerce_args_to_kwargs(
             self.event_decorator.decorated_func, args, kwargs
         )
-        event_cls = decorator_event_classes[self.event_decorator]
-        kwargs = _filter_kwargs_for_method_params(kwargs, event_cls)
-        self.aggregate.trigger_event(event_cls, **kwargs)
+        try:
+            event_cls = decorated_func_callers[self.event_decorator]
+        except KeyError as e:  # pragma: no cover
+            msg = (
+                f"Event class not registered for event decorator on "
+                f"{self.event_decorator.decorated_func.__qualname__}"
+            )
+            raise KeyError(msg) from e
+        kwargs = filter_kwargs_for_method_params(kwargs, event_cls)
+        assert issubclass(event_cls, AbstractDecoratedFuncCaller), event_cls
+        self.obj.trigger_event(event_cls, **kwargs)
 
     def __call__(self, *args: Any, **kwargs: Any) -> None:
         self.trigger(*args, **kwargs)
 
 
-class DecoratorEvent(CanMutateAggregate[Any]):
+class AbstractDecoratedFuncCaller:
+    pass
+
+
+class DecoratedFuncCaller(CanMutateAggregate[Any], AbstractDecoratedFuncCaller):
     def apply(self, aggregate: BaseAggregate[Any]) -> None:
         """Applies event to aggregate by calling method decorated by @event."""
         # Identify the function that was decorated.
-        decorated_func = _decorated_funcs[type(self)]
+        decorated_func = decorated_funcs[type(self)]
 
         # Select event attributes mentioned in function signature.
         self_dict = self._as_dict()
-        kwargs = _filter_kwargs_for_method_params(self_dict, decorated_func)
+        kwargs = filter_kwargs_for_method_params(self_dict, decorated_func)
 
         # Call the original method with event attribute values.
         decorated_method = decorated_func.__get__(aggregate, type(aggregate))
@@ -822,12 +872,22 @@ class DecoratorEvent(CanMutateAggregate[Any]):
         super().apply(aggregate)
 
 
-_given_event_classes: set[type] = set()
-_decorated_funcs: dict[type, CallableType] = {}
+# This helps enforce single usage of original event classes in decorators.
+_given_event_classes = set[type]()
+
+# This keeps track of the "created" event classes for an aggregate.
 _created_event_classes: dict[type, list[type[CanInitAggregate[Any]]]] = {}
 
+# This remembers which event class to trigger when a decorated method is called.
+decorated_func_callers: dict[
+    CommandMethodDecorator, type[AbstractDecoratedFuncCaller]
+] = {}
+
+# This remembers which decorated func a decorated func caller should call.
+decorated_funcs: dict[type, CallableType] = {}
 
-decorator_event_classes: dict[CommandMethodDecorator, type[DecoratorEvent]] = {}
+# This keeps track of decorated "non-command" projection-only methods called "_".
+underscore_method_decorators: list[tuple[str, CommandMethodDecorator]] = []
 
 
 def _raise_type_error_if_func_has_variable_params(method: CallableType) -> None:
@@ -1613,7 +1673,7 @@ class BaseAggregate(Generic[TAggregateID], metaclass=MetaAggregate):
                     #  the subclassing of events above? Maybe do this first?
                     event_cls = cls._define_event_class(
                         event_decorator.given_event_cls.__name__,
-                        (DecoratorEvent, given_subclass),
+                        (DecoratedFuncCaller, given_subclass),
                         None,
                     )
 
@@ -1634,20 +1694,20 @@ class BaseAggregate(Generic[TAggregateID], metaclass=MetaAggregate):
                     # Define event class from signature of original method.
                     event_cls = cls._define_event_class(
                         event_decorator.event_cls_name,
-                        (DecoratorEvent, base_event_cls),
+                        (DecoratedFuncCaller, base_event_cls),
                         event_decorator.decorated_func,
                         event_topic=event_decorator.event_topic,
                     )
 
                 # Cache the decorated method for the event class to use.
-                _decorated_funcs[event_cls] = event_decorator.decorated_func
+                decorated_funcs[event_cls] = event_decorator.decorated_func
 
                 # Set the event class as an attribute of the aggregate class.
                 setattr(cls, event_cls.__name__, event_cls)
 
                 # Remember which event class to trigger.
-                decorator_event_classes[event_decorator] = cast(
-                    "type[DecoratorEvent]", event_cls
+                decorated_func_callers[event_decorator] = cast(
+                    type[DecoratedFuncCaller], event_cls
                 )
 
         # Check any create_id() method defined on this class is static or class method.

eventsourcing/persistence.py

@@ -13,10 +13,10 @@ from queue import Queue
 from threading import Condition, Event, Lock, Semaphore, Thread, Timer
 from time import monotonic, sleep, time
 from types import GenericAlias, ModuleType
-from typing import TYPE_CHECKING, Any, Callable, Generic, Union, cast
+from typing import Any, Callable, Generic, Union, cast
 from uuid import UUID
 
-from typing_extensions import TypeVar
+from typing_extensions import Self, TypeVar
 
 from eventsourcing.domain import (
     DomainEventProtocol,
@@ -33,9 +33,6 @@ from eventsourcing.utils import (
     strtobool,
 )
 
-if TYPE_CHECKING:
-    from typing_extensions import Self
-
 
 class Transcoding(ABC):
     """Abstract base class for custom transcodings."""
@@ -679,14 +676,14 @@ class InfrastructureFactory(ABC, Generic[TTrackingRecorder]):
 
     @classmethod
     def construct(
-        cls: type[InfrastructureFactory[TTrackingRecorder]],
+        cls: type[Self],
         env: Environment | None = None,
-    ) -> InfrastructureFactory[TTrackingRecorder]:
+    ) -> Self:
         """Constructs concrete infrastructure factory for given
         named application. Reads and resolves persistence
         topic from environment variable 'PERSISTENCE_MODULE'.
         """
-        factory_cls: type[InfrastructureFactory[TTrackingRecorder]]
+        factory_cls: type[Self]
         if env is None:
             env = Environment()
         topic = (
@@ -705,9 +702,7 @@ class InfrastructureFactory(ABC, Generic[TTrackingRecorder]):
             or "eventsourcing.popo"
         )
         try:
-            obj: type[InfrastructureFactory[TTrackingRecorder]] | ModuleType = (
-                resolve_topic(topic)
-            )
+            obj: type[Self] | ModuleType = resolve_topic(topic)
         except TopicError as e:
             msg = (
                 "Failed to resolve persistence module topic: "
@@ -718,29 +713,29 @@ class InfrastructureFactory(ABC, Generic[TTrackingRecorder]):
 
         if isinstance(obj, ModuleType):
             # Find the factory in the module.
-            factory_classes: list[type[InfrastructureFactory[TTrackingRecorder]]] = []
+            factory_classes = set[type[Self]]()
             for member in obj.__dict__.values():
-                if (
-                    member is not InfrastructureFactory
-                    and isinstance(member, type)  # Look for classes...
-                    and isinstance(member, type)  # Look for classes...
-                    and not isinstance(
-                        member, GenericAlias
-                    )  # Issue with Python 3.9 and 3.10.
-                    and issubclass(member, InfrastructureFactory)  # Ignore base class.
-                    and member not in factory_classes  # Forgive aliases.
-                ):
-                    factory_classes.append(member)
+                # Look for classes...
+                if not isinstance(member, type):
+                    continue
+                # Issue with Python 3.9 and 3.10.
+                if isinstance(member, GenericAlias):
+                    continue  # pragma: no cover (for Python > 3.10 only)
+                if not issubclass(member, cls):
+                    continue
+                if getattr(member, "__parameters__", None):
+                    continue
+                factory_classes.add(member)
 
             if len(factory_classes) == 1:
-                factory_cls = factory_classes[0]
+                factory_cls = next(iter(factory_classes))
             else:
                 msg = (
                     f"Found {len(factory_classes)} infrastructure factory classes in"
                     f" '{topic}', expected 1."
                 )
                 raise InfrastructureFactoryError(msg)
-        elif isinstance(obj, type) and issubclass(obj, InfrastructureFactory):
+        elif isinstance(obj, type) and issubclass(obj, cls):
             factory_cls = obj
         else:
             msg = (

eventsourcing/popo.py

@@ -2,7 +2,7 @@ from __future__ import annotations
 
 import contextlib
 from collections import defaultdict
-from threading import Event, Lock
+from threading import Event, RLock
 from typing import TYPE_CHECKING, Any
 
 from eventsourcing.persistence import (
@@ -27,7 +27,7 @@ if TYPE_CHECKING:
 
 class POPORecorder:
     def __init__(self) -> None:
-        self._database_lock = Lock()
+        self._database_lock = RLock()
 
 
 class POPOAggregateRecorder(POPORecorder, AggregateRecorder):