whenly 0.1.0__tar.gz

whenly-0.1.0/PKG-INFO

@@ -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/README.md

@@ -0,0 +1,83 @@
+# 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/pyproject.toml

@@ -0,0 +1,44 @@
+[build-system]
+requires = ["setuptools>=68.0", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "whenly"
+version = "0.1.0"
+description = "Lightweight persistent job scheduler for Python"
+readme = "README.md"
+license = {text = "MIT"}
+requires-python = ">=3.10"
+authors = [{name = "Teja"}]
+keywords = ["scheduler", "cron", "jobs", "tasks", "periodic"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Software Development :: Libraries :: Python Modules",
+    "Operating System :: OS Independent",
+]
+dependencies = [
+    "croniter>=1.3.0",
+]
+
+[project.optional-dependencies]
+dev = ["pytest>=7.0", "pytest-cov", "ruff"]
+
+[project.scripts]
+whenly = "whenly.cli:main"
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+
+[tool.ruff]
+target-version = "py310"
+line-length = 100

whenly-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

whenly-0.1.0/src/whenly/__init__.py

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

whenly-0.1.0/src/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-0.1.0/src/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-0.1.0/src/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