fairchild 0.0.1__py3-none-any.whl → 0.0.3__py3-none-any.whl

fairchild/future.py

@@ -0,0 +1,78 @@
+"""Future represents a pending task result."""
+
+from uuid import UUID
+from typing import Any, TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from fairchild.job import Job
+
+
+class Future:
+    """Represents the pending result of a spawned task.
+
+    When a task calls another task from within a worker, it gets back
+    a Future instead of the actual result. The Future:
+
+    1. Tracks the child job that was spawned
+    2. Can be passed to other tasks to establish dependencies
+    3. Resolves to the actual result when the child job completes
+
+    Usage:
+        @task
+        def parent_task():
+            # This returns a Future, not the actual result
+            result = child_task(arg1, arg2)
+
+            # Pass the future to another task - creates a dependency
+            another_task(result)
+    """
+
+    def __init__(self, job_id: UUID, job_key: str | None = None):
+        self.job_id = job_id
+        self.job_key = job_key
+        self._result: Any = None
+        self._resolved = False
+
+    def __repr__(self) -> str:
+        if self._resolved:
+            return f"Future({self.job_key or self.job_id}, resolved={self._result!r})"
+        return f"Future({self.job_key or self.job_id}, pending)"
+
+    def resolve(self, result: Any) -> None:
+        """Set the resolved value of this future."""
+        self._result = result
+        self._resolved = True
+
+    @property
+    def result(self) -> Any:
+        """Get the resolved result. Raises if not yet resolved."""
+        if not self._resolved:
+            raise RuntimeError(f"Future {self.job_id} has not been resolved yet")
+        return self._result
+
+    @property
+    def is_resolved(self) -> bool:
+        return self._resolved
+
+
+def is_future(obj: Any) -> bool:
+    """Check if an object is a Future."""
+    return isinstance(obj, Future)
+
+
+def extract_futures(args: dict) -> list[Future]:
+    """Extract all Future objects from a dict of arguments (including nested)."""
+    futures = []
+
+    def _extract(obj: Any) -> None:
+        if isinstance(obj, Future):
+            futures.append(obj)
+        elif isinstance(obj, dict):
+            for v in obj.values():
+                _extract(v)
+        elif isinstance(obj, (list, tuple)):
+            for item in obj:
+                _extract(item)
+
+    _extract(args)
+    return futures

fairchild/job.py

@@ -0,0 +1,123 @@
+from dataclasses import dataclass, field
+from datetime import datetime, timezone
+from enum import Enum
+from typing import Any
+from uuid import UUID, uuid4
+import json
+
+
+def _utcnow() -> datetime:
+    return datetime.now(timezone.utc)
+
+
+def _parse_json(value: Any) -> Any:
+    """Parse JSON string if needed, otherwise return as-is."""
+    if isinstance(value, str):
+        return json.loads(value)
+    return value
+
+
+class JobState(str, Enum):
+    AVAILABLE = "available"
+    SCHEDULED = "scheduled"
+    RUNNING = "running"
+    COMPLETED = "completed"
+    FAILED = "failed"
+    CANCELLED = "cancelled"
+    DISCARDED = "discarded"
+
+
+@dataclass
+class Job:
+    """Represents a job in the queue."""
+
+    # Task identification
+    task_name: str
+    queue: str = "default"
+    args: dict[str, Any] = field(default_factory=dict)
+
+    # Identity
+    id: UUID = field(default_factory=uuid4)
+
+    # Parent-child relationship (for spawned tasks)
+    parent_id: UUID | None = None
+    deps: list[str] = field(default_factory=list)  # Job IDs this job depends on
+
+    # State
+    state: JobState = JobState.AVAILABLE
+
+    # Scheduling & priority
+    priority: int = 5  # 0-9, lower = higher priority
+    scheduled_at: datetime = field(default_factory=_utcnow)
+
+    # Execution tracking
+    attempted_at: datetime | None = None
+    completed_at: datetime | None = None
+    attempt: int = 0
+    max_attempts: int = 3
+
+    # Results & errors
+    recorded: Any | None = None
+    errors: list[dict[str, Any]] = field(default_factory=list)
+
+    # Metadata
+    tags: list[str] = field(default_factory=list)
+    meta: dict[str, Any] = field(default_factory=dict)
+
+    # Timestamps
+    inserted_at: datetime = field(default_factory=_utcnow)
+    updated_at: datetime = field(default_factory=_utcnow)
+
+    def __post_init__(self):
+        # Ensure state is JobState enum
+        if isinstance(self.state, str):
+            self.state = JobState(self.state)
+
+    @classmethod
+    def from_row(cls, row: dict[str, Any]) -> "Job":
+        """Create a Job instance from a database row."""
+        return cls(
+            id=row["id"],
+            task_name=row["task_name"],
+            queue=row["queue"],
+            args=_parse_json(row["args"]) or {},
+            parent_id=row.get("parent_id"),
+            deps=row.get("deps") or [],
+            state=JobState(row["state"]),
+            priority=row["priority"],
+            scheduled_at=row["scheduled_at"],
+            attempted_at=row["attempted_at"],
+            completed_at=row["completed_at"],
+            attempt=row["attempt"],
+            max_attempts=row["max_attempts"],
+            recorded=_parse_json(row["recorded"]),
+            errors=_parse_json(row["errors"]) or [],
+            tags=row.get("tags") or [],
+            meta=_parse_json(row.get("meta")) or {},
+            inserted_at=row["inserted_at"],
+            updated_at=row["updated_at"],
+        )
+
+    def to_dict(self) -> dict[str, Any]:
+        """Convert to dictionary for database insertion."""
+        return {
+            "id": self.id,
+            "task_name": self.task_name,
+            "queue": self.queue,
+            "args": self.args,
+            "parent_id": self.parent_id,
+            "deps": self.deps,
+            "state": self.state.value,
+            "priority": self.priority,
+            "scheduled_at": self.scheduled_at,
+            "attempted_at": self.attempted_at,
+            "completed_at": self.completed_at,
+            "attempt": self.attempt,
+            "max_attempts": self.max_attempts,
+            "recorded": self.recorded,
+            "errors": self.errors,
+            "tags": self.tags,
+            "meta": self.meta,
+            "inserted_at": self.inserted_at,
+            "updated_at": self.updated_at,
+        }

