render_sdk 0.1.2__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/__init__.py

@@ -11,6 +11,7 @@ from .task import Task
 from .task_complete import TaskComplete
 from .task_error import TaskError
 from .task_options import TaskOptions
+from .task_parameter import TaskParameter
 from .tasks import Tasks
 
 __all__ = (
@@ -25,5 +26,6 @@ __all__ = (
     "TaskComplete",
     "TaskError",
     "TaskOptions",
+    "TaskParameter",
     "Tasks",
 )

render_sdk/workflows/callback_api/models/task.py

@@ -8,6 +8,7 @@ from ..types import UNSET, Unset
 
 if TYPE_CHECKING:
     from ..models.task_options import TaskOptions
+    from ..models.task_parameter import TaskParameter
 
 
 T = TypeVar("T", bound="Task")
@@ -19,10 +20,12 @@ class Task:
     Attributes:
         name (str):
         options (Union[Unset, TaskOptions]):
+        parameters (Union[Unset, list['TaskParameter']]): Parameter schema extracted from the task function signature
     """
 
     name: str
     options: Union[Unset, "TaskOptions"] = UNSET
+    parameters: Union[Unset, list["TaskParameter"]] = UNSET
     additional_properties: dict[str, Any] = _attrs_field(init=False, factory=dict)
 
     def to_dict(self) -> dict[str, Any]:
@@ -32,6 +35,13 @@ class Task:
         if not isinstance(self.options, Unset):
             options = self.options.to_dict()
 
+        parameters: Union[Unset, list[dict[str, Any]]] = UNSET
+        if not isinstance(self.parameters, Unset):
+            parameters = []
+            for parameters_item_data in self.parameters:
+                parameters_item = parameters_item_data.to_dict()
+                parameters.append(parameters_item)
+
         field_dict: dict[str, Any] = {}
         field_dict.update(self.additional_properties)
         field_dict.update(
@@ -41,12 +51,15 @@ class Task:
         )
         if options is not UNSET:
             field_dict["options"] = options
+        if parameters is not UNSET:
+            field_dict["parameters"] = parameters
 
         return field_dict
 
     @classmethod
     def from_dict(cls: type[T], src_dict: Mapping[str, Any]) -> T:
         from ..models.task_options import TaskOptions
+        from ..models.task_parameter import TaskParameter
 
         d = dict(src_dict)
         name = d.pop("name")
@@ -58,9 +71,17 @@ class Task:
         else:
             options = TaskOptions.from_dict(_options)
 
+        parameters = []
+        _parameters = d.pop("parameters", UNSET)
+        for parameters_item_data in _parameters or []:
+            parameters_item = TaskParameter.from_dict(parameters_item_data)
+
+            parameters.append(parameters_item)
+
         task = cls(
             name=name,
             options=options,
+            parameters=parameters,
         )
 
         task.additional_properties = d

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/callback_api/models/task_parameter.py

@@ -0,0 +1,88 @@
+from collections.abc import Mapping
+from typing import Any, TypeVar, Union
+
+from attrs import define as _attrs_define
+from attrs import field as _attrs_field
+
+from ..types import UNSET, Unset
+
+T = TypeVar("T", bound="TaskParameter")
+
+
+@_attrs_define
+class TaskParameter:
+    """Information about a task parameter extracted from function signature
+
+    Attributes:
+        name (str): Parameter name
+        has_default (bool): Whether the parameter has a default value
+        type_ (Union[Unset, str]): String representation of the parameter type hint
+        default_value (Union[Unset, str]): JSON-encoded default value (if has_default is true)
+    """
+
+    name: str
+    has_default: bool
+    type_: Union[Unset, str] = UNSET
+    default_value: Union[Unset, str] = UNSET
+    additional_properties: dict[str, Any] = _attrs_field(init=False, factory=dict)
+
+    def to_dict(self) -> dict[str, Any]:
+        name = self.name
+
+        has_default = self.has_default
+
+        type_ = self.type_
+
+        default_value = self.default_value
+
+        field_dict: dict[str, Any] = {}
+        field_dict.update(self.additional_properties)
+        field_dict.update(
+            {
+                "name": name,
+                "has_default": has_default,
+            }
+        )
+        if type_ is not UNSET:
+            field_dict["type"] = type_
+        if default_value is not UNSET:
+            field_dict["default_value"] = default_value
+
+        return field_dict
+
+    @classmethod
+    def from_dict(cls: type[T], src_dict: Mapping[str, Any]) -> T:
+        d = dict(src_dict)
+        name = d.pop("name")
+
+        has_default = d.pop("has_default")
+
+        type_ = d.pop("type", UNSET)
+
+        default_value = d.pop("default_value", UNSET)
+
+        task_parameter = cls(
+            name=name,
+            has_default=has_default,
+            type_=type_,
+            default_value=default_value,
+        )
+
+        task_parameter.additional_properties = d
+        return task_parameter
+
+    @property
+    def additional_keys(self) -> list[str]:
+        return list(self.additional_properties.keys())
+
+    def __getitem__(self, key: str) -> Any:
+        return self.additional_properties[key]
+
+    def __setitem__(self, key: str, value: Any) -> None:
+        self.additional_properties[key] = value
+
+    def __delitem__(self, key: str) -> None:
+        del self.additional_properties[key]
+
+    def __contains__(self, key: str) -> bool:
+        return key in self.additional_properties

render_sdk/workflows/callback_api/py.typed

@@ -1 +1 @@
-# Marker file for PEP 561
+# Marker file for PEP 561

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),
             },
@@ -134,13 +129,17 @@ class UDSClient:
         async with self.get_client() as client:
             return await post_callback.asyncio_detailed(client=client, body=data)
 
-    async def run_subtask(self, task_name: str, input_data: Any = None) -> Any:
+    async def run_subtask(
+        self, task_name: str, input_data: list[Any] | dict[str, Any] | None = None
+    ) -> Any:
         """
         Run a subtask and wait for its completion.
 
         Args:
             task_name: Name of the task to run
-            input_data: Input data to pass to the task
+            input_data: Input data to pass to the task. Can be either:
+                - A list for positional arguments: [arg1, arg2, arg3]
+                - A dict for named parameters: {"param1": value1, "param2": value2}
 
         Returns:
             The result of the subtask execution

render_sdk/workflows/executor.py

@@ -17,7 +17,9 @@ class TaskExecutor:
         self.task_registry = task_registry
         self.client = client
 
-    async def _execute_task(self, task_name: str, input_args: list[Any]) -> Any:
+    async def _execute_task(
+        self, task_name: str, input_data: list[Any] | dict[str, Any]
+    ) -> Any:
         """Execute a task by name with the given input."""
         func = self.task_registry.get_function(task_name)
         if not func:
@@ -28,11 +30,19 @@ class TaskExecutor:
             context = _current_client.set(self.client)
 
             try:
-                # Check if the function is async
-                if inspect.iscoroutinefunction(func):
-                    result = await func(*input_args)
+                # Determine how to call the function based on input type
+                if isinstance(input_data, dict):
+                    # Named parameters: pass as keyword arguments
+                    if inspect.iscoroutinefunction(func):
+                        result = await func(**input_data)
+                    else:
+                        result = func(**input_data)
                 else:
-                    result = func(*input_args)
+                    # Positional parameters: unpack list
+                    if inspect.iscoroutinefunction(func):
+                        result = await func(*input_data)
+                    else:
+                        result = func(*input_data)
 
                 return TaskResult(result=result)
             finally:
@@ -42,7 +52,9 @@ class TaskExecutor:
         except Exception as e:
             return TaskResult(error=e)
 
-    async def execute(self, task_name: str, input_args: list[Any]) -> Any:
+    async def execute(
+        self, task_name: str, input_data: list[Any] | dict[str, Any]
+    ) -> Any:
         """Execute a task by name with the given input."""
         logger.debug(f"Starting execution of task: {task_name}")
 
@@ -50,7 +62,7 @@ class TaskExecutor:
 
         try:
             # Execute the task
-            result = await self._execute_task(task_name, input_args)
+            result = await self._execute_task(task_name, input_data)
             if result.error:
                 # Send error callback and raise the error
                 await self._send_error_callback(task_name, result.error)