python-cqrs 4.7.1__tar.gz → 4.7.3__tar.gz

{python_cqrs-4.7.1/src/python_cqrs.egg-info → python_cqrs-4.7.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: python-cqrs
-Version: 4.7.1
+Version: 4.7.3
 Summary: Python CQRS pattern implementation
 Author-email: Vadim Kozyrevskiy <vadikko2@mail.ru>, Dmitry Kutlubaev <kutlubaev00@mail.ru>
 Maintainer-email: Vadim Kozyrevskiy <vadikko2@mail.ru>

{python_cqrs-4.7.1 → python_cqrs-4.7.3}/pyproject.toml

@@ -31,7 +31,7 @@ maintainers = [{name = "Vadim Kozyrevskiy", email = "vadikko2@mail.ru"}]
 name = "python-cqrs"
 readme = "README.md"
 requires-python = ">=3.10"
-version = "4.7.1"
+version = "4.7.3"
 
 [project.optional-dependencies]
 aiobreaker = ["aiobreaker>=0.3.0"]
@@ -79,8 +79,5 @@ asyncio_mode = "auto"
 junit_family = "xunit1"
 testpaths = ["tests"]
 
-[tool.ruff]
-target-version = "py310"
-
 [tool.setuptools.packages.find]
 where = ["src"]

{python_cqrs-4.7.1 → python_cqrs-4.7.3}/src/cqrs/dispatcher/saga.py

@@ -53,7 +53,7 @@ class SagaDispatcher:
         self._compensation_retry_delay = compensation_retry_delay
         self._compensation_retry_backoff = compensation_retry_backoff
 
-    async def dispatch(
+    def dispatch(
         self,
         context: SagaContext,
         saga_id: uuid.UUID | None = None,
@@ -61,6 +61,7 @@ class SagaDispatcher:
         """
         Dispatch a saga execution for the given context.
 
+        Called without await; returns an AsyncIterator consumed with async for.
         Yields result after each step execution. After each yield, events are collected
         and included in the dispatch result.
 
@@ -75,6 +76,13 @@ class SagaDispatcher:
         Raises:
             SagaDoesNotExist: If no saga is registered for the context type
         """
+        return self._dispatch_impl(context, saga_id=saga_id)
+
+    async def _dispatch_impl(
+        self,
+        context: SagaContext,
+        saga_id: uuid.UUID | None = None,
+    ) -> typing.AsyncIterator[SagaDispatchResult]:
         # Find saga type by context type
         saga_type = self._saga_map.get(type(context))
         if not saga_type:

{python_cqrs-4.7.1 → python_cqrs-4.7.3}/src/cqrs/dispatcher/streaming.py

@@ -28,16 +28,23 @@ class StreamingRequestDispatcher:
         self._container = container
         self._middleware_chain = middleware_chain or MiddlewareChain()
 
-    async def dispatch(
+    def dispatch(
         self,
         request: IRequest,
     ) -> typing.AsyncIterator[RequestDispatchResult]:
         """
         Dispatch a request to a streaming handler and yield results.
 
+        Called without await; returns an AsyncIterator consumed with async for.
         After each yield from the handler, events are collected and included
         in the dispatch result. The generator continues until StopIteration.
         """
+        return self._dispatch_impl(request)
+
+    async def _dispatch_impl(
+        self,
+        request: IRequest,
+    ) -> typing.AsyncIterator[RequestDispatchResult]:
         handler_type = self._request_map.get(type(request), None)
         if handler_type is None:
             raise RequestHandlerDoesNotExist(
@@ -62,9 +69,7 @@ class StreamingRequestDispatcher:
 
         if not inspect.isasyncgenfunction(handler.handle):
             handler_name = (
-                handler_type_typed.__name__
-                if hasattr(handler_type_typed, "__name__")
-                else str(handler_type_typed)
+                handler_type_typed.__name__ if hasattr(handler_type_typed, "__name__") else str(handler_type_typed)
             )
             raise TypeError(
                 f"Handler {handler_name}.handle must be an async generator function",

{python_cqrs-4.7.1 → python_cqrs-4.7.3}/src/cqrs/mediator.py

@@ -172,9 +172,7 @@ class StreamingRequestMediator:
         max_concurrent_event_handlers: int = 1,
         concurrent_event_handle_enable: bool = True,
         *,
-        dispatcher_type: typing.Type[
-            StreamingRequestDispatcher
-        ] = StreamingRequestDispatcher,
+        dispatcher_type: typing.Type[StreamingRequestDispatcher] = StreamingRequestDispatcher,
     ) -> None:
         self._event_processor = EventProcessor(
             event_map=event_map or EventMap(),
@@ -188,13 +186,14 @@ class StreamingRequestMediator:
             middleware_chain=middleware_chain,  # type: ignore
         )
 
-    async def stream(
+    def stream(
         self,
         request: IRequest,
     ) -> typing.AsyncIterator[IResponse | None]:
         """
         Stream results from a generator-based handler.
 
+        Called without await; returns an AsyncIterator consumed with async for.
         After each yield from the handler:
         1. Events are processed (in parallel with semaphore limit or sequentially
            depending on concurrent_event_handle_enable) via event dispatcher
@@ -203,6 +202,12 @@ class StreamingRequestMediator:
 
         The generator continues until StopIteration is raised.
         """
+        return self._stream_impl(request)
+
+    async def _stream_impl(
+        self,
+        request: IRequest,
+    ) -> typing.AsyncIterator[IResponse | None]:
         async for dispatch_result in self._dispatcher.dispatch(request):
             await self._event_processor.emit_events(dispatch_result.events)
 
@@ -274,7 +279,7 @@ class SagaMediator:
             compensation_retry_backoff=compensation_retry_backoff,  # type: ignore
         )
 
-    async def stream(
+    def stream(
         self,
         context: SagaContext,
         saga_id: uuid.UUID | None = None,
@@ -282,6 +287,7 @@ class SagaMediator:
         """
         Stream results from saga execution.
 
+        Called without await; returns an AsyncIterator consumed with async for.
         After each step execution:
         1. Events are processed (in parallel with semaphore limit or sequentially
            depending on concurrent_event_handle_enable) via event dispatcher
@@ -298,6 +304,13 @@ class SagaMediator:
         Yields:
             SagaStepResult
         """
+        return self._stream_impl(context, saga_id=saga_id)
+
+    async def _stream_impl(
+        self,
+        context: SagaContext,
+        saga_id: uuid.UUID | None = None,
+    ) -> typing.AsyncIterator[SagaStepResult]:
         async for dispatch_result in self._dispatcher.dispatch(
             context,
             saga_id=saga_id,

{python_cqrs-4.7.1 → python_cqrs-4.7.3}/src/cqrs/requests/request_handler.py

@@ -79,7 +79,13 @@ class StreamingRequestHandler(abc.ABC, typing.Generic[ReqT, ResT]):
         raise NotImplementedError
 
     @abc.abstractmethod
-    async def handle(self, request: ReqT) -> typing.AsyncIterator[ResT]:
+    def handle(self, request: ReqT) -> typing.AsyncIterator[ResT]:
+        """
+        Handle the request by yielding results as an async generator.
+
+        Subclasses must implement this as an async generator (async def with
+        yield) so that callers receive an AsyncIterator when calling handle().
+        """
         raise NotImplementedError
 
     @abc.abstractmethod

{python_cqrs-4.7.1 → python_cqrs-4.7.3}/src/cqrs/saga/bootstrap.py

@@ -185,7 +185,7 @@ def bootstrap(
             saga_storage=MemorySagaStorage(),
         )
 
-        # Execute saga
+        # Execute saga (stream() returns AsyncIterator, consumed with async for)
         async for result in mediator.stream(order_context):
             print(f"Step: {result.step_result.step_type.__name__}")
 

{python_cqrs-4.7.1 → python_cqrs-4.7.3}/src/cqrs/saga/storage/memory.py

@@ -122,6 +122,7 @@ class MemorySagaStorage(ISagaStorage):
         limit: int,
         max_recovery_attempts: int = 5,
         stale_after_seconds: int | None = None,
+        saga_name: str | None = None,
     ) -> list[uuid.UUID]:
         recoverable = (SagaStatus.RUNNING, SagaStatus.COMPENSATING)
         now = datetime.datetime.now(datetime.timezone.utc)
@@ -136,6 +137,7 @@ class MemorySagaStorage(ISagaStorage):
             if data["status"] in recoverable
             and data.get("recovery_attempts", 0) < max_recovery_attempts
             and (threshold is None or data["updated_at"] < threshold)
+            and (saga_name is None or data["name"] == saga_name)
         ]
         candidates.sort(key=lambda sid: self._sagas[sid]["updated_at"])
         return candidates[:limit]
@@ -153,3 +155,15 @@ class MemorySagaStorage(ISagaStorage):
         data["version"] += 1
         if new_status is not None:
             data["status"] = new_status
+
+    async def set_recovery_attempts(
+        self,
+        saga_id: uuid.UUID,
+        attempts: int,
+    ) -> None:
+        if saga_id not in self._sagas:
+            raise ValueError(f"Saga {saga_id} not found")
+        data = self._sagas[saga_id]
+        data["recovery_attempts"] = attempts
+        data["updated_at"] = datetime.datetime.now(datetime.timezone.utc)
+        data["version"] += 1

python_cqrs-4.7.3/src/cqrs/saga/storage/protocol.py

@@ -0,0 +1,216 @@
+import abc
+import typing
+import uuid
+
+from cqrs.saga.storage.enums import SagaStatus, SagaStepStatus
+from cqrs.saga.storage.models import SagaLogEntry
+
+
+class ISagaStorage(abc.ABC):
+    """Interface for saga persistence storage.
+
+    Storage is responsible for persisting saga execution state so that:
+    - Saga progress (status, context, step history) survives process restarts.
+    - Recovery jobs can find interrupted sagas (RUNNING/COMPENSATING) and retry them.
+    - Optimistic locking (version) prevents lost updates when multiple workers
+      touch the same saga.
+    """
+
+    @abc.abstractmethod
+    async def create_saga(
+        self,
+        saga_id: uuid.UUID,
+        name: str,
+        context: dict[str, typing.Any],
+    ) -> None:
+        """Create a new saga record in storage (initial state).
+
+        Called when a saga is started for the first time. Creates the execution
+        record with PENDING status, initial context, and version 1.
+
+        Args:
+            saga_id: Unique identifier of the saga (used as primary key).
+            name: Saga name (e.g. handler/type name) for diagnostics and filtering.
+            context: Initial context as a JSON-serializable dict (step inputs/outputs).
+        """
+
+    @abc.abstractmethod
+    async def update_context(
+        self,
+        saga_id: uuid.UUID,
+        context: dict[str, typing.Any],
+        current_version: int | None = None,
+    ) -> None:
+        """Save saga context snapshot (e.g. after a step completes).
+
+        Persists the current context so recovery can resume with up-to-date data.
+        When current_version is provided, implements optimistic locking: update
+        succeeds only if the stored version equals current_version (and version
+        is incremented), otherwise a concurrent update is detected.
+
+        Args:
+            saga_id: The ID of the saga to update.
+            context: The new context data (full snapshot, JSON-serializable).
+            current_version: The expected current version of the saga execution.
+                If provided, optimistic locking is used; if the stored version
+                differs, the update is rejected.
+
+        Raises:
+            SagaConcurrencyError: If optimistic locking fails (version mismatch).
+        """
+
+    @abc.abstractmethod
+    async def update_status(
+        self,
+        saga_id: uuid.UUID,
+        status: SagaStatus,
+    ) -> None:
+        """Update the saga's global status.
+
+        Status drives lifecycle: PENDING → RUNNING → COMPLETED, or RUNNING →
+        COMPENSATING → FAILED. Used by execution and recovery to know whether
+        to run steps, compensate, or consider the saga finished.
+
+        Args:
+            saga_id: The ID of the saga to update.
+            status: New status (e.g. SagaStatus.RUNNING, SagaStatus.COMPLETED,
+                SagaStatus.COMPENSATING, SagaStatus.FAILED).
+        """
+
+    @abc.abstractmethod
+    async def log_step(
+        self,
+        saga_id: uuid.UUID,
+        step_name: str,
+        action: typing.Literal["act", "compensate"],
+        status: SagaStepStatus,
+        details: str | None = None,
+    ) -> None:
+        """Append a step transition to the saga log.
+
+        Used to record each step's outcome (started/completed/failed/compensated)
+        so that recovery can determine which steps have already been executed
+        and which need to be run or compensated.
+
+        Args:
+            saga_id: The ID of the saga this step belongs to.
+            step_name: Name of the step (must match the step handler name).
+            action: "act" for forward execution, "compensate" for compensation.
+            status: Step outcome: STARTED, COMPLETED, FAILED, or COMPENSATED.
+            details: Optional message (e.g. error text when status is FAILED).
+        """
+
+    @abc.abstractmethod
+    async def load_saga_state(
+        self,
+        saga_id: uuid.UUID,
+        *,
+        read_for_update: bool = False,
+    ) -> tuple[SagaStatus, dict[str, typing.Any], int]:
+        """Load current saga status, context, and version.
+
+        Used by execution and recovery to restore in-memory state. When
+        read_for_update is True, the implementation may lock the row (e.g.
+        SELECT FOR UPDATE) to avoid concurrent updates.
+
+        Args:
+            saga_id: The ID of the saga to load.
+            read_for_update: If True, lock the row for update (e.g. for
+                subsequent update_context with optimistic locking).
+
+        Returns:
+            Tuple of (status, context_dict, version). context_dict is the
+            last persisted context; version is used for optimistic locking.
+        """
+
+    @abc.abstractmethod
+    async def get_step_history(
+        self,
+        saga_id: uuid.UUID,
+    ) -> list[SagaLogEntry]:
+        """Return the ordered list of step log entries for the saga.
+
+        Used by recovery to determine which steps completed successfully
+        (and must be compensated in reverse order if compensating) and
+        which steps still need to be executed.
+
+        Args:
+            saga_id: The ID of the saga whose step history to load.
+
+        Returns:
+            List of SagaLogEntry in chronological order (oldest first).
+        """
+
+    @abc.abstractmethod
+    async def get_sagas_for_recovery(
+        self,
+        limit: int,
+        max_recovery_attempts: int = 5,
+        stale_after_seconds: int | None = None,
+        saga_name: str | None = None,
+    ) -> list[uuid.UUID]:
+        """Return saga IDs that are candidates for recovery.
+
+        Used by a recovery job/scheduler to find sagas that were left in
+        RUNNING or COMPENSATING (e.g. process crash) and should be retried.
+        Excludes COMPLETED and optionally limits by recovery attempts,
+        staleness, and saga name to avoid re-processing fresh or repeatedly
+        failing sagas.
+
+        Args:
+            limit: Maximum number of saga IDs to return per call.
+            max_recovery_attempts: Only include sagas with recovery_attempts
+                strictly less than this value. Sagas that have failed
+                recovery this many times can be excluded (e.g. marked FAILED).
+                Default 5.
+            stale_after_seconds: If set, only include sagas whose updated_at
+                is older than (now_utc - stale_after_seconds). Use this to
+                avoid picking sagas that are currently being executed (recently
+                updated). None means no staleness filter (backward compatible).
+            saga_name: If set, only include sagas with this name (e.g. handler
+                or type name). None means return all saga types (default).
+
+        Returns:
+            List of saga IDs (RUNNING or COMPENSATING only; FAILED/COMPLETED
+            are not included), ordered by updated_at ascending, with
+            recovery_attempts < max_recovery_attempts, and optionally
+            updated_at older than the staleness threshold and name equal to
+            saga_name when saga_name is provided.
+        """
+
+    @abc.abstractmethod
+    async def increment_recovery_attempts(
+        self,
+        saga_id: uuid.UUID,
+        new_status: SagaStatus | None = None,
+    ) -> None:
+        """Increment recovery attempt counter after a failed recovery run.
+
+        Called when recovery of a saga fails (e.g. exception). Increments
+        recovery_attempts and optionally sets status (e.g. to FAILED) so that
+        get_sagas_for_recovery can exclude this saga or limit retries.
+
+        Args:
+            saga_id: The saga that failed recovery.
+            new_status: If provided, set saga status to this value (e.g.
+                SagaStatus.FAILED) in the same atomic update.
+        """
+
+    @abc.abstractmethod
+    async def set_recovery_attempts(
+        self,
+        saga_id: uuid.UUID,
+        attempts: int,
+    ) -> None:
+        """Set recovery attempt counter to an explicit value.
+
+        Used to reset the counter after successfully recovering one of the
+        steps (e.g. set to 0), or to set it to the maximum value so that
+        get_sagas_for_recovery excludes this saga from further recovery
+        (e.g. mark as permanently failed without changing status).
+
+        Args:
+            saga_id: The saga to update.
+            attempts: The value to set recovery_attempts to (e.g. 0 to reset,
+                or max_recovery_attempts to exclude from recovery).
+        """

{python_cqrs-4.7.1 → python_cqrs-4.7.3}/src/cqrs/saga/storage/sqlalchemy.py

@@ -317,6 +317,7 @@ class SqlAlchemySagaStorage(ISagaStorage):
         limit: int,
         max_recovery_attempts: int = 5,
         stale_after_seconds: int | None = None,
+        saga_name: str | None = None,
     ) -> list[uuid.UUID]:
         recoverable = (
             SagaStatus.RUNNING,
@@ -328,6 +329,8 @@ class SqlAlchemySagaStorage(ISagaStorage):
                 .where(SagaExecutionModel.status.in_(recoverable))
                 .where(SagaExecutionModel.recovery_attempts < max_recovery_attempts)
             )
+            if saga_name is not None:
+                stmt = stmt.where(SagaExecutionModel.name == saga_name)
             if stale_after_seconds is not None:
                 threshold = datetime.datetime.now(
                     datetime.timezone.utc,
@@ -364,3 +367,25 @@ class SqlAlchemySagaStorage(ISagaStorage):
             except SQLAlchemyError:
                 await session.rollback()
                 raise
+
+    async def set_recovery_attempts(
+        self,
+        saga_id: uuid.UUID,
+        attempts: int,
+    ) -> None:
+        async with self.session_factory() as session:
+            try:
+                result = await session.execute(
+                    sqlalchemy.update(SagaExecutionModel)
+                    .where(SagaExecutionModel.id == saga_id)
+                    .values(
+                        recovery_attempts=attempts,
+                        version=SagaExecutionModel.version + 1,
+                    ),
+                )
+                if result.rowcount == 0:  # type: ignore[attr-defined]
+                    raise ValueError(f"Saga {saga_id} not found")
+                await session.commit()
+            except SQLAlchemyError:
+                await session.rollback()
+                raise

{python_cqrs-4.7.1 → python_cqrs-4.7.3/src/python_cqrs.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: python-cqrs
-Version: 4.7.1
+Version: 4.7.3
 Summary: Python CQRS pattern implementation
 Author-email: Vadim Kozyrevskiy <vadikko2@mail.ru>, Dmitry Kutlubaev <kutlubaev00@mail.ru>
 Maintainer-email: Vadim Kozyrevskiy <vadikko2@mail.ru>

python_cqrs-4.7.1/src/cqrs/saga/storage/protocol.py

@@ -1,113 +0,0 @@
-import abc
-import typing
-import uuid
-
-from cqrs.saga.storage.enums import SagaStatus, SagaStepStatus
-from cqrs.saga.storage.models import SagaLogEntry
-
-
-class ISagaStorage(abc.ABC):
-    """Interface for saga persistence storage."""
-
-    @abc.abstractmethod
-    async def create_saga(
-        self,
-        saga_id: uuid.UUID,
-        name: str,
-        context: dict[str, typing.Any],
-    ) -> None:
-        """Initialize a new saga in storage."""
-
-    @abc.abstractmethod
-    async def update_context(
-        self,
-        saga_id: uuid.UUID,
-        context: dict[str, typing.Any],
-        current_version: int | None = None,
-    ) -> None:
-        """Save saga context snapshot.
-
-        Args:
-            saga_id: The ID of the saga to update.
-            context: The new context data.
-            current_version: The expected current version of the saga execution.
-                             If provided, optimistic locking will be used.
-        Raises:
-            SagaConcurrencyError: If optimistic locking fails.
-        """
-
-    @abc.abstractmethod
-    async def update_status(
-        self,
-        saga_id: uuid.UUID,
-        status: SagaStatus,
-    ) -> None:
-        """Update saga global status."""
-
-    @abc.abstractmethod
-    async def log_step(
-        self,
-        saga_id: uuid.UUID,
-        step_name: str,
-        action: typing.Literal["act", "compensate"],
-        status: SagaStepStatus,
-        details: str | None = None,
-    ) -> None:
-        """Log a step transition."""
-
-    @abc.abstractmethod
-    async def load_saga_state(
-        self,
-        saga_id: uuid.UUID,
-        *,
-        read_for_update: bool = False,
-    ) -> tuple[SagaStatus, dict[str, typing.Any], int]:
-        """Load current saga status, context, and version."""
-
-    @abc.abstractmethod
-    async def get_step_history(
-        self,
-        saga_id: uuid.UUID,
-    ) -> list[SagaLogEntry]:
-        """Get step execution history."""
-
-    @abc.abstractmethod
-    async def get_sagas_for_recovery(
-        self,
-        limit: int,
-        max_recovery_attempts: int = 5,
-        stale_after_seconds: int | None = None,
-    ) -> list[uuid.UUID]:
-        """Return saga IDs that need recovery.
-
-        Args:
-            limit: Maximum number of saga IDs to return.
-            max_recovery_attempts: Only include sagas with recovery_attempts
-                strictly less than this value. Default 5.
-            stale_after_seconds: If set, only include sagas whose updated_at
-                is older than (now_utc - stale_after_seconds). Use this to
-                avoid picking sagas that are currently being executed (recently
-                updated). None means no staleness filter (backward compatible).
-
-        Returns:
-            List of saga IDs (RUNNING or COMPENSATING only; FAILED sagas are
-            not included), ordered by updated_at ascending, with
-            recovery_attempts < max_recovery_attempts, and optionally
-            updated_at older than the staleness threshold.
-        """
-
-    @abc.abstractmethod
-    async def increment_recovery_attempts(
-        self,
-        saga_id: uuid.UUID,
-        new_status: SagaStatus | None = None,
-    ) -> None:
-        """Atomically increment recovery attempts after a failed recovery.
-
-        Updates recovery_attempts += 1, updated_at = now(), and optionally
-        status. Also increments version for optimistic locking.
-
-        Args:
-            saga_id: The saga to update.
-            new_status: If provided, set saga status to this value (e.g. FAILED).
-        """