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

fairchild/__init__.py

@@ -0,0 +1,11 @@
+from fairchild.task import task
+from fairchild.job import Job
+from fairchild.record import Record
+from fairchild.fairchild import Fairchild
+
+__all__ = [
+    "task",
+    "Job",
+    "Record",
+    "Fairchild",
+]

fairchild/cli.py

@@ -0,0 +1,386 @@
+import asyncio
+import importlib
+import click
+import os
+
+from fairchild.fairchild import Fairchild
+
+
+def import_module(module_path: str) -> None:
+    """Import a module by its dotted path."""
+    try:
+        importlib.import_module(module_path)
+    except ImportError as e:
+        raise click.ClickException(f"Failed to import '{module_path}': {e}")
+
+
+def get_database_url() -> str:
+    """Get database URL from environment."""
+    url = os.environ.get("FAIRCHILD_DATABASE_URL")
+    if not url:
+        raise click.ClickException(
+            "FAIRCHILD_DATABASE_URL environment variable is required"
+        )
+    return url
+
+
+@click.group()
+def cli():
+    """Fairchild - PostgreSQL-backed job queue and workflow engine."""
+    pass
+
+
+@cli.command()
+@click.option(
+    "--force",
+    is_flag=True,
+    help="Drop all tables and reinstall from scratch (DESTRUCTIVE)",
+)
+def install(force):
+    """Install Fairchild schema (runs all migrations on a fresh database)."""
+    asyncio.run(_install(force))
+
+
+async def _install(force: bool = False):
+    from fairchild.db.migrations import migrate, drop_all
+
+    url = get_database_url()
+    fairchild = Fairchild(url)
+    await fairchild.connect()
+
+    try:
+        # Check if table exists
+        row = await fairchild._pool.fetchrow("""
+            SELECT EXISTS (
+                SELECT FROM information_schema.tables
+                WHERE table_name = 'fairchild_jobs'
+            )
+        """)
+
+        if row["exists"]:
+            if not force:
+                click.echo(
+                    "Fairchild is already installed. Use 'migrate' to update schema, or --force to reinstall."
+                )
+                return
+
+            click.echo("Dropping all Fairchild tables...")
+            await drop_all(fairchild._pool)
+
+        await migrate(fairchild._pool)
+        click.echo("Fairchild installed successfully.")
+    finally:
+        await fairchild.disconnect()
+
+
+@cli.command()
+def migrate():
+    """Run database migrations."""
+    asyncio.run(_migrate())
+
+
+async def _migrate():
+    from fairchild.db.migrations import migrate
+
+    url = get_database_url()
+    fairchild = Fairchild(url)
+    await fairchild.connect()
+
+    try:
+        await migrate(fairchild._pool)
+        click.echo("Migrations complete.")
+    finally:
+        await fairchild.disconnect()
+
+
+@cli.command()
+@click.option(
+    "--queues",
+    "-q",
+    default="default:1",
+    help='Queue configuration, e.g., "default:2,processing:4"',
+)
+@click.option(
+    "--import",
+    "-i",
+    "imports",
+    multiple=True,
+    help='Module to import for task registration, e.g., "myapp.tasks"',
+)
+def worker(queues: str, imports: tuple[str, ...]):
+    """Start workers to process jobs.
+
+    Queue format: "queue_name:num_workers,queue_name:num_workers"
+
+    Examples:
+
+        fairchild worker --import myapp.tasks --queues "default:2"
+
+        fairchild worker -i myapp.tasks -i myapp.workflows -q "default:2,processing:4"
+    """
+    # Import task modules to register them
+    for module_path in imports:
+        import_module(module_path)
+        click.echo(f"Imported {module_path}")
+
+    queue_config = parse_queue_config(queues)
+    click.echo(f"Starting workers: {queue_config}")
+    asyncio.run(_run_workers(queue_config))
+
+
+def parse_queue_config(config: str) -> dict[str, int]:
+    """Parse queue configuration string into dict."""
+    result = {}
+    for part in config.split(","):
+        part = part.strip()
+        if ":" in part:
+            queue, count = part.rsplit(":", 1)
+            result[queue.strip()] = int(count)
+        else:
+            result[part] = 1
+    return result
+
+
+async def _run_workers(queue_config: dict[str, int]):
+    from fairchild.worker import WorkerPool
+
+    url = get_database_url()
+    fairchild = Fairchild(url)
+    await fairchild.connect()
+
+    pool = WorkerPool(fairchild, queue_config)
+
+    try:
+        await pool.run()
+    except KeyboardInterrupt:
+        click.echo("\nShutting down workers...")
+    finally:
+        await pool.shutdown()
+        await fairchild.disconnect()
+
+
+@cli.command()
+@click.option("--host", "-h", default="127.0.0.1", help="Host to bind to")
+@click.option("--port", "-p", default=4000, help="Port to bind to")
+@click.option(
+    "--import",
+    "-i",
+    "imports",
+    multiple=True,
+    help='Module to import for task registration, e.g., "myapp.tasks"',
+)
+def ui(host: str, port: int, imports: tuple[str, ...]):
+    """Start the web UI dashboard."""
+    # Import task modules
+    for module_path in imports:
+        import_module(module_path)
+
+    click.echo(f"Starting Fairchild UI at http://{host}:{port}")
+    asyncio.run(_run_ui(host, port))
+
+
+async def _run_ui(host: str, port: int):
+    from fairchild.ui import create_app
+    from aiohttp import web
+
+    url = get_database_url()
+    fairchild = Fairchild(url)
+    await fairchild.connect()
+
+    app = create_app(fairchild)
+
+    runner = web.AppRunner(app)
+    await runner.setup()
+    site = web.TCPSite(runner, host, port)
+
+    try:
+        await site.start()
+        # Keep running until interrupted
+        while True:
+            await asyncio.sleep(3600)
+    except KeyboardInterrupt:
+        pass
+    finally:
+        await runner.cleanup()
+        await fairchild.disconnect()
+
+
+@cli.command()
+@click.argument("task_name")
+@click.option(
+    "--import",
+    "-i",
+    "imports",
+    multiple=True,
+    help='Module to import for task registration, e.g., "myapp.tasks"',
+)
+@click.option(
+    "--arg",
+    "-a",
+    "args",
+    multiple=True,
+    help="Task argument as key=value, e.g., -a name=World -a count=5",
+)
+@click.option(
+    "--in",
+    "delay",
+    default=None,
+    help='Delay before running, e.g., "5m", "1h", "30s"',
+)
+def enqueue(
+    task_name: str, imports: tuple[str, ...], args: tuple[str, ...], delay: str | None
+):
+    """Enqueue a task for execution.
+
+    Examples:
+
+        fairchild enqueue -i myapp.tasks myapp.tasks.hello -a name=World
+
+        fairchild enqueue -i myapp.tasks myapp.tasks.process --in 5m -a id=123
+    """
+    # Import task modules to register them
+    for module_path in imports:
+        import_module(module_path)
+
+    # Parse arguments
+    parsed_args = {}
+    for arg in args:
+        if "=" not in arg:
+            raise click.ClickException(f"Invalid argument format: {arg}. Use key=value")
+        key, value = arg.split("=", 1)
+        # Try to parse as JSON for numbers, bools, etc.
+        try:
+            import json
+
+            parsed_args[key] = json.loads(value)
+        except json.JSONDecodeError:
+            parsed_args[key] = value
+
+    # Parse delay
+    delay_seconds = 0
+    if delay:
+        delay_seconds = parse_delay(delay)
+
+    asyncio.run(_enqueue(task_name, parsed_args, delay_seconds))
+
+
+def parse_delay(delay: str) -> int:
+    """Parse delay string like '5m', '1h', '30s' into seconds."""
+    import re
+
+    match = re.match(r"^(\d+)([smhd])$", delay.lower())
+    if not match:
+        raise click.ClickException(
+            f"Invalid delay format: {delay}. Use e.g., '5m', '1h', '30s'"
+        )
+
+    value = int(match.group(1))
+    unit = match.group(2)
+
+    multipliers = {"s": 1, "m": 60, "h": 3600, "d": 86400}
+    return value * multipliers[unit]
+
+
+async def _enqueue(task_name: str, args: dict, delay_seconds: int):
+    from datetime import datetime, timedelta, timezone
+    from fairchild.task import get_task
+
+    url = get_database_url()
+    fairchild = Fairchild(url)
+    await fairchild.connect()
+
+    try:
+        task = get_task(task_name)
+
+        if delay_seconds > 0:
+            job = await fairchild.enqueue(
+                task=task,
+                args=args,
+                scheduled_at=datetime.now(timezone.utc)
+                + timedelta(seconds=delay_seconds),
+            )
+            click.echo(f"Enqueued job {job.id} (scheduled in {delay_seconds}s)")
+        else:
+            job = await fairchild.enqueue(task=task, args=args)
+            click.echo(f"Enqueued job {job.id}")
+    finally:
+        await fairchild.disconnect()
+
+
+@cli.command()
+@click.argument("task_name")
+@click.option(
+    "--import",
+    "-i",
+    "imports",
+    multiple=True,
+    help='Module to import for task registration, e.g., "myapp.tasks"',
+)
+@click.option(
+    "--arg",
+    "-a",
+    "args",
+    multiple=True,
+    help="Task argument as key=value, e.g., -a name=World -a count=5",
+)
+def run(task_name: str, imports: tuple[str, ...], args: tuple[str, ...]):
+    """Run a task locally for testing (does not enqueue).
+
+    Runs the task function directly in the current process and prints the result.
+    Useful for testing tasks without involving the database or workers.
+
+    Examples:
+
+        fairchild run -i myapp.tasks myapp.tasks.hello -a name=World
+
+        fairchild run -i myapp.tasks myapp.tasks.add -a a=2 -a b=3
+    """
+    # Import task modules to register them
+    for module_path in imports:
+        import_module(module_path)
+
+    # Parse arguments
+    parsed_args = {}
+    for arg in args:
+        if "=" not in arg:
+            raise click.ClickException(f"Invalid argument format: {arg}. Use key=value")
+        key, value = arg.split("=", 1)
+        # Try to parse as JSON for numbers, bools, etc.
+        try:
+            import json
+
+            parsed_args[key] = json.loads(value)
+        except json.JSONDecodeError:
+            parsed_args[key] = value
+
+    asyncio.run(_invoke(task_name, parsed_args))
+
+
+async def _invoke(task_name: str, args: dict):
+    import inspect
+    import traceback
+    from fairchild.task import get_task
+
+    task = get_task(task_name)
+    click.echo(f"Invoking {task_name}...")
+
+    try:
+        # Call the underlying function directly (bypasses worker context check)
+        result = task.fn(**args)
+
+        # Handle async functions
+        if inspect.isawaitable(result):
+            result = await result
+
+        click.echo(f"Result: {result}")
+    except Exception as e:
+        click.echo(traceback.format_exc(), err=True)
+        raise click.ClickException(f"Task failed: {e}")
+
+
+def main():
+    cli()
+
+
+if __name__ == "__main__":
+    main()

