python-event-sourcery 0.4.1a1__tar.gz → 0.5.0__tar.gz

python_event_sourcery-0.5.0/PKG-INFO

@@ -0,0 +1,152 @@
+Metadata-Version: 2.3
+Name: python-event-sourcery
+Version: 0.5.0
+Summary: A library for event-based systems in Python.
+License: MIT
+Author: Sebastian Buczyński
+Author-email: nnplaya@gmail.com
+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
+Classifier: Programming Language :: Python :: 3.13
+Provides-Extra: django
+Provides-Extra: kurrentdb
+Provides-Extra: sqlalchemy
+Requires-Dist: SQLAlchemy (>=2.0) ; extra == "sqlalchemy"
+Requires-Dist: django (>=4,<6) ; extra == "django"
+Requires-Dist: kurrentdbclient (>=1.0.6) ; extra == "kurrentdb"
+Requires-Dist: more-itertools
+Requires-Dist: psycopg2-binary (>2,<3)
+Requires-Dist: pydantic (>=2.0,<3)
+Description-Content-Type: text/markdown
+
+
+# Python Event Sourcery
+
+A library for event-based systems in Python. For event sourcing, CQRS, and event-driven architectures.
+
+```python
+event = EventSourceryIsBorn()
+
+event_store.append(event, stream_id=stream_id)
+```
+
+_Under heavy development_
+
+---
+
+Documentation: [python-event-sourcery.github.io/python-event-sourcery/](https://python-event-sourcery.github.io/python-event-sourcery/)
+
+---
+
+## Installation
+
+```bash
+pip install python-event-sourcery
+```
+
+---
+
+## Easy to setup
+Just configure your `EventStore` instance (or a factory) and call `configure_models` once. Examples below.
+
+## Versatile
+Event Sourcery makes no assumptions about your configuration or session management. It's designed to be plugged in into what you already have, without a need to adjust anything. It can be integrated smoothly with thread-scoped SQLAlchemy sessions as well as dependency injection.
+
+## NOT opinionated
+Although one can easily start with a library, the latter is very customizable and DOES NOT enforce a particular style of using. Also, libraries integrated, i.e. SQLAlchemy and Pydantic are not hardcoded dependencies. They can be replaced with a finite amount of effort.
+
+---
+
+## Use cases & features
+Until full documentation is available, you can follow tests
+
+- Event Sourcing [tests](https://github.com/Enforcer/python-event-sourcery/blob/main/tests/repository/test_aggregate_context_manager.py)
+- Snapshots (for Event Sourcing) [tests](https://github.com/Enforcer/python-event-sourcery/blob/main/tests/event_store/test_snapshots.py)
+- Event Store - storage for events [tests](https://github.com/Enforcer/python-event-sourcery/blob/main/tests/event_store/test_save_retrieval.py)
+- Outbox pattern [tests](https://github.com/Enforcer/python-event-sourcery/blob/main/tests/outbox/test_outbox.py)
+- Concurrency control with optimistic locking [tests](https://github.com/Enforcer/python-event-sourcery/blob/main/tests/event_store/test_concurrency_control.py)
+
+---
+
+## Quick start
+
+The script is complete, it should run as-is provided FastAPI and library with dependencies are installed.
+See examples/0-fastapi-integration
+
+```python
+from typing import Iterator, Literal
+from uuid import uuid4
+
+from fastapi import FastAPI, Depends
+from sqlalchemy import create_engine
+from sqlalchemy.orm import Session, as_declarative
+
+# Import a couple of things from event_sourcery
+from event_sourcery import EventStore  # for type annotations
+from event_sourcery import (
+    configure_models,  # set-up function for library's models
+    get_event_store,  # factory function to start quickly
+    Event,  # base class for events
+)
+
+# Set up your DB and application as you would normally do
+engine = create_engine(
+    "postgresql://event_sourcery:event_sourcery@localhost:5432/event_sourcery"
+)
+
+
+def db_session() -> Iterator[Session]:
+    session = Session(bind=engine)
+    try:
+        yield session
+    finally:
+        session.close()
+
+
+@as_declarative()
+class Base:
+    pass
+
+
+app = FastAPI(on_startup=[lambda: Base.metadata.create_all(bind=engine)])
+
+# initialize Event Sourcery models, so they can be handled by SQLAlchemy and e.g. alembic
+configure_models(Base)
+
+
+# Set up factory for event store to be injected into views
+def event_store(session: Session = Depends(db_session)) -> EventStore:
+    return get_event_store(session)
+
+
+# Define your event(s) using base-class provided
+class CustomerSubscribed(Event):
+    plan_id: int
+    model: Literal["monthly", "yearly"]
+
+
+@app.post("/subscription")
+def subscribe(
+    event_store: EventStore = Depends(event_store),
+    session: Session = Depends(db_session),
+):
+    # Create an event
+    event = CustomerSubscribed(plan_id=1, model="yearly")
+    # Put it in the event store!
+    event_store.append(event, stream_id=uuid4())
+    session.commit()
+
+```
+
+## Feature requests / feedback
+
+Anything missing? Create an issue in this repository. Let others upvote 
+
+## Inspirations
+- [Rails Event Store](https://railseventstore.org/)
+- [Marten](https://martendb.io/)
+

python_event_sourcery-0.5.0/README.md

@@ -0,0 +1,126 @@
+
+# Python Event Sourcery
+
+A library for event-based systems in Python. For event sourcing, CQRS, and event-driven architectures.
+
+```python
+event = EventSourceryIsBorn()
+
+event_store.append(event, stream_id=stream_id)
+```
+
+_Under heavy development_
+
+---
+
+Documentation: [python-event-sourcery.github.io/python-event-sourcery/](https://python-event-sourcery.github.io/python-event-sourcery/)
+
+---
+
+## Installation
+
+```bash
+pip install python-event-sourcery
+```
+
+---
+
+## Easy to setup
+Just configure your `EventStore` instance (or a factory) and call `configure_models` once. Examples below.
+
+## Versatile
+Event Sourcery makes no assumptions about your configuration or session management. It's designed to be plugged in into what you already have, without a need to adjust anything. It can be integrated smoothly with thread-scoped SQLAlchemy sessions as well as dependency injection.
+
+## NOT opinionated
+Although one can easily start with a library, the latter is very customizable and DOES NOT enforce a particular style of using. Also, libraries integrated, i.e. SQLAlchemy and Pydantic are not hardcoded dependencies. They can be replaced with a finite amount of effort.
+
+---
+
+## Use cases & features
+Until full documentation is available, you can follow tests
+
+- Event Sourcing [tests](https://github.com/Enforcer/python-event-sourcery/blob/main/tests/repository/test_aggregate_context_manager.py)
+- Snapshots (for Event Sourcing) [tests](https://github.com/Enforcer/python-event-sourcery/blob/main/tests/event_store/test_snapshots.py)
+- Event Store - storage for events [tests](https://github.com/Enforcer/python-event-sourcery/blob/main/tests/event_store/test_save_retrieval.py)
+- Outbox pattern [tests](https://github.com/Enforcer/python-event-sourcery/blob/main/tests/outbox/test_outbox.py)
+- Concurrency control with optimistic locking [tests](https://github.com/Enforcer/python-event-sourcery/blob/main/tests/event_store/test_concurrency_control.py)
+
+---
+
+## Quick start
+
+The script is complete, it should run as-is provided FastAPI and library with dependencies are installed.
+See examples/0-fastapi-integration
+
+```python
+from typing import Iterator, Literal
+from uuid import uuid4
+
+from fastapi import FastAPI, Depends
+from sqlalchemy import create_engine
+from sqlalchemy.orm import Session, as_declarative
+
+# Import a couple of things from event_sourcery
+from event_sourcery import EventStore  # for type annotations
+from event_sourcery import (
+    configure_models,  # set-up function for library's models
+    get_event_store,  # factory function to start quickly
+    Event,  # base class for events
+)
+
+# Set up your DB and application as you would normally do
+engine = create_engine(
+    "postgresql://event_sourcery:event_sourcery@localhost:5432/event_sourcery"
+)
+
+
+def db_session() -> Iterator[Session]:
+    session = Session(bind=engine)
+    try:
+        yield session
+    finally:
+        session.close()
+
+
+@as_declarative()
+class Base:
+    pass
+
+
+app = FastAPI(on_startup=[lambda: Base.metadata.create_all(bind=engine)])
+
+# initialize Event Sourcery models, so they can be handled by SQLAlchemy and e.g. alembic
+configure_models(Base)
+
+
+# Set up factory for event store to be injected into views
+def event_store(session: Session = Depends(db_session)) -> EventStore:
+    return get_event_store(session)
+
+
+# Define your event(s) using base-class provided
+class CustomerSubscribed(Event):
+    plan_id: int
+    model: Literal["monthly", "yearly"]
+
+
+@app.post("/subscription")
+def subscribe(
+    event_store: EventStore = Depends(event_store),
+    session: Session = Depends(db_session),
+):
+    # Create an event
+    event = CustomerSubscribed(plan_id=1, model="yearly")
+    # Put it in the event store!
+    event_store.append(event, stream_id=uuid4())
+    session.commit()
+
+```
+
+## Feature requests / feedback
+
+Anything missing? Create an issue in this repository. Let others upvote 
+
+## Inspirations
+- [Rails Event Store](https://railseventstore.org/)
+- [Marten](https://martendb.io/)

python_event_sourcery-0.5.0/event_sourcery/__init__.py

@@ -0,0 +1,21 @@
+__all__ = [
+    "DEFAULT_TENANT",
+    "NO_VERSIONING",
+    "Backend",
+    "Event",
+    "EventStore",
+    "Outbox",
+    "StreamCategory",
+    "StreamId",
+    "StreamUUID",
+    "TenantId",
+    "TransactionalBackend",
+]
+
+from event_sourcery._event_store.backend import Backend, TransactionalBackend
+from event_sourcery._event_store.event.dto import Event
+from event_sourcery._event_store.event_store import EventStore
+from event_sourcery._event_store.outbox import Outbox
+from event_sourcery._event_store.stream_id import StreamCategory, StreamId, StreamUUID
+from event_sourcery._event_store.tenant_id import DEFAULT_TENANT, TenantId
+from event_sourcery._event_store.versioning import NO_VERSIONING

{python_event_sourcery-0.4.1a1/event_sourcery/event_store → python_event_sourcery-0.5.0/event_sourcery/_event_store}/backend.py

@@ -1,48 +1,42 @@
-from collections.abc import Callable, Iterator
-from contextlib import AbstractContextManager
+from collections.abc import Callable
 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 (
+from event_sourcery._event_store.event.encryption import (
     Encryption,
-    EventRegistry,
+    EncryptionKeyStorageStrategy,
+    EncryptionStrategy,
     NoEncryptionStrategy,
     NoKeyStorageStrategy,
-    RawEvent,
-    RecordedRaw,
-    Serde,
 )
-from event_sourcery.event_store.event_store import EventStore
-from event_sourcery.event_store.interfaces import (
-    EncryptionKeyStorageStrategy,
-    EncryptionStrategy,
+from event_sourcery._event_store.event.registry import EventRegistry
+from event_sourcery._event_store.event.serde import Serde
+from event_sourcery._event_store.event_store import (
+    EventStore,
+    StorageStrategy,
+)
+from event_sourcery._event_store.outbox import (
+    NoOutboxStorageStrategy,
+    Outbox,
     OutboxFiltererStrategy,
     OutboxStorageStrategy,
-    StorageStrategy,
+    no_filter,
+)
+from event_sourcery._event_store.subscription.builder import (
+    SubscriptionBuilder,
+)
+from event_sourcery._event_store.subscription.in_transaction import (
+    Dispatcher,
+    Listeners,
+)
+from event_sourcery._event_store.subscription.interfaces import (
+    PositionPhase,
     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([])
-
+from event_sourcery._event_store.tenant_id import DEFAULT_TENANT, TenantId
+from event_sourcery.exceptions import NoProviderConfigured
 
 T = TypeVar("T")
 T_co = TypeVar("T_co", covariant=True)
@@ -51,6 +45,16 @@ _Provider = Callable[["_Container"], T]
 
 
 def singleton(provider: _Provider[T]) -> _Provider[T]:
+    """
+    Decorator that ensures the provider returns the same instance (singleton)
+    for every call within the container's lifecycle.
+
+    Args:
+        provider (_Provider[T]): The provider function to wrap.
+
+    Returns:
+        _Provider[T]: A provider that always returns the same instance.
+    """
     result: T | None = None
 
     @wraps(provider)
@@ -65,6 +69,13 @@ def singleton(provider: _Provider[T]) -> _Provider[T]:
 
 
 def not_configured(error_message: str) -> _Provider[T]:
+    """
+    Used as a placeholder for providers that require configuration.
+
+    Args:
+        error_message (str): str. The error message to raise with the exception.
+    """
+
     def _raise(container: "_Container") -> NoReturn:
         raise NoProviderConfigured(error_message)  # pragma: no cover
 
@@ -97,6 +108,18 @@ class _Container:
 
 
 class Backend(_Container):
+    """
+    Dependency Injection container for Event Sourcery components.
+
+    Dict-like object resolving object instance during access by type.
+    Providers are passed setting the type as key and provider as a value.
+
+    By default, basic implementations are registered or an exception is raised
+    if backend configuration (e.g., storage strategy) is required.
+
+    Core components are exposed by properties.
+    """
+
     def __init__(self) -> None:
         super().__init__()
         self[TenantId] = DEFAULT_TENANT
@@ -129,29 +152,44 @@ class Backend(_Container):
         self[SubscriptionStrategy] = not_configured(
             "Use one of pyES backends: SQLAlchemy, Django or KurrentDB",
         )
-        self[subscription.PositionPhase] = lambda c: subscription.SubscriptionBuilder(
+        self[PositionPhase] = lambda c: SubscriptionBuilder(
             c[Serde],
             c[SubscriptionStrategy],
         )
 
     @property
     def event_store(self) -> EventStore:
+        """
+        Returns the current instance of `EventStore`.
+        """
         return self[EventStore]
 
     @property
     def outbox(self) -> Outbox:
+        """
+        Returns the current instance of `Outbox`.
+        """
         return self[Outbox]
 
     @property
-    def subscriber(self) -> subscription.PositionPhase:
-        return self[subscription.PositionPhase]
+    def subscriber(self) -> PositionPhase:
+        """
+        Returns the current instance of `SubscriptionBuilder` (as `PositionPhase`).
+        """
+        return self[PositionPhase]
 
     def in_tenant_mode(self, tenant_id: TenantId) -> Self:
+        """
+        Returns a copy of the backend with the specified tenant ID set.
+        """
         in_tenant_mode = self.copy()
         in_tenant_mode[TenantId] = tenant_id
         return in_tenant_mode
 
     def with_outbox(self, filterer: OutboxFiltererStrategy = no_filter) -> Self:
+        """
+        Configure the outbox with a custom filter.
+        """
         raise NotImplementedError()
 
     def with_encryption(
@@ -159,6 +197,9 @@ class Backend(_Container):
         strategy: EncryptionStrategy,
         key_storage: EncryptionKeyStorageStrategy,
     ) -> Self:
+        """
+        Configures event encryption with the provided strategy and key storage.
+        """
         self[EncryptionStrategy] = strategy
         self[EncryptionKeyStorageStrategy] = lambda c: key_storage.scoped_for_tenant(
             c[TenantId],
@@ -167,6 +208,16 @@ class Backend(_Container):
 
 
 class TransactionalBackend(Backend):
+    """
+    Backend variant that provides transactional event handling support.
+
+    Registers additional services for managing listeners and dispatchers
+    to enable in-transaction event processing.
+
+    Properties:
+        in_transaction (Listeners): The current state of in transaction Listeners.
+    """
+
     def __init__(self) -> None:
         super().__init__()
         self[Listeners] = singleton(lambda _: Listeners())
@@ -174,4 +225,7 @@ class TransactionalBackend(Backend):
 
     @property
     def in_transaction(self) -> Listeners:
+        """
+        Returns the current instance of `Listeners` for transactional event handling.
+        """
         return cast(Listeners, self[Listeners])

python_event_sourcery-0.4.1a1/event_sourcery/event_store/event/_dto.py → python_event_sourcery-0.5.0/event_sourcery/_event_store/event/dto.py

@@ -6,14 +6,30 @@ 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
+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):
+    """
+    Data Transfer Object representing a raw event that will be stored.
+
+    Contains all event metadata and payload in a flat structure.
+    Used for low-level event store operations, serialization, and transport.
+
+    Attributes:
+        uuid (UUID): Unique identifier of the event.
+        stream_id (StreamId): Identifier of the stream to which the event belongs.
+        created_at (datetime): Timestamp when the event was created.
+        name (str): Name/type of the event.
+        data (dict[str, Any]): Event payload (fields and values).
+        context (dict[str, Any]): Event custom metadata.
+        version (int | None): Version of the event in the stream (if applicable).
+    """
+
     uuid: UUID
     stream_id: StreamId
     created_at: datetime
@@ -28,6 +44,18 @@ Position: TypeAlias = int
 
 @dataclasses.dataclass(frozen=True)
 class RecordedRaw(BaseModel):
+    """
+    DTO representing a raw event received from the event store.
+
+    Used for low-level event store operations.
+    Wraps a RawEvent with additional metadata (position and tenant id).
+
+    Attributes:
+        entry (RawEvent): The raw event data and metadata.
+        position (Position): Position of the event in the event store.
+        tenant_id (TenantId): Tenant identifier (for multi-tenant scenarios).
+    """
+
     entry: RawEvent
     position: Position
     tenant_id: TenantId = DEFAULT_TENANT
@@ -48,16 +76,38 @@ TEvent = TypeVar("TEvent", bound=Event)
 
 
 class Context(BaseModel, extra="allow"):
+    """
+    Extensible context object for event metadata.
+
+    Designed to carry correlation and causation identifiers, and can be extended
+    with additional metadata fields as needed. This allows for flexible propagation
+    of context information throughout event processing and handling pipelines.
+
+    Attributes:
+        correlation_id (UUID | None): Identifier for correlating related events.
+        causation_id (UUID | None): Identifier for the cause of the event.
+
+    Additional fields can be added dynamically due to `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.
+    """
+    Wrapper for events with all relevant metadata.
 
     Returned from EventStore when loading events from a stream.
 
+    Attributes:
+        event (TEvent): The event instance.
+        version (int | None): Version of the event in the stream (if applicable).
+        uuid (UUID): Unique identifier of the event instance.
+        created_at (datetime): Timestamp when the event was created.
+        context (Context): Context object containing additional metadata.
+
     Example usage:
     ```
     class OrderCancelled(Event):
@@ -83,6 +133,17 @@ class WrappedEvent(Generic[TEvent]):
 
 @dataclasses.dataclass(frozen=True)
 class Entry:
+    """
+    Container for a single event and its stream identifier.
+
+    Used as a base DTO for representing an event (with all metadata) and the stream
+    it belongs to. Serves as a base for more specialized event store DTOs (e.g. Recorded).
+
+    Attributes:
+        wrapped_event (WrappedEvent[Event]): The event instance with metadata.
+        stream_id (StreamId): The identifier of the stream to which the event belongs.
+    """
+
     wrapped_event: WrappedEvent[Event]
     stream_id: StreamId