python-saga-orchestrator 0.5.0__tar.gz → 0.7.0__tar.gz

python_saga_orchestrator-0.7.0/Makefile

@@ -0,0 +1,16 @@
+.PHONY: format tests lint
+
+lint: format
+test: tests
+
+
+format:
+	@ruff format .
+	@ruff check . --fix
+
+tests:
+	docker compose up \
+		--build \
+		--abort-on-container-exit \
+		--exit-code-from tests
+	docker compose down -v

{python_saga_orchestrator-0.5.0 → python_saga_orchestrator-0.7.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: python-saga-orchestrator
-Version: 0.5.0
+Version: 0.7.0
 Summary: Lightweight embedded saga orchestrator for asyncio Python services
 Author-email: Maxim Vasilyev <mayxis@inbox.ru>
 License-Expression: MIT
@@ -54,6 +54,7 @@ Unlike external workflow platforms, this library runs inside your service and st
 - async queue-style steps through `StepAwaitEvent` and `notify(...)`
 - administrative operations through `SagaAdmin`
 - PostgreSQL-first reliability using `SELECT ... FOR UPDATE`
+- strict CQRS-style separation of historical step data (`InputModel`) and async triggers (`Events`)
 
 ## Installation
 
@@ -90,8 +91,10 @@ pip install '.[dev]'
 ### `BaseStep`
 
 Each saga step is a class with:
-- `execute(inp) -> out`
-- optional `compensate(inp, out) -> None`
+- `execute(self, inp, event_type=None, event_payload=None) -> out`
+- optional `compensate(self, inp, out, event_type=None, event_payload=None) -> None`
+
+The `inp` object represents the immutable historical command parameters (mapped via `input_map`), while `event_type` and `event_payload` receive dynamic asynchronous continuation signals.
 
 Steps are regular Python objects. In practice they are created once at application startup and reused.
 
@@ -139,6 +142,7 @@ Your SQLAlchemy model inherits `SagaStateMixin` to store:
 ```python
 import uuid
 from datetime import timedelta
+from typing import Any
 
 from pydantic import BaseModel
 from sqlalchemy import ForeignKey
@@ -196,15 +200,21 @@ class ChargeOutput(BaseModel):
 
 
 class ReserveInventoryStep(BaseStep[ReserveInput, ReserveOutput]):
-    async def execute(self, inp: ReserveInput) -> ReserveOutput:
+    async def execute(
+        self, inp: ReserveInput, event_type: str | None = None, event_payload: Any | None = None
+    ) -> ReserveOutput:
         return ReserveOutput(reservation_id=f"res-{inp.order_id}")
 
-    async def compensate(self, inp: ReserveInput, out: ReserveOutput) -> None:
+    async def compensate(
+        self, inp: ReserveInput, out: ReserveOutput, event_type: str | None = None, event_payload: Any | None = None
+    ) -> None:
         return None
 
 
 class ChargePaymentStep(BaseStep[ChargeInput, ChargeOutput]):
-    async def execute(self, inp: ChargeInput) -> ChargeOutput:
+    async def execute(
+        self, inp: ChargeInput, event_type: str | None = None, event_payload: Any | None = None
+    ) -> ChargeOutput:
         return ChargeOutput(payment_id=f"pay-{inp.reservation_id}")
 
 
@@ -299,7 +309,7 @@ token = await orchestrator.await_event(
 )
 ```
 
-The event payload is stored in saga context and can be used by root-step `input_map` functions through `InputContext`.
+When a suspended saga is awakened by an event, the orchestrator passes the event directly to the step's `execute` or `compensate` method via the `event_type` and `event_payload` arguments. This strictly separates historical context (`InputModel`) from dynamic asynchronous triggers (`Events`).
 
 For distributed consumers, use transactional inbox ingestion first, then process inbox rows:
 

{python_saga_orchestrator-0.5.0 → python_saga_orchestrator-0.7.0}/README.md

@@ -20,6 +20,7 @@ Unlike external workflow platforms, this library runs inside your service and st
 - async queue-style steps through `StepAwaitEvent` and `notify(...)`
 - administrative operations through `SagaAdmin`
 - PostgreSQL-first reliability using `SELECT ... FOR UPDATE`
+- strict CQRS-style separation of historical step data (`InputModel`) and async triggers (`Events`)
 
 ## Installation
 
@@ -56,8 +57,10 @@ pip install '.[dev]'
 ### `BaseStep`
 
 Each saga step is a class with:
-- `execute(inp) -> out`
-- optional `compensate(inp, out) -> None`
+- `execute(self, inp, event_type=None, event_payload=None) -> out`
+- optional `compensate(self, inp, out, event_type=None, event_payload=None) -> None`
+
+The `inp` object represents the immutable historical command parameters (mapped via `input_map`), while `event_type` and `event_payload` receive dynamic asynchronous continuation signals.
 
 Steps are regular Python objects. In practice they are created once at application startup and reused.
 
@@ -105,6 +108,7 @@ Your SQLAlchemy model inherits `SagaStateMixin` to store:
 ```python
 import uuid
 from datetime import timedelta
+from typing import Any
 
 from pydantic import BaseModel
 from sqlalchemy import ForeignKey
@@ -162,15 +166,21 @@ class ChargeOutput(BaseModel):
 
 
 class ReserveInventoryStep(BaseStep[ReserveInput, ReserveOutput]):
-    async def execute(self, inp: ReserveInput) -> ReserveOutput:
+    async def execute(
+        self, inp: ReserveInput, event_type: str | None = None, event_payload: Any | None = None
+    ) -> ReserveOutput:
         return ReserveOutput(reservation_id=f"res-{inp.order_id}")
 
-    async def compensate(self, inp: ReserveInput, out: ReserveOutput) -> None:
+    async def compensate(
+        self, inp: ReserveInput, out: ReserveOutput, event_type: str | None = None, event_payload: Any | None = None
+    ) -> None:
         return None
 
 
 class ChargePaymentStep(BaseStep[ChargeInput, ChargeOutput]):
-    async def execute(self, inp: ChargeInput) -> ChargeOutput:
+    async def execute(
+        self, inp: ChargeInput, event_type: str | None = None, event_payload: Any | None = None
+    ) -> ChargeOutput:
         return ChargeOutput(payment_id=f"pay-{inp.reservation_id}")
 
 
@@ -265,7 +275,7 @@ token = await orchestrator.await_event(
 )
 ```
 
-The event payload is stored in saga context and can be used by root-step `input_map` functions through `InputContext`.
+When a suspended saga is awakened by an event, the orchestrator passes the event directly to the step's `execute` or `compensate` method via the `event_type` and `event_payload` arguments. This strictly separates historical context (`InputModel`) from dynamic asynchronous triggers (`Events`).
 
 For distributed consumers, use transactional inbox ingestion first, then process inbox rows:
 

{python_saga_orchestrator-0.5.0 → python_saga_orchestrator-0.7.0}/examples/common.py

@@ -2,6 +2,7 @@ from __future__ import annotations
 
 import os
 from datetime import timedelta
+from typing import Any
 from uuid import UUID
 
 from pydantic import BaseModel
@@ -73,14 +74,25 @@ class FinalizeOutput(BaseModel):
 
 
 class ReserveResourcesStep(BaseStep[StartInput, StartOutput]):
-    async def execute(self, inp: StartInput) -> StartOutput:
+    async def execute(
+        self,
+        inp: StartInput,
+        event_type: str | None = None,
+        event_payload: Any | None = None,
+    ) -> StartOutput:
         print(f"[reserve] reserving resources for {inp.model_name}")
         return StartOutput(
             model_name=inp.model_name,
             reservation_id=f"reservation-{inp.model_name}",
         )
 
-    async def compensate(self, inp: StartInput, out: StartOutput) -> None:
+    async def compensate(
+        self,
+        inp: StartInput,
+        out: StartOutput,
+        event_type: str | None = None,
+        event_payload: Any | None = None,
+    ) -> None:
         print(f"[reserve] compensating reservation {out.reservation_id}")
 
 
@@ -88,7 +100,12 @@ class DeployModelStep(BaseStep[DeployInput, DeployOutput]):
     def __init__(self) -> None:
         self.calls = 0
 
-    async def execute(self, inp: DeployInput) -> DeployOutput:
+    async def execute(
+        self,
+        inp: DeployInput,
+        event_type: str | None = None,
+        event_payload: Any | None = None,
+    ) -> DeployOutput:
         self.calls += 1
         print(f"[deploy] attempt={self.calls} model={inp.model_name}")
         if self.calls == 1:
@@ -97,19 +114,34 @@ class DeployModelStep(BaseStep[DeployInput, DeployOutput]):
 
 
 class FinalizeStep(BaseStep[FinalizeInput, FinalizeOutput]):
-    async def execute(self, inp: FinalizeInput) -> FinalizeOutput:
+    async def execute(
+        self,
+        inp: FinalizeInput,
+        event_type: str | None = None,
+        event_payload: Any | None = None,
+    ) -> FinalizeOutput:
         print(f"[finalize] model is available at {inp.endpoint}")
         return FinalizeOutput(status="COMPLETED")
 
 
 class FailingPublishStep(BaseStep[DeployInput, DeployOutput]):
-    async def execute(self, inp: DeployInput) -> DeployOutput:
+    async def execute(
+        self,
+        inp: DeployInput,
+        event_type: str | None = None,
+        event_payload: Any | None = None,
+    ) -> DeployOutput:
         print(f"[publish] forcing failure for {inp.model_name}")
         raise RuntimeError("publish failed")
 
 
 class ManualApprovalStep(BaseStep[StartInput, DeployOutput]):
-    async def execute(self, inp: StartInput) -> DeployOutput:
+    async def execute(
+        self,
+        inp: StartInput,
+        event_type: str | None = None,
+        event_payload: Any | None = None,
+    ) -> DeployOutput:
         print(f"[approval] waiting for manual approval for {inp.model_name}")
         raise RuntimeError("approval is pending")
 

{python_saga_orchestrator-0.5.0 → python_saga_orchestrator-0.7.0}/examples/http_and_queue.py

@@ -5,6 +5,7 @@ import contextlib
 import json
 import os
 from datetime import timedelta
+from typing import Any
 from uuid import uuid4
 
 from aio_pika import DeliveryMode, IncomingMessage, Message, connect_robust
@@ -70,8 +71,6 @@ class ReserveInput(BaseModel):
     order_id: str
     gateway_url: str
     correlation_id: str
-    response_event_type: str | None = None
-    response_payload: dict | None = None
 
 
 class ReserveOutput(BaseModel):
@@ -82,8 +81,6 @@ class ActivateInput(BaseModel):
     aggregation_id: str
     reservation_id: str
     correlation_id: str
-    response_event_type: str | None = None
-    response_payload: dict | None = None
 
 
 class ActivateOutput(BaseModel):
@@ -91,7 +88,12 @@ class ActivateOutput(BaseModel):
 
 
 class PrepareStep(BaseStep[PrepareInput, PrepareOutput]):
-    async def execute(self, inp: PrepareInput) -> PrepareOutput:
+    async def execute(
+        self,
+        inp: PrepareInput,
+        event_type: str | None = None,
+        event_payload: Any | None = None,
+    ) -> PrepareOutput:
         print(f"[http] request: prepare order={inp.order_id}")
         await asyncio.sleep(0.05)
         return PrepareOutput(
@@ -101,8 +103,13 @@ class PrepareStep(BaseStep[PrepareInput, PrepareOutput]):
 
 
 class ReserveQueueStep(BaseStep[ReserveInput, ReserveOutput]):
-    async def execute(self, inp: ReserveInput) -> ReserveOutput | StepAwaitEvent:
-        if inp.response_event_type is None:
+    async def execute(
+        self,
+        inp: ReserveInput,
+        event_type: str | None = None,
+        event_payload: Any | None = None,
+    ) -> ReserveOutput | StepAwaitEvent:
+        if event_type is None:
             print(f"[queue] send reserve command for order={inp.order_id}")
             return StepAwaitEvent(
                 event_types=("reserve.success", "reserve.failed"),
@@ -121,18 +128,24 @@ class ReserveQueueStep(BaseStep[ReserveInput, ReserveOutput]):
                     ),
                 ),
             )
