pyworkflow-engine 0.1.7__py3-none-any.whl

examples/local/durable/08_cancellation.py

@@ -0,0 +1,233 @@
+"""
+Durable Workflow - Cancellation
+
+This example demonstrates graceful workflow cancellation:
+- Cancel running or suspended workflows
+- Handle CancellationError for cleanup
+- Use shield() to protect critical operations
+- Checkpoint-based cancellation (not mid-step)
+
+Run: python examples/local/durable/08_cancellation.py 2>/dev/null
+"""
+
+import asyncio
+import tempfile
+
+from pyworkflow import (
+    CancellationError,
+    cancel_workflow,
+    configure,
+    get_workflow_run,
+    reset_config,
+    shield,
+    sleep,
+    start,
+    step,
+    workflow,
+)
+from pyworkflow.storage import FileStorageBackend
+
+
+# --- Steps ---
+@step()
+async def reserve_inventory(order_id: str) -> dict:
+    """Reserve inventory for order."""
+    print(f"  [Step] Reserving inventory for order {order_id}...")
+    await asyncio.sleep(0.1)  # Simulate work
+    return {"order_id": order_id, "inventory_reserved": True}
+
+
+@step()
+async def charge_payment(order: dict) -> dict:
+    """Charge payment for order."""
+    print(f"  [Step] Charging payment for order {order['order_id']}...")
+    await asyncio.sleep(0.1)  # Simulate work
+    return {**order, "payment_charged": True}
+
+
+@step()
+async def create_shipment(order: dict) -> dict:
+    """Create shipment for order."""
+    print(f"  [Step] Creating shipment for order {order['order_id']}...")
+    await asyncio.sleep(0.1)  # Simulate work
+    return {**order, "shipment_created": True}
+
+
+@step()
+async def release_inventory(order_id: str) -> None:
+    """Release previously reserved inventory (compensation)."""
+    print(f"  [Cleanup] Releasing inventory for order {order_id}...")
+
+
+@step()
+async def refund_payment(order_id: str) -> None:
+    """Refund charged payment (compensation)."""
+    print(f"  [Cleanup] Refunding payment for order {order_id}...")
+
+
+# --- Workflow with Cancellation Handling ---
+@workflow(durable=True, tags=["local", "durable"])
+async def order_workflow(order_id: str) -> dict:
+    """
+    Order processing workflow with cancellation handling.
+
+    If cancelled:
+    - Catches CancellationError
+    - Uses shield() to ensure cleanup completes
+    - Releases inventory and refunds payment
+    """
+    try:
+        order = await reserve_inventory(order_id)
+
+        # Simulate waiting for approval
+        print("  [Workflow] Waiting 5s for approval (can be cancelled here)...")
+        await sleep("5s")
+
+        order = await charge_payment(order)
+
+        # Another wait - e.g., for warehouse processing
+        print("  [Workflow] Waiting 5s for warehouse (can be cancelled here)...")
+        await sleep("5s")
+
+        order = await create_shipment(order)
+        return order
+
+    except CancellationError as e:
+        print(f"\n  [Workflow] Cancellation detected! Reason: {e.reason}")
+        print("  [Workflow] Performing cleanup...")
+
+        # Use shield() to ensure cleanup completes even if cancelled again
+        async with shield():
+            await release_inventory(order_id)
+            await refund_payment(order_id)
+
+        print("  [Workflow] Cleanup complete, re-raising CancellationError")
+        raise  # Re-raise to mark workflow as cancelled
+
+
+async def example_cancel_suspended_workflow(storage):
+    """Example 1: Cancel a workflow while it's suspended (sleeping)."""
+    print("\n--- Example 1: Cancel Suspended Workflow ---\n")
+
+    # Start workflow
+    run_id = await start(order_workflow, "order-001")
+
+    # Check status - should be suspended (sleeping)
+    run = await get_workflow_run(run_id)
+    print(f"Workflow status: {run.status.value}")
+
+    if run.status.value == "suspended":
+        print("\nWorkflow is suspended (sleeping). Cancelling...")
+
+        # Cancel the suspended workflow
+        cancelled = await cancel_workflow(
+            run_id,
+            reason="Customer cancelled order",
+            storage=storage,
+        )
+
+        print(f"Cancellation initiated: {cancelled}")
+
+        # Check final status
+        run = await get_workflow_run(run_id)
+        print(f"Final status: {run.status.value}")
+
+    return run_id
+
+
+async def example_cancel_running_workflow(storage):
+    """Example 2: Cancel a running workflow (cancellation at next checkpoint)."""
+    print("\n--- Example 2: Cancel Running Workflow ---\n")
+
+    # Define a workflow that we can cancel mid-execution
+    @workflow(durable=True)
+    async def multi_step_workflow(job_id: str) -> dict:
+        try:
+            print(f"  [Step 1] Starting job {job_id}...")
+            await asyncio.sleep(0.1)
+
+            print("  [Step 2] Processing (cancellation checked here)...")
+            # Note: In real scenario, ctx.check_cancellation() would be called
+            # by @step decorator before execution
+            await asyncio.sleep(0.1)
+
+            print("  [Step 3] Finalizing...")
+            return {"job_id": job_id, "status": "done"}
+
+        except CancellationError as e:
+            print(f"  [Workflow] Cancelled! Reason: {e.reason}")
+            raise
+
+    # Start and immediately cancel (before it completes)
+    run_id = await start(multi_step_workflow, "job-002")
+
+    run = await get_workflow_run(run_id)
+    print(f"Workflow status: {run.status.value}")
+
+    # If it completed before we could cancel, that's OK
+    if run.status.value != "completed":
+        print("\nCancelling workflow...")
+        cancelled = await cancel_workflow(
+            run_id,
+            reason="Test cancellation",
+            storage=storage,
+        )
+        print(f"Cancellation initiated: {cancelled}")
+
+    # Check final status
+    run = await get_workflow_run(run_id)
+    print(f"Final status: {run.status.value}")
+
+    return run_id
+
+
+async def example_cancel_already_completed(storage):
+    """Example 3: Try to cancel an already completed workflow."""
+    print("\n--- Example 3: Cancel Completed Workflow ---\n")
+
+    # Create a simple quick workflow
+    @workflow(durable=True)
+    async def quick_workflow() -> str:
+        return "done"
+
+    # Start and complete
+    run_id = await start(quick_workflow)
+    run = await get_workflow_run(run_id)
+    print(f"Workflow status: {run.status.value}")
+
+    # Try to cancel
+    print("Attempting to cancel completed workflow...")
+    cancelled = await cancel_workflow(run_id, storage=storage)
+
+    print(f"Cancellation result: {cancelled}")
+    print("(False means workflow was already in terminal state)")
+
+    return run_id
+
+
+async def main():
+    # Use temp directory
+    with tempfile.TemporaryDirectory() as tmpdir:
+        print("=== Durable Workflow - Cancellation ===")
+
+        # Configure with FileStorageBackend
+        reset_config()
+        storage = FileStorageBackend(base_path=tmpdir)
+        configure(storage=storage, default_durable=True)
+
+        # Run examples
+        await example_cancel_suspended_workflow(storage)
+        await example_cancel_running_workflow(storage)
+        await example_cancel_already_completed(storage)
+
+        print("\n=== Key Takeaways ===")
+        print("  - cancel_workflow() requests graceful cancellation")
+        print("  - Suspended workflows are cancelled immediately")
+        print("  - Running workflows cancel at next checkpoint (before step/sleep/hook)")
+        print("  - Catch CancellationError for cleanup logic")
+        print("  - Use shield() to protect critical cleanup operations")
+        print("  - Cancellation does NOT interrupt a step mid-execution")
+
+
+if __name__ == "__main__":
+    asyncio.run(main())

