render_sdk 0.1.3__py3-none-any.whl → 0.2.0__py3-none-any.whl

render_sdk/workflows/app.py

@@ -0,0 +1,262 @@
+"""Workflows application for defining durable tasks."""
+
+from __future__ import annotations
+
+import atexit
+import os
+import warnings
+from collections.abc import Callable
+from typing import Any, TypeVar
+
+from render_sdk.workflows.runner import register, run
+from render_sdk.workflows.task import (
+    Options,
+    Retry,
+    TaskCallable,
+    TaskRegistry,
+    create_task_decorator,
+)
+
+F = TypeVar("F", bound=Callable[..., Any])
+
+# Track whether auto_start has been registered
+_auto_start_app_registered = False
+
+
+class Workflows:
+    """
+    Task definition app for Render Durable Workflows.
+
+    This is the primary entry point for defining tasks that run on Render.
+    For calling tasks via REST API, use the Render class instead.
+
+    Example:
+        app = Workflows(auto_start=True)
+
+        @app.task
+        def my_task(x: int) -> int:
+            return x * 2
+
+    With configuration:
+        app = Workflows(
+            default_retry=Retry(max_retries=3, wait_duration_ms=1000),
+            default_timeout=300,
+            auto_start=True,
+        )
+
+        @app.task
+        def my_task(x: int) -> int:
+            return x * 2
+
+    Combining multiple modules:
+        from tasks_a import app as app_a
+        from tasks_b import app as app_b
+
+        combined = Workflows.from_workflows(app_a, app_b, auto_start=True)
+    """
+
+    _registry: TaskRegistry
+    _default_retry: Retry | None
+    _default_timeout: int | None
+    _default_plan: str | None
+    _auto_start: bool
+    _started: bool
+
+    def __init__(
+        self,
+        *,
+        default_retry: Retry | None = None,
+        default_timeout: int | None = None,
+        default_plan: str | None = None,
+        auto_start: bool = False,
+    ) -> None:
+        """
+        Initialize a Workflows application.
+
+        Args:
+            default_retry: Default retry configuration for all tasks.
+            default_timeout: Default timeout in seconds for all tasks.
+            default_plan: Default resource plan for all tasks.
+            auto_start: If True, automatically starts the worker on program exit
+                       when RENDER_SDK_MODE is set.
+        """
+        global _auto_start_app_registered
+
+        self._registry = TaskRegistry()
+        self._default_retry = default_retry
+        self._default_timeout = default_timeout
+        self._default_plan = default_plan
+        self._auto_start = auto_start
+        self._started = False
+
+        if auto_start:
+            if _auto_start_app_registered:
+                warnings.warn(
+                    "Multiple Workflows instances with auto_start=True detected. "
+                    "Only one instance's tasks will be executed per invocation.",
+                    UserWarning,
+                    stacklevel=2,
+                )
+            _auto_start_app_registered = True
+            atexit.register(self._maybe_start)
+
+    def __repr__(self) -> str:
+        task_count = len(self._registry.get_task_names())
+        return f"Workflows(tasks={task_count}, auto_start={self._auto_start})"
+
+    def _maybe_start(self) -> None:
+        """Start the worker if not already started and environment is configured."""
+
+        if self._started:
+            return
+
+        mode = os.environ.get("RENDER_SDK_MODE")
+        socket_path = os.environ.get("RENDER_SDK_SOCKET_PATH")
+
+        # Only start if both environment variables are set
+        if mode and socket_path:
+            self.start()
+
+    def task(
+        self,
+        func: F | None = None,
+        *,
+        name: str | None = None,
+        retry: Retry | None = None,
+        timeout: int | None = None,
+        plan: str | None = None,
+    ) -> F | Callable[[F], TaskCallable]:
+        """
+        Decorator to register a function as a task.
+
+        Args:
+            func: The function to decorate (when used without parentheses).
+            name: Optional custom name for the task (defaults to function name).
+            retry: Retry configuration (overrides default_retry).
+            timeout: Timeout in seconds (overrides default_timeout).
+            plan: Resource plan (overrides default_plan).
+
+        Returns:
+            The decorated function as a TaskCallable.
+
+        Example:
+            @app.task
+            def simple_task(x: int) -> int:
+                return x * 2
+
+            @app.task(timeout=60, plan="starter")
+            def quick_task(x: int) -> int:
+                return x + 1
+        """
+        # Build options from defaults and overrides
+        effective_retry = retry if retry is not None else self._default_retry
+        effective_timeout = timeout if timeout is not None else self._default_timeout
+        effective_plan = plan if plan is not None else self._default_plan
+
+        options = Options(
+            retry=effective_retry,
+            timeout_seconds=effective_timeout,
+            plan=effective_plan,
+        )
+
+        # Create the task decorator bound to this app's registry
+        task_decorator = create_task_decorator(self._registry)
+
+        def decorator(f: F) -> TaskCallable:
+            return task_decorator(f, name=name, options=options)
+
+        if func is None:
+            # Called with arguments: @app.task(name="...", timeout=30)
+            return decorator
+        # Called without arguments: @app.task
+        return decorator(func)
+
+    def start(self) -> None:
+        """
+        Start the workflow worker.
+
+        Reads RENDER_SDK_MODE and RENDER_SDK_SOCKET_PATH environment variables
+        to determine whether to run tasks or register them.
+
+        In most cases, use auto_start=True instead of calling this manually.
+
+        Raises:
+            ValueError: If required environment variables are not set.
+        """
+        import os
+
+        mode = os.environ.get("RENDER_SDK_MODE")
+        socket_path = os.environ.get("RENDER_SDK_SOCKET_PATH")
+
+        if not mode:
+            raise ValueError("RENDER_SDK_MODE environment variable is required")
+
+        if not socket_path:
+            raise ValueError("RENDER_SDK_SOCKET_PATH environment variable is required")
+
+        self._started = True
+
+        # Copy tasks to global registry for the runner to use
+        from render_sdk.workflows.task import _global_registry
+
+        for task_name in self._registry.get_task_names():
+            task_info = self._registry.get_task(task_name)
+            if task_info and task_name not in _global_registry._tasks:
+                _global_registry._tasks[task_name] = task_info
+
+        if mode == "run":
+            run(socket_path)
+        elif mode == "register":
+            register(socket_path)
+        else:
+            raise ValueError(f"Unknown mode: {mode}")
+
+    @classmethod
+    def from_workflows(
+        cls,
+        *apps: Workflows,
+        default_retry: Retry | None = None,
+        default_timeout: int | None = None,
+        default_plan: str | None = None,
+        auto_start: bool = False,
+    ) -> Workflows:
+        """
+        Combine multiple Workflows apps into one.
+
+        This is useful for organizing tasks across multiple modules.
+
+        Args:
+            *apps: Workflows instances to combine.
+            default_retry: Default retry for new tasks on combined app.
+            default_timeout: Default timeout for new tasks on combined app.
+            default_plan: Default plan for new tasks on combined app.
+            auto_start: If True, auto-start the combined app.
+
+        Returns:
+            A new Workflows instance with all tasks from the input apps.
+
+        Example:
+            from tasks_a import app as app_a
+            from tasks_b import app as app_b
+
+            combined = Workflows.from_workflows(app_a, app_b, auto_start=True)
+        """
+        combined = cls(
+            default_retry=default_retry,
+            default_timeout=default_timeout,
+            default_plan=default_plan,
+            auto_start=auto_start,
+        )
+
+        # Copy tasks from all apps
+        for app in apps:
+            for task_name in app._registry.get_task_names():
+                task_info = app._registry.get_task(task_name)
+                if task_info:
+                    if task_name in combined._registry._tasks:
+                        raise ValueError(
+                            f"Task '{task_name}' is defined in multiple apps"
+                        )
+                    combined._registry._tasks[task_name] = task_info
+
+        return combined