fairchild/context.py

@@ -0,0 +1,54 @@
+"""Execution context for tracking the currently running job.
+
+This module provides a way to track which job is currently being executed
+by a worker. When a task calls another task, we check this context to
+determine whether to spawn a child job (if inside a worker) or execute
+directly (if called from outside).
+"""
+
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from fairchild.job import Job
+    from fairchild.fairchild import Fairchild
+
+# The currently executing job (set by worker during task execution)
+_current_job: "Job | None" = None
+_current_fairchild: "Fairchild | None" = None
+_pending_children: list["Job"] = []
+
+
+def set_current_job(job: "Job | None", fairchild: "Fairchild | None" = None) -> None:
+    """Set the currently executing job. Called by worker."""
+    global _current_job, _current_fairchild, _pending_children
+    _current_job = job
+    _current_fairchild = fairchild
+    _pending_children = []  # Reset pending children for new job
+
+
+def get_current_job() -> "Job | None":
+    """Get the currently executing job, or None if not in a worker."""
+    return _current_job
+
+
+def get_current_fairchild() -> "Fairchild | None":
+    """Get the Fairchild instance for the current context."""
+    return _current_fairchild
+
+
+def is_inside_task() -> bool:
+    """Check if code is currently running inside a task (in a worker)."""
+    return _current_job is not None
+
+
+def add_pending_child(job: "Job") -> None:
+    """Add a child job to be inserted after the current task completes."""
+    _pending_children.append(job)
+
+
+def get_pending_children() -> list["Job"]:
+    """Get all pending child jobs and clear the list."""
+    global _pending_children
+    children = _pending_children
+    _pending_children = []
+    return children