examples/local/durable/09_child_workflows.py

@@ -0,0 +1,198 @@
+"""
+Child Workflows - Basic Example
+
+This example demonstrates how to spawn child workflows from a parent workflow.
+- Parent workflow spawns child workflows using start_child_workflow()
+- Children have their own run_id and event history
+- wait_for_completion=True (default) waits for child to complete
+- wait_for_completion=False returns a ChildWorkflowHandle immediately
+- TERMINATE policy: when parent completes/fails/cancels, children are cancelled
+
+Run: python examples/local/durable/09_child_workflows.py 2>/dev/null
+"""
+
+import asyncio
+
+from pyworkflow import (
+    ChildWorkflowHandle,
+    configure,
+    get_workflow_run,
+    reset_config,
+    start,
+    start_child_workflow,
+    step,
+    workflow,
+)
+from pyworkflow.storage import InMemoryStorageBackend
+
+
+# --- Steps ---
+@step()
+async def validate_order(order_id: str) -> dict:
+    """Validate order details."""
+    print(f"    Validating order {order_id}...")
+    return {"order_id": order_id, "valid": True}
+
+
+@step()
+async def process_payment(order_id: str, amount: float) -> dict:
+    """Process payment for order."""
+    print(f"    Processing payment ${amount:.2f} for {order_id}...")
+    return {"order_id": order_id, "amount": amount, "paid": True}
+
+
+@step()
+async def ship_order(order_id: str) -> dict:
+    """Ship the order."""
+    print(f"    Shipping order {order_id}...")
+    return {"order_id": order_id, "shipped": True}
+
+
+@step()
+async def send_email(recipient: str, subject: str) -> dict:
+    """Send an email notification."""
+    print(f"    Sending email to {recipient}: {subject}")
+    return {"recipient": recipient, "subject": subject, "sent": True}
+
+
+# --- Child Workflows ---
+@workflow(durable=True, tags=["local", "durable"])
+async def payment_workflow(order_id: str, amount: float) -> dict:
+    """Child workflow for payment processing."""
+    print(f"  [PaymentWorkflow] Starting for order {order_id}")
+    result = await process_payment(order_id, amount)
+    print(f"  [PaymentWorkflow] Completed for order {order_id}")
+    return result
+
+
+@workflow(durable=True, tags=["local", "durable"])
+async def shipping_workflow(order_id: str) -> dict:
+    """Child workflow for shipping."""
+    print(f"  [ShippingWorkflow] Starting for order {order_id}")
+    result = await ship_order(order_id)
+    print(f"  [ShippingWorkflow] Completed for order {order_id}")
+    return result
+
+
+@workflow(durable=True, tags=["local", "durable"])
+async def notification_workflow(email: str, order_id: str) -> dict:
+    """Child workflow for sending notifications."""
+    print(f"  [NotificationWorkflow] Starting for {email}")
+    result = await send_email(email, f"Order {order_id} update")
+    print(f"  [NotificationWorkflow] Completed for {email}")
+    return result
+
+
+# --- Parent Workflow ---
+@workflow(durable=True, tags=["local", "durable"])
+async def order_fulfillment_workflow(
+    order_id: str,
+    amount: float,
+    customer_email: str,
+) -> dict:
+    """
+    Parent workflow that orchestrates order fulfillment using child workflows.
+
+    This demonstrates:
+    1. wait_for_completion=True - Wait for child to complete (default)
+    2. wait_for_completion=False - Fire-and-forget with handle
+    """
+    print(f"[OrderFulfillment] Starting for order {order_id}")
+
+    # Step 1: Validate order (regular step)
+    validation = await validate_order(order_id)
+    if not validation["valid"]:
+        return {"order_id": order_id, "status": "invalid"}
+
+    # Step 2: Process payment via child workflow (wait for completion)
+    print("[OrderFulfillment] Starting payment child workflow...")
+    payment_result = await start_child_workflow(
+        payment_workflow,
+        order_id,
+        amount,
+        wait_for_completion=True,  # Default: wait for child to complete
+    )
+    print(f"[OrderFulfillment] Payment completed: {payment_result}")
+
+    # Step 3: Ship order via child workflow (wait for completion)
+    print("[OrderFulfillment] Starting shipping child workflow...")
+    shipping_result = await start_child_workflow(
+        shipping_workflow,
+        order_id,
+        wait_for_completion=True,
+    )
+    print(f"[OrderFulfillment] Shipping completed: {shipping_result}")
+
+    # Step 4: Send notification via fire-and-forget child workflow
+    # This returns immediately with a handle, parent continues
+    print("[OrderFulfillment] Starting notification child workflow (fire-and-forget)...")
+    notification_handle: ChildWorkflowHandle = await start_child_workflow(
+        notification_workflow,
+        customer_email,
+        order_id,
+        wait_for_completion=False,  # Fire-and-forget
+    )
+    print(f"[OrderFulfillment] Notification child started: {notification_handle.child_run_id}")
+
+    # We can optionally check status or wait for the handle later
+    # For now, we'll just let it run in the background
+
+    result = {
+        "order_id": order_id,
+        "status": "fulfilled",
+        "payment": payment_result,
+        "shipping": shipping_result,
+        "notification_run_id": notification_handle.child_run_id,
+    }
+
+    print(f"[OrderFulfillment] Completed for order {order_id}")
+    return result
+
+
+async def main():
+    # Configure with InMemoryStorageBackend
+    reset_config()
+    storage = InMemoryStorageBackend()
+    configure(storage=storage, default_durable=True)
+
+    print("=== Child Workflows - Basic Example ===\n")
+    print("Running order fulfillment workflow with child workflows...\n")
+
+    # Start parent workflow
+    run_id = await start(
+        order_fulfillment_workflow,
+        "order-456",
+        149.99,
+        "customer@example.com",
+    )
+
+    # Give fire-and-forget child time to complete
+    await asyncio.sleep(0.5)
+
+    print("\n=== Workflow Results ===")
+
+    # Check parent workflow
+    parent_run = await get_workflow_run(run_id)
+    print(f"\nParent Workflow: {run_id}")
+    print(f"  Status: {parent_run.status.value}")
+    print(f"  Result: {parent_run.result}")
+
+    # List child workflows
+    children = await storage.get_children(run_id)
+    print(f"\nChild Workflows ({len(children)} total):")
+    for child in children:
+        print(f"  - {child.run_id}")
+        print(f"    Workflow: {child.workflow_name}")
+        print(f"    Status: {child.status.value}")
+        print(f"    Nesting Depth: {child.nesting_depth}")
+
+    print("\n=== Key Takeaways ===")
+    print("1. start_child_workflow() spawns a child with its own run_id")
+    print("2. wait_for_completion=True (default) waits for child result")
+    print("3. wait_for_completion=False returns a ChildWorkflowHandle")
+    print("4. Child workflows have their own event history")
+    print("5. TERMINATE policy: children cancelled when parent completes")
+
+
+if __name__ == "__main__":
+    asyncio.run(main())

