eventsourcing 9.3.5__tar.gz → 9.4.0a2__tar.gz

{eventsourcing-9.3.5 → eventsourcing-9.4.0a2}/LICENSE

@@ -1,6 +1,6 @@
 BSD 3-Clause License
 
-Copyright (c) 2023, John Bywater
+Copyright (c) 2025, John Bywater
 All rights reserved.
 
 Redistribution and use in source and binary forms, with or without

{eventsourcing-9.3.5 → eventsourcing-9.4.0a2}/PKG-INFO

@@ -1,14 +1,14 @@
 Metadata-Version: 2.1
 Name: eventsourcing
-Version: 9.3.5
+Version: 9.4.0a2
 Summary: Event sourcing in Python
 Home-page: https://github.com/pyeventsourcing/eventsourcing
 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.8,<4.0
-Classifier: Development Status :: 5 - Production/Stable
+Requires-Python: >=3.8, !=2.7.*, !=3.0.*, !=3.1.*, !=3.2.*, !=3.3.*, !=3.4.*, !=3.5.*, !=3.6.*, !=3.7.*
+Classifier: Development Status :: 3 - Alpha
 Classifier: Intended Audience :: Developers
 Classifier: Intended Audience :: Education
 Classifier: Intended Audience :: Science/Research
@@ -18,22 +18,24 @@ Classifier: Operating System :: OS Independent
 Classifier: Programming Language :: Python
 Classifier: Programming Language :: Python :: 3
 Classifier: Programming Language :: Python :: 3.8
-Classifier: Programming Language :: Python :: 3.9
 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: Topic :: Software Development :: Libraries :: Python Modules
 Provides-Extra: crypto
+Provides-Extra: cryptography
 Provides-Extra: postgres
 Requires-Dist: backports.zoneinfo ; python_version < "3.9"
-Requires-Dist: psycopg[c,pool] (<=3.2.99999) ; extra == "postgres"
-Requires-Dist: pycryptodome (>=3.21,<3.22) ; extra == "crypto"
+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: typing_extensions
 Project-URL: Repository, https://github.com/pyeventsourcing/eventsourcing
 Description-Content-Type: text/markdown
 
