python-event-sourcery 0.3.0__tar.gz → 0.4.0__tar.gz

{python_event_sourcery-0.3.0 → python_event_sourcery-0.4.0}/PKG-INFO

@@ -1,23 +1,23 @@
-Metadata-Version: 2.1
+Metadata-Version: 2.3
 Name: python-event-sourcery
-Version: 0.3.0
+Version: 0.4.0
 Summary: 
 License: MIT
 Author: Your Name
 Author-email: you@example.com
-Requires-Python: >=3.10,<4.0
+Requires-Python: >=3.10
 Classifier: License :: OSI Approved :: MIT License
 Classifier: Programming Language :: Python :: 3
 Classifier: Programming Language :: Python :: 3.10
 Classifier: Programming Language :: Python :: 3.11
 Classifier: Programming Language :: Python :: 3.12
-Provides-Extra: cloudevents
+Classifier: Programming Language :: Python :: 3.13
 Provides-Extra: django
-Provides-Extra: kombu
-Requires-Dist: SQLAlchemy (>=2.0)
-Requires-Dist: cloudevents ; extra == "cloudevents"
+Provides-Extra: kurrentdb
+Provides-Extra: sqlalchemy
+Requires-Dist: SQLAlchemy (>=2.0) ; extra == "sqlalchemy"
 Requires-Dist: django (>=4,<6) ; extra == "django"
-Requires-Dist: esdbclient (>=1.0b3)
-Requires-Dist: kombu ; extra == "kombu"
+Requires-Dist: kurrentdbclient (>=1.0.6) ; extra == "kurrentdb"
 Requires-Dist: more-itertools
+Requires-Dist: psycopg2-binary (>2,<3)
 Requires-Dist: pydantic (>=2.0,<3)

python_event_sourcery-0.4.0/event_sourcery/event_sourcing/__init__.py

@@ -0,0 +1,7 @@
+__all__ = [
+    "Aggregate",
+    "Repository",
+]
+
+from event_sourcery.event_sourcing.aggregate import Aggregate
+from event_sourcery.event_sourcing.repository import Repository

{python_event_sourcery-0.3.0/event_sourcery/aggregate → python_event_sourcery-0.4.0/event_sourcery/event_sourcing}/aggregate.py

@@ -1,5 +1,6 @@
+from collections.abc import Iterator
 from contextlib import contextmanager
-from typing import ClassVar, Iterator
+from typing import ClassVar
 
 from event_sourcery.event_store import Event
 

{python_event_sourcery-0.3.0/event_sourcery/aggregate → python_event_sourcery-0.4.0/event_sourcery/event_sourcing}/repository.py

@@ -1,8 +1,15 @@
+from collections.abc import Iterator
 from contextlib import contextmanager
-from typing import Generic, Iterator, TypeVar, cast
+from typing import Generic, TypeVar, cast
 
-from event_sourcery.aggregate import Aggregate
-from event_sourcery.event_store import Event, EventStore, Metadata, StreamId, StreamUUID
+from event_sourcery.event_sourcing import Aggregate
+from event_sourcery.event_store import (
+    Event,
+    EventStore,
+    StreamId,
+    StreamUUID,
+    WrappedEvent,
+)
 
 TAggregate = TypeVar("TAggregate", bound=Aggregate)
 TEvent = TypeVar("TEvent", bound=Event)
@@ -41,14 +48,14 @@ class Repository(Generic[TAggregate]):
         with aggregate.__persisting_changes__() as pending:
             start_from = old_version + 1
             events = [
-                Metadata.wrap(event, version)
+                WrappedEvent.wrap(event, version)
                 for version, event in enumerate(pending, start=start_from)
             ]
 
             if not events:
                 return
 
