rappel 0.4.1__py3-none-win_amd64.whl

rappel/logger.py

@@ -0,0 +1,39 @@
+"""Simple logging helpers for configurable rappel loggers."""
+
+import logging
+import os
+from typing import Optional
+
+DEFAULT_LEVEL = logging.INFO
+ENV_VAR = "RAPPEL_LOG_LEVEL"
+
+
+def _resolve_level(value: Optional[str]) -> int:
+    if not value:
+        return DEFAULT_LEVEL
+    normalized = value.strip().upper()
+    mapping = {
+        "CRITICAL": logging.CRITICAL,
+        "FATAL": logging.FATAL,
+        "ERROR": logging.ERROR,
+        "WARNING": logging.WARNING,
+        "WARN": logging.WARNING,
+        "INFO": logging.INFO,
+        "DEBUG": logging.DEBUG,
+        "NOTSET": logging.NOTSET,
+    }
+    return mapping.get(normalized, DEFAULT_LEVEL)
+
+
+def configure(name: str) -> logging.Logger:
+    """Return a logger configured from RAPPEL_LOG_LEVEL."""
+
+    logger = logging.getLogger(name)
+    level = _resolve_level(os.environ.get(ENV_VAR))
+    logger.setLevel(level)
+    if not logger.handlers:
+        handler = logging.StreamHandler()
+        handler.setFormatter(logging.Formatter("[%(name)s] %(levelname)s: %(message)s"))
+        handler.setLevel(level)
+        logger.addHandler(handler)
+    return logger

rappel/registry.py

@@ -0,0 +1,75 @@
+from collections.abc import Awaitable, Callable
+from dataclasses import dataclass
+from threading import RLock
+from typing import Any, Optional
+
+AsyncAction = Callable[..., Awaitable[Any]]
+
+
+@dataclass
+class _ActionEntry:
+    module: str
+    name: str
+    func: AsyncAction
+
+
+def _make_key(module: str, name: str) -> str:
+    """Create a registry key from module and action name."""
+    return f"{module}:{name}"
+
+
+class ActionRegistry:
+    """In-memory registry of user-defined actions.
+
+    Actions are keyed by (module, name), allowing the same action name
+    to be used in different modules.
+    """
+
+    def __init__(self) -> None:
+        self._actions: dict[str, _ActionEntry] = {}
+        self._lock = RLock()
+
+    def register(self, module: str, name: str, func: AsyncAction) -> None:
+        """Register an action with its module and name.
+
+        Args:
+            module: The Python module containing the action.
+            name: The action name (from @action decorator).
+            func: The async function to execute.
+
+        Raises:
+            ValueError: If an action with the same module:name is already registered.
+        """
+        key = _make_key(module, name)
+        with self._lock:
+            if key in self._actions:
+                raise ValueError(f"action '{module}:{name}' already registered")
+            self._actions[key] = _ActionEntry(module=module, name=name, func=func)
+
+    def get(self, module: str, name: str) -> Optional[AsyncAction]:
+        """Look up an action by module and name.
+
+        Args:
+            module: The Python module containing the action.
+            name: The action name.
+
+        Returns:
+            The action function if found, None otherwise.
+        """
+        key = _make_key(module, name)
+        with self._lock:
+            entry = self._actions.get(key)
+            return entry.func if entry else None
+
+    def names(self) -> list[str]:
+        """Return all registered action keys (module:name format)."""
+        with self._lock:
+            return sorted(self._actions.keys())
+
+    def reset(self) -> None:
+        """Clear all registered actions."""
+        with self._lock:
+            self._actions.clear()
+
+
+registry = ActionRegistry()

rappel/schedule.py

