whenly 0.1.0__py3-none-any.whl

whenly/__init__.py

@@ -0,0 +1,6 @@
+"""whenly — Lightweight persistent job scheduler."""
+
+from .scheduler import Scheduler
+
+__all__ = ["Scheduler"]
+__version__ = "0.1.0"

whenly/cli.py

@@ -0,0 +1,95 @@
+"""CLI for whenly."""
+
+from __future__ import annotations
+
+import argparse
+import sys
+from datetime import datetime, timezone
+
+from .models import JobStatus
+from .store import Store
+
+
+def main(argv: list[str] | None = None) -> None:
+    parser = argparse.ArgumentParser(prog="whenly", description="Lightweight job scheduler")
+    parser.add_argument("--db", default="whenly.db", help="Database path")
+    sub = parser.add_subparsers(dest="command")
+
+    sub.add_parser("list", help="List all jobs and next run time")
+    sub.add_parser("history", help="Show job run history").add_argument("name")
+
+    run_parser = sub.add_parser("run", help="Manually trigger a job")
+    run_parser.add_argument("name")
+
+    args = parser.parse_args(argv)
+    if not args.command:
+        parser.print_help()
+        sys.exit(1)
+
+    store = Store(args.db)
+
+    if args.command == "list":
+        jobs = store.list_jobs()
+        if not jobs:
+            print("No jobs registered.")
+            return
+        for j in jobs:
+            next_run = j.next_run_at.strftime("%Y-%m-%d %H:%M:%S") if j.next_run_at else "—"
+            status = "✓" if j.enabled else "✗"
+            sched = _fmt_schedule(j)
+            print(f"  {status} {j.name:<30} [{sched:<12}] next: {next_run}")
+
+    elif args.command == "history":
+        runs = store.get_runs(args.name, limit=20)
+        if not runs:
+            print(f"No runs found for '{args.name}'.")
+            return
+        for r in runs:
+            ts = r.started_at.strftime("%Y-%m-%d %H:%M:%S") if r.started_at else "?"
+            dur = f"{r.duration_seconds:.1f}s" if r.duration_seconds else "?"
+            status_icon = {
+                JobStatus.SUCCESS: "✓",
+                JobStatus.FAILED: "✗",
+                JobStatus.TIMEOUT: "⏱",
+                JobStatus.RUNNING: "⟳",
+            }.get(r.status, "?")
+            err = f" — {r.error_message.splitlines()[-1][:60]}" if r.error_message else ""
+            print(f"  {status_icon} {ts}  {dur:>8}  {r.status.value:<8}{err}")
+
+    elif args.command == "run":
+        # For run, we need to try to import and execute the function
+        job = store.get_job(args.name)
+        if not job:
+            print(f"Job '{args.name}' not found.")
+            sys.exit(1)
+        try:
+            parts = job.func_path.rsplit(".", 1)
+            if len(parts) == 2:
+                import importlib
+                mod = importlib.import_module(parts[0])
+                func = getattr(mod, parts[1])
+                print(f"Running {args.name}...")
+                func()
+                print("Done.")
+            else:
+                print(f"Cannot resolve function: {job.func_path}")
+                sys.exit(1)
+        except Exception as e:
+            print(f"Error: {e}")
+            sys.exit(1)
+
+    store.close()
+
+
+def _fmt_schedule(job) -> str:
+    if job.schedule_type.value == "interval":
+        return f"every {job.interval_seconds}s"
+    elif job.schedule_type.value == "cron":
+        return job.cron_expr or "?"
+    elif job.schedule_type.value == "once":
+        return f"once at {job.scheduled_for or '?'}"
+    return job.schedule_type.value
+
+
+if __name__ == "__main__":
+    main()

whenly/models.py

