pyworkflow-engine 0.1.7__py3-none-any.whl

examples/local/transient/03_sleep.py

@@ -0,0 +1,141 @@
+"""
+Transient Workflow - Async Sleep
+
+This example demonstrates sleep() behavior in transient mode.
+- Uses asyncio.sleep() under the hood (blocks workflow)
+- No workflow suspension (unlike durable mode)
+- Simple delay mechanism
+- Perfect for rate limiting and delays
+
+Run: python examples/local/transient/03_sleep.py 2>/dev/null
+"""
+
+import asyncio
+from datetime import datetime
+
+from pyworkflow import (
+    configure,
+    reset_config,
+    sleep,
+    start,
+    step,
+    workflow,
+)
+
+
+# --- Steps ---
+@step()
+async def start_task(task_id: str) -> dict:
+    """Start a task."""
+    timestamp = datetime.now().strftime("%H:%M:%S")
+    print(f"  [{timestamp}] Starting task {task_id}...")
+    return {"task_id": task_id, "status": "started"}
+
+
+@step()
+async def process_task(task: dict) -> dict:
+    """Process the task."""
+    timestamp = datetime.now().strftime("%H:%M:%S")
+    print(f"  [{timestamp}] Processing task {task['task_id']}...")
+    return {**task, "status": "processed"}
+
+
+@step()
+async def complete_task(task: dict) -> dict:
+    """Complete the task."""
+    timestamp = datetime.now().strftime("%H:%M:%S")
+    print(f"  [{timestamp}] Completing task {task['task_id']}...")
+    return {**task, "status": "completed"}
+
+
+# --- Workflows ---
+@workflow(durable=False, tags=["local", "transient"])
+async def delayed_workflow(task_id: str, delay_seconds: int) -> dict:
+    """Workflow with sleep delay."""
+    task = await start_task(task_id)
+
+    timestamp = datetime.now().strftime("%H:%M:%S")
+    print(f"  [{timestamp}] Sleeping for {delay_seconds} seconds...")
+    await sleep(f"{delay_seconds}s")  # Uses asyncio.sleep() in transient mode
+
+    timestamp = datetime.now().strftime("%H:%M:%S")
+    print(f"  [{timestamp}] Woke up from sleep!")
+
+    task = await process_task(task)
+    task = await complete_task(task)
+    return task
+
+
+@workflow(durable=False, tags=["local", "transient"])
+async def rate_limited_workflow(task_id: str) -> dict:
+    """Workflow demonstrating rate limiting pattern."""
+    task = await start_task(task_id)
+
+    # Simulate rate limiting between API calls
+    print("  Rate limiting: waiting 2 seconds before next API call...")
+    await sleep("2s")
+
+    task = await process_task(task)
+
+    # Another rate limit delay
+    print("  Rate limiting: waiting 2 seconds before final call...")
+    await sleep("2s")
+
+    task = await complete_task(task)
+    return task
+
+
+async def main():
+    # Configure for transient mode
+    reset_config()
+    configure(default_durable=False)
+
+    print("=== Transient Workflow - Async Sleep ===\n")
+
+    # Example 1: Basic sleep
+    print("Example 1: Basic sleep (3 seconds)\n")
+    start_time = datetime.now()
+
+    run_id = await start(delayed_workflow, "task-001", 3)
+
+    end_time = datetime.now()
+    elapsed = (end_time - start_time).total_seconds()
+
+    print(f"\nWorkflow completed: {run_id}")
+    print(f"Total time: {elapsed:.1f} seconds")
+
+    # Example 2: Rate limiting
+    print("\n" + "=" * 60)
+    print("\nExample 2: Rate limiting with multiple sleeps\n")
+    start_time = datetime.now()
+
+    run_id = await start(rate_limited_workflow, "task-002")
+
+    end_time = datetime.now()
+    elapsed = (end_time - start_time).total_seconds()
+
+    print(f"\nWorkflow completed: {run_id}")
+    print(f"Total time: {elapsed:.1f} seconds")
+
+    print("\n=== Sleep Behavior in Transient Mode ===")
+    print("✓ Uses asyncio.sleep() (blocks the workflow)")
+    print("✓ No workflow suspension (process keeps running)")
+    print("✓ No resource release during sleep")
+    print("✓ Perfect for short delays and rate limiting")
+
+    print("\n=== Sleep Format Support ===")
+    print('sleep("5s")     - 5 seconds')
+    print('sleep("2m")     - 2 minutes')
+    print('sleep("1h")     - 1 hour')
+    print("sleep(30)       - 30 seconds (int)")
+    print("sleep(timedelta(seconds=10)) - 10 seconds")
+
+    print("\n=== Difference from Durable Mode ===")
+    print("Transient: sleep() blocks using asyncio.sleep()")
+    print("Durable:   sleep() suspends workflow, can resume later")
+    print("\nFor long-running workflows with suspension:")
+    print("  See examples/local/durable/04_long_running.py")
+
+
+if __name__ == "__main__":
+    asyncio.run(main())