render_sdk/workflows/callback_api/models/task_options.py

@@ -18,9 +18,13 @@ class TaskOptions:
     """
     Attributes:
         retry (Union[Unset, RetryConfig]):
+        timeout_seconds (Union[Unset, int]): Task execution timeout in seconds (30-86400)
+        plan (Union[Unset, str]): Resource plan for task execution
     """
 
     retry: Union[Unset, "RetryConfig"] = UNSET
+    timeout_seconds: Union[Unset, int] = UNSET
+    plan: Union[Unset, str] = UNSET
     additional_properties: dict[str, Any] = _attrs_field(init=False, factory=dict)
 
     def to_dict(self) -> dict[str, Any]:
@@ -28,11 +32,19 @@ class TaskOptions:
         if not isinstance(self.retry, Unset):
             retry = self.retry.to_dict()
 
+        timeout_seconds = self.timeout_seconds
+
+        plan = self.plan
+
         field_dict: dict[str, Any] = {}
         field_dict.update(self.additional_properties)
         field_dict.update({})
         if retry is not UNSET:
             field_dict["retry"] = retry
+        if timeout_seconds is not UNSET:
+            field_dict["timeout_seconds"] = timeout_seconds
+        if plan is not UNSET:
+            field_dict["plan"] = plan
 
         return field_dict
 
@@ -48,8 +60,14 @@ class TaskOptions:
         else:
             retry = RetryConfig.from_dict(_retry)
 
+        timeout_seconds = d.pop("timeout_seconds", UNSET)
+
+        plan = d.pop("plan", UNSET)
+
         task_options = cls(
             retry=retry,
+            timeout_seconds=timeout_seconds,
+            plan=plan,
         )
 
         task_options.additional_properties = d

render_sdk/workflows/cli.py