@@ -0,0 +1,70 @@
+"""Data models for whenly."""
+
+from __future__ import annotations
+
+import uuid
+from dataclasses import dataclass, field
+from datetime import datetime
+from enum import Enum
+from typing import Any
+
+
+def _utcnow() -> datetime:
+    return datetime.utcnow()
+
+
+def _uuid() -> str:
+    return uuid.uuid4().hex
+
+
+class ScheduleType(str, Enum):
+    INTERVAL = "interval"
+    CRON = "cron"
+    ONCE = "once"
+
+
+class MissedPolicy(str, Enum):
+    RUN_ONCE = "run_once"
+    RUN_ALL = "run_all"
+    SKIP = "skip"
+
+
+class JobStatus(str, Enum):
+    SUCCESS = "success"
+    FAILED = "failed"
+    TIMEOUT = "timeout"
+    RUNNING = "running"
+    PENDING = "pending"
+
+
+@dataclass
+class Job:
+    name: str
+    func_path: str
+    schedule_type: ScheduleType
+    interval_seconds: int | float | None = None
+    cron_expr: str | None = None
+    scheduled_for: datetime | None = None
+    missed_policy: MissedPolicy = MissedPolicy.RUN_ONCE
+    max_concurrent: int = 1
+    timeout_seconds: int | None = None
+    enabled: bool = True
+    id: str = field(default_factory=_uuid)
+    next_run_at: datetime | None = None
+    last_run_at: datetime | None = None
+    created_at: datetime = field(default_factory=_utcnow)
+    updated_at: datetime = field(default_factory=_utcnow)
+    # Runtime only — not persisted
+    func: Any = field(default=None, repr=False, compare=False)
+
+
+@dataclass
+class JobRun:
+    job_id: str
+    status: JobStatus = JobStatus.PENDING
+    started_at: datetime | None = None
+    finished_at: datetime | None = None
+    duration_seconds: float | None = None
+    error_message: str | None = None
+    scheduled_for: datetime | None = None
+    id: str = field(default_factory=_uuid)

whenly/runner.py

@@ -0,0 +1,113 @@
+"""Job execution engine."""
+
+from __future__ import annotations
+
+import logging
+import threading
+import traceback
+from concurrent.futures import Future, ThreadPoolExecutor
+from datetime import datetime
+from typing import Any, Callable
+
+from .models import Job, JobRun, JobStatus
+from .store import Store
+
+logger = logging.getLogger(__name__)
+
+
+class JobRunner:
+    """Executes jobs in a thread pool."""
+
+    def __init__(self, store: Store, max_workers: int = 10) -> None:
+        self._store = store
+        self._max_workers = max_workers
+        self._executor: ThreadPoolExecutor | None = None
+        self._futures: dict[str, Future[None]] = {}
+        self._lock = threading.Lock()
+
+    def _ensure_executor(self) -> ThreadPoolExecutor:
+        if self._executor is None:
+            self._executor = ThreadPoolExecutor(max_workers=self._max_workers)
+        return self._executor
+
+    def submit(self, job: Job, scheduled_for: datetime | None = None) -> bool:
+        """Submit a job for execution. Returns True if submitted."""
+        if not job.enabled:
+            return False
+        running = self._store.get_running_count(job.id)
+        if running >= job.max_concurrent:
+            logger.debug("Job %s at max concurrent (%d), skipping", job.name, job.max_concurrent)
+            return False
+
+        run = JobRun(
+            job_id=job.id,
+            status=JobStatus.RUNNING,
+            started_at=datetime.utcnow(),
+            scheduled_for=scheduled_for,
+        )
+        self._store.save_run(run)
+
+        executor = self._ensure_executor()
+        with self._lock:
+            self._futures[run.id] = executor.submit(self._execute, job, run)
+        return True
+
+    def _execute(self, job: Job, run: JobRun) -> None:
+        func: Callable[..., Any] = job.func
+        if func is None:
+            func = _resolve_func(job.func_path)
+            if func is None:
+                run.status = JobStatus.FAILED
+                run.error_message = f"Cannot resolve function: {job.func_path}"
+                self._store.update_run(run)
+                with self._lock:
+                    self._futures.pop(run.id, None)
+                return
+
+        try:
+            args = getattr(job, '_args', ()) or ()
+            kwargs = getattr(job, '_kwargs', {}) or {}
+            result = func(*args, **kwargs)
+            # Check if result is a future we should wait on
+            if isinstance(result, Future):
+                result.result(timeout=job.timeout_seconds)
+        except Exception as exc:
+            if isinstance(exc, TimeoutError):
+                run.status = JobStatus.TIMEOUT
+            else:
+                run.status = JobStatus.FAILED
+            run.error_message = traceback.format_exc()
+            logger.error("Job %s failed: %s", job.name, exc)
+        finally:
+            run.finished_at = datetime.utcnow()
+            run.duration_seconds = (run.finished_at - (run.started_at or run.finished_at)).total_seconds()
+            if run.status == JobStatus.RUNNING:
+                run.status = JobStatus.SUCCESS
+            self._store.update_run(run)
+            self._store.update_last_run(job.id, run.finished_at)
+
+        with self._lock:
+            self._futures.pop(run.id, None)
+
+    def shutdown(self, wait: bool = True) -> None:
+        with self._lock:
+            executor = self._executor
+            self._executor = None
+        if executor is not None:
+            executor.shutdown(wait=wait)
+        with self._lock:
+            self._futures.clear()
+
+
+def _resolve_func(func_path: str) -> Callable[..., Any] | None:
+    """Import a function from its dotted path (e.g. 'mymodule.jobs.sync_data')."""
+    try:
+        parts = func_path.rsplit(".", 1)
+        if len(parts) == 2:
+            mod_path, func_name = parts
+            import importlib
+            mod = importlib.import_module(mod_path)
+            return getattr(mod, func_name, None)
+    except Exception:
+        logger.debug("Cannot resolve %s", func_path, exc_info=True)
+    return None