@@ -0,0 +1,294 @@
+"""
+Scheduled workflow execution.
+
+This module provides functions for registering workflows to run on a cron
+schedule or at fixed intervals.
+"""
+
+from dataclasses import dataclass
+from datetime import datetime, timedelta
+from typing import Any, Dict, List, Literal, Optional, Type, Union
+
+from grpc import aio  # type: ignore[attr-defined]
+
+from proto import messages_pb2 as pb2
+
+from .bridge import _workflow_stub, ensure_singleton
+from .serialization import build_arguments_from_kwargs
+from .workflow import Workflow
+
+ScheduleType = Literal["cron", "interval"]
+ScheduleStatus = Literal["active", "paused"]
+
+
+@dataclass
+class ScheduleInfo:
+    """Information about a registered schedule."""
+
+    id: str
+    workflow_name: str
+    schedule_type: ScheduleType
+    cron_expression: Optional[str]
+    interval_seconds: Optional[int]
+    status: ScheduleStatus
+    next_run_at: Optional[datetime]
+    last_run_at: Optional[datetime]
+    last_instance_id: Optional[str]
+    created_at: datetime
+    updated_at: datetime
+
+
+async def schedule_workflow(
+    workflow_cls: Type[Workflow],
+    *,
+    schedule: Union[str, timedelta],
+    inputs: Optional[Dict[str, Any]] = None,
+) -> str:
+    """
+    Register a schedule for a workflow.
+
+    This function registers both the workflow DAG and the schedule in a single
+    call. When the schedule fires, the registered workflow version will be
+    executed.
+
+    Args:
+        workflow_cls: The Workflow class to schedule.
+        schedule: Either a cron expression string (e.g., "0 * * * *" for hourly)
+                  or a timedelta for interval-based scheduling.
+        inputs: Optional keyword arguments to pass to each scheduled run.
+
+    Returns:
+        The schedule ID.
+
+    Examples:
+        # Run every hour at minute 0
+        await schedule_workflow(MyWorkflow, schedule="0 * * * *")
+
+        # Run every 5 minutes
+        await schedule_workflow(MyWorkflow, schedule=timedelta(minutes=5))
+
+        # Run daily at midnight with inputs
+        await schedule_workflow(
+            MyWorkflow,
+            schedule="0 0 * * *",
+            inputs={"batch_size": 100}
+        )
+
+    Raises:
+        ValueError: If the cron expression is invalid or interval is non-positive.
+        RuntimeError: If the gRPC call fails.
+    """
+    workflow_name = workflow_cls.short_name()
+
+    # Build schedule definition
+    schedule_def = pb2.ScheduleDefinition()
+    if isinstance(schedule, str):
+        schedule_def.type = pb2.SCHEDULE_TYPE_CRON
+        schedule_def.cron_expression = schedule
+    elif isinstance(schedule, timedelta):
+        interval_seconds = int(schedule.total_seconds())
+        if interval_seconds <= 0:
+            raise ValueError("Interval must be positive")
+        schedule_def.type = pb2.SCHEDULE_TYPE_INTERVAL
+        schedule_def.interval_seconds = interval_seconds
+    else:
+        raise TypeError(f"schedule must be str or timedelta, got {type(schedule)}")
+
+    # Build the workflow registration payload to ensure the DAG is registered
+    # This is required for the schedule to execute - the scheduler needs a
+    # registered workflow version to create instances from.
+    registration = workflow_cls._build_registration_payload()
+
+    # Build request with both registration and schedule
+    request = pb2.RegisterScheduleRequest(
+        workflow_name=workflow_name,
+        schedule=schedule_def,
+        registration=registration,
+    )
+
+    # Add inputs if provided
+    if inputs:
+        request.inputs.CopyFrom(build_arguments_from_kwargs(inputs))
+
+    # Send to server
+    async with ensure_singleton():
+        stub = await _workflow_stub()
+
+    try:
+        response = await stub.RegisterSchedule(request, timeout=30.0)
+    except aio.AioRpcError as exc:
+        raise RuntimeError(f"Failed to register schedule: {exc}") from exc
+
+    return response.schedule_id
+
+
+async def pause_schedule(workflow_cls: Type[Workflow]) -> bool:
+    """
+    Pause a workflow's schedule.
+
+    The schedule will not fire until resumed. Existing running instances
+    are not affected.
+
+    Args:
+        workflow_cls: The Workflow class whose schedule to pause.
+
+    Returns:
+        True if a schedule was found and paused, False otherwise.
+    """
+    request = pb2.UpdateScheduleStatusRequest(
+        workflow_name=workflow_cls.short_name(),
+        status=pb2.SCHEDULE_STATUS_PAUSED,
+    )
+    async with ensure_singleton():
+        stub = await _workflow_stub()
+
+    try:
+        response = await stub.UpdateScheduleStatus(request, timeout=30.0)
+    except aio.AioRpcError as exc:
+        raise RuntimeError(f"Failed to pause schedule: {exc}") from exc
+
+    return response.success
+
+
+async def resume_schedule(workflow_cls: Type[Workflow]) -> bool:
+    """
+    Resume a paused workflow schedule.
+
+    Args:
+        workflow_cls: The Workflow class whose schedule to resume.
+
+    Returns:
+        True if a schedule was found and resumed, False otherwise.
+    """
+    request = pb2.UpdateScheduleStatusRequest(
+        workflow_name=workflow_cls.short_name(),
+        status=pb2.SCHEDULE_STATUS_ACTIVE,
+    )
+    async with ensure_singleton():
+        stub = await _workflow_stub()
+
+    try:
+        response = await stub.UpdateScheduleStatus(request, timeout=30.0)
+    except aio.AioRpcError as exc:
+        raise RuntimeError(f"Failed to resume schedule: {exc}") from exc
+
+    return response.success
+
+
+async def delete_schedule(workflow_cls: Type[Workflow]) -> bool:
+    """
+    Delete a workflow's schedule.
+
+    The schedule is soft-deleted and can be recreated by calling
+    schedule_workflow again.
+
+    Args:
+        workflow_cls: The Workflow class whose schedule to delete.
+
+    Returns:
+        True if a schedule was found and deleted, False otherwise.
+    """
+    request = pb2.DeleteScheduleRequest(
+        workflow_name=workflow_cls.short_name(),
+    )
+    async with ensure_singleton():
+        stub = await _workflow_stub()
+
+    try:
+        response = await stub.DeleteSchedule(request, timeout=30.0)
+    except aio.AioRpcError as exc:
+        raise RuntimeError(f"Failed to delete schedule: {exc}") from exc
+
+    return response.success
+
+
+def _parse_iso_datetime(value: str) -> Optional[datetime]:
+    """Parse an ISO 8601 datetime string, returning None if empty."""
+    if not value:
+        return None
+    return datetime.fromisoformat(value.replace("Z", "+00:00"))
+
+
+def _proto_schedule_type_to_str(
+    schedule_type: "pb2.ScheduleType.V",
+) -> ScheduleType:
+    """Convert protobuf ScheduleType to string literal."""
+    if schedule_type == pb2.SCHEDULE_TYPE_CRON:
+        return "cron"
+    elif schedule_type == pb2.SCHEDULE_TYPE_INTERVAL:
+        return "interval"
+    else:
+        return "cron"  # Default fallback
+
+
+def _proto_schedule_status_to_str(
+    status: "pb2.ScheduleStatus.V",
+) -> ScheduleStatus:
+    """Convert protobuf ScheduleStatus to string literal."""
+    if status == pb2.SCHEDULE_STATUS_ACTIVE:
+        return "active"
+    elif status == pb2.SCHEDULE_STATUS_PAUSED:
+        return "paused"
+    else:
+        return "active"  # Default fallback
+
+
+async def list_schedules(
+    status_filter: Optional[ScheduleStatus] = None,
+) -> List[ScheduleInfo]:
+    """
+    List all registered workflow schedules.
+
+    Args:
+        status_filter: Optional filter by status ("active" or "paused").
+                       If None, returns all non-deleted schedules.
+
+    Returns:
+        A list of ScheduleInfo objects containing schedule details.
+
+    Examples:
+        # List all schedules
+        schedules = await list_schedules()
+        for s in schedules:
+            print(f"{s.workflow_name}: {s.status}")
+
+        # List only active schedules
+        active = await list_schedules(status_filter="active")
+
+        # List only paused schedules
+        paused = await list_schedules(status_filter="paused")
+
+    Raises:
+        RuntimeError: If the gRPC call fails.
+    """
+    request = pb2.ListSchedulesRequest()
+    if status_filter is not None:
+        request.status_filter = status_filter
+
+    async with ensure_singleton():
+        stub = await _workflow_stub()
+
+    try:
+        response = await stub.ListSchedules(request, timeout=30.0)
+    except aio.AioRpcError as exc:
+        raise RuntimeError(f"Failed to list schedules: {exc}") from exc
+
+    schedules = []
+    for s in response.schedules:
+        schedules.append(
+            ScheduleInfo(
+                id=s.id,
+                workflow_name=s.workflow_name,
+                schedule_type=_proto_schedule_type_to_str(s.schedule_type),
+                cron_expression=s.cron_expression if s.cron_expression else None,
+                interval_seconds=s.interval_seconds if s.interval_seconds else None,
+                status=_proto_schedule_status_to_str(s.status),
+                next_run_at=_parse_iso_datetime(s.next_run_at),
+                last_run_at=_parse_iso_datetime(s.last_run_at),
+                last_instance_id=s.last_instance_id if s.last_instance_id else None,
+                created_at=_parse_iso_datetime(s.created_at),  # type: ignore
+                updated_at=_parse_iso_datetime(s.updated_at),  # type: ignore
+            )
+        )
+
+    return schedules