fairchild/db/migrations.py

@@ -0,0 +1,69 @@
+"""Database migration system for Fairchild.
+
+Migrations are stored as numbered SQL files in the migrations/ directory:
+- 001_initial.sql
+- 002_add_parent_id.sql
+- etc.
+
+Each migration runs exactly once, tracked in the fairchild_migrations table.
+"""
+
+from pathlib import Path
+
+MIGRATIONS_DIR = Path(__file__).parent / "migrations"
+
+
+async def migrate(pool) -> None:
+    """Run all pending database migrations in order.
+
+    Usage:
+        fairchild = Fairchild("postgresql://localhost/myapp")
+        await fairchild.connect()
+        await migrate(fairchild._pool)
+    """
+    async with pool.acquire() as conn:
+        # Ensure migrations tracking table exists
+        await conn.execute("""
+            CREATE TABLE IF NOT EXISTS fairchild_migrations (
+                id SERIAL PRIMARY KEY,
+                name VARCHAR(255) NOT NULL UNIQUE,
+                applied_at TIMESTAMPTZ NOT NULL DEFAULT now()
+            )
+        """)
+
+        # Get list of already applied migrations
+        applied = set()
+        rows = await conn.fetch("SELECT name FROM fairchild_migrations")
+        for row in rows:
+            applied.add(row["name"])
+
+        # Find and run pending migrations in order
+        migration_files = sorted(MIGRATIONS_DIR.glob("*.sql"))
+
+        for migration_file in migration_files:
+            name = migration_file.name
+
+            if name in applied:
+                continue
+
+            print(f"Running migration: {name}")
+            sql = migration_file.read_text()
+
+            async with conn.transaction():
+                await conn.execute(sql)
+                await conn.execute(
+                    "INSERT INTO fairchild_migrations (name) VALUES ($1)",
+                    name,
+                )
+
+            print(f"  Applied: {name}")
+
+    print("Migrations complete.")
+
+
+async def drop_all(pool) -> None:
+    """Drop all Fairchild tables. Use with caution!"""
+    async with pool.acquire() as conn:
+        await conn.execute("DROP TABLE IF EXISTS fairchild_workers CASCADE")
+        await conn.execute("DROP TABLE IF EXISTS fairchild_jobs CASCADE")
+        await conn.execute("DROP TABLE IF EXISTS fairchild_migrations CASCADE")

