pyworkflow-engine 0.1.7__py3-none-any.whl

examples/celery/durable/workflows/cancellation.py

@@ -0,0 +1,273 @@
+"""
+Celery Durable Workflow - Cancellation
+
+This example demonstrates graceful workflow cancellation with Celery:
+- Cancel running or suspended workflows via CLI
+- Handle CancellationError for cleanup
+- Use shield() to protect critical operations
+
+================================================================================
+PREREQUISITES
+================================================================================
+
+1. Start Redis:
+   docker run -d -p 6379:6379 redis:7-alpine
+
+2. Start the Celery worker (in a separate terminal):
+   pyworkflow --module examples.celery.durable.08_cancellation worker run
+
+================================================================================
+HOW TO RUN AND CANCEL
+================================================================================
+
+STEP 1: Start the workflow (it will sleep for 60 seconds):
+
+   pyworkflow --module examples.celery.durable.08_cancellation workflows run \
+       cancellable_order_workflow --arg order_id=order-123
+
+   Output: Workflow started: run_abc123def456...
+
+STEP 2: Check the status (should be "suspended" during sleep):
+
+   pyworkflow runs status <run_id>
+   pyworkflow runs list --status suspended
+
+STEP 3: Cancel the workflow while it's sleeping:
+
+   pyworkflow runs cancel <run_id> --reason "Customer cancelled"
+
+   Or wait for cancellation to complete:
+
+   pyworkflow runs cancel <run_id> --wait --reason "Customer cancelled"
+
+STEP 4: Check the worker logs - you should see:
+   - [Workflow] Cancellation detected!
+   - [Cleanup] Releasing inventory...
+   - [Cleanup] Refunding payment...
+
+STEP 5: Verify the final status:
+
+   pyworkflow runs status <run_id>
+   pyworkflow runs logs <run_id> --filter cancel
+
+================================================================================
+KEY POINTS
+================================================================================
+
+- Cancellation is CHECKPOINT-BASED: happens before steps, during sleep/hook
+- If a step is already running, cancellation waits until it completes
+- Use shield() to protect cleanup code from cancellation
+- Catch CancellationError to perform compensation logic
+
+================================================================================
+"""
+
+import asyncio
+
+from loguru import logger
+
+from pyworkflow import (
+    CancellationError,
+    get_context,
+    shield,
+    sleep,
+    step,
+    workflow,
+)
+
+
+# --- Steps (prefixed to avoid naming conflicts with other examples) ---
+@step()
+async def cancel_demo_reserve_inventory(order_id: str) -> dict:
+    """Reserve inventory for order."""
+    logger.info(f"[Step] Reserving inventory for order {order_id}...")
+    await asyncio.sleep(1)  # Simulate API call
+    logger.info(f"[Step] Inventory reserved for {order_id}")
+    return {"order_id": order_id, "inventory_reserved": True}
+
+
+@step()
+async def cancel_demo_charge_payment(order: dict) -> dict:
+    """Charge payment for order."""
+    logger.info(f"[Step] Charging payment for order {order['order_id']}...")
+    await asyncio.sleep(1)  # Simulate payment processing
+    logger.info(f"[Step] Payment charged for {order['order_id']}")
+    return {**order, "payment_charged": True}
+
+
+@step()
+async def cancel_demo_create_shipment(order: dict) -> dict:
+    """Create shipment for order."""
+    logger.info(f"[Step] Creating shipment for order {order['order_id']}...")
+    await asyncio.sleep(1)  # Simulate shipment creation
+    logger.info(f"[Step] Shipment created for {order['order_id']}")
+    return {**order, "shipment_created": True}
+
+
+@step()
+async def cancel_demo_release_inventory(order_id: str) -> None:
+    """Release previously reserved inventory (compensation)."""
+    logger.warning(f"[Cleanup] Releasing inventory for order {order_id}...")
+    await asyncio.sleep(0.5)
+    logger.warning(f"[Cleanup] Inventory released for {order_id}")
+
+
+@step()
+async def cancel_demo_refund_payment(order_id: str) -> None:
+    """Refund charged payment (compensation)."""
+    logger.warning(f"[Cleanup] Refunding payment for order {order_id}...")
+    await asyncio.sleep(0.5)
+    logger.warning(f"[Cleanup] Payment refunded for {order_id}")
+
+
+# --- Workflow with Cancellation Handling ---
+@workflow(tags=["celery", "durable"])
+async def cancellable_order_workflow(order_id: str) -> dict:
+    """
+    Order processing workflow with cancellation handling.
+
+    Flow:
+    1. Reserve inventory
+    2. Sleep 60s (waiting for approval) <-- CANCEL HERE
+    3. Charge payment
+    4. Sleep 60s (waiting for warehouse) <-- OR CANCEL HERE
+    5. Create shipment
+
+    If cancelled at any point:
+    - CancellationError is raised at the next checkpoint
+    - Cleanup logic releases inventory and refunds payment
+    - shield() ensures cleanup completes
+
+    To cancel this workflow:
+        pyworkflow runs cancel <run_id> --reason "Customer cancelled"
+    """
+    try:
+        logger.info(f"[Workflow] Starting order processing for {order_id}")
+
+        # Step 1: Reserve inventory
+        order = await cancel_demo_reserve_inventory(order_id)
+
+        # Sleep - workflow suspends here
+        # This is a good time to cancel!
+        logger.info("[Workflow] Waiting 60s for customer approval...")
+        logger.info("[Workflow] >>> To cancel: pyworkflow runs cancel <run_id> --reason 'test'")
+        await sleep("60s")
+
+        # Step 2: Charge payment
+        # Cancellation check happens here (before step)
+        order = await cancel_demo_charge_payment(order)
+
+        # Another sleep - another opportunity to cancel
+        logger.info("[Workflow] Waiting 60s for warehouse processing...")
+        logger.info("[Workflow] >>> To cancel: pyworkflow runs cancel <run_id> --reason 'test'")
+        await sleep("60s")
+
+        # Step 3: Create shipment
+        order = await cancel_demo_create_shipment(order)
+
+        logger.info(f"[Workflow] Order {order_id} completed successfully!")
+        return order
+
+    except CancellationError as e:
+        # Workflow was cancelled - perform cleanup
+        logger.warning(f"[Workflow] Cancellation detected! Reason: {e.reason}")
+        logger.warning("[Workflow] Performing compensation/cleanup...")
+
+        # Use shield() to ensure cleanup completes
+        # Even if another cancellation is requested, this block will finish
+        async with shield():
+            await cancel_demo_release_inventory(order_id)
+            await cancel_demo_refund_payment(order_id)
+
+        logger.warning("[Workflow] Cleanup complete. Re-raising CancellationError.")
+        raise  # Re-raise to mark workflow as CANCELLED
+
+
+@step()
+async def cancel_demo_long_running_step(items: list) -> list:
+    """
+    Example of cooperative cancellation within a long-running step.
+
+    Since cancellation doesn't interrupt steps mid-execution, use
+    ctx.check_cancellation() for responsive cancellation in long loops.
+    """
+    ctx = get_context()
+    results = []
+
+    for i, item in enumerate(items):
+        # Check for cancellation periodically
+        if i % 10 == 0:
+            ctx.check_cancellation()  # Raises CancellationError if cancelled
+
+        # Process item
+        await asyncio.sleep(0.1)
+        results.append(f"processed_{item}")
+
+    return results
+
+
+# --- Alternative: Workflow without cleanup ---
+@workflow(tags=["celery", "durable"])
+async def cancel_demo_simple_workflow(data: str) -> str:
+    """
+    Simple workflow without explicit cancellation handling.
+
+    If cancelled:
+    - CancellationError propagates up
+    - Workflow is marked as CANCELLED
+    - No cleanup is performed
+
+    This is fine for workflows that don't need compensation logic.
+    """
+    logger.info(f"[Workflow] Processing: {data}")
+
+    await sleep("60s")  # Cancel during this sleep
+
+    logger.info(f"[Workflow] Done: {data}")
+    return f"result_{data}"
+
+
+async def main() -> None:
+    """Run the order workflow example."""
+    import argparse
+
+    import pyworkflow
+
+    parser = argparse.ArgumentParser(description="Order Workflow with Cancellation")
+    parser.add_argument("--order-id", default="order-123", help="Order ID to process")
+    args = parser.parse_args()
+
+    print("=" * 70)
+    print("ORDER WORKFLOW WITH CANCELLATION SUPPORT")
+    print("=" * 70)
+    print()
+    print(f"Starting order workflow for {args.order_id}...")
+    print("The workflow will sleep for 60 seconds - perfect time to cancel!")
+    print()
+
+    run_id = await pyworkflow.start(cancellable_order_workflow, args.order_id)
+
+    print(f"Workflow started with run_id: {run_id}")
+    print()
+    print("=" * 70)
+    print("TO CANCEL THIS WORKFLOW:")
+    print("=" * 70)
+    print()
+    print(f"  pyworkflow runs cancel {run_id} --reason 'Customer cancelled'")
+    print()
+    print("Or wait for it and see cleanup:")
+    print()
+    print(f"  pyworkflow runs cancel {run_id} --wait --reason 'Customer cancelled'")
+    print()
+    print("=" * 70)
+    print("CHECK STATUS:")
+    print("=" * 70)
+    print()
+    print(f"  pyworkflow runs status {run_id}")
+    print(f"  pyworkflow runs logs {run_id}")
+    print(f"  pyworkflow runs logs {run_id} --filter cancel")
+    print()
+
+
+if __name__ == "__main__":
+    asyncio.run(main())

