python-cqrs 4.7.0__tar.gz → 4.7.2__tar.gz

{python_cqrs-4.7.0/src/python_cqrs.egg-info → python_cqrs-4.7.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: python-cqrs
-Version: 4.7.0
+Version: 4.7.2
 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.0 → python_cqrs-4.7.2}/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.0"
+version = "4.7.2"
 
 [project.optional-dependencies]
 aiobreaker = ["aiobreaker>=0.3.0"]

{python_cqrs-4.7.0 → python_cqrs-4.7.2}/src/cqrs/saga/compensation.py

@@ -54,6 +54,14 @@ class SagaCompensator(typing.Generic[ContextT]):
         """
         await self._storage.update_status(self._saga_id, SagaStatus.COMPENSATING)
 
+        if not completed_steps:
+            logger.info(
+                f"Saga {self._saga_id}: completed_steps is empty, "
+                "skipping compensation (no step.compensate() will be called).",
+            )
+            await self._storage.update_status(self._saga_id, SagaStatus.FAILED)
+            return
+
         # Load history to skip already compensated steps
         history = await self._storage.get_step_history(self._saga_id)
         compensated_steps = {

{python_cqrs-4.7.0 → python_cqrs-4.7.2}/src/cqrs/saga/saga.py

@@ -234,6 +234,14 @@ class SagaTransaction(typing.Generic[ContextT]):
                         for step in reconstructed_steps
                     ]
 
+                    if not self._completed_steps:
+                        logger.warning(
+                            f"Saga {self._saga_id}: no completed steps to compensate "
+                            "(saga failed before any step finished 'act', or step names in "
+                            "storage do not match saga step class names). "
+                            "Marking as FAILED without calling compensate().",
+                        )
+
                     # Immediately proceed to compensation - no forward execution
                     await self._compensate()
 

{python_cqrs-4.7.0 → python_cqrs-4.7.2}/src/cqrs/saga/storage/memory.py

@@ -122,8 +122,9 @@ 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, SagaStatus.FAILED)
+        recoverable = (SagaStatus.RUNNING, SagaStatus.COMPENSATING)
         now = datetime.datetime.now(datetime.timezone.utc)
         threshold = (
             (now - datetime.timedelta(seconds=stale_after_seconds))
@@ -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.2/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.0 → python_cqrs-4.7.2}/src/cqrs/saga/storage/sqlalchemy.py

@@ -317,11 +317,11 @@ 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,
             SagaStatus.COMPENSATING,
-            SagaStatus.FAILED,
         )
         async with self.session_factory() as session:
             stmt = (
@@ -329,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,
@@ -365,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.0 → python_cqrs-4.7.2/src/python_cqrs.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: python-cqrs
-Version: 4.7.0
+Version: 4.7.2
 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.0/src/cqrs/saga/storage/protocol.py

@@ -1,112 +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, COMPENSATING, or FAILED), 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).
-        """