rappel/serialization.py

@@ -0,0 +1,205 @@
+import dataclasses
+import importlib
+import traceback
+from typing import Any
+
+from google.protobuf import json_format, struct_pb2
+from pydantic import BaseModel
+
+from proto import messages_pb2 as pb2
+
+NULL_VALUE = struct_pb2.NULL_VALUE  # type: ignore[attr-defined]
+
+PRIMITIVE_TYPES = (str, int, float, bool, type(None))
+
+
+def dumps(value: Any) -> pb2.WorkflowArgumentValue:
+    """Serialize a Python value into a WorkflowArgumentValue message."""
+
+    return _to_argument_value(value)
+
+
+def loads(data: Any) -> Any:
+    """Deserialize a workflow argument payload into a Python object."""
+
+    if isinstance(data, pb2.WorkflowArgumentValue):
+        argument = data
+    elif isinstance(data, dict):
+        argument = pb2.WorkflowArgumentValue()
+        json_format.ParseDict(data, argument)
+    else:
+        raise TypeError("argument value payload must be a dict or ArgumentValue message")
+    return _from_argument_value(argument)
+
+
+def build_arguments_from_kwargs(kwargs: dict[str, Any]) -> pb2.WorkflowArguments:
+    arguments = pb2.WorkflowArguments()
+    for key, value in kwargs.items():
+        entry = arguments.arguments.add()
+        entry.key = key
+        entry.value.CopyFrom(dumps(value))
+    return arguments
+
+
+def arguments_to_kwargs(arguments: pb2.WorkflowArguments | None) -> dict[str, Any]:
+    if arguments is None:
+        return {}
+    result: dict[str, Any] = {}
+    for entry in arguments.arguments:
+        result[entry.key] = loads(entry.value)
+    return result
+
+
+def _to_argument_value(value: Any) -> pb2.WorkflowArgumentValue:
+    argument = pb2.WorkflowArgumentValue()
+    if isinstance(value, PRIMITIVE_TYPES):
+        argument.primitive.CopyFrom(_serialize_primitive(value))
+        return argument
+    if isinstance(value, BaseException):
+        argument.exception.type = value.__class__.__name__
+        argument.exception.module = value.__class__.__module__
+        argument.exception.message = str(value)
+        tb_text = "".join(traceback.format_exception(type(value), value, value.__traceback__))
+        argument.exception.traceback = tb_text
+        return argument
+    if _is_base_model(value):
+        model_class = value.__class__
+        model_data = _serialize_model_data(value)
+        argument.basemodel.module = model_class.__module__
+        argument.basemodel.name = model_class.__qualname__
+        # Serialize as dict to preserve types (Struct converts all numbers to float)
+        for key, item in model_data.items():
+            entry = argument.basemodel.data.entries.add()
+            entry.key = key
+            entry.value.CopyFrom(_to_argument_value(item))
+        return argument
+    if _is_dataclass_instance(value):
+        # Dataclasses use the same basemodel serialization path as Pydantic models
+        dc_class = value.__class__
+        dc_data = dataclasses.asdict(value)
+        argument.basemodel.module = dc_class.__module__
+        argument.basemodel.name = dc_class.__qualname__
+        for key, item in dc_data.items():
+            entry = argument.basemodel.data.entries.add()
+            entry.key = key
+            entry.value.CopyFrom(_to_argument_value(item))
+        return argument
+    if isinstance(value, dict):
+        argument.dict_value.SetInParent()
+        for key, item in value.items():
+            if not isinstance(key, str):
+                raise TypeError("workflow dict keys must be strings")
+            entry = argument.dict_value.entries.add()
+            entry.key = key
+            entry.value.CopyFrom(_to_argument_value(item))
+        return argument
+    if isinstance(value, list):
+        argument.list_value.SetInParent()
+        for item in value:
+            item_value = argument.list_value.items.add()
+            item_value.CopyFrom(_to_argument_value(item))
+        return argument
+    if isinstance(value, tuple):
+        argument.tuple_value.SetInParent()
+        for item in value:
+            item_value = argument.tuple_value.items.add()
+            item_value.CopyFrom(_to_argument_value(item))
+        return argument
+    raise TypeError(f"unsupported value type {type(value)!r}")
+
+
+def _from_argument_value(argument: pb2.WorkflowArgumentValue) -> Any:
+    kind = argument.WhichOneof("kind")  # type: ignore[attr-defined]
+    if kind == "primitive":
+        return _primitive_to_python(argument.primitive)
+    if kind == "basemodel":
+        module = argument.basemodel.module
+        name = argument.basemodel.name
+        # Deserialize dict entries to preserve types
+        data: dict[str, Any] = {}
+        for entry in argument.basemodel.data.entries:
+            data[entry.key] = _from_argument_value(entry.value)
+        return _instantiate_serialized_model(module, name, data)
+    if kind == "exception":
+        return {
+            "type": argument.exception.type,
+            "module": argument.exception.module,
+            "message": argument.exception.message,
+            "traceback": argument.exception.traceback,
+        }
+    if kind == "list_value":
+        return [_from_argument_value(item) for item in argument.list_value.items]
+    if kind == "tuple_value":
+        return tuple(_from_argument_value(item) for item in argument.tuple_value.items)
+    if kind == "dict_value":
+        result: dict[str, Any] = {}
+        for entry in argument.dict_value.entries:
+            result[entry.key] = _from_argument_value(entry.value)
+        return result
+    raise ValueError("argument value missing kind discriminator")
+
+
+def _serialize_model_data(model: BaseModel) -> dict[str, Any]:
+    if hasattr(model, "model_dump"):
+        return model.model_dump(mode="python")  # type: ignore[attr-defined]
+    if hasattr(model, "dict"):
+        return model.dict()  # type: ignore[attr-defined]
+    return model.__dict__
+
+
+def _serialize_primitive(value: Any) -> pb2.PrimitiveWorkflowArgument:
+    primitive = pb2.PrimitiveWorkflowArgument()
+    if value is None:
+        primitive.null_value = NULL_VALUE
+    elif isinstance(value, bool):
+        primitive.bool_value = value
+    elif isinstance(value, int) and not isinstance(value, bool):
+        primitive.int_value = value
+    elif isinstance(value, float):
+        primitive.double_value = value
+    elif isinstance(value, str):
+        primitive.string_value = value
+    else:  # pragma: no cover - unreachable given PRIMITIVE_TYPES
+        raise TypeError(f"unsupported primitive type {type(value)!r}")
+    return primitive
+
+
+def _primitive_to_python(primitive: pb2.PrimitiveWorkflowArgument) -> Any:
+    kind = primitive.WhichOneof("kind")  # type: ignore[attr-defined]
+    if kind == "string_value":
+        return primitive.string_value
+    if kind == "double_value":
+        return primitive.double_value
+    if kind == "int_value":
+        return primitive.int_value
+    if kind == "bool_value":
+        return primitive.bool_value
+    if kind == "null_value":
+        return None
+    raise ValueError("primitive argument missing kind discriminator")
+
+
+def _instantiate_serialized_model(module: str, name: str, model_data: dict[str, Any]) -> Any:
+    cls = _import_symbol(module, name)
+    if hasattr(cls, "model_validate"):
+        return cls.model_validate(model_data)  # type: ignore[attr-defined]
+    return cls(**model_data)
+
+
+def _is_base_model(value: Any) -> bool:
+    return isinstance(value, BaseModel)
+
+
+def _is_dataclass_instance(value: Any) -> bool:
+    """Check if value is a dataclass instance (not a class)."""
+    return dataclasses.is_dataclass(value) and not isinstance(value, type)
+
+
+def _import_symbol(module: str, qualname: str) -> Any:
+    module_obj = importlib.import_module(module)
+    attr: Any = module_obj
+    for part in qualname.split("."):
+        attr = getattr(attr, part)
+    if not isinstance(attr, type):
+        raise ValueError(f"{qualname} from {module} is not a class")
+    return attr