whenly/scheduler.py

@@ -0,0 +1,360 @@
+"""Main Scheduler class for whenly."""
+
+from __future__ import annotations
+
+import logging
+import threading
+import time
+from datetime import datetime, timedelta
+from functools import wraps
+from typing import Any, Callable
+
+from croniter import croniter
+
+from .models import Job, JobRun, MissedPolicy, ScheduleType
+from .runner import JobRunner
+from .store import Store
+
+logger = logging.getLogger(__name__)
+
+
+class Scheduler:
+    """Lightweight persistent job scheduler."""
+
+    def __init__(
+        self,
+        db_path: str = "whenly.db",
+        tick_interval: float = 1.0,
+        max_workers: int = 10,
+    ) -> None:
+        self._store = Store(db_path)
+        self._runner = JobRunner(self._store, max_workers=max_workers)
+        self._tick_interval = tick_interval
+        self._thread: threading.Thread | None = None
+        self._running = False
+        self._stopped = False
+        self._lock = threading.Lock()
+        self._funcs: dict[str, Callable[..., Any]] = {}
+
+    def __enter__(self) -> Scheduler:
+        return self
+
+    def __exit__(self, *args: Any) -> None:
+        self.close()
+
+    def close(self) -> None:
+        """Stop the scheduler and close the store safely."""
+        if self._stopped:
+            return
+        self.stop()
+        with self._lock:
+            self._stopped = True
+        self._store.close()
+
+    # -- decorators --
+
+    def every(
+        self,
+        amount: int = 1,
+        unit: str = "seconds",
+        *,
+        name: str | None = None,
+        missed: str | MissedPolicy = MissedPolicy.RUN_ONCE,
+        timeout: int | None = None,
+        max_concurrent: int = 1,
+    ) -> Callable[[Callable[..., Any]], Callable[..., Any]]:
+        """Decorator to register an interval job.
+
+        Usage:
+            @s.every(5, "minutes")
+            def my_job(): ...
+            @s.every(10, minutes=True)
+            def my_job(): ...
+        """
+        seconds = _parse_interval(amount, unit)
+        policy = MissedPolicy(missed) if isinstance(missed, str) else missed
+
+        def decorator(fn: Callable[..., Any]) -> Callable[..., Any]:
+            job_name = name or fn.__name__
+            with self._lock:
+                self._funcs[job_name] = fn
+            job = Job(
+                name=job_name,
+                func_path=_func_path(fn),
+                schedule_type=ScheduleType.INTERVAL,
+                interval_seconds=seconds,
+                missed_policy=policy,
+                timeout_seconds=timeout,
+                max_concurrent=max_concurrent,
+                next_run_at=datetime.utcnow(),
+                func=fn,
+            )
+            self._store.save_job(job)
+            return fn
+        return decorator
+
+    def cron(
+        self,
+        expr: str,
+        *,
+        name: str | None = None,
+        missed: str | MissedPolicy = MissedPolicy.SKIP,
+        timeout: int | None = None,
+        max_concurrent: int = 1,
+    ) -> Callable[[Callable[..., Any]], Callable[..., Any]]:
+        """Decorator to register a cron job."""
+        policy = MissedPolicy(missed) if isinstance(missed, str) else missed
+
+        def decorator(fn: Callable[..., Any]) -> Callable[..., Any]:
+            job_name = name or fn.__name__
+            with self._lock:
+                self._funcs[job_name] = fn
+            next_run = croniter(expr, datetime.utcnow()).get_next(datetime)
+            job = Job(
+                name=job_name,
+                func_path=_func_path(fn),
+                schedule_type=ScheduleType.CRON,
+                cron_expr=expr,
+                missed_policy=policy,
+                timeout_seconds=timeout,
+                max_concurrent=max_concurrent,
+                next_run_at=next_run,
+                func=fn,
+            )
+            self._store.save_job(job)
+            return fn
+        return decorator
+
+    # -- programmatic API --
+
+    def add(
+        self,
+        func: Callable[..., Any],
+        *,
+        every: str | None = None,
+        cron: str | None = None,
+        name: str | None = None,
+        missed: str | MissedPolicy = MissedPolicy.RUN_ONCE,
+        timeout: int | None = None,
+        max_concurrent: int = 1,
+    ) -> Job:
+        """Add a job programmatically."""
+        policy = MissedPolicy(missed) if isinstance(missed, str) else missed
+        job_name = name or func.__name__
+        with self._lock:
+            self._funcs[job_name] = func
+
+        if cron:
+            next_run = croniter(cron, datetime.utcnow()).get_next(datetime)
+            job = Job(
+                name=job_name, func_path=_func_path(func),
+                schedule_type=ScheduleType.CRON, cron_expr=cron,
+                missed_policy=policy, timeout_seconds=timeout,
+                max_concurrent=max_concurrent, next_run_at=next_run, func=func,
+            )
+        elif every:
+            seconds = _parse_interval_str(every)
+            job = Job(
+                name=job_name, func_path=_func_path(func),
+                schedule_type=ScheduleType.INTERVAL, interval_seconds=seconds,
+                missed_policy=policy, timeout_seconds=timeout,
+                max_concurrent=max_concurrent, next_run_at=datetime.utcnow(), func=func,
+            )
+        else:
+            raise ValueError("Must specify either 'every' or 'cron'")
+
+        return self._store.save_job(job)
+
+    def later(
+        self,
+        amount: int = 1,
+        unit: str = "seconds",
+        func: Callable[..., Any] | None = None,
+        *,
+        name: str | None = None,
+        args: tuple = (),
+        kwargs: dict | None = None,
+    ) -> Job | Callable[[Callable[..., Any]], Job]:
+        """Schedule a one-off job to run after a delay.
+
+        Can be used as a method or decorator:
+            s.later(30, "seconds", send_email)
+            @s.later(5, "minutes")
+            def cleanup(): ...
+        """
+        seconds = _parse_interval(amount, unit)
+        _kwargs = kwargs or {}
+
+        if func is not None:
+            return self._create_oneoff(func, seconds, name or func.__name__, args, _kwargs)
+
+        def decorator(fn: Callable[..., Any]) -> Job:
+            return self._create_oneoff(fn, seconds, name or fn.__name__, args, _kwargs)
+
+        return decorator  # type: ignore[return-value]
+
+    def _create_oneoff(
+        self, func: Callable[..., Any], delay_seconds: int, name: str,
+        args: tuple = (), kwargs: dict | None = None,
+    ) -> Job:
+        job_name = name
+        _kwargs = kwargs or {}
+        with self._lock:
+            self._funcs[job_name] = func
+        scheduled = datetime.utcnow() + timedelta(seconds=delay_seconds)
+        job = Job(
+            name=job_name, func_path=_func_path(func),
+            schedule_type=ScheduleType.ONCE, scheduled_for=scheduled,
+            next_run_at=scheduled, func=func,
+        )
+        job._args = args  # type: ignore[attr-defined]
+        job._kwargs = _kwargs  # type: ignore[attr-defined]
+        return self._store.save_job(job)
+
+    def run_now(self, name: str) -> bool:
+        """Manually trigger a job by name."""
+        job = self._store.get_job(name)
+        if not job:
+            return False
+        # Attach runtime func if available
+        with self._lock:
+            job.func = self._funcs.get(job.name)
+        self._runner.submit(job)
+        return True
+
+    def disable(self, name: str) -> bool:
+        job = self._store.get_job(name)
+        if not job:
+            return False
+        self._store.set_enabled(job.id, False)
+        return True
+
+    def enable(self, name: str) -> bool:
+        job = self._store.get_job(name)
+        if not job:
+            return False
+        self._store.set_enabled(job.id, True)
+        return True
+
+    # -- scheduler loop --
+
+    def start(self) -> None:
+        """Start the scheduler in a background thread."""
+        with self._lock:
+            if self._running:
+                return
+            self._running = True
+            self._thread = threading.Thread(target=self._loop, daemon=True)
+            self._thread.start()
+            logger.info("Scheduler started (background)")
+
+    def stop(self) -> None:
+        """Stop the scheduler (idempotent)."""
+        with self._lock:
+            was_running = self._running
+            self._running = False
+            thread = self._thread
+            self._thread = None
+        if was_running and thread:
+            thread.join(timeout=5)
+        self._runner.shutdown(wait=True)
+        logger.info("Scheduler stopped")
+
+    def run(self) -> None:
+        """Run the scheduler blocking (foreground)."""
+        with self._lock:
+            if self._running:
+                return
+            self._running = True
+        try:
+            self._loop()
+        finally:
+            self._running = False
+            self._runner.shutdown(wait=True)
+
+    def _loop(self) -> None:
+        while self._running:
+            self._tick()
+            time.sleep(self._tick_interval)
+
+    def _tick(self) -> None:
+        now = datetime.utcnow()
+        due_jobs = self._store.get_due_jobs(now)
+
+        for job in due_jobs:
+            # Attach runtime func if available
+            with self._lock:
+                job.func = self._funcs.get(job.name)
+            submitted = self._runner.submit(job, scheduled_for=job.next_run_at)
+
+            if submitted:
+                # Handle missed runs and schedule next
+                if job.schedule_type == ScheduleType.ONCE:
+                    # One-off: clear next_run to prevent re-scheduling
+                    self._store.update_next_run(job.id, now + timedelta(days=365 * 100))
+                    self._store.set_enabled(job.id, False)
+                    continue
+
+                # Compute next run FIRST to avoid duplicates
+                next_run = self._compute_next(job, now)
+                self._store.update_next_run(job.id, next_run)
+
+                # Handle missed runs
+                if job.missed_policy == MissedPolicy.RUN_ALL:
+                    missed = self._store.get_missed_count(job.id, now)
+                    for i in range(missed - 1):
+                        missed_job = Job(
+                            **{k: getattr(job, k) for k in job.__dataclass_fields__ if k != "func"},
+                            func=job.func,
+                        )
+                        self._runner.submit(missed_job)
+
+    def _compute_next(self, job: Job, after: datetime) -> datetime:
+        if job.schedule_type == ScheduleType.CRON and job.cron_expr:
+            return croniter(job.cron_expr, after).get_next(datetime)
+        elif job.schedule_type == ScheduleType.INTERVAL and job.interval_seconds:
+            return after + timedelta(seconds=job.interval_seconds)
+        return after + timedelta(seconds=60)
+
+    # -- accessors --
+
+    @property
+    def store(self) -> Store:
+        return self._store
+
+    @property
+    def jobs(self) -> list[Job]:
+        return self._store.list_jobs()
+
+    def get_history(self, name: str, limit: int = 20) -> list[JobRun]:
+        return self._store.get_runs(name, limit)
+
+
+# -- helpers --
+
+def _parse_interval(amount: int, unit: str) -> int:
+    """Parse interval amount + unit to seconds."""
+    unit = unit.lower().rstrip("s")
+    multipliers = {
+        "second": 1, "minute": 60, "hour": 3600, "day": 86400,
+    }
+    if unit not in multipliers:
+        raise ValueError(f"Unknown unit: {unit}. Use seconds/minutes/hours/days")
+    return amount * multipliers[unit]
+
+
+def _parse_interval_str(s: str) -> int | float:
+    """Parse human interval like '5m', '2h', '30s', '1d'."""
+    s = s.strip().lower()
+    units = {"ms": 0.001, "s": 1, "m": 60, "h": 3600, "d": 86400}
+    for suffix, mult in units.items():
+        if s.endswith(suffix):
+            try:
+                return int(s[:-len(suffix)]) * mult
+            except ValueError:
+                raise ValueError(f"Invalid interval: {s}")
+    raise ValueError(f"Invalid interval: {s}. Use format like '5m', '2h', '30s', '1d'")
+
+
+def _func_path(fn: Callable[..., Any]) -> str:
+    return f"{fn.__module__}.{fn.__qualname__}"