-        if inp.response_event_type == "reserve.failed":
-            reason = (inp.response_payload or {}).get("reason", "unknown")
+        if event_type == "reserve.failed":
+            reason = (event_payload or {}).get("reason", "unknown")
             raise RuntimeError(f"reserve failed: {reason}")
-        if inp.response_event_type != "reserve.success":
-            raise RuntimeError(f"unexpected reserve event: {inp.response_event_type}")
-        payload = inp.response_payload or {}
+        if event_type != "reserve.success":
+            raise RuntimeError(f"unexpected reserve event: {event_type}")
+
+        payload = event_payload or {}
         return ReserveOutput(reservation_id=payload["reservation_id"])
 
 
 class ActivateQueueStep(BaseStep[ActivateInput, ActivateOutput]):
-    async def execute(self, inp: ActivateInput) -> ActivateOutput | StepAwaitEvent:
-        if inp.response_event_type is None:
+    async def execute(
+        self,
+        inp: ActivateInput,
+        event_type: str | None = None,
+        event_payload: Any | None = None,
+    ) -> ActivateOutput | StepAwaitEvent:
+        if event_type is None:
             print(f"[queue] send activate command for reservation={inp.reservation_id}")
             return StepAwaitEvent(
                 event_types=("activate.success", "activate.failed"),
@@ -150,15 +163,17 @@ class ActivateQueueStep(BaseStep[ActivateInput, ActivateOutput]):
                     ),
                 ),
             )
