eventsourcing 9.4.5__tar.gz → 9.5.0a0__tar.gz

{eventsourcing-9.4.5 → eventsourcing-9.5.0a0}/PKG-INFO

@@ -1,13 +1,13 @@
 Metadata-Version: 2.3
 Name: eventsourcing
-Version: 9.4.5
+Version: 9.5.0a0
 Summary: Event sourcing in Python
 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
-Classifier: Development Status :: 5 - Production/Stable
+Classifier: Development Status :: 3 - Alpha
 Classifier: Intended Audience :: Developers
 Classifier: Intended Audience :: Education
 Classifier: Intended Audience :: Science/Research

{eventsourcing-9.4.5 → eventsourcing-9.5.0a0}/eventsourcing/application.py

@@ -54,6 +54,8 @@ from eventsourcing.utils import Environment, EnvType, strtobool
 if TYPE_CHECKING:
     from uuid import UUID
 
+    from typing_extensions import Self
+
 ProjectorFunction = Callable[
     [Optional[TMutableOrImmutableAggregate], Iterable[TDomainEvent]],
     Optional[TMutableOrImmutableAggregate],
@@ -279,6 +281,7 @@ class Repository(Generic[TAggregateID]):
                 if self.fastforward:
                     # Fast-forward cached aggregate.
                     fastforward_lock = self._use_fastforward_lock(aggregate_id)
+                    # TODO: Should this be 'fastforward or self.fastforward_skipping'?
                     blocking = not (fastforward_skipping or self.fastforward_skipping)
                     try:
                         if fastforward_lock.acquire(blocking=blocking):
@@ -635,6 +638,7 @@ class Application(Generic[TAggregateID]):
         a :class:`~eventsourcing.application.Repository`, and
         a :class:`~eventsourcing.application.LocalNotificationLog`.
         """
+        self.closing = Event()
         self.env = self.construct_env(self.name, env)  # type: ignore[misc]
         self.factory = self.construct_factory(self.env)
         self.mapper: Mapper[TAggregateID] = self.construct_mapper()
@@ -645,7 +649,6 @@ class Application(Generic[TAggregateID]):
             self.snapshots = self.construct_snapshot_store()
         self._repository: Repository[TAggregateID] = self.construct_repository()
         self._notification_log = self.construct_notification_log()
-        self.closing = Event()
 
     @property
     def repository(self) -> Repository[TAggregateID]:
@@ -663,7 +666,7 @@ class Application(Generic[TAggregateID]):
     @property
     def log(self) -> LocalNotificationLog:
         warn(
-            "'log' is deprecated, use 'notifications' instead",
+            "'log' is deprecated, use 'notification_log' instead",
             DeprecationWarning,
             stacklevel=2,
         )
@@ -840,7 +843,7 @@ class Application(Generic[TAggregateID]):
                 "application class."
             )
             raise AssertionError(msg)
-        aggregate: BaseAggregate[UUID | str] = self.repository.get(
+        aggregate: BaseAggregate[TAggregateID] = self.repository.get(
             aggregate_id, version=version, projector_func=projector_func
         )
         snapshot_class = getattr(type(aggregate), "Snapshot", type(self).snapshot_class)
@@ -875,6 +878,16 @@ class Application(Generic[TAggregateID]):
         self.closing.set()
         self.factory.close()
 
+    def __enter__(self) -> Self:
+        return self
+
+    def __exit__(self, *args: object, **kwargs: Any) -> None:
+        self.close()
+
+    def __del__(self) -> None:
+        with contextlib.suppress(AttributeError):
+            self.close()
+
 
 TApplication = TypeVar("TApplication", bound=Application[Any])
 

eventsourcing-9.5.0a0/eventsourcing/dcb/api.py

@@ -0,0 +1,65 @@
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+from dataclasses import dataclass, field
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from collections.abc import Sequence
+
+
+@dataclass
+class DCBQueryItem:
+    types: list[str] = field(default_factory=list)
+    tags: list[str] = field(default_factory=list)
+
+
+@dataclass
+class DCBQuery:
+    items: list[DCBQueryItem] = field(default_factory=list)
+
+
+@dataclass
+class DCBAppendCondition:
+    fail_if_events_match: DCBQuery = field(default_factory=DCBQuery)
+    after: int | None = None
+
+
+@dataclass
+class DCBEvent:
+    type: str
+    data: bytes
+    tags: list[str] = field(default_factory=list)
+
+
+@dataclass
+class DCBSequencedEvent:
+    event: DCBEvent
+    position: int
+
+
+class DCBRecorder(ABC):
+
+    @abstractmethod
+    def read(
+        self,
+        query: DCBQuery | None = None,
+        *,
+        after: int | None = None,
+        limit: int | None = None,
+    ) -> tuple[Sequence[DCBSequencedEvent], int | None]:
+        """
+        Returns all events, unless 'after' is given then only those with position
+        greater than 'after', and unless any query items are given, then only those
+        that match at least one query item. An event matches a query item if its type
+        is in the item types or there are no item types, and if all the item tags are
+        in the event tags.
+        """
+
+    @abstractmethod
+    def append(
+        self, events: Sequence[DCBEvent], condition: DCBAppendCondition | None = None
+    ) -> int:
+        """
+        Appends given events to the event store, unless the condition fails.
+        """

eventsourcing-9.5.0a0/eventsourcing/dcb/application.py

@@ -0,0 +1,116 @@
+from __future__ import annotations
+
+import os
+from typing import TYPE_CHECKING, Any, ClassVar
+
+from eventsourcing.dcb.domain import (
+    CanInitialiseEnduringObject,
+    CanMutateEnduringObject,
+    EnduringObject,
+    Perspective,
+    Selector,
+)
+from eventsourcing.dcb.persistence import (
+    DCBEventStore,
+    DCBInfrastructureFactory,
+    NotFoundError,
+    TGroup,
+)
+from eventsourcing.utils import Environment, EnvType
+
+if TYPE_CHECKING:
+    from collections.abc import Sequence
+
+    from typing_extensions import Self
+
+
+class DCBApplication:
+    name = "DCBApplication"
+    env: ClassVar[dict[str, str]] = {"PERSISTENCE_MODULE": "eventsourcing.dcb.popo"}
+
+    def __init_subclass__(cls, **kwargs: Any) -> None:
+        if "name" not in cls.__dict__:
+            cls.name = cls.__name__
+
+    def __init__(self, env: EnvType | None = None):
+        self.env = self.construct_env(self.name, env)  # type: ignore[misc]
+        self.factory = DCBInfrastructureFactory.construct(self.env)
+        self.recorder = self.factory.dcb_event_store()
+
+    def construct_env(self, name: str, env: EnvType | None = None) -> Environment:
+        """Constructs environment from which application will be configured."""
+        _env = dict(type(self).env)
+        _env.update(os.environ)
+        if env is not None:
+            _env.update(env)
+        return Environment(name, _env)
+
+    def __enter__(self) -> Self:
+        return self
+
+    def __exit__(self, *args: object, **kwargs: Any) -> None:
+        self.factory.close()
+
+
+class DCBRepository:
+    def __init__(self, eventstore: DCBEventStore):
+        self.eventstore = eventstore
+
+    def save(self, obj: Perspective) -> int:
+        new_events = obj.collect_events()
+        return self.eventstore.put(
+            *new_events, cb=obj.cb, after=obj.last_known_position
+        )
+
+    def get(
+        self,
+        enduring_object_id: str,
+        cb_types: Sequence[type[CanMutateEnduringObject]] = (),
+    ) -> EnduringObject:
+        cb = [Selector(tags=[enduring_object_id], types=cb_types)]
+        events, head = self.eventstore.get(*cb, with_last_position=True)
+        obj: EnduringObject | None = None
+        for event in events:
+            obj = event.mutate(obj)
+        if obj is None:
+            raise NotFoundError
+        obj.last_known_position = head
+        obj.cb_types = cb_types
+        return obj
+
+    def get_many(
+        self,
+        *enduring_object_ids: str,
+        cb_types: Sequence[type[CanMutateEnduringObject]] = (),
+    ) -> list[EnduringObject | None]:
+        cb = [
+            Selector(tags=[enduring_object_id], types=cb_types)
+            for enduring_object_id in enduring_object_ids
+        ]
+        events, head = self.eventstore.get(cb, with_last_position=True)
+        objs: dict[str, EnduringObject | None] = dict.fromkeys(enduring_object_ids)
+        for event in events:
+            for tag in event.tags:
+                obj = objs.get(tag)
+                if not isinstance(event, CanInitialiseEnduringObject) and not obj:
+                    continue
+                obj = event.mutate(obj)
+                objs[tag] = obj
+        for obj in objs.values():
+            if obj is not None:
+                obj.last_known_position = head
+                obj.cb_types = cb_types
+        return list(objs.values())
+
+    def get_group(self, cls: type[TGroup], *enduring_object_ids: str) -> TGroup:
+        enduring_objects = self.get_many(*enduring_object_ids, cb_types=cls.cb_types)
+        perspective = cls(*enduring_objects)
+        last_known_positions = [
+            o.last_known_position
+            for o in enduring_objects
+            if o and o.last_known_position
+        ]
+        perspective.last_known_position = (
+            max(last_known_positions) if last_known_positions else None
+        )
+        return perspective

eventsourcing-9.5.0a0/eventsourcing/dcb/domain.py

@@ -0,0 +1,381 @@
+from __future__ import annotations
+
+import sys
+from dataclasses import dataclass
+from typing import TYPE_CHECKING, Any, TypeVar, cast
+from uuid import uuid4
+
+from typing_extensions import Self
+
+from eventsourcing.domain import (
+    AbstractDCBEvent,
+    AbstractDecoratedFuncCaller,
+    CallableType,
+    CommandMethodDecorator,
+    ProgrammingError,
+    decorated_func_callers,
+    decorated_funcs,
+    filter_kwargs_for_method_params,
+    underscore_method_decorators,
+)
+from eventsourcing.persistence import IntegrityError
+from eventsourcing.utils import construct_topic, get_topic, resolve_topic
+
+if TYPE_CHECKING:
+    from collections.abc import Sequence
+
+_enduring_object_init_classes: dict[type[Any], type[CanInitialiseEnduringObject]] = {}
+
+
+class CanMutateEnduringObject(AbstractDCBEvent):
+    tags: list[str]
+
+    def _as_dict(self) -> dict[str, Any]:
+        raise NotImplementedError  # pragma: no cover
+
+    def mutate(self, obj: EnduringObject | None) -> EnduringObject | None:
+        assert obj is not None
+        self.apply(obj)
+        return obj
+
+    def apply(self, obj: Any) -> None:
+        pass
+
+
+class CanInitialiseEnduringObject(CanMutateEnduringObject):
+    originator_topic: str
+
+    def mutate(self, obj: EnduringObject | None) -> EnduringObject | None:
+        kwargs = self._as_dict()
+        originator_topic = resolve_topic(kwargs.pop("originator_topic"))
+        enduring_object_cls = cast(type[EnduringObject], originator_topic)
+        enduring_object_id = kwargs.pop(self.id_attr_name(enduring_object_cls))
+        kwargs.pop("tags")
+        try:
+            enduring_object = type.__call__(enduring_object_cls, **kwargs)
+        except TypeError as e:
+            msg = (
+                f"{type(self).__qualname__} cannot __init__ "
+                f"{enduring_object_cls.__qualname__} "
+                f"with kwargs {kwargs}: {e}"
+            )
+            raise TypeError(msg) from e
+        enduring_object.id = enduring_object_id
+        enduring_object.__post_init__()
+        return enduring_object
+
+    @classmethod
+    def id_attr_name(cls, enduring_object_class: type[EnduringObject]) -> str:
+        return f"{enduring_object_class.__name__.lower()}_id"
+
+
+class DecoratedFuncCaller(CanMutateEnduringObject, AbstractDecoratedFuncCaller):
+    def apply(self, obj: EnduringObject) -> None:
+        """Applies event by calling method decorated by @event."""
+
+        event_class_topic = construct_topic(type(self))
+
+        # Identify the function that was decorated.
+        try:
+            # Either an "underscore" non-command method.
+            decorated_func_collection = cross_cutting_decorated_funcs[event_class_topic]
+            assert type(obj) in decorated_func_collection
+            decorated_func = decorated_func_collection[type(obj)]
+
+        except KeyError:
+            # Or a normal command method.
+            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)
+
+        # Call the original method with event attribute values.
+        decorated_method = decorated_func.__get__(obj, type(obj))
+        decorated_method(**kwargs)
+
+        # Call super method, just in case.
+        super().apply(obj)
+
+
+T = TypeVar("T")
+
+
+class MetaPerspective(type):
+    pass
+
+
+class Perspective(metaclass=MetaPerspective):
+    last_known_position: int | None
+    cb_types: Sequence[type[CanMutateEnduringObject]] = ()
+    new_decisions: tuple[CanMutateEnduringObject, ...]
+
+    def __new__(cls, *_: Any, **__: Any) -> Self:
+        perspective = super().__new__(cls)
+        perspective.last_known_position = None
+        perspective.cb_types = cls.cb_types
+        perspective.new_decisions = ()
+        return perspective
+
+    def collect_events(self) -> Sequence[CanMutateEnduringObject]:
+        collected, self.new_decisions = self.new_decisions, ()
+        return collected
+
+    @property
+    def cb(self) -> list[Selector]:
+        raise NotImplementedError  # pragma: no cover
+
+    def check_cb_types(self, decision_cls: type[CanMutateEnduringObject]) -> None:
+        if self.cb_types and decision_cls not in self.cb_types:
+            msg = (
+                f"Decision type {decision_cls.__qualname__} "
+                f"not in consistency boundary types: {self.cb_types}"
+            )
+            raise IntegrityError(msg)
+
+
+cross_cutting_event_classes: dict[str, type[CanMutateEnduringObject]] = {}
+cross_cutting_decorated_funcs: dict[str, dict[type, CallableType]] = {}
+
+
+class MetaEnduringObject(MetaPerspective):
+    def __init__(
+        cls, name: str, bases: tuple[type, ...], namespace: dict[str, Any]
+    ) -> None:
+        super().__init__(name, bases, namespace)
+        # Find and remember the "initialised" class.
+        for item in cls.__dict__.values():
+            if isinstance(item, type) and issubclass(item, CanInitialiseEnduringObject):
+                _enduring_object_init_classes[cls] = item
+                break
+
+        # Process the event decorators.
+        for attr, value in namespace.items():
+            if isinstance(value, CommandMethodDecorator):
+                if attr == "_":
+                    # Deal with cross-cutting events later.
+                    continue
+
+                event_class = value.given_event_cls
+                # Just keep things simple by only supporting given classes (not names).
+                assert event_class is not None, "Event class not given"
+                assert issubclass(event_class, CanMutateEnduringObject)
+                # TODO: Maybe support event name strings, maybe not....
+                event_class_qual = event_class.__qualname__
+
+                # Keep things simple by only supporting nested classes.
+                assert event_class_qual.startswith(cls.__qualname__ + ".")
+                assert cls.__dict__[event_class.__name__] is event_class
+
+                # Subclass given class to make a "decorator class".
+                event_subclass_dict = {
+                    "__module__": cls.__module__,
+                    "__qualname__": event_class_qual,
+                }
+
+                subclass_name = event_class.__name__
+                event_subclass = cast(
+                    type[DecoratedFuncCaller],
+                    type(
+                        subclass_name,
+                        (DecoratedFuncCaller, event_class),
+                        event_subclass_dict,
+                    ),
+                )
+                # Update the enduring object class dict.
+                setattr(cls, event_class.__name__, event_subclass)
+                # Remember which event class to trigger when method is called.
+                decorated_func_callers[value] = event_subclass
+                # Remember which method body to execute when event is applied.
+                decorated_funcs[event_subclass] = value.decorated_func
+
+        # Deal with cross-cutting events.
+        enduring_object_class_topic = construct_topic(cls)
+        for topic, decorator in underscore_method_decorators:
+            if topic.startswith(enduring_object_class_topic):
+
+                event_class = decorator.given_event_cls
+                # Keep things simple by only supporting given classes (not names).
+                # TODO: Maybe support event name strings, maybe not....
+                assert event_class is not None, "Event class not given"
+                # Make sure event decorator has a CanMutateEnduringObject class.
+                assert issubclass(event_class, CanMutateEnduringObject)
+
+                # Assume this is a cross-cutting event, and we need to register
+                # multiple handler methods for the same class. Expect its mutate
+                # method will be called once for each enduring object tagged in
+                # its instances. The decorator event can then select which
+                # method body to call, according to the 'obj' argument of its
+                # apply() method. This means we do need to subclass the given
+                # event once only.
+                event_class_topic = construct_topic(event_class)
+                if event_class_topic not in cross_cutting_event_classes:
+                    # Subclass the cross-cutting event class once only.
+                    #  - keep things simple by only supporting non-nested classes
+                    event_class_qual = event_class.__qualname__
+                    assert (
+                        "." not in event_class_qual
+                    ), "Nested cross-cutting classes aren't supported"
+                    # Get the global namespace for the event class.
+                    event_class_globalns = getattr(
+                        sys.modules.get(event_class.__module__, None),
+                        "__dict__",
+                        {},
+                    )
+                    assert event_class_qual in event_class_globalns
+                    event_subclass_dict = {
+                        "__module__": cls.__module__,
+                        "__qualname__": event_class_qual,
+                    }
+                    subclass_name = event_class.__name__
+                    event_subclass = cast(
+                        type[DecoratedFuncCaller],
+                        type(
+                            subclass_name,
+                            (DecoratedFuncCaller, event_class),
+                            event_subclass_dict,
+                        ),
+                    )
+                    cross_cutting_event_classes[event_class_topic] = event_subclass
+                    event_class_globalns[event_class_qual] = event_subclass
+
+                # Register decorated func for event class / enduring object class.
+                try:
+                    decorated_func_collection = cross_cutting_decorated_funcs[
+                        event_class_topic
+                    ]
+                except KeyError:
+                    decorated_func_collection = {}
+                    cross_cutting_decorated_funcs[event_class_topic] = (
+                        decorated_func_collection
+                    )
+
+                decorated_func_collection[cls] = decorator.decorated_func
+
+    def __call__(cls: type[T], **kwargs: Any) -> T:
+        # TODO: For convenience, make this error out in the same way
+        #  as it would if the arguments didn't match the __init__
+        #  method and __init__was called directly, and verify the
+        #  event's __init__ is valid when initialising the class,
+        #  just like we do for event-sourced aggregates.
+
+        assert issubclass(cls, EnduringObject)
+        try:
+            init_enduring_object_class = _enduring_object_init_classes[cls]
+        except KeyError:
+            msg = (
+                f"Enduring object class {cls.__name__} has no "
+                f"CanInitialiseEnduringObject class. Please define a subclass of "
+                f"CanInitialiseEnduringObject as a nested class on {cls.__name__}."
+            )
+            raise ProgrammingError(msg) from None
+
+        return cast(
+            T,
+            cls._create(
+                decision_cls=init_enduring_object_class,
+                **kwargs,
+            ),
+        )
+
+
+class EnduringObject(Perspective, metaclass=MetaEnduringObject):
+    id: str
+
+    @classmethod
+    def _create(
+        cls: type[Self], decision_cls: type[CanInitialiseEnduringObject], **kwargs: Any
+    ) -> Self:
+        enduring_object_id = cls._create_id()
+        id_attr_name = decision_cls.id_attr_name(cls)
+        assert id_attr_name not in kwargs
+        assert "originator_topic" not in kwargs
+        assert "tags" not in kwargs
+        initial_kwargs: dict[str, Any] = {
+            id_attr_name: enduring_object_id,
+            "originator_topic": get_topic(cls),
+            "tags": [enduring_object_id],
+        }
+        initial_kwargs.update(kwargs)
+        try:
+            initialised = decision_cls(**initial_kwargs)
+        except TypeError as e:
+            msg = (
+                f"Unable to construct {decision_cls.__qualname__} event "
+                f"with kwargs {initial_kwargs}: {e}"
+            )
+            raise TypeError(msg) from e
+        enduring_object = cast(Self, initialised.mutate(None))
+        assert enduring_object is not None
+        enduring_object.new_decisions += (initialised,)
+        return enduring_object
+
+    @classmethod
+    def _create_id(cls) -> str:
+        return f"{cls.__name__.lower()}-{uuid4()}"
+
+    def __post_init__(self) -> None:
+        pass
+
+    @property
+    def cb(self) -> list[Selector]:
+        return [Selector(tags=[self.id], types=self.cb_types)]
+
+    def trigger_event(
+        self,
+        decision_cls: type[CanMutateEnduringObject],
+        *,
+        tags: Sequence[str] = (),
+        **kwargs: Any,
+    ) -> None:
+        tags = [self.id, *tags]
+        kwargs["tags"] = tags
+        self.check_cb_types(decision_cls)
+        assert issubclass(decision_cls, DecoratedFuncCaller), decision_cls
+        decision = decision_cls(**kwargs)
+        decision.mutate(self)
+        self.new_decisions += (decision,)
+
+
+class Group(Perspective):
+    @property
+    def cb(self) -> list[Selector]:
+        return [
+            Selector(types=tuple(self.cb_types) + tuple(cb.types), tags=cb.tags)
+            for cbs in [
+                o.cb for o in self.__dict__.values() if isinstance(o, EnduringObject)
+            ]
+            for cb in cbs
+        ]
+
+    def trigger_event(
+        self,
+        decision_cls: type[CanMutateEnduringObject],
+        *,
+        tags: Sequence[str] = (),
+        **kwargs: Any,
+    ) -> None:
+        self.check_cb_types(decision_cls)
+        objs = self.enduring_objects
+        tags = [o.id for o in objs] + list(tags)
+        kwargs["tags"] = tags
+        decision = decision_cls(**kwargs)
+        for o in objs:
+            decision.mutate(o)
+        self.new_decisions += (decision,)
+
+    @property
+    def enduring_objects(self) -> Sequence[EnduringObject]:
+        return [o for o in self.__dict__.values() if isinstance(o, EnduringObject)]
+
+    def collect_events(self) -> Sequence[CanMutateEnduringObject]:
+        group_events = list(super().collect_events())
+        for o in self.enduring_objects:
+            group_events.extend(o.collect_events())
+        return group_events
+
+
+@dataclass
+class Selector:
+    types: Sequence[type[CanMutateEnduringObject]] = ()
+    tags: Sequence[str] = ()