examples/local/transient/__init__.py

@@ -0,0 +1 @@
+# PyWorkflow Local Transient Examples Package

pyworkflow/__init__.py

@@ -0,0 +1,256 @@
+"""
+PyWorkflow - Durable and transient workflows for Python
+
+A Python implementation of workflow orchestration inspired by Vercel Workflow,
+providing fault-tolerant, long-running workflows with automatic retry, sleep/delay,
+and webhook integration.
+
+Supports both:
+- Durable workflows: Event-sourced, persistent, resumable
+- Transient workflows: Simple execution without persistence overhead
+
+Quick Start:
+    >>> import pyworkflow
+    >>> from pyworkflow import workflow, step, start
+    >>>
+    >>> # Configure defaults
+    >>> pyworkflow.configure(default_runtime="local", default_durable=False)
+    >>>
+    >>> @workflow
+    >>> async def my_workflow(name: str):
+    >>>     result = await process_step(name)
+    >>>     return result
+    >>>
+    >>> @step
+    >>> async def process_step(name: str):
+    >>>     return f"Hello, {name}!"
+    >>>
+    >>> # Execute workflow
+    >>> run_id = await start(my_workflow, "Alice")
+"""
+
+__version__ = "0.1.7"
+
+# Configuration
+from pyworkflow.config import (
+    configure,
+    configure_from_yaml,
+    get_config,
+    get_storage,
+    reset_config,
+)
+
+# Context API (new unified context via contextvars)
+from pyworkflow.context import (
+    LocalContext,
+    MockContext,
+    WorkflowContext,
+    get_context,
+    has_context,
+    reset_context,
+    set_context,
+)
+
+# Exceptions
+from pyworkflow.core.exceptions import (
+    CancellationError,
+    ChildWorkflowError,
+    ChildWorkflowFailedError,
+    FatalError,
+    HookAlreadyReceivedError,
+    HookExpiredError,
+    HookNotFoundError,
+    InvalidTokenError,
+    MaxNestingDepthError,
+    RetryableError,
+    SuspensionSignal,
+    WorkflowAlreadyRunningError,
+    WorkflowError,
+    WorkflowNotFoundError,
+)
+
+# Registry functions
+from pyworkflow.core.registry import (
+    get_step,
+    get_workflow,
+    list_steps,
+    list_workflows,
+)
+
+# Core decorators and primitives
+from pyworkflow.core.scheduled import (
+    ScheduledWorkflowMetadata,
+    activate_scheduled_workflows,
+    get_scheduled_workflow,
+    list_scheduled_workflows,
+    scheduled_workflow,
+)
+from pyworkflow.core.step import step
+from pyworkflow.core.workflow import workflow
+
+# Discovery
+from pyworkflow.discovery import DiscoveryError, discover_workflows
+
+# Execution engine
+from pyworkflow.engine.executor import (
+    ConfigurationError,
+    cancel_workflow,
+    get_workflow_chain,
+    get_workflow_events,
+    get_workflow_run,
+    resume,
+    start,
+)
+
+# Core decorators and primitives
+# Execution engine
+# Logging and observability
+from pyworkflow.observability.logging import (
+    bind_step_context,
+    bind_workflow_context,
+    configure_logging,
+    get_logger,
+)
+from pyworkflow.primitives.child_handle import ChildWorkflowHandle
+from pyworkflow.primitives.child_workflow import start_child_workflow
+from pyworkflow.primitives.continue_as_new import continue_as_new
+from pyworkflow.primitives.define_hook import TypedHook, define_hook
+from pyworkflow.primitives.hooks import hook
+from pyworkflow.primitives.resume_hook import ResumeResult, resume_hook
+from pyworkflow.primitives.schedule import (
+    backfill_schedule,
+    create_schedule,
+    delete_schedule,
+    get_schedule,
+    list_schedules,
+    pause_schedule,
+    resume_schedule,
+    trigger_schedule,
+    update_schedule,
+)
+from pyworkflow.primitives.shield import shield
+from pyworkflow.primitives.sleep import sleep
+
+# Runtime
+from pyworkflow.runtime import LocalRuntime, Runtime, get_runtime, register_runtime
+
+# Scheduler
+from pyworkflow.scheduler import LocalScheduler
+
+# Storage backends
+from pyworkflow.storage.base import StorageBackend
+from pyworkflow.storage.file import FileStorageBackend
+from pyworkflow.storage.memory import InMemoryStorageBackend
+from pyworkflow.storage.schemas import (
+    CalendarSpec,
+    OverlapPolicy,
+    RunStatus,
+    Schedule,
+    ScheduleSpec,
+    ScheduleStatus,
+    WorkflowRun,
+)
+
+__all__ = [
+    # Version
+    "__version__",
+    # Configuration
+    "configure",
+    "configure_from_yaml",
+    "get_config",
+    "get_storage",
+    "reset_config",
+    # Discovery
+    "discover_workflows",
+    "DiscoveryError",
+    # Core decorators
+    "workflow",
+    "step",
+    "scheduled_workflow",
+    # Schedule management
+    "create_schedule",
+    "get_schedule",
+    "list_schedules",
+    "update_schedule",
+    "pause_schedule",
+    "resume_schedule",
+    "delete_schedule",
+    "trigger_schedule",
+    "backfill_schedule",
+    "activate_scheduled_workflows",
+    "get_scheduled_workflow",
+    "list_scheduled_workflows",
+    "ScheduledWorkflowMetadata",
+    # Primitives
+    "sleep",
+    "hook",
+    "define_hook",
+    "TypedHook",
+    "resume_hook",
+    "ResumeResult",
+    "shield",
+    "continue_as_new",
+    # Child workflows
+    "start_child_workflow",
+    "ChildWorkflowHandle",
+    # Execution
+    "start",
+    "resume",
+    "cancel_workflow",
+    "get_workflow_run",
+    "get_workflow_events",
+    "get_workflow_chain",
+    # Exceptions
+    "WorkflowError",
+    "FatalError",
+    "RetryableError",
+    "CancellationError",
+    "SuspensionSignal",
+    "WorkflowNotFoundError",
+    "WorkflowAlreadyRunningError",
+    "HookNotFoundError",
+    "HookExpiredError",
+    "HookAlreadyReceivedError",
+    "InvalidTokenError",
+    "ConfigurationError",
+    "ChildWorkflowError",
+    "ChildWorkflowFailedError",
+    "MaxNestingDepthError",
+    # Context API
+    "WorkflowContext",
+    "LocalContext",
+    "MockContext",
+    "get_context",
+    "has_context",
+    "set_context",
+    "reset_context",
+    # Registry
+    "list_workflows",
+    "get_workflow",
+    "list_steps",
+    "get_step",
+    # Storage
+    "StorageBackend",
+    "FileStorageBackend",
+    "InMemoryStorageBackend",
+    "WorkflowRun",
+    "RunStatus",
+    # Schedule types
+    "Schedule",
+    "ScheduleSpec",
+    "CalendarSpec",
+    "ScheduleStatus",
+    "OverlapPolicy",
+    # Runtime
+    "Runtime",
+    "LocalRuntime",
+    "get_runtime",
+    "register_runtime",
+    # Scheduler
+    "LocalScheduler",
+    # Logging
+    "configure_logging",
+    "get_logger",
+    "bind_workflow_context",
+    "bind_step_context",
+]