@@ -0,0 +1,58 @@
+"""CLI entrypoint for running Render Workflows.
+
+Usage:
+    render-workflows myapp:app
+    render-workflows myapp.tasks:app
+
+This is an alternative to auto_start=True. It provides explicit control
+over when and how the worker starts.
+"""
+
+from __future__ import annotations
+
+import importlib
+import sys
+
+
+def main() -> None:
+    """Main CLI entrypoint."""
+    if len(sys.argv) < 2:
+        print("Usage: render-workflows <module:app>", file=sys.stderr)
+        print("Example: render-workflows myapp:app", file=sys.stderr)
+        sys.exit(1)
+
+    app_path = sys.argv[1]
+
+    if ":" not in app_path:
+        print(f"Error: Invalid app path '{app_path}'", file=sys.stderr)
+        print("Expected format: <module>:<app_variable>", file=sys.stderr)
+        print("Example: render-workflows myapp:app", file=sys.stderr)
+        sys.exit(1)
+
+    module_path, app_name = app_path.rsplit(":", 1)
+
+    try:
+        module = importlib.import_module(module_path)
+    except ImportError as e:
+        print(f"Error: Could not import module '{module_path}': {e}", file=sys.stderr)
+        sys.exit(1)
+
+    try:
+        app = getattr(module, app_name)
+    except AttributeError:
+        print(
+            f"Error: Module '{module_path}' has no attribute '{app_name}'",
+            file=sys.stderr,
+        )
+        sys.exit(1)
+
+    if not hasattr(app, "start"):
+        print(f"Error: '{app_name}' does not have a start() method", file=sys.stderr)
+        print("Expected a Workflows instance", file=sys.stderr)
+        sys.exit(1)
+
+    app.start()
+
+
+if __name__ == "__main__":
+    main()

render_sdk/workflows/client.py

@@ -2,7 +2,6 @@
 
 import asyncio
 import base64
-import importlib.metadata
 import json
 import time
 from dataclasses import dataclass
@@ -13,6 +12,7 @@ import httpx
 
 from render_sdk.client.errors import RenderError, TaskRunError
 from render_sdk.client.util import handle_http_errors
+from render_sdk.version import get_user_agent
 from render_sdk.workflows.callback_api.api.default import (
     get_input,
     post_callback,
@@ -65,11 +65,6 @@ POLLING_INTERVAL = 1.0
 POLLING_TIMEOUT = 24 * 60 * 60  # 24 hours
 QUERY_TIMEOUT = 15  # 15 seconds
 
-try:
-    version = importlib.metadata.version("render")
-except importlib.metadata.PackageNotFoundError:
-    version = "unknown"  # fallback version
-
 
 class UDSClient:
     """Client for communicating with the SDK server over Unix Domain Socket."""
@@ -80,7 +75,7 @@ class UDSClient:
     def get_client(self) -> Client:
         return Client(
             base_url="http://localhost",
-            headers={"User-Agent": f"render-workflows-python-sdk/{version}"},
+            headers={"User-Agent": get_user_agent()},
             httpx_args={
                 "transport": httpx.AsyncHTTPTransport(uds=self.socket_path),
             },

render_sdk/workflows/runner.py

@@ -88,13 +88,18 @@ async def register_async(socket_path: str) -> None:
 
             options = TaskOptions()
             # Add options if present
-            if task_info and task_info.options and task_info.options.retry:
-                retry = task_info.options.retry
-                options.retry = RetryConfig(
-                    max_retries=retry.max_retries,
-                    wait_duration_ms=retry.wait_duration,
-                    factor=retry.backoff_scaling,
-                )
+            if task_info and task_info.options:
+                if task_info.options.retry:
+                    retry = task_info.options.retry
+                    options.retry = RetryConfig(
+                        max_retries=retry.max_retries,
+                        wait_duration_ms=retry.wait_duration_ms,
+                        factor=retry.backoff_scaling,
+                    )
+                if task_info.options.timeout_seconds:
+                    options.timeout_seconds = task_info.options.timeout_seconds
+                if task_info.options.plan:
+                    options.plan = task_info.options.plan
 
             parameters: list[TaskParameter] | Unset = UNSET
             if task_info and task_info.parameters:

render_sdk/workflows/task.py

@@ -20,15 +20,24 @@ class Retry:
     """Retry configuration for a task."""
 
     max_retries: int
-    wait_duration: int
+    wait_duration_ms: int
     backoff_scaling: float = 1.5
 
 
 @dataclass
 class Options:
-    """Configuration options for a task."""
+    """Configuration options for a task.
+
+    Attributes:
+        retry: Retry configuration for automatic task retries.
+        timeout_seconds: Task execution timeout in seconds (30-86400).
+        plan: Resource plan for task execution. Options: "starter" (0.5CPU/512MB),
+              "standard" (1CPU/2GB), "pro" (2CPU/4GB). Defaults to "standard".
+    """
 
     retry: Retry | None = None
+    timeout_seconds: int | None = None
+    plan: str | None = None
 
 
 @dataclass