-        if inp.response_event_type == "activate.failed":
-            reason = (inp.response_payload or {}).get("reason", "unknown")
+        if event_type == "activate.failed":
+            reason = (event_payload or {}).get("reason", "unknown")
             raise RuntimeError(f"activate failed: {reason}")
-        if inp.response_event_type != "activate.success":
-            raise RuntimeError(f"unexpected activate event: {inp.response_event_type}")
-        payload = inp.response_payload or {}
+        if event_type != "activate.success":
+            raise RuntimeError(f"unexpected activate event: {event_type}")
+
+        payload = event_payload or {}
         return ActivateOutput(deployment_id=payload["deployment_id"])
 
 
+# ... (RabbitMqPublisher остается без изменений) ...
 class RabbitMqPublisher:
     def __init__(self, channel) -> None:
         self._channel = channel
@@ -214,10 +229,6 @@ async def main() -> None:
             order_id=ctx.initial_data["order_id"],
             gateway_url=ctx.step_outputs["step_0"]["gateway_url"],
             correlation_id=f"reserve-{ctx.initial_data['order_id']}",
-            response_event_type=(ctx.context.get("latest_event_meta") or {}).get(
-                "event_type"
-            ),
-            response_payload=ctx.latest_event,
         ),
     )
     builder.add_step(
@@ -226,10 +237,6 @@ async def main() -> None:
             aggregation_id=ctx.initial_data["order_id"],
             reservation_id=ctx.step_outputs["step_1"]["reservation_id"],
             correlation_id=f"activate-{ctx.step_outputs['step_1']['reservation_id']}",
-            response_event_type=(ctx.context.get("latest_event_meta") or {}).get(
-                "event_type"
-            ),
-            response_payload=ctx.latest_event,
         ),
     )
     orchestrator.register("http_queue_3_steps", builder.build())