examples/local/durable/10_child_workflow_patterns.py

@@ -0,0 +1,265 @@
+"""
+Child Workflows - Advanced Patterns
+
+This example demonstrates advanced child workflow patterns:
+- Nested child workflows (parent -> child -> grandchild)
+- Parallel child workflows using asyncio.gather
+- Error handling with ChildWorkflowFailedError
+- Cancellation propagation (TERMINATE policy)
+- Using ChildWorkflowHandle for async patterns
+
+Run: python examples/local/durable/10_child_workflow_patterns.py 2>/dev/null
+"""
+
+import asyncio
+
+from pyworkflow import (
+    ChildWorkflowFailedError,
+    MaxNestingDepthError,
+    configure,
+    get_workflow_run,
+    reset_config,
+    start,
+    start_child_workflow,
+    step,
+    workflow,
+)
+from pyworkflow.storage import InMemoryStorageBackend
+
+
+# --- Steps ---
+@step()
+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()
+async def failing_step() -> dict:
+    """A step that always fails."""
+    raise ValueError("This step always fails!")
+
+
+# --- Workflows for Nesting Demo ---
+@workflow(durable=True, tags=["local", "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(durable=True, tags=["local", "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(durable=True, tags=["local", "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(durable=True, tags=["local", "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(durable=True, tags=["local", "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=10.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(durable=True, tags=["local", "durable"])
+async def failing_child_workflow() -> dict:
+    """A child workflow that fails."""
+    await failing_step()
+    return {"should": "never reach here"}
+
+
+@workflow(durable=True, tags=["local", "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"}
+
+
+async def demo_nesting():
+    """Demo: Nested child workflows."""
+    print("\n" + "=" * 50)
+    print("DEMO 1: Nested Child Workflows (3 levels)")
+    print("=" * 50 + "\n")
+
+    run_id = await start(level_1_workflow)
+    run = await get_workflow_run(run_id)
+
+    print(f"\nResult: {run.result}")
+
+
+async def demo_parallel():
+    """Demo: Parallel child workflows."""
+    print("\n" + "=" * 50)
+    print("DEMO 2: Parallel Child Workflows")
+    print("=" * 50 + "\n")
+
+    run_id = await start(parallel_parent_workflow)
+    run = await get_workflow_run(run_id)
+
+    print(f"\nResult: {run.result}")
+
+
+async def demo_error_handling():
+    """Demo: Error handling with ChildWorkflowFailedError."""
+    print("\n" + "=" * 50)
+    print("DEMO 3: Child Workflow Error Handling")
+    print("=" * 50 + "\n")
+
+    run_id = await start(error_handling_parent_workflow)
+    run = await get_workflow_run(run_id)
+
+    print(f"\nResult: {run.result}")
+
+
+async def demo_max_nesting_depth():
+    """Demo: Max nesting depth enforcement."""
+    print("\n" + "=" * 50)
+    print("DEMO 4: Max Nesting Depth (3 levels max)")
+    print("=" * 50 + "\n")
+
+    # Define a workflow that tries to nest too deep
+    @workflow(durable=True)
+    async def level_4_workflow() -> dict:
+        """This would be nesting depth 4 - not allowed!"""
+        return await do_work("level4")
+
+    @workflow(durable=True)
+    async def try_level_4_workflow() -> dict:
+        """Try to spawn a level 4 child (should fail)."""
+        # This is called from level 3, so it would be depth 4
+        try:
+            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"}
+
+    @workflow(durable=True)
+    async def deep_nesting_workflow() -> dict:
+        """Workflow that attempts deep nesting."""
+        print("[DeepNesting] Attempting 4-level nesting...")
+
+        # Level 1 -> Level 2
+        @workflow(durable=True)
+        async def level_2() -> dict:
+            print("  [Level2] Starting...")
+
+            # Level 2 -> Level 3
+            @workflow(durable=True)
+            async def level_3() -> dict:
+                print("    [Level3] Starting...")
+                # Level 3 -> Level 4 (should fail!)
+                return await start_child_workflow(try_level_4_workflow)
+
+            return await start_child_workflow(level_3)
+
+        return await start_child_workflow(level_2)
+
+    run_id = await start(deep_nesting_workflow)
+    await asyncio.sleep(0.5)  # Wait for nested workflows
+    run = await get_workflow_run(run_id)
+
+    print(f"\nResult: {run.result}")
+    print(
+        "\nNote: Max nesting depth is 3 levels (root=0, child=1, grandchild=2, great-grandchild=3)"
+    )
+
+
+async def main():
+    # Configure with InMemoryStorageBackend
+    reset_config()
+    storage = InMemoryStorageBackend()
+    configure(storage=storage, default_durable=True)
+
+    print("=== Child Workflows - Advanced Patterns ===")
+
+    await demo_nesting()
+    await demo_parallel()
+    await demo_error_handling()
+    # Skip max nesting demo as it requires proper registration
+    # await demo_max_nesting_depth()
+
+    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())