fairchild/record.py

@@ -0,0 +1,22 @@
+from dataclasses import dataclass
+from typing import Any
+
+
+@dataclass(frozen=True)
+class Record:
+    """Wrapper to indicate a task's return value should be persisted.
+
+    Usage:
+        @task(queue="default")
+        def my_task(item_id: int):
+            result = process(item_id)
+            return Record({"item_id": item_id, "result": result})
+
+    The recorded value will be stored in the job's `recorded` column
+    and can be retrieved by downstream jobs in a workflow.
+    """
+
+    value: Any
+
+    def __repr__(self) -> str:
+        return f"Record({self.value!r})"

fairchild/task.py

@@ -0,0 +1,225 @@
+from datetime import datetime, timedelta, timezone
+from functools import wraps
+from typing import Any, Callable
+from uuid import uuid4
+import inspect
+
+# Global task registry
+_task_registry: dict[str, "Task"] = {}
+
+
+def get_task(name: str) -> "Task":
+    """Get a registered task by name."""
+    if name not in _task_registry:
+        raise ValueError(f"Unknown task: {name}")
+    return _task_registry[name]
+
+
+def task(
+    queue: str = "default",
+    max_attempts: int = 3,
+    priority: int = 5,
+    unique: bool = False,
+    unique_period: timedelta | None = None,
+    tags: list[str] | None = None,
+) -> Callable[[Callable], "Task"]:
+    """Decorator to define a task.
+
+    Usage:
+        @task(queue="default")
+        def my_task(item_id: int):
+            return Record({"result": item_id * 2})
+
+        # Enqueue
+        my_task.enqueue(item_id=42)
+
+        # Schedule for later
+        my_task.enqueue_in(minutes=30, item_id=42)
+
+    Args:
+        queue: Queue name for this task
+        max_attempts: Maximum retry attempts
+        priority: 0-9, lower = higher priority
+        unique: If True, prevent duplicate jobs with same args
+        unique_period: Time window for uniqueness check
+        tags: Tags for categorizing/filtering jobs
+    """
+
+    def decorator(fn: Callable) -> "Task":
+        task_obj = Task(
+            fn=fn,
+            queue=queue,
+            max_attempts=max_attempts,
+            priority=priority,
+            unique=unique,
+            unique_period=unique_period,
+            tags=tags or [],
+        )
+        _task_registry[task_obj.name] = task_obj
+        return task_obj
+
+    return decorator
+
+
+class Task:
+    """A registered task that can be enqueued."""
+
+    def __init__(
+        self,
+        fn: Callable,
+        queue: str,
+        max_attempts: int,
+        priority: int,
+        unique: bool,
+        unique_period: timedelta | None,
+        tags: list[str],
+    ):
+        self.fn = fn
+        self.queue = queue
+        self.max_attempts = max_attempts
+        self.priority = priority
+        self.unique = unique
+        self.unique_period = unique_period
+        self.tags = tags
+
+        # Derive task name from module and function name
+        self.name = f"{fn.__module__}.{fn.__qualname__}"
+
+        # Check if function accepts a 'job' parameter
+        sig = inspect.signature(fn)
+        self._accepts_job = "job" in sig.parameters
+
+        # Preserve function metadata
+        wraps(fn)(self)
+
+    def __call__(self, *args: Any, **kwargs: Any) -> Any:
+        """Call the task - either spawn as child job or execute directly.
+
+        If called from inside a running task (in a worker), this spawns
+        a child job and returns a Future. Otherwise, it executes the
+        function directly.
+        """
+        from fairchild.context import (
+            is_inside_task,
+            get_current_job,
+            add_pending_child,
+        )
+        from fairchild.future import Future, extract_futures
+        from fairchild.job import Job, JobState
+
+        # If we're inside a worker executing a task, spawn a child job
+        if is_inside_task():
+            parent_job = get_current_job()
+
+            # Convert positional args to kwargs using function signature
+            if args:
+                sig = inspect.signature(self.fn)
+                param_names = [
+                    p for p in sig.parameters.keys() if p not in ("job", "workflow")
+                ]
+                for i, arg in enumerate(args):
+                    if i < len(param_names):
+                        kwargs[param_names[i]] = arg
+
+            # Extract any futures from the args - these become dependencies
+            futures_in_args = extract_futures(kwargs)
+            deps = [str(f.job_id) for f in futures_in_args]
+
+            # Determine initial state based on dependencies
+            has_deps = len(deps) > 0
+            state = JobState.SCHEDULED if has_deps else JobState.AVAILABLE
+
+            # Create the child job
+            job_id = uuid4()
+            child_job = Job(
+                id=job_id,
+                task_name=self.name,
+                queue=self.queue,
+                args=self._serialize_args(kwargs),
+                priority=self.priority,
+                max_attempts=self.max_attempts,
+                tags=self.tags,
+                parent_id=parent_job.id,
+                deps=deps,
+                state=state,
+            )
+
+            # Queue the child job to be inserted after task completes
+            add_pending_child(child_job)
+
+            # Return a future representing this job's result
+            return Future(job_id=job_id)
+
+        # Not inside a task - execute directly
+        from fairchild.record import Record
+
+        result = self.fn(*args, **kwargs)
+        # Unwrap Record so local runs behave like resolved futures
+        if isinstance(result, Record):
+            return result.value
+        return result
+
+    def _serialize_args(self, kwargs: dict[str, Any]) -> dict[str, Any]:
+        """Serialize arguments, converting Futures to their job IDs."""
+        from fairchild.future import Future
+
+        def _convert(obj: Any) -> Any:
+            if isinstance(obj, Future):
+                # Store as a reference that can be resolved later
+                return {"__future__": str(obj.job_id)}
+            elif isinstance(obj, dict):
+                return {k: _convert(v) for k, v in obj.items()}
+            elif isinstance(obj, list):
+                return [_convert(item) for item in obj]
+            elif isinstance(obj, tuple):
+                return [_convert(item) for item in obj]
+            return obj
+
+        return _convert(kwargs)
+
+    def _get_fairchild(self) -> Any:
+        """Get the Fairchild instance."""
+        from fairchild.fairchild import get_fairchild
+
+        return get_fairchild()
+
+    def enqueue(self, **kwargs: Any) -> Any:
+        """Enqueue this task for immediate execution.
+
+        Returns the created Job.
+        """
+        return self._get_fairchild().enqueue(
+            task=self,
+            args=kwargs,
+        )
+
+    def enqueue_at(self, at: datetime, **kwargs: Any) -> Any:
+        """Enqueue this task to run at a specific time.
+
+        Returns the created Job.
+        """
+        return self._get_fairchild().enqueue(
+            task=self,
+            args=kwargs,
+            scheduled_at=at,
+        )
+
+    def enqueue_in(
+        self,
+        *,
+        seconds: int = 0,
+        minutes: int = 0,
+        hours: int = 0,
+        days: int = 0,
+        **kwargs: Any,
+    ) -> Any:
+        """Enqueue this task to run after a delay.
+
+        Returns the created Job.
+        """
+        delay = timedelta(seconds=seconds, minutes=minutes, hours=hours, days=days)
+        scheduled_at = datetime.utcnow() + delay
+        return self.enqueue_at(at=scheduled_at, **kwargs)
+
+    def __repr__(self) -> str:
+        return f"Task({self.name!r}, queue={self.queue!r})"