{python_saga_orchestrator-0.5.0 → python_saga_orchestrator-0.7.0}/examples/llm_deploy.py

@@ -4,6 +4,7 @@ import asyncio
 import os
 import uuid
 from datetime import timedelta
+from typing import Any
 
 from pydantic import BaseModel
 from sqlalchemy import ForeignKey
@@ -65,12 +66,22 @@ class DeployOutput(BaseModel):
 
 
 class CheckModelStep(BaseStep[CheckModelInput, CheckModelOutput]):
-    async def execute(self, inp: CheckModelInput) -> CheckModelOutput:
+    async def execute(
+        self,
+        inp: CheckModelInput,
+        event_type: str | None = None,
+        event_payload: Any | None = None,
+    ) -> CheckModelOutput:
         return CheckModelOutput(exists=inp.model_name in {"llama-2"})
 
 
 class DeployStep(BaseStep[DeployInput, DeployOutput]):
-    async def execute(self, inp: DeployInput) -> DeployOutput:
+    async def execute(
+        self,
+        inp: DeployInput,
+        event_type: str | None = None,
+        event_payload: Any | None = None,
+    ) -> DeployOutput:
         await asyncio.sleep(0.01)
         return DeployOutput(endpoint=f"https://models.local/{inp.model_name}")
 

