python-saga-orchestrator 0.2.3.dev0__tar.gz → 0.3.0__tar.gz

{python_saga_orchestrator-0.2.3.dev0 → python_saga_orchestrator-0.3.0}/.github/workflows/publish.yml

@@ -31,6 +31,10 @@ jobs:
           python -m pip install --upgrade pip
           python -m pip install build twine setuptools-scm
 
+      - name: Pin version from tag for build
+        run: |
+          echo "SETUPTOOLS_SCM_PRETEND_VERSION=${GITHUB_REF_NAME#v}" >> "$GITHUB_ENV"
+
       - name: Validate version matches tag
         run: |
           EXPECTED_VERSION="${GITHUB_REF_NAME#v}"

{python_saga_orchestrator-0.2.3.dev0 → python_saga_orchestrator-0.3.0}/Makefile

@@ -5,8 +5,8 @@ test: tests
 
 
 format:
-	@isort .
-	@black .
+	@ruff format .
+	@ruff check . --fix
 
 tests:
 	@docker compose up --build --abort-on-container-exit

{python_saga_orchestrator-0.2.3.dev0 → python_saga_orchestrator-0.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: python-saga-orchestrator
-Version: 0.2.3.dev0
+Version: 0.3.0
 Summary: Lightweight embedded saga orchestrator for asyncio Python services
 Author-email: Maxim Vasilyev <mayxis@inbox.ru>
 License-Expression: MIT

{python_saga_orchestrator-0.2.3.dev0 → python_saga_orchestrator-0.3.0}/pyproject.toml

@@ -71,10 +71,16 @@ testpaths = ["tests"]
 [tool.ruff]
 target-version = "py312"
 
+[tool.ruff.lint]
+select = [
+    "W", # pycodestyle warnings
+    "F", # pyflakes
+    "I", # isort
+]
+
 [dependency-groups]
 dev = [
-    "black>=26.3.1",
-    "isort>=8.0.1",
     "pytest>=9.0.3",
     "pytest-asyncio>=1.3.0",
+    "ruff>=0.15.12",
 ]

{python_saga_orchestrator-0.2.3.dev0 → python_saga_orchestrator-0.3.0}/python_saga_orchestrator.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: python-saga-orchestrator
-Version: 0.2.3.dev0
+Version: 0.3.0
 Summary: Lightweight embedded saga orchestrator for asyncio Python services
 Author-email: Maxim Vasilyev <mayxis@inbox.ru>
 License-Expression: MIT

{python_saga_orchestrator-0.2.3.dev0 → python_saga_orchestrator-0.3.0}/python_saga_orchestrator.egg-info/SOURCES.txt

@@ -43,6 +43,7 @@ saga_orchestrator/domain/models/retry.py
 saga_orchestrator/domain/models/saga_snapshot.py
 saga_orchestrator/domain/models/step.py
 saga_orchestrator/domain/models/enums/__init__.py
+saga_orchestrator/domain/models/enums/base_str_enum.py
 saga_orchestrator/domain/models/enums/saga_status.py
 saga_orchestrator/domain/models/enums/saga_step_phase.py
 saga_orchestrator/domain/models/enums/saga_step_status.py
@@ -79,6 +80,8 @@ tests/integration/test_repository.py
 tests/unit/__init__.py
 tests/unit/test_builder.py
 tests/unit/test_inbox_extensibility.py
+tests/unit/test_input_context.py
 tests/unit/test_orchestrator_helpers.py
 tests/unit/test_outbox_extensibility.py
-tests/unit/test_retry.py
+tests/unit/test_retry.py
+tests/unit/test_step_type_resolution.py

{python_saga_orchestrator-0.2.3.dev0 → python_saga_orchestrator-0.3.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.2.3.dev0'
-__version_tuple__ = version_tuple = (0, 2, 3, 'dev0')
+__version__ = version = '0.3.0'
+__version_tuple__ = version_tuple = (0, 3, 0)
 
-__commit_id__ = commit_id = 'g4268b7950'
+__commit_id__ = commit_id = None

{python_saga_orchestrator-0.2.3.dev0 → python_saga_orchestrator-0.3.0}/saga_orchestrator/domain/models/context.py

@@ -55,7 +55,6 @@ class SagaStepHistoryEntry(BaseModel):
 
 
 class SagaContext(BaseModel):
-
     model_config = ConfigDict(from_attributes=True, validate_assignment=True)
 
     # -- Core data --

python_saga_orchestrator-0.3.0/saga_orchestrator/domain/models/enums/base_str_enum.py

@@ -0,0 +1,10 @@
+from enum import StrEnum
+
+
+class BaseStrEnum(StrEnum):
+    @staticmethod
+    def _generate_next_value_(name, start, count, last_values) -> str:
+        """
+        Return the upper-cased version of the member name.
+        """
+        return name.upper()

python_saga_orchestrator-0.3.0/saga_orchestrator/domain/models/enums/saga_status.py

@@ -0,0 +1,17 @@
+from enum import auto
+
+from .base_str_enum import BaseStrEnum
+
+
+class SagaStatus(BaseStrEnum):
+    RUNNING = auto()
+    SUSPENDED = auto()
+    FAILED = auto()
+    COMPENSATING = auto()
+    COMPLETED = auto()
+    COMPENSATING_SUSPENDED = auto()
+    COMPENSATED = auto()
+
+    @property
+    def is_terminal(self) -> bool:
+        return self in {self.FAILED, self.COMPLETED, self.COMPENSATED}

python_saga_orchestrator-0.3.0/saga_orchestrator/domain/models/enums/saga_step_phase.py

@@ -0,0 +1,9 @@
+from enum import auto
+
+from .base_str_enum import BaseStrEnum
+
+
+class SagaStepPhase(BaseStrEnum):
+    COMPENSATE = auto()
+    SUCCESS = auto()
+    EXECUTE = auto()

python_saga_orchestrator-0.3.0/saga_orchestrator/domain/models/enums/saga_step_status.py

@@ -0,0 +1,9 @@
+from enum import auto
+
+from .base_str_enum import BaseStrEnum
+
+
+class SagaStepStatus(BaseStrEnum):
+    SUCCESS = auto()
+    ERROR = auto()
+    WAITING = auto()

{python_saga_orchestrator-0.2.3.dev0 → python_saga_orchestrator-0.3.0}/saga_orchestrator/domain/models/step.py

@@ -1,6 +1,5 @@
 from __future__ import annotations
 
-import contextlib
 import inspect
 from collections.abc import Callable
 from dataclasses import dataclass
@@ -8,6 +7,7 @@ from datetime import timedelta
 from typing import (
     Any,
     Generic,
+    Mapping,
     TypeAlias,
     TypeVar,
     get_args,
@@ -60,16 +60,16 @@ class InputContext:
         """
         Возвращает тип ('event_type') последнего полученного события.
         """
-        with contextlib.suppress(KeyError, TypeError):
-            return self.context["latest_event_meta"]["event_type"]
-        return None
+        if not isinstance(self.context.latest_event_meta, Mapping):
+            return None
+        return self.context.latest_event_meta.get("event_type")
 
     @property
     def latest_event_payload(self) -> Any | None:
         """
         Возвращает "сырую" полезную нагрузку (payload) последнего полученного события.
         """
-        return self.context.get("latest_event")
+        return self.context.latest_event
 
 
 RootInputMap: TypeAlias = Callable[[InputContext], InputModelT | dict[str, Any]]
@@ -102,16 +102,56 @@ class BaseStep(Generic[InputModelT, OutputModelT]):
 
     def __init_subclass__(cls) -> None:
         super().__init_subclass__()
-        if cls is BaseStep:
+        if cls is BaseStep or inspect.isabstract(cls):
             return
+        generic_base = None
+        for base in getattr(cls, "__orig_bases__", []):
+            origin = get_origin(base)
+            if origin and issubclass(origin, BaseStep):
+                generic_base = base
+                break
+
+        if not generic_base:
+            raise TypeValidationError(
+                f"Could not find generic parameters for {cls.__name__}. "
+                f"Ensure it inherits from a parameterized BaseStep, e.g., BaseStep[MyInput, MyOutput]"
+            )
+
+        concrete_args = get_args(generic_base)
+        if not concrete_args or any(isinstance(arg, TypeVar) for arg in concrete_args):
+            raise TypeValidationError(
+                f"Step '{cls.__name__}' inherits from a generic Step "
+                "but was not parameterized with concrete Input/Output models."
+            )
+
+        concrete_input_model, concrete_output_model = concrete_args
+        try:
+            hints = get_type_hints(
+                cls.execute,
+                globalns=inspect.getmodule(cls).__dict__,
+                include_extras=True,
+            )
+        except (AttributeError, NameError) as e:
+            raise TypeValidationError(
+                f"Could not resolve type hints for '{cls.__name__}.execute'. "
+                f"Ensure all types are correctly imported. Original error: {e}"
+            )
 
-        hints = get_type_hints(cls.execute)
         if "inp" not in hints or "return" not in hints:
             raise TypeValidationError(
                 f"Step '{cls.__name__}' must type annotate execute(inp) and return type"
             )
-        input_model = hints["inp"]
-        output_model = cls._resolve_output_model(hints["return"])
+
+        input_annotation = hints["inp"]
+        if isinstance(input_annotation, TypeVar):
+            input_model = concrete_input_model
+        else:
+            input_model = input_annotation
+
+        return_annotation = hints["return"]
+        output_model = cls._resolve_output_model(
+            return_annotation, concrete_output_model
+        )
         if not (inspect.isclass(input_model) and issubclass(input_model, BaseModel)):
             raise TypeValidationError(
                 f"Step '{cls.__name__}' input must inherit from pydantic BaseModel"
@@ -120,22 +160,38 @@ class BaseStep(Generic[InputModelT, OutputModelT]):
         cls.output_model = output_model
 
     @staticmethod
-    def _resolve_output_model(annotation: Any) -> type[BaseModel]:
+    def _resolve_output_model(
+        annotation: Any, concrete_model: type[BaseModel] | None = None
+    ) -> type[BaseModel]:
+        def find_model_in_args(args_tuple: tuple) -> list[type[BaseModel]]:
+            candidates = []
+            for arg in args_tuple:
+                if isinstance(arg, TypeVar) and concrete_model:
+                    candidates.append(concrete_model)
+                elif inspect.isclass(arg) and issubclass(arg, BaseModel):
+                    candidates.append(arg)
+            return list(dict.fromkeys(candidates))
+
         if inspect.isclass(annotation) and issubclass(annotation, BaseModel):
             return annotation
 
         origin = get_origin(annotation)
         if origin is None:
+            if isinstance(annotation, TypeVar) and concrete_model:
+                return concrete_model
             raise TypeValidationError("Step execute return type must include BaseModel")
-        args = tuple(arg for arg in get_args(annotation) if arg is not type(None))
-        model_candidates = [
-            arg for arg in args if inspect.isclass(arg) and issubclass(arg, BaseModel)
-        ]
+
+        args = get_args(annotation)
+        model_candidates = find_model_in_args(args)
         await_candidates = [arg for arg in args if arg is StepAwaitEvent]
+
         if len(model_candidates) == 1 and len(await_candidates) <= 1:
             return model_candidates[0]
+
         raise TypeValidationError(
-            "Step execute return type must be BaseModel or BaseModel | StepAwaitEvent"
+            f"Step execute return type must be BaseModel or BaseModel | StepAwaitEvent. "
+            f"Found models: {[m.__name__ for m in model_candidates]}, "
+            f"Found await events: {len(await_candidates)}."
         )
 
     async def execute(self, inp: InputModelT) -> OutputModelT | StepAwaitEvent:

{python_saga_orchestrator-0.2.3.dev0 → python_saga_orchestrator-0.3.0}/saga_orchestrator/inbox/models.py

@@ -5,9 +5,8 @@ from datetime import datetime
 from enum import Enum
 from typing import Any
 
-from sqlalchemy import JSON, DateTime
+from sqlalchemy import JSON, DateTime, Integer, String, Text, UniqueConstraint, func
 from sqlalchemy import Enum as SqlEnum
-from sqlalchemy import Integer, String, Text, UniqueConstraint, func
 from sqlalchemy.dialects.postgresql import JSONB, UUID
 from sqlalchemy.ext.mutable import MutableDict
 from sqlalchemy.orm import Mapped, declarative_mixin, mapped_column

{python_saga_orchestrator-0.2.3.dev0 → python_saga_orchestrator-0.3.0}/saga_orchestrator/outbox/models.py

@@ -5,9 +5,8 @@ from datetime import datetime
 from enum import Enum
 from typing import Any
 
-from sqlalchemy import JSON, DateTime
+from sqlalchemy import JSON, DateTime, Integer, String, Text, func
 from sqlalchemy import Enum as SqlEnum
-from sqlalchemy import Integer, String, Text, func
 from sqlalchemy.dialects.postgresql import JSONB, UUID
 from sqlalchemy.ext.mutable import MutableDict
 from sqlalchemy.orm import Mapped, declarative_mixin, mapped_column

{python_saga_orchestrator-0.2.3.dev0 → python_saga_orchestrator-0.3.0}/tests/integration/test_admin_api.py

@@ -58,7 +58,7 @@ async def test_admin_retry_rejects_failed_saga_after_compensation(session_maker)
     )
     state = await admin.get_saga(saga_id)
     assert state.status == SagaStatus.COMPENSATED
-    assert any(entry.phase == "compensate" for entry in state.step_history)
+    assert any(entry.phase == "COMPENSATE" for entry in state.step_history)
 
     with pytest.raises(SagaStateError):
         await admin.retry_step(saga_id)
@@ -150,7 +150,7 @@ async def test_admin_compensate_rolls_back_suspended_saga(session_maker):
     state_after = await admin.get_saga(saga_id)
     assert state_after.status == SagaStatus.COMPENSATED
     assert compensating_step.compensated is True
-    assert any(entry.phase == "compensate" for entry in state_after.step_history)
+    assert any(entry.phase == "COMPENSATE" for entry in state_after.step_history)
 
 
 @pytest.mark.asyncio
@@ -225,7 +225,7 @@ async def test_get_admin_snapshot_returns(session_maker):
     assert isinstance(admin_snapshot.step_history, list)
     assert len(admin_snapshot.step_history) == 1
     assert admin_snapshot.step_history[0].step_name == "AddOneStep"
-    assert admin_snapshot.step_history[0].status == "success"
+    assert admin_snapshot.step_history[0].status == "SUCCESS"
 
 
 @pytest.mark.asyncio

{python_saga_orchestrator-0.2.3.dev0 → python_saga_orchestrator-0.3.0}/tests/integration/test_context_persistence.py

@@ -277,9 +277,9 @@ async def test_step_history_with_orm_model_is_persisted_and_rehydrated(
 
         rehydrated_entry = reloaded_saga.step_history[0]
 
-        assert isinstance(
-            rehydrated_entry, IntegrationSagaHistory
-        ), f"Expected IntegrationSagaHistory, got {type(rehydrated_entry)}"
+        assert isinstance(rehydrated_entry, IntegrationSagaHistory), (
+            f"Expected IntegrationSagaHistory, got {type(rehydrated_entry)}"
+        )
 
         assert rehydrated_entry.step_id == "test_step_orm"
         assert rehydrated_entry.status == SagaStepStatus.SUCCESS

python_saga_orchestrator-0.3.0/tests/unit/test_input_context.py

@@ -0,0 +1,86 @@
+from uuid import uuid4
+
+import pytest
+
+from saga_orchestrator import InputContext
+from saga_orchestrator.domain.models.context import SagaContext
+
+
+@pytest.mark.parametrize(
+    "test_id, saga_context_config, expected_type, expected_payload",
+    [
+        (
+            "happy_path",
+            {
+                "latest_event": {"user_id": 123},
+                "latest_event_meta": {
+                    "event_type": "user.created",
+                    "event_id": "evt-1",
+                },
+            },
+            "user.created",
+            {"user_id": 123},
+        ),
+        (
+            "no_event_data",
+            {},
+            None,
+            None,
+        ),
+        (
+            "meta_without_type",
+            {
+                "latest_event": {"data": "something"},
+                "latest_event_meta": {"source": "legacy_system"},
+            },
+            None,
+            {"data": "something"},
+        ),
+        (
+            "payload_is_none",
+            {
+                "latest_event": None,
+                "latest_event_meta": {"event_type": "user.deleted"},
+            },
+            "user.deleted",
+            None,
+        ),
+        (
+            "payload_is_primitive",
+            {
+                "latest_event": "simple_string_payload",
+                "latest_event_meta": {"event_type": "notification.sent"},
+            },
+            "notification.sent",
+            "simple_string_payload",
+        ),
+    ],
+)
+def test_input_context_properties_parametrized(
+    test_id, saga_context_config, expected_type, expected_payload
+):
+    """
+    Параметризованный тест для проверки свойств InputContext.
+    """
+    saga_id = uuid4()
+    initial_data = {"key": "value"}
+
+    saga_context = SagaContext(
+        saga_id=saga_id,
+        saga_name="test_saga",
+        initial_data=initial_data,
+        **saga_context_config,
+    )
+
+    input_ctx = InputContext(
+        saga_id=saga_id,
+        initial_data=initial_data,
+        context=saga_context,
+        step_outputs={},
+        latest_event=saga_context.latest_event,
+    )
+
+    assert input_ctx.latest_event_type == expected_type, f"Failed on test: {test_id}"
+    assert input_ctx.latest_event_payload == expected_payload, (
+        f"Failed on test: {test_id}"
+    )

python_saga_orchestrator-0.3.0/tests/unit/test_step_type_resolution.py

@@ -0,0 +1,136 @@
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+from dataclasses import dataclass
+from typing import Generic, TypeVar
+
+import pytest
+from pydantic import BaseModel
+
+from saga_orchestrator import BaseStep, TypeValidationError
+
+
+class OutboxEvent(BaseModel):
+    topic: str
+    payload: dict
+
+
+class InputModelA(BaseModel):
+    a: int
+
+
+class OutputModelA(BaseModel):
+    b: str
+
+
+class InputModelB(BaseModel):
+    x: float
+
+
+class OutputModelB(BaseModel):
+    y: bool
+
+
+InputModelT = TypeVar("InputModelT", bound=BaseModel)
+OutputModelT = TypeVar("OutputModelT", bound=BaseModel)
+
+
+@dataclass(frozen=True)
+class StepAwaitEvent:
+    event_types: tuple[str, ...] | None = None
+
+
+IntermediateInputT = TypeVar("IntermediateInputT", bound=BaseModel)
+IntermediateOutputT = TypeVar("IntermediateOutputT", bound=BaseModel)
+
+
+class AbstractIntermediateStep(
+    BaseStep[IntermediateInputT, IntermediateOutputT],
+    ABC,
+    Generic[IntermediateInputT, IntermediateOutputT],
+):
+    @abstractmethod
+    def some_abstract_method(self):
+        pass
+
+    async def execute(
+        self, inp: IntermediateInputT
+    ) -> IntermediateOutputT | StepAwaitEvent:
+        pass
+
+
+class TestTypeResolution:
+    def test_indirect_inheritance_resolves_types_correctly(self):
+        """
+        GIVEN a concrete step class inheriting from a generic abstract step
+        WHEN the concrete class is defined
+        THEN BaseStep.__init_subclass__ should correctly resolve input and output models.
+        """
+
+        class ConcreteStep(AbstractIntermediateStep[InputModelA, OutputModelA]):
+            def some_abstract_method(self):
+                pass
+
+        assert hasattr(ConcreteStep, "input_model")
+        assert hasattr(ConcreteStep, "output_model")
+        assert ConcreteStep.input_model is InputModelA
+        assert ConcreteStep.output_model is OutputModelA
+
+    def test_direct_inheritance_resolves_types_correctly(self):
+        """
+        GIVEN a concrete step class inheriting directly from BaseStep
+        WHEN the concrete class is defined
+        THEN input and output models should be resolved from its own `execute` method.
+        """
+
+        class DirectStep(BaseStep[InputModelB, OutputModelB]):
+            async def execute(self, inp: InputModelB) -> OutputModelB:
+                pass
+
+        assert DirectStep.input_model is InputModelB
+        assert DirectStep.output_model is OutputModelB
+
+    def test_missing_annotation_on_execute_raises_error(self):
+        """
+        GIVEN a step class with a missing type annotation on `execute`
+        WHEN the class is defined
+        THEN TypeValidationError should be raised.
+        """
+        with pytest.raises(TypeValidationError, match="must type annotate execute"):
+
+            class FaultyStep(BaseStep[InputModelA, OutputModelA]):
+                # `inp` не аннотирован
+                async def execute(self, inp) -> OutputModelA:
+                    pass
+
+    def test_wrong_parameterization_raises_error(self):
+        """
+        GIVEN a step class parameterized with a non-BaseModel type
+        WHEN the class is defined
+        THEN a TypeError or TypeValidationError should be raised.
+        """
+
+        @dataclass
+        class NotAModel:
+            pass
+
+        with pytest.raises(TypeValidationError, match="Could not resolve type hints"):
+
+            class FaultyStep(BaseStep[InputModelA, OutputModelA]):
+                async def execute(self, inp: NotAModel) -> OutputModelA:
+                    pass
+
+    def test_unparameterized_generic_step_raises_error(self):
+        """
+        GIVEN a concrete step inheriting from a generic abstract step without parameters
+        WHEN the class is defined
+        THEN TypeValidationError should be raised by our custom logic.
+        """
+        with pytest.raises(
+            TypeValidationError,
+            match="inherits from a generic Step but was not parameterized with concrete Input/Output models",
+        ):
+
+            class UnparameterizedStep(AbstractIntermediateStep):
+                def some_abstract_method(self):
+                    pass

python_saga_orchestrator-0.2.3.dev0/saga_orchestrator/domain/models/enums/saga_status.py

@@ -1,15 +0,0 @@
-from enum import StrEnum
-
-
-class SagaStatus(StrEnum):
-    RUNNING = "RUNNING"
-    SUSPENDED = "SUSPENDED"
-    FAILED = "FAILED"
-    COMPENSATING = "COMPENSATING"
-    COMPLETED = "COMPLETED"
-    COMPENSATING_SUSPENDED = "COMPENSATING_SUSPENDED"
-    COMPENSATED = "COMPENSATED"
-
-    @property
-    def is_terminal(self) -> bool:
-        return self in {self.FAILED, self.COMPLETED, self.COMPENSATED}

python_saga_orchestrator-0.2.3.dev0/saga_orchestrator/domain/models/enums/saga_step_phase.py

@@ -1,7 +0,0 @@
-from enum import StrEnum, auto
-
-
-class SagaStepPhase(StrEnum):
-    COMPENSATE = auto()
-    SUCCESS = auto()
-    EXECUTE = auto()

python_saga_orchestrator-0.2.3.dev0/saga_orchestrator/domain/models/enums/saga_step_status.py

@@ -1,7 +0,0 @@
-from enum import StrEnum, auto
-
-
-class SagaStepStatus(StrEnum):
-    SUCCESS = auto()
-    ERROR = auto()
-    WAITING = auto()