pyworkflow-engine 0.1.7__py3-none-any.whl → 0.1.10__py3-none-any.whl

examples/local/durable/08_cancellation.py

@@ -1,233 +0,0 @@
-"""
-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

@@ -1,198 +0,0 @@
-"""
-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

@@ -1,265 +0,0 @@
-"""
-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())