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

python_saga_orchestrator-0.2.3.dev0/.github/workflows/ci.yml

@@ -0,0 +1,55 @@
+name: CI
+
+on:
+  push:
+    branches:
+      - main
+  pull_request:
+
+jobs:
+  test-and-build:
+    runs-on: ubuntu-latest
+
+    services:
+      postgres:
+        image: postgres:16
+        env:
+          POSTGRES_DB: saga_test_db
+          POSTGRES_USER: postgres
+          POSTGRES_PASSWORD: postgres
+        ports:
+          - 5432:5432
+        options: >-
+          --health-cmd "pg_isready -U postgres -d saga_test_db"
+          --health-interval 10s
+          --health-timeout 5s
+          --health-retries 5
+
+    env:
+      TEST_DATABASE_URL: postgresql+asyncpg://postgres:postgres@localhost:5432/saga_test_db
+
+    steps:
+      - name: Check out repository
+        uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: Install dependencies
+        run: |
+          python -m pip install --upgrade pip
+          python -m pip install .[dev]
+
+      - name: Lint
+        run: ruff check .
+
+      - name: Run tests
+        run: pytest -q
+
+      - name: Build package
+        run: python -m build
+
+      - name: Validate distributions
+        run: python -m twine check dist/*

python_saga_orchestrator-0.2.3.dev0/.github/workflows/publish.yml

@@ -0,0 +1,52 @@
+name: Publish
+
+on:
+  push:
+    tags:
+      - "v*"
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    permissions:
+      id-token: write
+      contents: read
+
+    environment:
+      name: pypi
+
+    steps:
+      - name: Check out repository
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: Install build tools
+        run: |
+          python -m pip install --upgrade pip
+          python -m pip install build twine setuptools-scm
+
+      - name: Validate version matches tag
+        run: |
+          EXPECTED_VERSION="${GITHUB_REF_NAME#v}"
+          COMPUTED_VERSION="$(python -m setuptools_scm)"
+          echo "Tag version: ${EXPECTED_VERSION}"
+          echo "Computed version: ${COMPUTED_VERSION}"
+          if [ "${COMPUTED_VERSION}" != "${EXPECTED_VERSION}" ]; then
+            echo "Version mismatch: tag ${EXPECTED_VERSION}, computed ${COMPUTED_VERSION}"
+            exit 1
+          fi
+
+      - name: Build package
+        run: python -m build
+
+      - name: Validate distributions
+        run: python -m twine check dist/*
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1

python_saga_orchestrator-0.2.3.dev0/.gitignore

@@ -0,0 +1,207 @@
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[codz]
+*$py.class
+
+# C extensions
+*.so
+
+# Distribution / packaging
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+share/python-wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+# PyInstaller
+#  Usually these files are written by a python script from a template
+#  before PyInstaller builds the exe, so as to inject date/other infos into it.
+*.manifest
+*.spec
+
+# Installer logs
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.nox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+*.py.cover
+.hypothesis/
+.pytest_cache/
+cover/
+
+# Translations
+*.mo
+*.pot
+
+# Django stuff:
+*.log
+local_settings.py
+db.sqlite3
+db.sqlite3-journal
+
+# Flask stuff:
+instance/
+.webassets-cache
+
+# Scrapy stuff:
+.scrapy
+
+# Sphinx documentation
+docs/_build/
+
+# PyBuilder
+.pybuilder/
+target/
+
+# Jupyter Notebook
+.ipynb_checkpoints
+
+# IPython
+profile_default/
+ipython_config.py
+
+# pyenv
+#   For a library or package, you might want to ignore these files since the code is
+#   intended to run in multiple environments; otherwise, check them in:
+# .python-version
+
+# pipenv
+#   According to pypa/pipenv#598, it is recommended to include Pipfile.lock in version control.
+#   However, in case of collaboration, if having platform-specific dependencies or dependencies
+#   having no cross-platform support, pipenv may install dependencies that don't work, or not
+#   install all needed dependencies.
+#Pipfile.lock
+
+# UV
+#   Similar to Pipfile.lock, it is generally recommended to include uv.lock in version control.
+#   This is especially recommended for binary packages to ensure reproducibility, and is more
+#   commonly ignored for libraries.
+uv.lock
+
+# poetry
+#   Similar to Pipfile.lock, it is generally recommended to include poetry.lock in version control.
+#   This is especially recommended for binary packages to ensure reproducibility, and is more
+#   commonly ignored for libraries.
+#   https://python-poetry.org/docs/basic-usage/#commit-your-poetrylock-file-to-version-control
+#poetry.lock
+#poetry.toml
+
+# pdm
+#   Similar to Pipfile.lock, it is generally recommended to include pdm.lock in version control.
+#   pdm recommends including project-wide configuration in pdm.toml, but excluding .pdm-python.
+#   https://pdm-project.org/en/latest/usage/project/#working-with-version-control
+#pdm.lock
+#pdm.toml
+.pdm-python
+.pdm-build/
+
+# pixi
+#   Similar to Pipfile.lock, it is generally recommended to include pixi.lock in version control.
+#pixi.lock
+#   Pixi creates a virtual environment in the .pixi directory, just like venv module creates one
+#   in the .venv directory. It is recommended not to include this directory in version control.
+.pixi
+
+# PEP 582; used by e.g. github.com/David-OConnor/pyflow and github.com/pdm-project/pdm
+__pypackages__/
+
+# Celery stuff
+celerybeat-schedule
+celerybeat.pid
+
+# SageMath parsed files
+*.sage.py
+
+# Environments
+.env
+.envrc
+.venv
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+
+# Spyder project settings
+.spyderproject
+.spyproject
+
+# Rope project settings
+.ropeproject
+
+# mkdocs documentation
+/site
+
+# mypy
+.mypy_cache/
+.dmypy.json
+dmypy.json
+
+# Pyre type checker
+.pyre/
+
+# pytype static type analyzer
+.pytype/
+
+# Cython debug symbols
+cython_debug/
+
+# PyCharm
+#  JetBrains specific template is maintained in a separate JetBrains.gitignore that can
+#  be found at https://github.com/github/gitignore/blob/main/Global/JetBrains.gitignore
+#  and can be added to the global gitignore or merged into this file.  For a more nuclear
+#  option (not recommended) you can uncomment the following to ignore the entire idea folder.
+.idea/
+
+# Abstra
+# Abstra is an AI-powered process automation framework.
+# Ignore directories containing user credentials, local state, and settings.
+# Learn more at https://abstra.io/docs
+.abstra/
+
+# Visual Studio Code
+#  Visual Studio Code specific template is maintained in a separate VisualStudioCode.gitignore 
+#  that can be found at https://github.com/github/gitignore/blob/main/Global/VisualStudioCode.gitignore
+#  and can be added to the global gitignore or merged into this file. However, if you prefer, 
+#  you could uncomment the following to ignore the entire vscode folder
+# .vscode/
+
+# Ruff stuff:
+.ruff_cache/
+
+# PyPI configuration file
+.pypirc
+
+# Cursor
+#  Cursor is an AI-powered code editor. `.cursorignore` specifies files/directories to
+#  exclude from AI features like autocomplete and code analysis. Recommended for sensitive data
+#  refer to https://docs.cursor.com/context/ignore-files
+.cursorignore
+.cursorindexingignore
+
+# Marimo
+marimo/_static/
+marimo/_lsp/
+__marimo__/

python_saga_orchestrator-0.2.3.dev0/Dockerfile

@@ -0,0 +1,18 @@
+FROM ghcr.io/astral-sh/uv:python3.13-alpine3.23
+
+WORKDIR /app/
+
+ENV PIP_NO_CACHE_DIR=1 \
+    PIP_DISABLE_PIP_VERSION_CHECK=1 \
+    PYTHONUNBUFFERED=1 \
+    UV_NO_DEV=0 \
+    PATH="/app/.venv/bin:$PATH" \
+    SETUPTOOLS_SCM_PRETEND_VERSION_FOR_PYTHON_SAGA_ORCHESTRATOR="0.0.1.dev"
+
+COPY pyproject.toml pyproject.toml
+
+RUN uv sync
+
+COPY saga_orchestrator saga_orchestrator
+COPY tests tests
+CMD ["pytest"]

python_saga_orchestrator-0.2.3.dev0/Makefile

@@ -0,0 +1,12 @@
+.PHONY: format tests lint
+
+lint: format
+test: tests
+
+
+format:
+	@isort .
+	@black .
+
+tests:
+	@docker compose up --build --abort-on-container-exit

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: python-saga-orchestrator
-Version: 0.1.3
+Version: 0.2.3.dev0
 Summary: Lightweight embedded saga orchestrator for asyncio Python services
 Author-email: Maxim Vasilyev <mayxis@inbox.ru>
 License-Expression: MIT
@@ -51,6 +51,7 @@ Unlike external workflow platforms, this library runs inside your service and st
 - persisted saga state through `SagaStateMixin`
 - runtime execution through `SagaOrchestrator` and `SagaEngine`
 - retry, timeout, recovery, and compensation
+- async queue-style steps through `StepAwaitEvent` and `notify(...)`
 - administrative operations through `SagaAdmin`
 - PostgreSQL-first reliability using `SELECT ... FOR UPDATE`
 
@@ -136,11 +137,13 @@ Your SQLAlchemy model inherits `SagaStateMixin` to store:
 ## Quick start
 
 ```python
+import uuid
 from datetime import timedelta
 
 from pydantic import BaseModel
+from sqlalchemy import ForeignKey
 from sqlalchemy.ext.asyncio import async_sessionmaker
-from sqlalchemy.orm import DeclarativeBase
+from sqlalchemy.orm import DeclarativeBase, Mapped, mapped_column, relationship
 
 from saga_orchestrator import (
     BaseStep,
@@ -149,6 +152,7 @@ from saga_orchestrator import (
     SagaBuilder,
     SagaOrchestrator,
     SagaStateMixin,
+    SagaStepHistoryMixin,
 )
 
 
@@ -156,9 +160,24 @@ class Base(DeclarativeBase):
     pass
 
 
+class OrderSagaHistory(Base, SagaStepHistoryMixin):
+    __tablename__ = "order_saga_history"
+
+    saga_id: Mapped[uuid.UUID] = mapped_column(
+        ForeignKey("order_saga_state.id", ondelete="CASCADE"),
+        index=True,
+    )
+
+
 class OrderSagaState(Base, SagaStateMixin):
     __tablename__ = "order_saga_state"
 
+    step_history: Mapped[list[OrderSagaHistory]] = relationship(
+        "OrderSagaHistory",
+        cascade="all, delete-orphan",
+        order_by="OrderSagaHistory.id",
+    )
+
 
 class ReserveInput(BaseModel):
     order_id: str
@@ -211,15 +230,20 @@ def build_order_saga():
 
 
 def setup_saga(
-        session_maker: async_sessionmaker,
-) -> tuple[SagaOrchestrator[OrderSagaState], SagaAdmin[OrderSagaState]]:
-    orchestrator = SagaOrchestrator[OrderSagaState](
+    session_maker: async_sessionmaker,
+) -> tuple[
+    SagaOrchestrator[OrderSagaState, OrderSagaHistory], 
+    SagaAdmin[OrderSagaState, OrderSagaHistory]
+]:
+    orchestrator = SagaOrchestrator[OrderSagaState, OrderSagaHistory](
         model_class=OrderSagaState,
+        history_model_class=OrderSagaHistory,
         session_maker=session_maker,
     )
     orchestrator.register("create_order_v1", build_order_saga())
 
-    admin = SagaAdmin[OrderSagaState](engine=orchestrator.engine)
+    admin = SagaAdmin[OrderSagaState, OrderSagaHistory](engine=orchestrator.engine)
+    
     return orchestrator, admin
 ```
 
@@ -277,6 +301,23 @@ 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`.
 
+For distributed consumers, use transactional inbox ingestion first, then process inbox rows:
+
+```python
+stored = await orchestrator.ingest_event(
+    aggregation_id="order-123",
+    event={
+        "event_id": "evt-123",
+        "event_type": "payment.completed",
+        "correlation_id": "corr-123",
+        "payload": {"payment_id": "pay-1"},
+    },
+)
+
+if stored:
+    await orchestrator.run_inbox_due(limit=100)
+```
+
 ## Administrative operations
 
 Get the full persisted state:
@@ -334,6 +375,7 @@ A runnable end-to-end example is available in:
 - [`examples/retry_recovery.py`](./examples/retry_recovery.py)
 - [`examples/compensation_flow.py`](./examples/compensation_flow.py)
 - [`examples/admin_skip.py`](./examples/admin_skip.py)
+- [`examples/http_and_queue.py`](./examples/http_and_queue.py)
 
 These examples demonstrate:
 - basic model deployment

{python_saga_orchestrator-0.1.3 → python_saga_orchestrator-0.2.3.dev0}/README.md

@@ -17,6 +17,7 @@ Unlike external workflow platforms, this library runs inside your service and st
 - persisted saga state through `SagaStateMixin`
 - runtime execution through `SagaOrchestrator` and `SagaEngine`
 - retry, timeout, recovery, and compensation
+- async queue-style steps through `StepAwaitEvent` and `notify(...)`
 - administrative operations through `SagaAdmin`
 - PostgreSQL-first reliability using `SELECT ... FOR UPDATE`
 
@@ -102,11 +103,13 @@ Your SQLAlchemy model inherits `SagaStateMixin` to store:
 ## Quick start
 
 ```python
+import uuid
 from datetime import timedelta
 
 from pydantic import BaseModel
+from sqlalchemy import ForeignKey
 from sqlalchemy.ext.asyncio import async_sessionmaker
-from sqlalchemy.orm import DeclarativeBase
+from sqlalchemy.orm import DeclarativeBase, Mapped, mapped_column, relationship
 
 from saga_orchestrator import (
     BaseStep,
@@ -115,6 +118,7 @@ from saga_orchestrator import (
     SagaBuilder,
     SagaOrchestrator,
     SagaStateMixin,
+    SagaStepHistoryMixin,
 )
 
 
@@ -122,9 +126,24 @@ class Base(DeclarativeBase):
     pass
 
 
+class OrderSagaHistory(Base, SagaStepHistoryMixin):
+    __tablename__ = "order_saga_history"
+
+    saga_id: Mapped[uuid.UUID] = mapped_column(
+        ForeignKey("order_saga_state.id", ondelete="CASCADE"),
+        index=True,
+    )
+
+
 class OrderSagaState(Base, SagaStateMixin):
     __tablename__ = "order_saga_state"
 
+    step_history: Mapped[list[OrderSagaHistory]] = relationship(
+        "OrderSagaHistory",
+        cascade="all, delete-orphan",
+        order_by="OrderSagaHistory.id",
+    )
+
 
 class ReserveInput(BaseModel):
     order_id: str
@@ -177,15 +196,20 @@ def build_order_saga():
 
 
 def setup_saga(
-        session_maker: async_sessionmaker,
-) -> tuple[SagaOrchestrator[OrderSagaState], SagaAdmin[OrderSagaState]]:
-    orchestrator = SagaOrchestrator[OrderSagaState](
+    session_maker: async_sessionmaker,
+) -> tuple[
+    SagaOrchestrator[OrderSagaState, OrderSagaHistory], 
+    SagaAdmin[OrderSagaState, OrderSagaHistory]
+]:
+    orchestrator = SagaOrchestrator[OrderSagaState, OrderSagaHistory](
         model_class=OrderSagaState,
+        history_model_class=OrderSagaHistory,
         session_maker=session_maker,
     )
     orchestrator.register("create_order_v1", build_order_saga())
 
-    admin = SagaAdmin[OrderSagaState](engine=orchestrator.engine)
+    admin = SagaAdmin[OrderSagaState, OrderSagaHistory](engine=orchestrator.engine)
+    
     return orchestrator, admin
 ```
 
@@ -243,6 +267,23 @@ 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`.
 
+For distributed consumers, use transactional inbox ingestion first, then process inbox rows:
+
+```python
+stored = await orchestrator.ingest_event(
+    aggregation_id="order-123",
+    event={
+        "event_id": "evt-123",
+        "event_type": "payment.completed",
+        "correlation_id": "corr-123",
+        "payload": {"payment_id": "pay-1"},
+    },
+)
+
+if stored:
+    await orchestrator.run_inbox_due(limit=100)
+```
+
 ## Administrative operations
 
 Get the full persisted state:
@@ -300,6 +341,7 @@ A runnable end-to-end example is available in:
 - [`examples/retry_recovery.py`](./examples/retry_recovery.py)
 - [`examples/compensation_flow.py`](./examples/compensation_flow.py)
 - [`examples/admin_skip.py`](./examples/admin_skip.py)
+- [`examples/http_and_queue.py`](./examples/http_and_queue.py)
 
 These examples demonstrate:
 - basic model deployment

python_saga_orchestrator-0.2.3.dev0/docker-compose.yaml

@@ -0,0 +1,29 @@
+services:
+  db:
+    image: postgres:16-alpine3.19
+    container_name: saga-test-db
+    environment:
+      - POSTGRES_USER=testuser
+      - POSTGRES_PASSWORD=testpass
+      - POSTGRES_DB=testdb
+    healthcheck:
+      test: ["CMD-SHELL", "pg_isready -U testuser -d testdb"]
+      interval: 5s
+      timeout: 5s
+      retries: 5
+
+  tests:
+    build:
+      context: .
+      dockerfile: Dockerfile
+    container_name: saga-tests-runner
+    depends_on:
+      db:
+        condition: service_healthy
+    environment:
+      - TEST_DATABASE_URL=postgresql+asyncpg://testuser:testpass@db:5432/testdb
+    command: ["pytest", "-v", "-s"]
+
+networks:
+  default:
+    driver: bridge

python_saga_orchestrator-0.2.3.dev0/examples/admin_skip.py

@@ -0,0 +1,55 @@
+from __future__ import annotations
+
+import asyncio
+from datetime import timedelta
+
+from examples.common import (
+    DeployOutput,
+    FinalizeInput,
+    FinalizeStep,
+    ManualApprovalStep,
+    StartInput,
+    create_runtime,
+    dispose_runtime,
+    print_snapshot,
+)
+from saga_orchestrator import ExponentialRetry, SagaBuilder
+
+
+async def main() -> None:
+    session_maker, orchestrator, admin = await create_runtime()
+    try:
+        builder = SagaBuilder()
+        approval_ref = builder.add_step(
+            step=ManualApprovalStep(),
+            input_map=lambda ctx: StartInput(model_name=ctx.initial_data["model_name"]),
+            retry_policy=ExponentialRetry(
+                max_attempts=1,
+                base_delay=timedelta(hours=1),
+            ),
+        )
+        builder.add_step(
+            step=FinalizeStep(),
+            depends_on=approval_ref,
+            input_map=lambda out: FinalizeInput(endpoint=out.endpoint),
+        )
+
+        orchestrator.register("admin_skip_demo", builder.build())
+        saga_id = await orchestrator.start(
+            saga_name="admin_skip_demo",
+            initial_data={"model_name": "qwen-2.5"},
+            aggregation_id="admin-skip-demo",
+        )
+        await print_snapshot(admin, saga_id, title="Before admin skip")
+
+        await admin.skip_step(
+            saga_id,
+            mock_output=DeployOutput(endpoint="https://models.local/qwen-2.5"),
+        )
+        await print_snapshot(admin, saga_id, title="After admin skip")
+    finally:
+        await dispose_runtime(session_maker)
+
+
+if __name__ == "__main__":
+    asyncio.run(main())