edda-framework 0.1.0__tar.gz → 0.2.0__tar.gz

{edda_framework-0.1.0 → edda_framework-0.2.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: edda-framework
-Version: 0.1.0
+Version: 0.2.0
 Summary: Lightweight Durable Execution Framework
 Project-URL: Homepage, https://github.com/i2y/edda
 Project-URL: Documentation, https://github.com/i2y/edda#readme
@@ -20,7 +20,9 @@ Classifier: Programming Language :: Python :: 3.14
 Classifier: Topic :: Software Development :: Libraries :: Application Frameworks
 Classifier: Topic :: System :: Distributed Computing
 Requires-Python: >=3.11
+Requires-Dist: a2wsgi>=1.10.0
 Requires-Dist: aiosqlite>=0.21.0
+Requires-Dist: anyio>=4.0.0
 Requires-Dist: cloudevents>=1.12.0
 Requires-Dist: httpx>=0.28.1
 Requires-Dist: pydantic>=2.0.0
@@ -75,6 +77,7 @@ For detailed documentation, visit [https://i2y.github.io/edda/](https://i2y.gith
 - 📦 **Transactional Outbox**: Reliable event publishing with guaranteed delivery
 - ☁️ **CloudEvents Support**: Native support for CloudEvents protocol
 - ⏱️ **Event & Timer Waiting**: Free up worker resources while waiting for events or timers, resume on any available worker
+- 🌍 **ASGI/WSGI Support**: Deploy with your preferred server (uvicorn, gunicorn, uWSGI)
 
 ## Use Cases
 
@@ -638,6 +641,51 @@ api.mount("/workflows", edda_app)
 
 This works with any ASGI framework (Starlette, FastAPI, Quart, etc.)
 
+### WSGI Integration
+
+For WSGI environments (gunicorn, uWSGI, Flask, Django), use the WSGI adapter:
+
+```python
+from edda import EddaApp
+from edda.wsgi import create_wsgi_app
+
+# Create Edda app
+edda_app = EddaApp(db_url="sqlite:///workflow.db")
+
+# Convert to WSGI
+wsgi_application = create_wsgi_app(edda_app)
+```
+
+**Running with WSGI servers:**
+
+```bash
+# With Gunicorn
+gunicorn demo_app:wsgi_application --workers 4
+
+# With uWSGI
+uwsgi --http :8000 --wsgi-file demo_app.py --callable wsgi_application
+```
+
+**Sync Activities**: For WSGI environments or legacy codebases, you can write synchronous activities:
+
+```python
+from edda import activity, WorkflowContext
+
+@activity
+def process_payment(ctx: WorkflowContext, amount: float) -> dict:
+    # Sync function - automatically executed in thread pool
+    # No async/await needed!
+    return {"status": "paid", "amount": amount}
+
+@workflow
+async def payment_workflow(ctx: WorkflowContext, order_id: str) -> dict:
+    # Workflows still use async (for deterministic replay)
+    result = await process_payment(ctx, 99.99, activity_id="pay:1")
+    return result
+```
+
+**Performance note**: ASGI servers (uvicorn, hypercorn) are recommended for better performance with Edda's async architecture. WSGI support is provided for compatibility with existing infrastructure and users who prefer synchronous programming.
+
 ## Observability Hooks
 
 Extend Edda with custom observability without coupling to specific tools:

{edda_framework-0.1.0 → edda_framework-0.2.0}/README.md

@@ -27,6 +27,7 @@ For detailed documentation, visit [https://i2y.github.io/edda/](https://i2y.gith
 - 📦 **Transactional Outbox**: Reliable event publishing with guaranteed delivery
 - ☁️ **CloudEvents Support**: Native support for CloudEvents protocol
 - ⏱️ **Event & Timer Waiting**: Free up worker resources while waiting for events or timers, resume on any available worker
+- 🌍 **ASGI/WSGI Support**: Deploy with your preferred server (uvicorn, gunicorn, uWSGI)
 
 ## Use Cases
 
@@ -590,6 +591,51 @@ api.mount("/workflows", edda_app)
 
 This works with any ASGI framework (Starlette, FastAPI, Quart, etc.)
 
+### WSGI Integration
+
+For WSGI environments (gunicorn, uWSGI, Flask, Django), use the WSGI adapter:
+
+```python
+from edda import EddaApp
+from edda.wsgi import create_wsgi_app
+
+# Create Edda app
+edda_app = EddaApp(db_url="sqlite:///workflow.db")
+
+# Convert to WSGI
+wsgi_application = create_wsgi_app(edda_app)
+```
+
+**Running with WSGI servers:**
+
+```bash
+# With Gunicorn
+gunicorn demo_app:wsgi_application --workers 4
+
+# With uWSGI
+uwsgi --http :8000 --wsgi-file demo_app.py --callable wsgi_application
+```
+
+**Sync Activities**: For WSGI environments or legacy codebases, you can write synchronous activities:
+
+```python
+from edda import activity, WorkflowContext
+
+@activity
+def process_payment(ctx: WorkflowContext, amount: float) -> dict:
+    # Sync function - automatically executed in thread pool
+    # No async/await needed!
+    return {"status": "paid", "amount": amount}
+
+@workflow
+async def payment_workflow(ctx: WorkflowContext, order_id: str) -> dict:
+    # Workflows still use async (for deterministic replay)
+    result = await process_payment(ctx, 99.99, activity_id="pay:1")
+    return result
+```
+
+**Performance note**: ASGI servers (uvicorn, hypercorn) are recommended for better performance with Edda's async architecture. WSGI support is provided for compatibility with existing infrastructure and users who prefer synchronous programming.
+
 ## Observability Hooks
 
 Extend Edda with custom observability without coupling to specific tools:

{edda_framework-0.1.0 → edda_framework-0.2.0}/demo_app.py

@@ -1817,3 +1817,9 @@ async def scheduled_order_shipment_workflow(
 # Export as ASGI application
 # No need to manually register event handlers!
 application = app
+
+# Export as WSGI application (for gunicorn, uWSGI, etc.)
+# Usage: gunicorn demo_app:wsgi_application --workers 4
+from edda.wsgi import create_wsgi_app
+
+wsgi_application = create_wsgi_app(app)

{edda_framework-0.1.0 → edda_framework-0.2.0}/docs/core-features/workflows-activities.md

@@ -121,6 +121,46 @@ async def create_order_with_db(ctx: WorkflowContext, order_id: str):
     return {"order_id": order_id}
 ```
 
+### Sync Activities (WSGI Compatibility)
+
+For WSGI environments (gunicorn, uWSGI) or legacy codebases, Edda supports synchronous activities:
+
+```python
+from edda import activity, WorkflowContext
+
+@activity
+def create_user_record(ctx: WorkflowContext, user_id: str, email: str) -> dict:
+    """Sync activity - executed in thread pool"""
+    # Traditional sync code - no async/await needed!
+    user = User(user_id=user_id, email=email)
+    db.session.add(user)
+    db.session.commit()
+    return {"user_id": user.id}
+
+@activity
+async def async_activity(ctx: WorkflowContext, data: str) -> dict:
+    """Async activity - recommended for I/O operations"""
+    result = await httpx.get(f"https://api.example.com/{data}")
+    return result.json()
+
+@workflow
+async def mixed_workflow(ctx: WorkflowContext, user_id: str) -> dict:
+    # Workflows are always async (for deterministic replay)
+    # But can call both sync and async activities
+    user = await create_user_record(ctx, user_id, "user@example.com", activity_id="create:1")
+    data = await async_activity(ctx, user_id, activity_id="fetch:1")
+    return {"user": user, "data": data}
+```
+
+**When to use sync activities:**
+
+- ✅ Existing sync codebases (Flask, Django)
+- ✅ WSGI deployments (gunicorn, uWSGI)
+- ✅ Libraries without async support
+- ✅ Simple CPU-bound operations
+
+**Performance note:** Async activities are recommended for I/O-bound operations (database queries, HTTP requests, file I/O) for better performance. Sync activities are executed in a thread pool to avoid blocking the event loop.
+
 ## Retry Policies
 
 Activities automatically retry on failure with exponential backoff. This provides resilience against transient failures like network timeouts or temporary service unavailability.
@@ -755,26 +795,41 @@ async def order_workflow(ctx: WorkflowContext, order_id: str, amount: float):
     pass
 ```
 
-### 4. Don't Mix Async/Sync
+### 4. Choose Async or Sync Appropriately
 
-❌ **Bad:**
+✅ **Preferred: Async activities** (better performance for I/O)
 
 ```python
 @activity
-def sync_activity(ctx: WorkflowContext, param: str):  # ❌ Not async!
-    # This won't work!
-    pass
+async def fetch_user_data(ctx: WorkflowContext, user_id: str) -> dict:
+    # Async I/O operations (recommended)
+    result = await httpx.get(f"https://api.example.com/users/{user_id}")
+    return result.json()
 ```
 
-✅ **Good:**
+✅ **Valid: Sync activities** (WSGI compatibility, legacy code)
 
 ```python
 @activity
-async def async_activity(ctx: WorkflowContext, param: str):  # ✅ Async
-    # Correct!
-    pass
+def process_legacy_data(ctx: WorkflowContext, data: str) -> dict:
+    # Sync operations (executed in thread pool)
+    result = legacy_library.process(data)  # No async support
+    return {"processed": result}
 ```
 
+✅ **Good: Mix sync and async in same workflow**
+
+```python
+@workflow
+async def order_workflow(ctx: WorkflowContext, order_id: str) -> dict:
+    # Both sync and async activities work fine
+    user = await create_user_record(ctx, order_id, activity_id="user:1")  # Sync
+    payment = await process_payment(ctx, 99.99, activity_id="pay:1")  # Async
+    return {"user": user, "payment": payment}
+```
+
+**Performance tip**: Prefer async activities for I/O-bound operations (database queries, HTTP requests, file I/O). Use sync activities when integrating with legacy code or libraries without async support.
+
 ## Next Steps
 
 - **[Durable Execution](durable-execution/replay.md)**: Learn how Edda ensures workflows never lose progress

{edda_framework-0.1.0 → edda_framework-0.2.0}/edda/__init__.py

@@ -30,6 +30,7 @@ from edda.hooks import HooksBase, WorkflowHooks
 from edda.outbox import OutboxRelayer, send_event_transactional
 from edda.retry import RetryPolicy
 from edda.workflow import workflow
+from edda.wsgi import create_wsgi_app
 
 __version__ = "0.1.0"
 
@@ -53,4 +54,5 @@ __all__ = [
     "RetryPolicy",
     "RetryExhaustedError",
     "TerminalError",
+    "create_wsgi_app",
 ]

{edda_framework-0.1.0 → edda_framework-0.2.0}/edda/activity.py

@@ -13,6 +13,8 @@ import time
 from collections.abc import Callable
 from typing import Any, TypeVar, cast
 
+import anyio
+
 from edda.context import WorkflowContext
 from edda.exceptions import RetryExhaustedError, TerminalError, WorkflowCancelledException
 from edda.pydantic_utils import (
@@ -40,12 +42,13 @@ class Activity:
         Initialize activity wrapper.
 
         Args:
-            func: The async function to wrap
+            func: The async or sync function to wrap
             retry_policy: Optional retry policy for this activity.
                          If None, uses the default policy from EddaApp.
         """
         self.func = func
         self.name = func.__name__
+        self.is_async = inspect.iscoroutinefunction(func)
         self.retry_policy = retry_policy
         functools.update_wrapper(self, func)
 
@@ -284,8 +287,12 @@ class Activity:
             "kwargs": {k: to_json_dict(v) for k, v in kwargs.items()},
         }
 
-        # Execute the activity function
-        result = await self.func(ctx, *args, **kwargs)
+        # Execute the activity function (sync or async)
+        if self.is_async:
+            result = await self.func(ctx, *args, **kwargs)
+        else:
+            # Run sync function in thread pool to avoid blocking
+            result = await anyio.to_thread.run_sync(self.func, ctx, *args, **kwargs)
 
         # Convert Pydantic model result to JSON dict for storage
         result_for_storage = to_json_dict(result)
@@ -369,7 +376,7 @@ class Activity:
             return self.retry_policy
 
         # Priority 2: App-level policy (EddaApp default_retry_policy)
-        # Note: This will be implemented in Phase 5 (edda/app.py)
+        # Set by ReplayEngine when creating WorkflowContext (edda/replay.py)
         if hasattr(ctx, "_app_retry_policy") and ctx._app_retry_policy is not None:
             return cast(RetryPolicy, ctx._app_retry_policy)
 
@@ -426,8 +433,9 @@ def activity(
     """
     Decorator for defining activities (atomic units of work) with automatic retry.
 
-    Activities are async functions that take a WorkflowContext as the first
-    parameter, followed by any other parameters.
+    Activities can be async or sync functions that take a WorkflowContext as the first
+    parameter, followed by any other parameters. Sync functions are executed in a
+    thread pool to avoid blocking the event loop.
 
     Activities are automatically wrapped in a transaction, ensuring that
     activity execution, history recording, and event sending are atomic.
@@ -443,34 +451,39 @@ def activity(
     Workflow function.
 
     Example:
-        >>> @activity  # Uses default retry policy (5 attempts, exponential backoff)
-        ... async def reserve_inventory(ctx: WorkflowContext, order_id: str) -> dict:
-        ...     # Your business logic here
+        >>> @activity  # Sync activity (no async/await)
+        ... def reserve_inventory(ctx: WorkflowContext, order_id: str) -> dict:
+        ...     # Your business logic here (executed in thread pool)
+        ...     return {"reservation_id": "123"}
+
+        >>> @activity  # Async activity (recommended for I/O-bound operations)
+        ... async def reserve_inventory_async(ctx: WorkflowContext, order_id: str) -> dict:
+        ...     # Async I/O operations
         ...     return {"reservation_id": "123"}
 
         >>> from edda.retry import RetryPolicy, AGGRESSIVE_RETRY
         >>> @activity(retry_policy=AGGRESSIVE_RETRY)  # Custom retry policy
-        ... async def process_payment(ctx: WorkflowContext, amount: float) -> dict:
+        ... def process_payment(ctx: WorkflowContext, amount: float) -> dict:
         ...     # Fast retries for low-latency services
         ...     return {"status": "completed"}
 
         >>> @activity  # Non-idempotent operations cached during replay
-        ... async def charge_credit_card(ctx: WorkflowContext, amount: float) -> dict:
+        ... def charge_credit_card(ctx: WorkflowContext, amount: float) -> dict:
         ...     # External API call - result is cached, won't be called again on replay
         ...     # If this fails, automatic retry with exponential backoff
         ...     return {"transaction_id": "txn_123"}
 
         >>> from edda.exceptions import TerminalError
         >>> @activity
-        ... async def validate_user(ctx: WorkflowContext, user_id: str) -> dict:
-        ...     user = await fetch_user(user_id)
+        ... def validate_user(ctx: WorkflowContext, user_id: str) -> dict:
+        ...     user = fetch_user(user_id)  # No await needed for sync
         ...     if not user:
         ...         # Don't retry - user doesn't exist
         ...         raise TerminalError(f"User {user_id} not found")
         ...     return {"user_id": user_id, "name": user.name}
 
     Args:
-        func: Async function to wrap as an activity
+        func: Async or sync function to wrap as an activity
         retry_policy: Optional retry policy for this activity.
                      If None, uses the default policy from EddaApp.
 
@@ -480,14 +493,14 @@ def activity(
     Raises:
         RetryExhaustedError: When all retry attempts are exhausted
         TerminalError: For non-retryable errors (no retry attempted)
+
+    Sync activities are executed in a thread pool. For I/O-bound operations
+    (database queries, HTTP requests, etc.), async activities are recommended
+    for better performance.
     """
 
     def decorator(f: F) -> F:
-        # Verify the function is async
-        if not inspect.iscoroutinefunction(f):
-            raise TypeError(f"Activity {f.__name__} must be an async function")
-
-        # Create the Activity wrapper with retry policy
+        # Create the Activity wrapper with retry policy (supports both sync and async)
         activity_wrapper = Activity(f, retry_policy=retry_policy)
 
         # Mark as activity for introspection

edda_framework-0.2.0/edda/wsgi.py

@@ -0,0 +1,77 @@
+"""
+WSGI adapter for Edda framework.
+
+This module provides a WSGI adapter that wraps EddaApp (ASGI) for use with
+WSGI servers like gunicorn or uWSGI.
+
+The adapter uses a2wsgi to convert the ASGI interface to WSGI.
+"""
+
+from typing import Any
+
+from a2wsgi import ASGIMiddleware
+
+from edda.app import EddaApp
+
+
+def create_wsgi_app(edda_app: EddaApp) -> Any:
+    """
+    Create a WSGI-compatible application from an EddaApp instance.
+
+    This function wraps an EddaApp (ASGI) with a2wsgi's ASGIMiddleware,
+    making it compatible with WSGI servers like gunicorn or uWSGI.
+
+    Args:
+        edda_app: An initialized EddaApp instance
+
+    Returns:
+        A WSGI-compatible application callable
+
+    Example:
+        Basic usage with EddaApp::
+
+            from edda import EddaApp
+            from edda.wsgi import create_wsgi_app
+            from edda.storage.sqlalchemy_storage import SQLAlchemyStorage
+
+            # Create storage and EddaApp
+            storage = SQLAlchemyStorage("sqlite:///edda.db")
+            app = EddaApp(storage=storage)
+
+            # Create WSGI application
+            wsgi_app = create_wsgi_app(app)
+
+        Running with gunicorn::
+
+            # In your module (e.g., demo_app.py):
+            from edda import EddaApp
+            from edda.wsgi import create_wsgi_app
+
+            application = EddaApp(...)  # ASGI
+            wsgi_application = create_wsgi_app(application)  # WSGI
+
+            # Command line:
+            $ gunicorn demo_app:wsgi_application --workers 4
+
+        Running with uWSGI::
+
+            $ uwsgi --http :8000 --wsgi-file demo_app.py --callable wsgi_application
+
+    Background tasks (auto-resume, timer checks, etc.) will run in each
+    worker process.
+
+    For production deployments, ASGI servers (uvicorn, hypercorn) are
+    recommended for better performance with Edda's async architecture.
+    WSGI support is provided for compatibility with existing infrastructure
+    and for users who prefer synchronous programming with sync activities.
+
+    See Also:
+        - :class:`edda.app.EddaApp`: The main ASGI application class
+        - :func:`edda.activity.activity`: Decorator supporting sync activities
+    """
+    # Type ignore due to a2wsgi's strict ASGI type checking
+    # EddaApp implements ASGI 3.0 interface correctly
+    return ASGIMiddleware(edda_app)  # type: ignore[arg-type]
+
+
+__all__ = ["create_wsgi_app"]

{edda_framework-0.1.0 → edda_framework-0.2.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "edda-framework"
-version = "0.1.0"
+version = "0.2.0"
 description = "Lightweight Durable Execution Framework"
 authors = [
     { name = "Yasushi Itoh", email = "6240399+i2y@users.noreply.github.com" }
@@ -22,6 +22,8 @@ classifiers = [
 ]
 
 dependencies = [
+    "anyio>=4.0.0",
+    "a2wsgi>=1.10.0",
     "cloudevents>=1.12.0",
     "httpx>=0.28.1",
     "pydantic>=2.0.0",

{edda_framework-0.1.0 → edda_framework-0.2.0}/tests/test_activity.py

@@ -42,14 +42,20 @@ class TestActivityDecorator:
         assert my_test_activity.__name__ == "my_test_activity"
         assert my_test_activity.__doc__ == "Test activity docstring."
 
-    async def test_activity_decorator_requires_async(self):
-        """Test that decorator raises error for non-async functions."""
+    async def test_activity_decorator_supports_sync(self):
+        """Test that decorator supports both sync and async functions."""
 
-        with pytest.raises(TypeError, match="must be an async function"):
+        @activity
+        def sync_function(ctx: WorkflowContext) -> dict:
+            return {"result": "sync"}
+
+        # Verify it's a valid activity
+        assert hasattr(sync_function, "_is_activity")
+        assert sync_function._is_activity is True
 
-            @activity
-            def sync_function(ctx: WorkflowContext) -> dict:
-                return {}
+        # Verify it's detected as a sync function
+        assert hasattr(sync_function, "is_async")
+        assert sync_function.is_async is False
 
     async def test_activity_decorator_creates_wrapper(self):
         """Test that decorator creates Activity wrapper."""