pyworkflow/aws/__init__.py

@@ -0,0 +1,68 @@
+"""
+AWS Durable Lambda Functions integration for PyWorkflow.
+
+This module provides integration with AWS Lambda Durable Functions,
+allowing PyWorkflow workflows to run on AWS Lambda with automatic
+checkpointing, durability, and cost-free sleep/wait operations.
+
+Quick Start:
+    ```python
+    from pyworkflow import workflow, step
+    from pyworkflow.aws import aws_workflow_handler, AWSWorkflowContext
+
+    @step
+    async def process_order(order_id: str) -> dict:
+        return {"order_id": order_id, "status": "processed"}
+
+    @aws_workflow_handler
+    @workflow
+    async def order_workflow(ctx: AWSWorkflowContext, order_id: str):
+        # Execute step with automatic checkpointing
+        result = await process_order(order_id)
+
+        # Sleep without compute charges
+        ctx.sleep(300)  # 5 minutes
+
+        return result
+
+    # Export Lambda handler
+    handler = order_workflow
+    ```
+
+Installation:
+    pip install pyworkflow[aws]
+
+Features:
+    - Automatic checkpointing via AWS Durable Execution SDK
+    - Cost-free waits using context.wait()
+    - Support for both sync and async workflows
+    - Local testing with mock context
+"""
+
+from pyworkflow.aws.context import (
+    AWSWorkflowContext,
+    get_aws_context,
+    has_aws_context,
+)
+from pyworkflow.aws.handler import aws_workflow_handler, create_lambda_handler
+from pyworkflow.aws.testing import (
+    MockCallback,
+    MockDurableContext,
+    MockDuration,
+    create_test_handler,
+)
+
+__all__ = [
+    # Context
+    "AWSWorkflowContext",
+    "get_aws_context",
+    "has_aws_context",
+    # Handler
+    "aws_workflow_handler",
+    "create_lambda_handler",
+    # Testing
+    "MockDurableContext",
+    "MockDuration",
+    "MockCallback",
+    "create_test_handler",
+]