{python_saga_orchestrator-0.5.0 → python_saga_orchestrator-0.7.0}/python_saga_orchestrator.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: python-saga-orchestrator
-Version: 0.5.0
+Version: 0.7.0
 Summary: Lightweight embedded saga orchestrator for asyncio Python services
 Author-email: Maxim Vasilyev <mayxis@inbox.ru>
 License-Expression: MIT
@@ -54,6 +54,7 @@ Unlike external workflow platforms, this library runs inside your service and st
 - async queue-style steps through `StepAwaitEvent` and `notify(...)`
 - administrative operations through `SagaAdmin`
 - PostgreSQL-first reliability using `SELECT ... FOR UPDATE`
+- strict CQRS-style separation of historical step data (`InputModel`) and async triggers (`Events`)
 
 ## Installation
 
@@ -90,8 +91,10 @@ pip install '.[dev]'
 ### `BaseStep`
 
 Each saga step is a class with:
-- `execute(inp) -> out`
-- optional `compensate(inp, out) -> None`
+- `execute(self, inp, event_type=None, event_payload=None) -> out`
+- optional `compensate(self, inp, out, event_type=None, event_payload=None) -> None`
+
+The `inp` object represents the immutable historical command parameters (mapped via `input_map`), while `event_type` and `event_payload` receive dynamic asynchronous continuation signals.
 
 Steps are regular Python objects. In practice they are created once at application startup and reused.
 
@@ -139,6 +142,7 @@ Your SQLAlchemy model inherits `SagaStateMixin` to store:
 ```python
 import uuid
 from datetime import timedelta
+from typing import Any
 
 from pydantic import BaseModel
 from sqlalchemy import ForeignKey
@@ -196,15 +200,21 @@ class ChargeOutput(BaseModel):
 
 
 class ReserveInventoryStep(BaseStep[ReserveInput, ReserveOutput]):
-    async def execute(self, inp: ReserveInput) -> ReserveOutput:
+    async def execute(
+        self, inp: ReserveInput, event_type: str | None = None, event_payload: Any | None = None
+    ) -> ReserveOutput:
         return ReserveOutput(reservation_id=f"res-{inp.order_id}")
 
-    async def compensate(self, inp: ReserveInput, out: ReserveOutput) -> None:
+    async def compensate(
+        self, inp: ReserveInput, out: ReserveOutput, event_type: str | None = None, event_payload: Any | None = None
+    ) -> None:
         return None
 
 
 class ChargePaymentStep(BaseStep[ChargeInput, ChargeOutput]):
-    async def execute(self, inp: ChargeInput) -> ChargeOutput:
+    async def execute(
+        self, inp: ChargeInput, event_type: str | None = None, event_payload: Any | None = None
+    ) -> ChargeOutput:
         return ChargeOutput(payment_id=f"pay-{inp.reservation_id}")
 
 
@@ -299,7 +309,7 @@ token = await orchestrator.await_event(
 )
 ```
 
-The event payload is stored in saga context and can be used by root-step `input_map` functions through `InputContext`.
+When a suspended saga is awakened by an event, the orchestrator passes the event directly to the step's `execute` or `compensate` method via the `event_type` and `event_payload` arguments. This strictly separates historical context (`InputModel`) from dynamic asynchronous triggers (`Events`).
 
 For distributed consumers, use transactional inbox ingestion first, then process inbox rows:
 

{python_saga_orchestrator-0.5.0 → python_saga_orchestrator-0.7.0}/saga_orchestrator/_version.py

@@ -18,7 +18,7 @@ version_tuple: tuple[int | str, ...]
 commit_id: str | None
 __commit_id__: str | None
 
-__version__ = version = '0.5.0'
-__version_tuple__ = version_tuple = (0, 5, 0)
+__version__ = version = '0.7.0'
+__version_tuple__ = version_tuple = (0, 7, 0)
 
 __commit_id__ = commit_id = None