examples/celery/durable/workflows/child_workflow_patterns.py

@@ -0,0 +1,240 @@
+"""
+Celery Durable Workflow - Child Workflows Advanced Patterns
+
+This example demonstrates advanced child workflow patterns:
+- Nested child workflows (parent -> child -> grandchild)
+- Parallel child workflows using fire-and-forget + handle.result()
+- Error handling with ChildWorkflowFailedError
+- Cancellation propagation (TERMINATE policy)
+- Using ChildWorkflowHandle for async patterns
+
+Prerequisites:
+    1. Start Redis: docker run -d -p 6379:6379 redis:7-alpine
+    2. Start worker: pyworkflow --module examples.celery.durable.10_child_workflow_patterns worker run
+
+Run demos with CLI:
+    # Nested workflows (3 levels)
+    pyworkflow --module examples.celery.durable.10_child_workflow_patterns workflows run level_1_workflow
+
+    # Parallel children
+    pyworkflow --module examples.celery.durable.10_child_workflow_patterns workflows run parallel_parent_workflow
+
+    # Error handling
+    pyworkflow --module examples.celery.durable.10_child_workflow_patterns workflows run error_handling_parent_workflow
+
+Check status:
+    pyworkflow runs list
+    pyworkflow runs status <run_id>
+    pyworkflow runs children <run_id>
+"""
+
+import asyncio
+
+from pyworkflow import (
+    ChildWorkflowFailedError,
+    MaxNestingDepthError,
+    start_child_workflow,
+    step,
+    workflow,
+)
+
+
+# --- Steps ---
+@step(name="patterns_demo_do_work")
+async def do_work(name: str, duration: float = 0.1) -> dict:
+    """Simulate some work."""
+    print(f"      [{name}] Working for {duration}s...")
+    await asyncio.sleep(duration)
+    return {"name": name, "completed": True}
+
+
+@step(
+    name="patterns_demo_failing_step", max_retries=0
+)  # No retries so failure propagates immediately
+async def failing_step() -> dict:
+    """A step that always fails."""
+    raise ValueError("This step always fails!")
+
+
+# --- Workflows for Nesting Demo ---
+@workflow(name="patterns_demo_level_3_workflow", tags=["celery", "durable"])
+async def level_3_workflow(task_id: str) -> dict:
+    """Grandchild workflow (nesting depth 3)."""
+    print(f"    [Level3] Starting task {task_id}")
+    result = await do_work(f"level3-{task_id}")
+    print(f"    [Level3] Completed task {task_id}")
+    return result
+
+
+@workflow(name="patterns_demo_level_2_workflow", tags=["celery", "durable"])
+async def level_2_workflow(task_id: str) -> dict:
+    """Child workflow that spawns a grandchild."""
+    print(f"  [Level2] Starting task {task_id}")
+
+    # Spawn grandchild (nesting depth 3)
+    grandchild_result = await start_child_workflow(
+        level_3_workflow,
+        task_id,
+    )
+
+    print(f"  [Level2] Completed task {task_id}")
+    return {"level2": task_id, "grandchild": grandchild_result}
+
+
+@workflow(name="patterns_demo_level_1_workflow", tags=["celery", "durable"])
+async def level_1_workflow() -> dict:
+    """Parent workflow demonstrating max nesting depth."""
+    print("[Level1] Starting nested workflow demo")
+
+    # Spawn child which will spawn grandchild
+    child_result = await start_child_workflow(level_2_workflow, "nested-task")
+
+    print("[Level1] Completed nested workflow demo")
+    return {"level1": True, "child": child_result}
+
+
+# --- Workflows for Parallel Demo ---
+@workflow(name="patterns_demo_parallel_task_workflow", tags=["celery", "durable"])
+async def parallel_task_workflow(task_id: str, duration: float) -> dict:
+    """A simple workflow for parallel execution."""
+    result = await do_work(f"parallel-{task_id}", duration)
+    return {"task_id": task_id, **result}
+
+
+@workflow(name="patterns_demo_parallel_parent_workflow", tags=["celery", "durable"])
+async def parallel_parent_workflow() -> dict:
+    """Parent workflow that runs multiple children in parallel."""
+    print("[ParallelParent] Starting parallel children demo")
+
+    # Start multiple children with fire-and-forget
+    handles = []
+    for i in range(3):
+        handle = await start_child_workflow(
+            parallel_task_workflow,
+            f"task-{i}",
+            0.1 * (i + 1),  # Different durations
+            wait_for_completion=False,
+        )
+        handles.append(handle)
+        print(f"  Started child {i}: {handle.child_run_id}")
+
+    # Wait for all children to complete using handles
+    print("[ParallelParent] Waiting for all children...")
+    results = []
+    for i, handle in enumerate(handles):
+        result = await handle.result(timeout=30.0)
+        results.append(result)
+        print(f"  Child {i} completed: {result}")
+
+    print("[ParallelParent] All children completed")
+    return {"children_count": len(results), "results": results}
+
+
+# --- Workflows for Error Handling Demo ---
+@workflow(name="patterns_demo_failing_child_workflow", tags=["celery", "durable"])
+async def failing_child_workflow() -> dict:
+    """A child workflow that fails."""
+    await failing_step()
+    return {"should": "never reach here"}
+
+
+@workflow(name="patterns_demo_error_handling_parent_workflow", tags=["celery", "durable"])
+async def error_handling_parent_workflow() -> dict:
+    """Parent workflow demonstrating error handling."""
+    print("[ErrorParent] Starting error handling demo")
+
+    try:
+        # This child will fail
+        await start_child_workflow(failing_child_workflow)
+    except ChildWorkflowFailedError as e:
+        print("[ErrorParent] Caught child failure!")
+        print(f"  Child run_id: {e.child_run_id}")
+        print(f"  Child workflow: {e.child_workflow_name}")
+        print(f"  Error: {e.error}")
+        print(f"  Error type: {e.error_type}")
+        return {
+            "status": "child_failed",
+            "error": e.error,
+            "child_run_id": e.child_run_id,
+        }
+
+    return {"status": "success"}
+
+
+# --- Workflow for Max Nesting Depth Demo ---
+@workflow(name="patterns_demo_try_exceed_max_depth", tags=["celery", "durable"])
+async def try_exceed_max_depth() -> dict:
+    """Try to exceed max nesting depth (should fail at depth 4)."""
+    try:
+        # Define a workflow that would be depth 4
+        @workflow(name="patterns_demo_level_4_workflow")
+        async def level_4_workflow() -> dict:
+            return await do_work("level4")
+
+        await start_child_workflow(level_4_workflow)
+    except MaxNestingDepthError as e:
+        print(f"  Caught MaxNestingDepthError: {e}")
+        return {"error": str(e), "max_depth": e.MAX_DEPTH}
+    return {"status": "success"}
+
+
+async def main() -> None:
+    """Run the child workflow patterns demos."""
+    import argparse
+
+    import pyworkflow
+    from pyworkflow import get_workflow_run
+
+    parser = argparse.ArgumentParser(description="Child Workflow Patterns Demo")
+    parser.add_argument(
+        "--demo",
+        choices=["nested", "parallel", "error", "all"],
+        default="all",
+        help="Which demo to run",
+    )
+    args = parser.parse_args()
+
+    print("=== Child Workflows - Advanced Patterns ===")
+
+    demos = []
+    if args.demo in ("nested", "all"):
+        demos.append(("Nested Child Workflows (3 levels)", level_1_workflow))
+    if args.demo in ("parallel", "all"):
+        demos.append(("Parallel Child Workflows", parallel_parent_workflow))
+    if args.demo in ("error", "all"):
+        demos.append(("Child Workflow Error Handling", error_handling_parent_workflow))
+
+    for demo_name, workflow_func in demos:
+        print(f"\n{'=' * 50}")
+        print(f"DEMO: {demo_name}")
+        print("=" * 50 + "\n")
+
+        run_id = await pyworkflow.start(workflow_func)
+        print(f"\nWorkflow started: {run_id}")
+
+        # Poll for completion
+        for _ in range(30):
+            await asyncio.sleep(1)
+            run = await get_workflow_run(run_id)
+            if run.status.value in ("completed", "failed", "cancelled"):
+                print(f"Status: {run.status.value}")
+                if run.result:
+                    print(f"Result: {run.result}")
+                if run.error:
+                    print(f"Error: {run.error}")
+                break
+        else:
+            print("Timeout waiting for workflow completion")
+
+    print("\n" + "=" * 50)
+    print("=== Key Takeaways ===")
+    print("=" * 50)
+    print("1. Child workflows can spawn their own children (up to depth 3)")
+    print("2. Use wait_for_completion=False + handle.result() for parallel")
+    print("3. ChildWorkflowFailedError propagates child failures to parent")
+    print("4. MaxNestingDepthError prevents infinite nesting")
+    print("5. TERMINATE policy ensures cleanup on parent completion")
+
+
+if __name__ == "__main__":
+    asyncio.run(main())