eventsourcing 9.3.5__py3-none-any.whl → 9.4.0a1__py3-none-any.whl

eventsourcing/application.py

@@ -25,7 +25,7 @@ from typing import (
 )
 from warnings import warn
 
-from typing_extensions import deprecated
+from typing_extensions import Self, deprecated
 
 from eventsourcing.domain import (
     Aggregate,
@@ -34,12 +34,11 @@ from eventsourcing.domain import (
     DomainEventProtocol,
     EventSourcingError,
     MutableOrImmutableAggregate,
-    ProgrammingError,
     Snapshot,
     SnapshotProtocol,
     TDomainEvent,
     TMutableOrImmutableAggregate,
-    create_utc_datetime_now,
+    datetime_now_with_tzinfo,
 )
 from eventsourcing.persistence import (
     ApplicationRecorder,
@@ -47,16 +46,18 @@ from eventsourcing.persistence import (
     DecimalAsStr,
     EventStore,
     InfrastructureFactory,
+    JSONTranscoder,
     Mapper,
     Notification,
     Recording,
     Tracking,
+    TrackingRecorder,
     Transcoder,
     UUIDAsHex,
 )
 from eventsourcing.utils import Environment, EnvType, strtobool
 
-if TYPE_CHECKING:  # pragma: nocover
+if TYPE_CHECKING:  # pragma: no cover
     from uuid import UUID
 
 ProjectorFunction = Callable[
@@ -70,6 +71,10 @@ MutatorFunction = Callable[
 ]
 
 
+class ProgrammingError(Exception):
+    pass
+
+
 def project_aggregate(
     aggregate: TMutableOrImmutableAggregate | None,
     domain_events: Iterable[DomainEventProtocol],
@@ -435,10 +440,12 @@ class NotificationLog(ABC):
     @abstractmethod
     def select(
         self,
-        start: int,
+        start: int | None,
         limit: int,
         stop: int | None = None,
         topics: Sequence[str] = (),
+        *,
+        inclusive_of_start: bool = True,
     ) -> List[Notification]:
         """
         Returns a selection of
@@ -523,10 +530,12 @@ class LocalNotificationLog(NotificationLog):
 
     def select(
         self,
-        start: int,
+        start: int | None,
         limit: int,
         stop: int | None = None,
         topics: Sequence[str] = (),
+        *,
+        inclusive_of_start: bool = True,
     ) -> List[Notification]:
         """
         Returns a selection of
@@ -539,7 +548,11 @@ class LocalNotificationLog(NotificationLog):
             )
             raise ValueError(msg)
         return self.recorder.select_notifications(
-            start=start, limit=limit, stop=stop, topics=topics
+            start=start,
+            limit=limit,
+            stop=stop,
+            topics=topics,
+            inclusive_of_start=inclusive_of_start,
         )
 
     @staticmethod
@@ -685,7 +698,9 @@ class Application:
             _env.update(env)
         return Environment(name, _env)
 
-    def construct_factory(self, env: Environment) -> InfrastructureFactory:
+    def construct_factory(
+        self, env: Environment
+    ) -> InfrastructureFactory[TrackingRecorder]:
         """
         Constructs an :class:`~eventsourcing.persistence.InfrastructureFactory`
         for use by the application.
@@ -705,10 +720,11 @@ class Application:
         for use by the application.
         """
         transcoder = self.factory.transcoder()
-        self.register_transcodings(transcoder)
+        if isinstance(transcoder, JSONTranscoder):
+            self.register_transcodings(transcoder)
         return transcoder
 
-    def register_transcodings(self, transcoder: Transcoder) -> None:
+    def register_transcodings(self, transcoder: JSONTranscoder) -> None:
         """
         Registers :class:`~eventsourcing.persistence.Transcoding`
         objects on given :class:`~eventsourcing.persistence.JSONTranscoder`.
@@ -887,6 +903,21 @@ class Application:
         need to take action when new domain events have been saved.
         """
 
+    def subscribe(self, gt: int | None = None) -> ApplicationSubscription:
+        """
+        Returns an iterator that yields all domain events recorded in an application
+        sequence that have notification IDs greater than a given value. The iterator
+        will block when all recorded domain events have been yielded, and then
+        continue when new events are recorded. Domain events are returned along
+        with tracking objects that identify the position in the application sequence.
+        """
+        return ApplicationSubscription(
+            name=self.name,
+            recorder=self.recorder,
+            mapper=self.mapper,
+            gt=gt,
+        )
+
     def close(self) -> None:
         self.closing.set()
         self.factory.close()
@@ -967,7 +998,7 @@ class EventSourcedLog(Generic[TDomainEvent]):
         return logged_cls(  # type: ignore
             originator_id=self.originator_id,
             originator_version=next_originator_version,
-            timestamp=create_utc_datetime_now(),
+            timestamp=datetime_now_with_tzinfo(),
             **kwargs,
         )
 
@@ -1011,3 +1042,36 @@ class EventSourcedLog(Generic[TDomainEvent]):
                 limit=limit,
             ),
         )
+
+
+class ApplicationSubscription:
+    def __init__(
+        self,
+        name: str,
+        recorder: ApplicationRecorder,
+        mapper: Mapper,
+        gt: int | None = None,
+    ):
+        self.name = name
+        self.recorder = recorder
+        self.mapper = mapper
+        self.subscription = self.recorder.subscribe(gt=gt)
+
+    def __enter__(self) -> Self:
+        self.subscription.__enter__()
+        return self
+
+    def __exit__(self, *args: object, **kwargs: Any) -> None:
+        self.subscription.__exit__(*args, **kwargs)
+
+    def __iter__(self) -> Self:
+        return self
+
+    def __next__(self) -> Tuple[DomainEventProtocol, Tracking]:
+        notification = next(self.subscription)
+        tracking = Tracking(self.name, notification.id)
+        domain_event = self.mapper.to_domain_event(notification)
+        return domain_event, tracking
+
+    def __del__(self) -> None:
+        self.subscription.stop()

eventsourcing/cipher.py

@@ -10,7 +10,7 @@ from Crypto.Cipher.AES import key_size
 
 from eventsourcing.persistence import Cipher
 
-if TYPE_CHECKING:  # pragma: nocover
+if TYPE_CHECKING:  # pragma: no cover
     from eventsourcing.utils import Environment
 
 

eventsourcing/domain.py

@@ -25,10 +25,20 @@ from typing import (
     runtime_checkable,
 )
 from uuid import UUID, uuid4
+from warnings import warn
 
 from eventsourcing.utils import get_method_name, get_topic, resolve_topic
 
 TZINFO: tzinfo = resolve_topic(os.getenv("TZINFO_TOPIC", "datetime:timezone.utc"))
+"""
+A Python :py:obj:`tzinfo` object that defaults to UTC (:py:obj:`timezone.utc`). Used
+as the timezone argument in :func:`~eventsourcing.domain.datetime_now_with_tzinfo`.
+
+Set environment variable ``TZINFO_TOPIC`` to the topic of a different :py:obj:`tzinfo`
+object so that all your domain model event timestamps are located in that timezone
+(not recommended). It is generally recommended to locate all timestamps in the UTC
+domain and convert to local timezones when presenting values in user interfaces.
+"""
 
 
 @runtime_checkable
@@ -153,13 +163,27 @@ class CanMutateProtocol(DomainEventProtocol, Protocol[TMutableOrImmutableAggrega
         """
 
 
-def create_utc_datetime_now() -> datetime:
+def datetime_now_with_tzinfo() -> datetime:
     """
     Constructs a timezone-aware :class:`datetime` object for the current date and time.
+
+    Uses :py:obj:`TZINFO` as the timezone.
     """
     return datetime.now(tz=TZINFO)
 
 
+def create_utc_datetime_now() -> datetime:
+    """
+    Deprected in favour of :func:`~eventsourcing.domain.datetime_now_with_tzinfo`.
+    """
+    msg = (
+        "'create_utc_datetime_now()' is deprecated, "
+        "use 'datetime_now_with_tzinfo()' instead"
+    )
+    warn(msg, DeprecationWarning, stacklevel=2)
+    return datetime_now_with_tzinfo()
+
+
 class CanCreateTimestamp:
     """
     Provides a create_timestamp() method to subclasses.
@@ -171,7 +195,7 @@ class CanCreateTimestamp:
         Constructs a timezone-aware :class:`datetime` object
         representing when an event occurred.
         """
-        return create_utc_datetime_now()
+        return datetime_now_with_tzinfo()
 
 
 TAggregate = TypeVar("TAggregate", bound="Aggregate")
@@ -386,7 +410,7 @@ def _spec_filter_kwargs_for_method_params(method: Callable[..., Any]) -> set[str
     return set(method_signature.parameters)
 
 
-if TYPE_CHECKING:  # pragma: nocover
+if TYPE_CHECKING:  # pragma: no cover
     EventSpecType = Union[str, Type[CanMutateAggregate]]
 
 CommandMethod = Callable[..., None]
@@ -668,6 +692,8 @@ class UnboundCommandMethodDecorator:
         self.__qualname__ = event_decorator.decorated_method.__qualname__
         self.__annotations__ = event_decorator.decorated_method.__annotations__
         self.__doc__ = event_decorator.decorated_method.__doc__
+        # self.__wrapped__ = event_decorator.decorated_method
+        # functools.update_wrapper(self, event_decorator.decorated_method)
 
     def __call__(self, *args: Any, **kwargs: Any) -> None:
         # Expect first argument is an aggregate instance.

eventsourcing/interface.py

@@ -25,7 +25,12 @@ class NotificationLogInterface(ABC):
 
     @abstractmethod
     def get_notifications(
-        self, start: int, limit: int, topics: Sequence[str] = ()
+        self,
+        start: int | None,
+        limit: int,
+        topics: Sequence[str] = (),
+        *,
+        inclusive_of_start: bool = True,
     ) -> str:
         """
         Returns a serialised list of :class:`~eventsourcing.persistence.Notification`
@@ -68,10 +73,18 @@ class NotificationLogJSONService(NotificationLogInterface, Generic[TApplication]
         )
 
     def get_notifications(
-        self, start: int, limit: int, topics: Sequence[str] = ()
+        self,
+        start: int | None,
+        limit: int,
+        topics: Sequence[str] = (),
+        *,
+        inclusive_of_start: bool = True,
     ) -> str:
         notifications = self.app.notification_log.select(
-            start=start, limit=limit, topics=topics
+            start=start,
+            limit=limit,
+            topics=topics,
+            inclusive_of_start=inclusive_of_start,
         )
         return json.dumps(
             [
@@ -123,10 +136,12 @@ class NotificationLogJSONClient(NotificationLog):
 
     def select(
         self,
-        start: int,
+        start: int | None,
         limit: int,
         _: int | None = None,
         topics: Sequence[str] = (),
+        *,
+        inclusive_of_start: bool = True,
     ) -> List[Notification]:
         """
         Returns a selection of
@@ -143,7 +158,10 @@ class NotificationLogJSONClient(NotificationLog):
             )
             for item in json.loads(
                 self.interface.get_notifications(
-                    start=start, limit=limit, topics=topics
+                    start=start,
+                    limit=limit,
+                    topics=topics,
+                    inclusive_of_start=inclusive_of_start,
                 )
             )
         ]