pyworkflow/aws/context.py

@@ -0,0 +1,234 @@
+"""
+AWS Durable Lambda Functions context adapter.
+
+This module provides an adapter that wraps AWS DurableContext to work
+with PyWorkflow's step and sleep primitives.
+"""
+
+from __future__ import annotations
+
+import asyncio
+from collections.abc import Awaitable, Callable
+from contextvars import ContextVar
+from typing import TYPE_CHECKING, Any
+
+from loguru import logger
+
+from pyworkflow.context.base import StepFunction, WorkflowContext
+from pyworkflow.utils.duration import parse_duration
+
+if TYPE_CHECKING:
+    # Only import AWS SDK types for type checking
+    # Actual import happens at runtime if available
+    from aws_durable_execution_sdk_python import DurableContext
+
+
+# Context variable to track current AWS context (for backward compatibility)
+_aws_context: ContextVar[AWSWorkflowContext | None] = ContextVar(
+    "aws_workflow_context", default=None
+)
+
+
+def get_aws_context() -> AWSWorkflowContext | None:
+    """Get the current AWS workflow context if running in AWS environment."""
+    return _aws_context.get()
+
+
+def has_aws_context() -> bool:
+    """Check if currently running in AWS Durable Lambda context."""
+    return _aws_context.get() is not None
+
+
+class AWSWorkflowContext(WorkflowContext):
+    """
+    Adapts AWS DurableContext to PyWorkflow's context interface.
+
+    This class wraps the AWS Durable Execution SDK's context to provide
+    a familiar interface for PyWorkflow primitives while leveraging
+    AWS's native checkpointing and durability features.
+
+    Attributes:
+        _aws_ctx: The underlying AWS DurableContext
+        _step_counter: Counter for generating unique step names
+    """
+
+    def __init__(
+        self,
+        aws_ctx: DurableContext,
+        run_id: str = "aws_run",
+        workflow_name: str = "aws_workflow",
+    ) -> None:
+        """
+        Initialize the AWS workflow context adapter.
+
+        Args:
+            aws_ctx: The AWS DurableContext from the Lambda handler
+            run_id: Optional run ID for logging
+            workflow_name: Optional workflow name for logging
+        """
+        super().__init__(run_id=run_id, workflow_name=workflow_name)
+        self._aws_ctx = aws_ctx
+        self._step_counter = 0
+
+        # Set this context as the current AWS context (for backward compatibility)
+        _aws_context.set(self)
+
+        logger.debug("AWS workflow context initialized")
+
+    async def run(
+        self,
+        func: StepFunction,
+        *args: Any,
+        name: str | None = None,
+        **kwargs: Any,
+    ) -> Any:
+        """
+        Execute a step function with AWS checkpointing.
+
+        This is the new unified interface for step execution.
+        Uses AWS's context.step() for automatic checkpointing and replay.
+
+        Args:
+            func: Step function to execute
+            *args: Arguments for the function
+            name: Optional step name (used for checkpointing)
+            **kwargs: Keyword arguments
+
+        Returns:
+            Step result
+        """
+        return self.execute_step(func, *args, step_name=name, **kwargs)
+
+    def execute_step(
+        self,
+        step_fn: Callable[..., Any],
+        *args: Any,
+        step_name: str | None = None,
+        **kwargs: Any,
+    ) -> Any:
+        """
+        Execute a step with AWS checkpointing (legacy interface).
+
+        This method wraps a step function call with AWS's context.step(),
+        which provides automatic checkpointing and replay behavior.
+
+        Args:
+            step_fn: The step function to execute
+            *args: Positional arguments to pass to the step
+            step_name: Optional name for the step (defaults to function name)
+            **kwargs: Keyword arguments to pass to the step
+
+        Returns:
+            The result of the step function
+        """
+        # Generate step name
+        name = step_name or getattr(step_fn, "__name__", None)
+        if not name:
+            self._step_counter += 1
+            name = f"step_{self._step_counter}"
+
+        logger.debug(f"Executing AWS step: {name}")
+
+        def run_step(_: Any) -> Any:
+            """Inner function to execute the step, handling async/sync."""
+            # Check if the step function is async
+            if asyncio.iscoroutinefunction(step_fn):
+                # Get or create event loop for async execution
+                try:
+                    loop = asyncio.get_running_loop()
+                except RuntimeError:
+                    loop = None
+
+                if loop is not None:
+                    # We're in an async context - create a task
+                    # This shouldn't happen in normal AWS Lambda flow
+                    # but handle it gracefully
+                    import concurrent.futures
+
+                    with concurrent.futures.ThreadPoolExecutor() as executor:
+                        future = executor.submit(asyncio.run, step_fn(*args, **kwargs))
+                        return future.result()
+                else:
+                    # No running loop - use asyncio.run()
+                    return asyncio.run(step_fn(*args, **kwargs))
+            else:
+                # Synchronous function - execute directly
+                return step_fn(*args, **kwargs)
+
+        # Use AWS context.step() for checkpointing
+        result = self._aws_ctx.step(run_step, name=name)
+
+        logger.debug(f"AWS step completed: {name}")
+        return result
+
+    async def sleep(self, duration: str | int | float) -> None:
+        """
+        Sleep using AWS wait (no compute charges during wait).
+
+        This method uses AWS's context.wait() which suspends the Lambda
+        execution without incurring compute charges.
+
+        Args:
+            duration: Sleep duration as:
+                - str: Duration string like "5s", "10m", "1h"
+                - int/float: Duration in seconds
+        """
+        # Parse duration to seconds
+        duration_seconds = parse_duration(duration) if isinstance(duration, str) else int(duration)
+
+        logger.debug(f"AWS sleep: {duration_seconds} seconds")
+
+        # Try to use AWS Duration, fall back to raw seconds for mock context
+        try:
+            from aws_durable_execution_sdk_python.config import Duration
+
+            duration_obj = Duration.from_seconds(duration_seconds)
+        except ImportError:
+            # AWS SDK not installed - likely using mock context for testing
+            # MockDurableContext.wait() accepts raw seconds
+            duration_obj = duration_seconds
+
+        # Use AWS context.wait() for cost-free waiting
+        self._aws_ctx.wait(duration_obj)
+
+        logger.debug(f"AWS sleep completed: {duration_seconds} seconds")
+
+    async def parallel(self, *tasks: Any) -> list[Any]:
+        """Execute tasks in parallel using asyncio.gather."""
+        return list(await asyncio.gather(*tasks))
+
+    # =========================================================================
+    # Cancellation support (not fully implemented for AWS - defer to AWS SDK)
+    # =========================================================================
+
+    def is_cancellation_requested(self) -> bool:
+        """Check if cancellation requested (AWS manages this internally)."""
+        return False
+
+    def request_cancellation(self, reason: str | None = None) -> None:
+        """Request cancellation (AWS manages this internally)."""
+        logger.warning("Cancellation not supported in AWS context")
+
+    def check_cancellation(self) -> None:
+        """Check cancellation (AWS manages this internally)."""
+        pass  # AWS handles this
+
+    @property
+    def cancellation_blocked(self) -> bool:
+        """Check if cancellation blocked."""
+        return False
+
+    async def hook(
+        self,
+        name: str,
+        timeout: int | None = None,
+        on_created: Callable[[str], Awaitable[None]] | None = None,
+        payload_schema: type | None = None,
+    ) -> Any:
+        """Wait for hook (not implemented for AWS - use wait_for_callback)."""
+        raise NotImplementedError("Use AWS context.wait_for_callback() instead")
+
+    def cleanup(self) -> None:
+        """Clean up the context when workflow completes."""
+        _aws_context.set(None)
+        logger.debug("AWS workflow context cleaned up")