-            self._event_store.publish(
+            self._event_store.append(
                 *events,
                 stream_id=stream_id,
                 expected_version=old_version,

{python_event_sourcery-0.3.0 → python_event_sourcery-0.4.0}/event_sourcery/event_store/__init__.py

@@ -1,50 +1,50 @@
 __all__ = [
+    "DEFAULT_TENANT",
+    "NO_VERSIONING",
     "Backend",
-    "BackendFactory",
+    "Context",
     "Dispatcher",
     "Entry",
     "Event",
     "EventRegistry",
     "EventStore",
     "ExplicitVersioning",
-    "InMemoryBackendFactory",
+    "InMemoryBackend",
     "Listener",
-    "Metadata",
-    "NO_VERSIONING",
     "Position",
     "RawEvent",
     "Recorded",
     "RecordedRaw",
     "StreamId",
     "StreamUUID",
+    "TenantId",
     "TransactionalBackend",
     "Versioning",
+    "WrappedEvent",
+    "backend",
     "exceptions",
-    "factory",
     "interfaces",
     "subscription",
 ]
 
-from event_sourcery.event_store import exceptions, factory, interfaces, subscription
+from event_sourcery.event_store import backend, exceptions, interfaces, subscription
+from event_sourcery.event_store.backend import Backend, TransactionalBackend
 from event_sourcery.event_store.dispatcher import Dispatcher, Listener
 from event_sourcery.event_store.event import (
+    Context,
     Entry,
     Event,
     EventRegistry,
-    Metadata,
     Position,
     RawEvent,
     Recorded,
     RecordedRaw,
+    WrappedEvent,
 )
 from event_sourcery.event_store.event_store import EventStore
-from event_sourcery.event_store.factory import (
-    Backend,
-    BackendFactory,
-    TransactionalBackend,
-)
-from event_sourcery.event_store.in_memory import InMemoryBackendFactory
+from event_sourcery.event_store.in_memory import InMemoryBackend
 from event_sourcery.event_store.stream_id import StreamId, StreamUUID
+from event_sourcery.event_store.tenant_id import DEFAULT_TENANT, TenantId
 from event_sourcery.event_store.versioning import (
     NO_VERSIONING,
     ExplicitVersioning,

python_event_sourcery-0.4.0/event_sourcery/event_store/backend.py

@@ -0,0 +1,177 @@
+from collections.abc import Callable, Iterator
+from contextlib import AbstractContextManager
+from functools import wraps
+from typing import NoReturn, TypeVar, cast
+
+from typing_extensions import Self
+
+from event_sourcery.event_store import subscription
+from event_sourcery.event_store.dispatcher import Dispatcher, Listeners
+from event_sourcery.event_store.event import (
+    Encryption,
+    EventRegistry,
+    NoEncryptionStrategy,
+    NoKeyStorageStrategy,
+    RawEvent,
+    RecordedRaw,
+    Serde,
+)
+from event_sourcery.event_store.event_store import EventStore
+from event_sourcery.event_store.interfaces import (
+    EncryptionKeyStorageStrategy,
+    EncryptionStrategy,
+    OutboxFiltererStrategy,
+    OutboxStorageStrategy,
+    StorageStrategy,
+    SubscriptionStrategy,
+)
+from event_sourcery.event_store.outbox import Outbox
+from event_sourcery.event_store.tenant_id import DEFAULT_TENANT, TenantId
+
+
+class NoProviderConfigured(Exception):
+    pass
+
+
+def no_filter(entry: RawEvent) -> bool:
+    return True
+
+
+class NoOutboxStorageStrategy(OutboxStorageStrategy):
+    def outbox_entries(
+        self, limit: int
+    ) -> Iterator[AbstractContextManager[RecordedRaw]]:
+        return iter([])
+
+
+T = TypeVar("T")
+T_co = TypeVar("T_co", covariant=True)
+
+_Provider = Callable[["_Container"], T]
+
+
+def singleton(provider: _Provider[T]) -> _Provider[T]:
+    result: T | None = None
+
+    @wraps(provider)
+    def _wrapper(container: "_Container") -> T:
+        nonlocal result
+        if result is not None:
+            return result
+        result = provider(container)
+        return result
+
+    return _wrapper
+
+
+def not_configured(error_message: str) -> _Provider[T]:
+    def _raise(container: "_Container") -> NoReturn:
+        raise NoProviderConfigured(error_message)  # pragma: no cover
+
+    return _raise
+
+
+class _Container:
+    def __init__(self) -> None:
+        self.providers: dict[type, _Provider] = {}
+
+    def __getitem__(self, _type: type[T]) -> T:
+        return cast(_Provider[T], self.providers[_type])(self)
+
+    def __setitem__(self, _type: type[T], value: T | _Provider[T]) -> None:
+        self.providers[_type] = (
+            cast(_Provider[T], lambda _: value)
+            if isinstance(value, _type)
+            else cast(_Provider[T], value)
+        )
+
+    def get(self, _type: type[T], default: T | None = None) -> T | None:
+        if _type not in self.providers:
+            return default
+        return self[_type]
+
+    def copy(self) -> Self:
+        new: Self = self.__class__()
+        new.providers.update(self.providers.copy())
+        return new
+
+
+class Backend(_Container):
+    def __init__(self) -> None:
+        super().__init__()
+        self[TenantId] = DEFAULT_TENANT
+        self[EventRegistry] = EventRegistry()
+        self[EncryptionStrategy] = NoEncryptionStrategy()
+        self[EncryptionKeyStorageStrategy] = (
+            lambda c: NoKeyStorageStrategy().scoped_for_tenant(c[TenantId])
+        )
+        self[Encryption] = lambda c: Encryption(
+            registry=c[EventRegistry],
+            strategy=c[EncryptionStrategy],
+            key_storage=c[EncryptionKeyStorageStrategy],
+        )
+        self[Serde] = lambda c: Serde(
+            registry=c[EventRegistry],
+            encryption=c[Encryption],
+        )
+        self[StorageStrategy] = not_configured(
+            "Use one of pyES backends: SQLAlchemy, Django or KurrentDB",
+        )
+        self[EventStore] = lambda c: EventStore(
+            storage_strategy=c[StorageStrategy],
+            serde=c[Serde],
+        )
+        self[Outbox] = lambda c: Outbox(
+            strategy=c[OutboxStorageStrategy],
+            serde=c[Serde],
+        )
+        self[OutboxStorageStrategy] = lambda _: NoOutboxStorageStrategy()
+        self[SubscriptionStrategy] = not_configured(
+            "Use one of pyES backends: SQLAlchemy, Django or KurrentDB",
+        )
+        self[subscription.PositionPhase] = lambda c: subscription.SubscriptionBuilder(
+            c[Serde],
+            c[SubscriptionStrategy],
+        )
+
+    @property
+    def event_store(self) -> EventStore:
+        return self[EventStore]
+
+    @property
+    def outbox(self) -> Outbox:
+        return self[Outbox]
+
+    @property
+    def subscriber(self) -> subscription.PositionPhase:
+        return self[subscription.PositionPhase]
+
+    def in_tenant_mode(self, tenant_id: TenantId) -> Self:
+        in_tenant_mode = self.copy()
+        in_tenant_mode[TenantId] = tenant_id
+        return in_tenant_mode
+
+    def with_outbox(self, filterer: OutboxFiltererStrategy = no_filter) -> Self:
+        raise NotImplementedError()
+
+    def with_encryption(
+        self,
+        strategy: EncryptionStrategy,
+        key_storage: EncryptionKeyStorageStrategy,
+    ) -> Self:
+        self[EncryptionStrategy] = strategy
+        self[EncryptionKeyStorageStrategy] = lambda c: key_storage.scoped_for_tenant(
+            c[TenantId],
+        )
+        return self
+
+
+class TransactionalBackend(Backend):
+    def __init__(self) -> None:
+        super().__init__()
+        self[Listeners] = singleton(lambda _: Listeners())
+        self[Dispatcher] = lambda c: Dispatcher(c[Serde], c[Listeners])
+
+    @property
+    def in_transaction(self) -> Listeners:
+        return cast(Listeners, self[Listeners])

python_event_sourcery-0.4.0/event_sourcery/event_store/dispatcher.py

@@ -0,0 +1,64 @@
+from collections.abc import Iterator
+from itertools import chain
+from typing import Protocol
+
+from event_sourcery.event_store.event import (
+    Event,
+    Position,
+    RecordedRaw,
+    Serde,
+    WrappedEvent,
+)
+from event_sourcery.event_store.stream_id import StreamId
+from event_sourcery.event_store.tenant_id import TenantId
+
+
+class Listener(Protocol):
+    def __call__(
+        self,
+        wrapped_event: WrappedEvent,
+        stream_id: StreamId,
+        tenant_id: TenantId,
+        position: Position,
+    ) -> None: ...
+
+
+class Listeners:
+    def __init__(self) -> None:
+        self._listeners: dict[type[Event], set[Listener]] = {}
+
+    def __getitem__(self, event_type: type[Event]) -> Iterator[Listener]:
+        return chain(
+            *(
+                listeners
+                for registered_to, listeners in self._listeners.items()
+                if issubclass(event_type, registered_to)
+            )
+        )
+
+    def register(self, listener: Listener, to: type[Event]) -> None:
+        if to not in self._listeners:
+            self._listeners[to] = set()
+        self._listeners[to].add(listener)
+
+    def remove(self, listener: Listener, to: type[Event]) -> None:
+        if to in self._listeners and listener in self._listeners[to]:
+            self._listeners[to].remove(listener)
+
+
+class Dispatcher:
+    def __init__(self, serde: Serde, listeners: Listeners) -> None:
+        self._serde = serde
+        self._listeners = listeners
+
+    def dispatch(self, *raws: RecordedRaw) -> None:
+        for raw in raws:
+            record = self._serde.deserialize_record(raw)
+            event_type = record.wrapped_event.event.__class__
+            for listener in self._listeners[event_type]:
+                listener(
+                    record.wrapped_event,
+                    record.stream_id,
+                    record.tenant_id,
+                    record.position,
+                )

python_event_sourcery-0.4.0/event_sourcery/event_store/event/__init__.py

@@ -0,0 +1,38 @@
+__all__ = [
+    "Context",
+    "DataSubject",
+    "Encrypted",
+    "Encryption",
+    "Entry",
+    "Event",
+    "EventRegistry",
+    "NoEncryptionStrategy",
+    "NoKeyStorageStrategy",
+    "Position",
+    "RawEvent",
+    "Recorded",
+    "RecordedRaw",
+    "Serde",
+    "WrappedEvent",
+]
+
+
+from event_sourcery.event_store.event._dto import (
+    Context,
+    DataSubject,
+    Encrypted,
+    Entry,
+    Event,
+    Position,
+    RawEvent,
+    Recorded,
+    RecordedRaw,
+    WrappedEvent,
+)
+from event_sourcery.event_store.event._encryption import (
+    Encryption,
+    NoEncryptionStrategy,
+    NoKeyStorageStrategy,
+)
+from event_sourcery.event_store.event._registry import EventRegistry
+from event_sourcery.event_store.event._serde import Serde

python_event_sourcery-0.4.0/event_sourcery/event_store/event/_dto.py

@@ -0,0 +1,137 @@
+import dataclasses
+from dataclasses import dataclass
+from datetime import datetime, timezone
+from typing import Any, Generic, TypeAlias, TypeVar
+from uuid import UUID, uuid4
+
+from pydantic import BaseModel
+
+from event_sourcery.event_store.stream_id import StreamId
+from event_sourcery.event_store.tenant_id import DEFAULT_TENANT, TenantId
+
+DataSubject = object()
+
+
+@dataclasses.dataclass(frozen=True)
+class RawEvent(BaseModel):
+    uuid: UUID
+    stream_id: StreamId
+    created_at: datetime
+    name: str
+    data: dict[str, Any]
+    context: dict[str, Any]
+    version: int | None = None
+
+
+Position: TypeAlias = int
+
+
+@dataclasses.dataclass(frozen=True)
+class RecordedRaw(BaseModel):
+    entry: RawEvent
+    position: Position
+    tenant_id: TenantId = DEFAULT_TENANT
+
+
+class Event(BaseModel, extra="forbid"):
+    """Base class for all events.
+
+    Example usage:
+    ```
+    class OrderCancelled(Event):
+        order_id: OrderId
+    ```
+    """
+
+
+TEvent = TypeVar("TEvent", bound=Event)
+
+
+class Context(BaseModel, extra="allow"):
+    correlation_id: UUID | None = None
+    causation_id: UUID | None = None
+
+
+@dataclasses.dataclass()
+class WrappedEvent(Generic[TEvent]):
+    """Wrapper for events with all relevant metadata.
+
+    Returned from EventStore when loading events from a stream.
+
+    Example usage:
+    ```
+    class OrderCancelled(Event):
+        order_id: OrderId
+
+    event = OrderCancelled(order_id=OrderId("#123"))
+    wrapped_event = WrappedEvent.wrap(event, version=1)
+    ```
+    """
+
+    event: TEvent
+    version: int | None
+    uuid: UUID = dataclasses.field(default_factory=uuid4)
+    created_at: datetime = dataclasses.field(
+        default_factory=lambda: datetime.now(timezone.utc).replace(tzinfo=None)
+    )
+    context: Context = dataclasses.field(default_factory=Context)
+
+    @classmethod
+    def wrap(cls, event: TEvent, version: int | None) -> "WrappedEvent[TEvent]":
+        return WrappedEvent[TEvent](event=event, version=version)
+
+
+@dataclasses.dataclass(frozen=True)
+class Entry:
+    wrapped_event: WrappedEvent[Event]
+    stream_id: StreamId
+
+
+@dataclasses.dataclass(frozen=True)
+class Recorded(Entry):
+    """DTO containing events saved in the event store.
+
+    It contains position of the event in the event store and tenant id.
+    """
+
+    position: Position
+    tenant_id: TenantId = DEFAULT_TENANT
+
+
+@dataclass(frozen=True)
+class Encrypted:
+    """Field annotation for marking event fields that should be encrypted.
+
+    This annotation is used in combination with DataSubject to implement
+    crypto-shredding, allowing for GDPR-compliant data removal in event-sourced systems.
+
+    Args:
+        mask_value: Value to display when the data is shredded (deleted).
+                    Must match the field type.
+        subject_field: Optional. Name of the field containing the subject ID for this
+                      encrypted field. If not provided, the field marked with
+                      DataSubject will be used.
+
+    Example:
+        ```python
+        class UserRegistered(Event):
+            user_id: Annotated[str, DataSubject]
+            email: Annotated[str, Encrypted(mask_value="[REDACTED]")]
+            # Custom subject field
+            other_data: Annotated[
+                str,
+                Encrypted(
+                    mask_value="[HIDDEN]",
+                    subject_field="alternative_id",
+                ),
+            ]
+        ```
+
+    Note:
+        - Every event with encrypted fields must have exactly one DataSubject field.
+        - The mask_value type must match the field type.
+        - After shredding, the field will always return its mask_value.
+    """
+
+    mask_value: Any
+    subject_field: str | None = None

python_event_sourcery-0.4.0/event_sourcery/event_store/event/_encryption.py

@@ -0,0 +1,129 @@
+import json
+from collections import UserDict
+from dataclasses import dataclass
+from typing import Any
+
+from pydantic import BaseModel
+from typing_extensions import Self
+
+from event_sourcery.event_store.event._registry import EventRegistry
+from event_sourcery.event_store.exceptions import KeyNotFoundError, NoSubjectIdFound
+from event_sourcery.event_store.interfaces import (
+    EncryptionKeyStorageStrategy,
+    EncryptionStrategy,
+)
+from event_sourcery.event_store.stream_id import StreamId
+from event_sourcery.event_store.tenant_id import TenantId
+
+
+class NoEncryptionStrategy(EncryptionStrategy):
+    def encrypt(self, data: Any, key: bytes) -> str:
+        raise NotImplementedError("NoEncryptionStrategy does not support encryption.")
+
+    def decrypt(self, data: str, key: bytes) -> Any:
+        raise NotImplementedError("NoEncryptionStrategy does not support decryption.")
+
+
+class NoKeyStorageStrategy(EncryptionKeyStorageStrategy):
+    def get(self, subject_id: str) -> bytes | None:
+        raise NotImplementedError(
+            "NoKeyStorageStrategy does not support key retrieval."
+        )
+
+    def store(self, subject_id: str, key: bytes) -> None:
+        raise NotImplementedError("NoKeyStorageStrategy does not support key storage.")
+
+    def delete(self, subject_id: str) -> None:
+        raise NotImplementedError("NoKeyStorageStrategy does not support key deletion.")
+
+    def scoped_for_tenant(self, tenant_id: TenantId) -> Self:
+        return self
+
+
+class NestedDict(UserDict):
+    def __getitem__(self, item: str) -> Any:
+        match item.split(".", 1):
+            case [prefix, key]:
+                return NestedDict(self.data[prefix])[key]
+            case _:
+                return self.data[item]
+
+    def __setitem__(self, item: str, value: Any) -> None:
+        match item.rsplit(".", 1):
+            case [prefix, key]:
+                self[prefix][key] = value
+            case _:
+                self.data[item] = value
+
+
+@dataclass
+class Encryption:
+    """
+    Integrates encryption logic and key management.
+    Uses the KeyStorageStrategy and EncryptionStrategy interfaces.
+    Responsible for:
+      - Retrieving the key for a given subject_id
+      - Encrypting and decrypting data
+      - Masking data when the key is not available (crypto-shredding)
+      - Processing event encryption/decryption with field annotations
+    """
+
+    registry: EventRegistry
+    strategy: EncryptionStrategy
+    key_storage: EncryptionKeyStorageStrategy
+
+    def encrypt(self, event: BaseModel, stream_id: StreamId) -> dict[str, Any]:
+        event_type = type(event)
+        data = NestedDict(event.model_dump(mode="json"))
+        for field_name in self.registry.encrypted_fields(of=event_type).keys():
+            subject_field = self.registry.subject_filed(field_name, of=event_type)
+            subject_id = (
+                subject_field and getattr(event, subject_field)
+            ) or stream_id.name
+
+            if subject_id is None:
+                raise NoSubjectIdFound(stream_id)
+            data[field_name] = self._encrypt_value(data[field_name], subject_id)
+        return data.data
+
+    def decrypt(
+        self,
+        event_type: type[BaseModel],
+        raw: dict[str, Any],
+        stream_id: StreamId,
+    ) -> dict[str, Any]:
+        data = NestedDict(raw)
+        encrypted_fields = self.registry.encrypted_fields(of=event_type)
+        for field_name, encrypted_config in encrypted_fields.items():
+            subject_field = self.registry.subject_filed(field_name, of=event_type)
+            subject_id = data[subject_field] if subject_field else stream_id.name or ""
+            data[field_name] = self._decrypt_value(
+                data[field_name],
+                subject_id,
+                encrypted_config.mask_value,
+            )
+        return data.data
+
+    def _decrypt_value(self, value: str, subject_id: str, mask_value: Any) -> Any:
+        key = self.key_storage.get(subject_id)
+        if key is None:
+            return mask_value
+        decrypted = self.strategy.decrypt(value, key)
+        try:
+            return json.loads(decrypted)
+        except (json.JSONDecodeError, TypeError):
+            return decrypted
+
+    def _encrypt_value(self, value: Any, subject_id: str) -> str:
+        key = self.key_storage.get(subject_id)
+        if key is None:
+            raise KeyNotFoundError(subject_id)
+        match value:
+            case str():
+                serialized = value
+            case _:
+                serialized = json.dumps(value)
+        return self.strategy.encrypt(serialized, key)
+
+    def shred(self, subject_id: str) -> None:
+        self.key_storage.delete(subject_id)