fairchild/fairchild.py

@@ -0,0 +1,166 @@
+from datetime import datetime, timezone
+from typing import Any, TYPE_CHECKING
+from uuid import UUID
+import json
+
+
+def utcnow() -> datetime:
+    """Return current UTC time as timezone-aware datetime."""
+    return datetime.now(timezone.utc)
+
+
+if TYPE_CHECKING:
+    from fairchild.job import Job
+    from fairchild.task import Task
+
+# Global Fairchild instance
+_instance: "Fairchild | None" = None
+
+
+def get_fairchild() -> "Fairchild":
+    """Get the global Fairchild instance."""
+    if _instance is None:
+        raise RuntimeError(
+            "Fairchild not initialized. Call Fairchild(database_url) first."
+        )
+    return _instance
+
+
+class Fairchild:
+    """Main entry point for Fairchild job queue.
+
+    Usage:
+        fairchild = Fairchild("postgresql://localhost/myapp")
+
+        # Enqueue jobs
+        my_task.enqueue(item_id=42)
+
+        # Or use directly
+        fairchild.enqueue(my_task, args={"item_id": 42})
+    """
+
+    def __init__(self, database_url: str):
+        global _instance
+
+        self.database_url = database_url
+        self._pool = None
+
+        # Set as global instance
+        _instance = self
+
+    async def connect(self) -> None:
+        """Initialize the database connection pool."""
+        import asyncpg
+
+        self._pool = await asyncpg.create_pool(self.database_url)
+
+    async def disconnect(self) -> None:
+        """Close the database connection pool."""
+        if self._pool:
+            await self._pool.close()
+            self._pool = None
+
+    async def _ensure_connected(self) -> None:
+        """Ensure we have a database connection."""
+        if self._pool is None:
+            await self.connect()
+
+    async def enqueue(
+        self,
+        task: "Task",
+        args: dict[str, Any],
+        scheduled_at: datetime | None = None,
+        priority: int | None = None,
+    ) -> "Job":
+        """Enqueue a job for execution.
+
+        Returns the created Job.
+        """
+        from fairchild.job import Job, JobState
+
+        await self._ensure_connected()
+
+        job = Job(
+            task_name=task.name,
+            queue=task.queue,
+            args=args,
+            priority=priority if priority is not None else task.priority,
+            max_attempts=task.max_attempts,
+            tags=task.tags,
+            scheduled_at=scheduled_at or utcnow(),
+            state=JobState.AVAILABLE if scheduled_at is None else JobState.SCHEDULED,
+        )
+
+        await self._insert_job(job)
+        return job
+
+    async def _insert_job(self, job: "Job") -> None:
+        """Insert a job into the database."""
+        query = """
+            INSERT INTO fairchild_jobs (
+                id, task_name, queue, args,
+                parent_id, deps,
+                state, priority, scheduled_at,
+                attempt, max_attempts, tags, meta,
+                inserted_at, updated_at
+            ) VALUES (
+                $1, $2, $3, $4,
+                $5, $6,
+                $7, $8, $9,
+                $10, $11, $12, $13,
+                $14, $15
+            )
+        """
+
+        await self._pool.execute(
+            query,
+            job.id,
+            job.task_name,
+            job.queue,
+            json.dumps(job.args),
+            job.parent_id,
+            job.deps,
+            job.state.value,
+            job.priority,
+            job.scheduled_at,
+            job.attempt,
+            job.max_attempts,
+            job.tags,
+            json.dumps(job.meta),
+            job.inserted_at,
+            job.updated_at,
+        )
+
+    async def get_job(self, job_id: UUID) -> "Job | None":
+        """Get a job by ID."""
+        from fairchild.job import Job
+
+        await self._ensure_connected()
+
+        query = """
+            SELECT * FROM fairchild_jobs WHERE id = $1
+        """
+        row = await self._pool.fetchrow(query, job_id)
+        if row is None:
+            return None
+
+        return Job.from_row(dict(row))
+
+    async def get_recorded(self, job_id: UUID) -> Any:
+        """Get the recorded value from a completed job."""
+        await self._ensure_connected()
+
+        query = """
+            SELECT recorded FROM fairchild_jobs
+            WHERE id = $1
+        """
+
+        row = await self._pool.fetchrow(query, job_id)
+        if row is None:
+            return None
+
+        recorded = row["recorded"]
+        if recorded is None:
+            return None
+
+        return json.loads(recorded) if isinstance(recorded, str) else recorded