whenly/store.py

@@ -0,0 +1,247 @@
+"""SQLite + in-memory store for whenly."""
+
+from __future__ import annotations
+
+import logging
+import sqlite3
+from datetime import datetime
+from typing import Any
+
+from .models import Job, JobRun, JobStatus, MissedPolicy, ScheduleType
+
+logger = logging.getLogger(__name__)
+
+_SCHEMA = """
+CREATE TABLE IF NOT EXISTS jobs (
+    id TEXT PRIMARY KEY,
+    name TEXT UNIQUE NOT NULL,
+    func_path TEXT NOT NULL,
+    schedule_type TEXT NOT NULL,
+    interval_seconds INTEGER,
+    cron_expr TEXT,
+    scheduled_for TEXT,
+    missed_policy TEXT DEFAULT 'run_once',
+    max_concurrent INTEGER DEFAULT 1,
+    timeout_seconds INTEGER,
+    enabled INTEGER DEFAULT 1,
+    next_run_at TEXT,
+    last_run_at TEXT,
+    created_at TEXT NOT NULL,
+    updated_at TEXT NOT NULL
+);
+
+CREATE TABLE IF NOT EXISTS job_runs (
+    id TEXT PRIMARY KEY,
+    job_id TEXT NOT NULL REFERENCES jobs(id),
+    status TEXT NOT NULL,
+    started_at TEXT,
+    finished_at TEXT,
+    duration_seconds REAL,
+    error_message TEXT,
+    scheduled_for TEXT
+);
+"""
+
+
+def _dt(s: str | None) -> datetime | None:
+    return datetime.fromisoformat(s) if s else None
+
+
+def _dts(d: datetime | None) -> str | None:
+    return d.isoformat() if d else None
+
+
+class Store:
+    """Persistent store backend (SQLite or :memory:)."""
+
+    def __init__(self, db_path: str = "whenly.db") -> None:
+        self._db_path = db_path
+        self._conn: sqlite3.Connection | None = None
+        self._connect()
+        self._conn.execute("PRAGMA journal_mode=WAL")  # type: ignore[union-attr]
+        self._conn.executescript(_SCHEMA)  # type: ignore[union-attr]
+
+    # -- connection management --
+
+    def _connect(self) -> None:
+        detect = sqlite3.PARSE_DECLTYPES
+        self._conn = sqlite3.connect(self._db_path, detect_types=detect, check_same_thread=False, isolation_level=None)
+        self._conn.execute("PRAGMA foreign_keys = ON")
+        self._conn.row_factory = sqlite3.Row  # type: ignore[union-attr]
+
+    @property
+    def conn(self) -> sqlite3.Connection:
+        assert self._conn is not None
+        return self._conn
+
+    def close(self) -> None:
+        if self._conn:
+            self._conn.close()
+            self._conn = None
+
+    # -- jobs CRUD --
+
+    def save_job(self, job: Job) -> Job:
+        row = self.conn.execute(
+            """INSERT INTO jobs (id, name, func_path, schedule_type, interval_seconds,
+               cron_expr, scheduled_for, missed_policy, max_concurrent, timeout_seconds,
+               enabled, next_run_at, last_run_at, created_at, updated_at)
+               VALUES (?,?,?,?,?,?,?,?,?,?,?,?,?,?,?)
+               ON CONFLICT(name) DO UPDATE SET
+                 func_path=excluded.func_path, schedule_type=excluded.schedule_type,
+                 interval_seconds=excluded.interval_seconds, cron_expr=excluded.cron_expr,
+                 scheduled_for=excluded.scheduled_for, missed_policy=excluded.missed_policy,
+                 max_concurrent=excluded.max_concurrent, timeout_seconds=excluded.timeout_seconds,
+                 enabled=excluded.enabled, next_run_at=excluded.next_run_at,
+                 last_run_at=excluded.last_run_at, updated_at=excluded.updated_at""",
+            (
+                job.id, job.name, job.func_path, job.schedule_type.value,
+                job.interval_seconds, job.cron_expr, _dts(job.scheduled_for),
+                job.missed_policy.value, job.max_concurrent, job.timeout_seconds,
+                int(job.enabled), _dts(job.next_run_at), _dts(job.last_run_at),
+                job.created_at.isoformat(), job.updated_at.isoformat(),
+            ),
+        )
+        self.conn.commit()
+        result = self.get_job(job.name)
+        return result if result else job
+
+    def get_job(self, name: str) -> Job | None:
+        row = self.conn.execute("SELECT * FROM jobs WHERE name=?", (name,)).fetchone()
+        return self._row_to_job(row) if row else None
+
+    def get_job_by_id(self, job_id: str) -> Job | None:
+        row = self.conn.execute("SELECT * FROM jobs WHERE id=?", (job_id,)).fetchone()
+        return self._row_to_job(row) if row else None
+
+    def list_jobs(self) -> list[Job]:
+        rows = self.conn.execute("SELECT * FROM jobs ORDER BY created_at").fetchall()
+        return [self._row_to_job(r) for r in rows]
+
+    def delete_job(self, name: str) -> bool:
+        # Delete associated runs first to satisfy FK constraint
+        job = self.get_job(name)
+        if job:
+            self.conn.execute("DELETE FROM job_runs WHERE job_id=?", (job.id,))
+        cur = self.conn.execute("DELETE FROM jobs WHERE name=?", (name,))
+        self.conn.commit()
+        return cur.rowcount > 0
+
+    def update_next_run(self, job_id: str, next_run: datetime) -> None:
+        self.conn.execute(
+            "UPDATE jobs SET next_run_at=?, updated_at=? WHERE id=?",
+            (next_run.isoformat(), datetime.utcnow().isoformat(), job_id),
+        )
+        self.conn.commit()
+
+    def update_last_run(self, job_id: str, last_run: datetime) -> None:
+        self.conn.execute(
+            "UPDATE jobs SET last_run_at=?, updated_at=? WHERE id=?",
+            (last_run.isoformat(), datetime.utcnow().isoformat(), job_id),
+        )
+        self.conn.commit()
+
+    def set_enabled(self, job_id: str, enabled: bool) -> None:
+        self.conn.execute(
+            "UPDATE jobs SET enabled=?, updated_at=? WHERE id=?",
+            (int(enabled), datetime.utcnow().isoformat(), job_id),
+        )
+        self.conn.commit()
+
+    # -- due jobs + missed runs --
+
+    def get_due_jobs(self, now: datetime) -> list[Job]:
+        rows = self.conn.execute(
+            """SELECT * FROM jobs
+               WHERE enabled=1 AND next_run_at IS NOT NULL AND next_run_at <= ?
+               ORDER BY next_run_at""",
+            (now.isoformat(),),
+        ).fetchall()
+        return [self._row_to_job(r) for r in rows]
+
+    def get_running_count(self, job_id: str) -> int:
+        row = self.conn.execute(
+            "SELECT COUNT(*) FROM job_runs WHERE job_id=? AND status='running'", (job_id,)
+        ).fetchone()
+        return row[0]
+
+    def get_missed_count(self, job_id: str, now: datetime) -> int:
+        """Count how many scheduled runs were missed between last_run_at and now."""
+        job = self.get_job_by_id(job_id)
+        if not job:
+            return 0
+        if job.missed_policy == MissedPolicy.SKIP:
+            return 0
+        # For simplicity: interval jobs can calculate count; cron/once just 0 or 1
+        if job.schedule_type == ScheduleType.INTERVAL and job.interval_seconds and job.last_run_at:
+            elapsed = (now - job.last_run_at).total_seconds()
+            count = int(elapsed // job.interval_seconds)
+            return max(0, count - 1) if job.next_run_at else max(0, count)
+        return 0
+
+    # -- job runs --
+
+    def save_run(self, run: JobRun) -> JobRun:
+        self.conn.execute(
+            """INSERT INTO job_runs (id, job_id, status, started_at, finished_at,
+               duration_seconds, error_message, scheduled_for)
+               VALUES (?,?,?,?,?,?,?,?)""",
+            (
+                run.id, run.job_id, run.status.value,
+                _dts(run.started_at), _dts(run.finished_at),
+                run.duration_seconds, run.error_message, _dts(run.scheduled_for),
+            ),
+        )
+        self.conn.commit()
+        return run
+
+    def update_run(self, run: JobRun) -> None:
+        self.conn.execute(
+            """UPDATE job_runs SET status=?, started_at=?, finished_at=?,
+               duration_seconds=?, error_message=? WHERE id=?""",
+            (run.status.value, _dts(run.started_at), _dts(run.finished_at),
+             run.duration_seconds, run.error_message, run.id),
+        )
+        self.conn.commit()
+
+    def get_runs(self, job_name: str, limit: int = 20) -> list[JobRun]:
+        rows = self.conn.execute(
+            """SELECT jr.* FROM job_runs jr
+               JOIN jobs j ON jr.job_id = j.id WHERE j.name=?
+               ORDER BY jr.started_at DESC LIMIT ?""",
+            (job_name, limit),
+        ).fetchall()
+        return [self._row_to_run(r) for r in rows]
+
+    # -- internals --
+
+    def _row_to_job(self, row: sqlite3.Row) -> Job:  # type: ignore[type-arg]
+        return Job(
+            id=row["id"],
+            name=row["name"],
+            func_path=row["func_path"],
+            schedule_type=ScheduleType(row["schedule_type"]),
+            interval_seconds=row["interval_seconds"],
+            cron_expr=row["cron_expr"],
+            scheduled_for=_dt(row["scheduled_for"]),
+            missed_policy=MissedPolicy(row["missed_policy"]),
+            max_concurrent=row["max_concurrent"],
+            timeout_seconds=row["timeout_seconds"],
+            enabled=bool(row["enabled"]),
+            next_run_at=_dt(row["next_run_at"]),
+            last_run_at=_dt(row["last_run_at"]),
+            created_at=datetime.fromisoformat(row["created_at"]),
+            updated_at=datetime.fromisoformat(row["updated_at"]),
+        )
+
+    def _row_to_run(self, row: sqlite3.Row) -> JobRun:  # type: ignore[type-arg]
+        return JobRun(
+            id=row["id"],
+            job_id=row["job_id"],
+            status=JobStatus(row["status"]),
+            started_at=_dt(row["started_at"]),
+            finished_at=_dt(row["finished_at"]),
+            duration_seconds=row["duration_seconds"],
+            error_message=row["error_message"],
+            scheduled_for=_dt(row["scheduled_for"]),
+        )

whenly-0.1.0.dist-info/METADATA

@@ -0,0 +1,108 @@
+Metadata-Version: 2.4
+Name: whenly
+Version: 0.1.0
+Summary: Lightweight persistent job scheduler for Python
+Author: Teja
+License: MIT
+Keywords: scheduler,cron,jobs,tasks,periodic
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Operating System :: OS Independent
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+Requires-Dist: croniter>=1.3.0
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0; extra == "dev"
+Requires-Dist: pytest-cov; extra == "dev"
+Requires-Dist: ruff; extra == "dev"
+
+# whenly
+
+Lightweight persistent job scheduler for Python — SQLite-backed, minimal dependencies.
+
+```python
+from whenly import Scheduler
+
+s = Scheduler()
+
+@s.every(5, minutes)
+def sync_data():
+    ...
+
+@s.cron("0 9 * * MON")
+def weekly_report():
+    ...
+
+s.start()  # background thread
+```
+
+## Features
+
+- **SQLite persistence** — jobs survive restarts
+- **Cron expressions** via croniter
+- **Interval scheduling** — every N seconds/minutes/hours
+- **One-off delayed jobs** — run once after a delay
+- **Decorator or programmatic API**
+- **Thread-safe** background runner
+- **CLI** for basic management
+- **Zero external dependencies** (except croniter for cron support)
+
+## Install
+
+```bash
+pip install whenly
+```
+
+## Quick Start
+
+```python
+from whenly import Scheduler
+
+s = Scheduler()
+
+# Interval jobs
+@s.every(30, seconds)
+def poll_api():
+    print("Polling...")
+
+# Cron jobs
+@s.cron("0 */2 * * *")
+def cleanup():
+    print("Running cleanup...")
+
+# One-off delayed job
+s.later(10, minutes, send_notification, msg="Hello")
+
+# Start the scheduler (non-blocking)
+s.start()
+
+# Or run blocking
+# s.run()
+```
+
+### Programmatic API
+
+```python
+s.add_job("poll", interval=60, unit="seconds", fn=poll_api)
+s.add_job("cleanup", cron="0 3 * * *", fn=cleanup)
+s.remove_job("poll")
+s.list_jobs()
+```
+
+## CLI
+
+```bash
+whenly list
+whenly run
+```
+
+## License
+
+MIT

whenly-0.1.0.dist-info/RECORD

@@ -0,0 +1,11 @@
+whenly/__init__.py,sha256=6AZ1-oRNeMqTp8_sIqfa9dR7IndKomNR75cjJ9UyECI,136
+whenly/cli.py,sha256=-wqkzChaSp6UNITX6rf2dYZacfJD75lyA0w0SEj59gY,3206
+whenly/models.py,sha256=agi6ZlBMWZf7W2OMgOo_m0_q238p73HyjNS6B0pgcSc,1674
+whenly/runner.py,sha256=FbQHhvJUSsKk7ED0IIQLuRiZYAbeuuUazysAJO_68as,4029
+whenly/scheduler.py,sha256=SM8zYQBqd7Hl2HX4SNHgdORyt6xJzZ-QCDRVgf81wHw,12061
+whenly/store.py,sha256=z6n6j0xPXa9JUgEsjLh0rDsVGot4Oo6J2NKeMqj9M_o,9445
+whenly-0.1.0.dist-info/METADATA,sha256=69_yeSALdStQs2gbEpn5S6UhUls0O0AsX-jmGcypIwI,2284
+whenly-0.1.0.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
+whenly-0.1.0.dist-info/entry_points.txt,sha256=qDxS0nyAE5kvfmmBFmjUCLnGM0wqj5yC8oguxCNFmFQ,43
+whenly-0.1.0.dist-info/top_level.txt,sha256=ssN8iFQSwCeBny9J2bjhTHoHW70oDwkzYnSYzJeX3bA,7
+whenly-0.1.0.dist-info/RECORD,,

whenly-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (82.0.1)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

whenly-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+whenly = whenly.cli:main

whenly-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+whenly