-[![Build Status](https://github.com/pyeventsourcing/eventsourcing/actions/workflows/runtests.yaml/badge.svg?branch=main)](https://github.com/pyeventsourcing/eventsourcing/tree/main)
+[![Build Status](https://github.com/pyeventsourcing/eventsourcing/actions/workflows/runtests.yaml/badge.svg)](https://github.com/pyeventsourcing/eventsourcing)
 [![Coverage Status](https://coveralls.io/repos/github/pyeventsourcing/eventsourcing/badge.svg?branch=main)](https://coveralls.io/github/pyeventsourcing/eventsourcing?branch=main)
 [![Documentation Status](https://readthedocs.org/projects/eventsourcing/badge/?version=stable)](https://eventsourcing.readthedocs.io/en/stable/)
 [![Latest Release](https://badge.fury.io/py/eventsourcing.svg)](https://pypi.org/project/eventsourcing/)

{eventsourcing-9.3.5 → eventsourcing-9.4.0a2}/README.md

@@ -1,4 +1,4 @@
-[![Build Status](https://github.com/pyeventsourcing/eventsourcing/actions/workflows/runtests.yaml/badge.svg?branch=main)](https://github.com/pyeventsourcing/eventsourcing/tree/main)
+[![Build Status](https://github.com/pyeventsourcing/eventsourcing/actions/workflows/runtests.yaml/badge.svg)](https://github.com/pyeventsourcing/eventsourcing)
 [![Coverage Status](https://coveralls.io/repos/github/pyeventsourcing/eventsourcing/badge.svg?branch=main)](https://coveralls.io/github/pyeventsourcing/eventsourcing?branch=main)
 [![Documentation Status](https://readthedocs.org/projects/eventsourcing/badge/?version=stable)](https://eventsourcing.readthedocs.io/en/stable/)
 [![Latest Release](https://badge.fury.io/py/eventsourcing.svg)](https://pypi.org/project/eventsourcing/)

{eventsourcing-9.3.5 → eventsourcing-9.4.0a2}/eventsourcing/application.py

@@ -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:
     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`.
@@ -967,7 +983,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,
         )
 

{eventsourcing-9.3.5 → eventsourcing-9.4.0a2}/eventsourcing/cipher.py

@@ -10,13 +10,14 @@ from Crypto.Cipher.AES import key_size
 
 from eventsourcing.persistence import Cipher
 
-if TYPE_CHECKING:  # pragma: nocover
+if TYPE_CHECKING:
     from eventsourcing.utils import Environment
 
 
 class AESCipher(Cipher):
     """
-    Cipher strategy that uses AES cipher in GCM mode.
+    Cipher strategy that uses AES cipher (in GCM mode)
+    from the Python pycryptodome package.
     """
 
     CIPHER_KEY = "CIPHER_KEY"
@@ -71,6 +72,7 @@ class AESCipher(Cipher):
 
         # Return ciphertext.
         return nonce + tag + encrypted
+        # return nonce + tag + encrypted
 
     def construct_cipher(self, nonce: bytes) -> GcmMode:
         cipher = AES.new(

eventsourcing-9.4.0a2/eventsourcing/cryptography.py

@@ -0,0 +1,96 @@
+from __future__ import annotations
+
+import os
+from base64 import b64decode, b64encode
+from typing import TYPE_CHECKING
+
+from cryptography.exceptions import InvalidTag
+from cryptography.hazmat.primitives.ciphers.aead import AESGCM
+
+from eventsourcing.persistence import Cipher
+
+if TYPE_CHECKING:
+    from eventsourcing.utils import Environment
+
+
+class AESCipher(Cipher):
+    """
+    Cipher strategy that uses AES cipher (in GCM mode)
+    from the Python cryptography package.
+    """
+
+    CIPHER_KEY = "CIPHER_KEY"
+    KEY_SIZES = (16, 24, 32)
+
+    @staticmethod
+    def create_key(num_bytes: int) -> str:
+        """
+        Creates AES cipher key, with length num_bytes.
+
+        :param num_bytes: An int value, either 16, 24, or 32.
+
+        """
+        AESCipher.check_key_size(num_bytes)
+        key = AESGCM.generate_key(num_bytes * 8)
+        return b64encode(key).decode("utf8")
+
+    @staticmethod
+    def check_key_size(num_bytes: int) -> None:
+        if num_bytes not in AESCipher.KEY_SIZES:
+            msg = f"Invalid key size: {num_bytes} not in {AESCipher.KEY_SIZES}"
+            raise ValueError(msg)
+
+    @staticmethod
+    def random_bytes(num_bytes: int) -> bytes:
+        return os.urandom(num_bytes)
+
+    def __init__(self, environment: Environment):
+        """
+        Initialises AES cipher with ``cipher_key``.
+
+        :param str cipher_key: 16, 24, or 32 bytes encoded as base64
+        """
+        cipher_key = environment.get(self.CIPHER_KEY)
+        if not cipher_key:
+            msg = f"'{self.CIPHER_KEY}' not in env"
+            raise OSError(msg)
+        key = b64decode(cipher_key.encode("utf8"))
+        AESCipher.check_key_size(len(key))
+        self.key = key
+
+    def encrypt(self, plaintext: bytes) -> bytes:
+        """Return ciphertext for given plaintext."""
+
+        # Construct AES-GCM cipher, with 96-bit nonce.
+        aesgcm = AESGCM(self.key)
+        nonce = AESCipher.random_bytes(12)
+        res = aesgcm.encrypt(nonce, plaintext, None)
+        # Put tag at the front for compatibility with eventsourcing.crypto.AESCipher.
+        tag = res[-16:]
+        encrypted = res[:-16]
+        return nonce + tag + encrypted
+
+    def decrypt(self, ciphertext: bytes) -> bytes:
+        """Return plaintext for given ciphertext."""
+
+        # Split out the nonce, tag, and encrypted data.
+        nonce = ciphertext[:12]
+        if len(nonce) != 12:
+            msg = "Damaged cipher text: invalid nonce length"
+            raise ValueError(msg)
+
+        # Expect tag at the front.
+        tag = ciphertext[12:28]
+        if len(tag) != 16:
+            msg = "Damaged cipher text: invalid tag length"
+            raise ValueError(msg)
+        encrypted = ciphertext[28:]
+
+        aesgcm = AESGCM(self.key)
+        try:
+            plaintext = aesgcm.decrypt(nonce, encrypted + tag, None)
+        except InvalidTag as e:
+            msg = "Invalid cipher tag"
+            raise ValueError(msg) from e
+        # Decrypt and verify.
+        return plaintext

{eventsourcing-9.3.5 → eventsourcing-9.4.0a2}/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:
     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.
@@ -1526,12 +1552,6 @@ class VersionError(OriginatorVersionError):
 
 
 class SnapshotProtocol(DomainEventProtocol, Protocol):
-    @property
-    def topic(self) -> str:
-        """
-        Snapshots have a read-only 'topic'.
-        """
-
     @property
     def state(self) -> Dict[str, Any]:
         """

{eventsourcing-9.3.5 → eventsourcing-9.4.0a2}/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,
                 )
             )
         ]