pybgworker 0.2.1__py3-none-any.whl

pybgworker/__init__.py

@@ -0,0 +1,6 @@
+from .task import task
+from .result import AsyncResult
+
+__all__ = ["task", "AsyncResult"]
+__version__ = "0.2.1"
+

pybgworker/backends.py

@@ -0,0 +1,47 @@
+from abc import ABC, abstractmethod
+import sqlite3
+import json
+from .config import DB_PATH
+
+class BaseBackend(ABC):
+    @abstractmethod
+    def get_task(self, task_id):
+        pass
+
+    @abstractmethod
+    def store_result(self, task_id, result):
+        pass
+
+    @abstractmethod
+    def forget(self, task_id):
+        pass
+
+
+class SQLiteBackend(BaseBackend):
+    def __init__(self, db_path=DB_PATH):
+        self.db_path = db_path
+
+    def get_task(self, task_id):
+        from .utils import get_conn
+        with get_conn() as conn:
+            conn.row_factory = sqlite3.Row
+            row = conn.execute(
+                "SELECT * FROM tasks WHERE id=?",
+                (task_id,)
+            ).fetchone()
+            return dict(row) if row else None
+
+    def store_result(self, task_id, result):
+        from .utils import get_conn
+        with get_conn() as conn:
+            conn.execute(
+                "UPDATE tasks SET result=? WHERE id=?",
+                (json.dumps(result), task_id)
+            )
+            conn.commit()
+
+    def forget(self, task_id):
+        from .utils import get_conn
+        with get_conn() as conn:
+            conn.execute("DELETE FROM tasks WHERE id=?", (task_id,))
+            conn.commit()

pybgworker/cancel.py

@@ -0,0 +1,29 @@
+from .utils import get_conn, now
+
+
+def cancel(task_id):
+    with get_conn() as conn:
+        row = conn.execute(
+            "SELECT status FROM tasks WHERE id=?",
+            (task_id,)
+        ).fetchone()
+
+        if not row:
+            print("❌ Task not found")
+            return
+
+        if row[0] != "running":
+            print("⚠ Task is not running")
+            return
+
+        conn.execute("""
+            UPDATE tasks
+            SET status='cancelled',
+                finished_at=?,
+                updated_at=?
+            WHERE id=?
+        """, (now().isoformat(), now().isoformat(), task_id))
+
+        conn.commit()
+
+    print("🛑 Task cancelled")

pybgworker/cli.py

@@ -0,0 +1,69 @@
+import argparse
+import sys
+import os
+import importlib
+
+from .worker import run_worker
+from .inspect import inspect
+from .retry import retry
+from .purge import purge
+from .cancel import cancel
+from .failed import list_failed
+from .stats import stats
+
+
+def main():
+    parser = argparse.ArgumentParser("pybgworker")
+
+    parser.add_argument(
+        "command",
+        choices=["run", "inspect", "retry", "purge", "cancel", "failed", "stats"],
+        help="worker control commands"
+    )
+
+    parser.add_argument(
+        "task_id",
+        nargs="?",
+        help="task id for retry/cancel"
+    )
+
+    parser.add_argument(
+        "--app",
+        help="module containing task definitions (required for run)"
+    )
+
+    args = parser.parse_args()
+
+    if args.command == "run":
+        if not args.app:
+            parser.error("--app is required for 'run'")
+
+        sys.path.insert(0, os.getcwd())
+        importlib.import_module(args.app)
+        run_worker()
+
+    elif args.command == "inspect":
+        inspect()
+
+    elif args.command == "retry":
+        if not args.task_id:
+            parser.error("retry requires task_id")
+        retry(args.task_id)
+
+    elif args.command == "purge":
+        purge()
+
+    elif args.command == "cancel":
+        if not args.task_id:
+            parser.error("cancel requires task_id")
+        cancel(args.task_id)
+
+    elif args.command == "failed":
+        list_failed()
+
+    elif args.command == "stats":
+        stats()
+
+
+if __name__ == "__main__":
+    main()

pybgworker/config.py

@@ -0,0 +1,7 @@
+import os
+WORKER_TIMEOUT = 15 
+RATE_LIMIT = 5  # tasks per second
+DB_PATH = os.getenv("PYBGWORKER_DB", "pybgworker.db")
+WORKER_NAME = os.getenv("PYBGWORKER_WORKER_NAME", "worker-1")
+POLL_INTERVAL = float(os.getenv("PYBGWORKER_POLL_INTERVAL", 1.0))
+LOCK_TIMEOUT = int(os.getenv("PYBGWORKER_LOCK_TIMEOUT", 60))

pybgworker/failed.py

@@ -0,0 +1,24 @@
+from .utils import get_conn
+
+
+def list_failed():
+    with get_conn() as conn:
+        rows = conn.execute("""
+            SELECT id, name, attempt, last_error
+            FROM tasks
+            WHERE status='failed'
+            ORDER BY updated_at DESC
+        """).fetchall()
+
+    if not rows:
+        print("✅ No failed tasks")
+        return
+
+    print("\n❌ Failed Tasks\n")
+
+    for r in rows:
+        print(f"ID: {r[0]}")
+        print(f"Task: {r[1]}")
+        print(f"Attempts: {r[2]}")
+        print(f"Error: {r[3][:120] if r[3] else 'None'}")
+        print("-" * 40)

pybgworker/inspect.py

@@ -0,0 +1,42 @@
+from .utils import get_conn
+from datetime import datetime, timezone
+
+
+def inspect():
+    with get_conn() as conn:
+        conn.row_factory = dict_factory
+
+        print("\n📦 Task Stats")
+
+        stats = conn.execute("""
+            SELECT status, COUNT(*) as count
+            FROM tasks
+            GROUP BY status
+        """).fetchall()
+
+        total = 0
+        for row in stats:
+            print(f"{row['status']:10} {row['count']}")
+            total += row["count"]
+
+        print(f"{'total':10} {total}")
+
+        print("\n👷 Workers")
+
+        workers = conn.execute("""
+            SELECT name, last_seen
+            FROM workers
+        """).fetchall()
+
+        now = datetime.now(timezone.utc)
+
+        for w in workers:
+            last_seen = datetime.fromisoformat(w["last_seen"])
+            delta = (now - last_seen).total_seconds()
+
+            status = "alive" if delta < 15 else "dead"
+            print(f"{w['name']:10} {status:5} ({int(delta)}s ago)")
+
+        print()
+def dict_factory(cursor, row):
+    return {col[0]: row[idx] for idx, col in enumerate(cursor.description)}

pybgworker/logger.py

@@ -0,0 +1,14 @@
+import json
+import sys
+from datetime import datetime, timezone
+
+
+def log(event, **fields):
+    entry = {
+        "timestamp": datetime.now(timezone.utc).isoformat(),
+        "event": event,
+        **fields
+    }
+
+    sys.stdout.write(json.dumps(entry) + "\n")
+    sys.stdout.flush()

pybgworker/purge.py

@@ -0,0 +1,14 @@
+from .utils import get_conn
+
+
+def purge():
+    with get_conn() as conn:
+        cursor = conn.execute("""
+            DELETE FROM tasks
+            WHERE status IN ('queued', 'retrying')
+        """)
+
+        deleted = cursor.rowcount
+        conn.commit()
+
+    print(f"🧹 Purged {deleted} queued tasks")

pybgworker/queue.py

@@ -0,0 +1,23 @@
+from abc import ABC, abstractmethod
+
+class BaseQueue(ABC):
+
+    @abstractmethod
+    def enqueue(self, task: dict):
+        pass
+
+    @abstractmethod
+    def fetch_next(self, worker_name: str):
+        pass
+
+    @abstractmethod
+    def ack(self, task_id: str):
+        pass
+
+    @abstractmethod
+    def fail(self, task_id: str, error: str):
+        pass
+
+    @abstractmethod
+    def reschedule(self, task_id: str, run_at):
+        pass

pybgworker/ratelimit.py

@@ -0,0 +1,26 @@
+import time
+import threading
+
+
+class RateLimiter:
+    def __init__(self, rate_per_sec):
+        self.rate = rate_per_sec
+        self.lock = threading.Lock()
+        self.timestamps = []
+
+    def acquire(self):
+        with self.lock:
+            now = time.time()
+
+            # remove old timestamps
+            self.timestamps = [
+                t for t in self.timestamps
+                if now - t < 1
+            ]
+
+            if len(self.timestamps) >= self.rate:
+                sleep_time = 1 - (now - self.timestamps[0])
+                if sleep_time > 0:
+                    time.sleep(sleep_time)
+
+            self.timestamps.append(time.time())

pybgworker/result.py

@@ -0,0 +1,64 @@
+import time
+import json
+from .state import TaskState
+from .backends import BaseBackend, SQLiteBackend
+
+
+class AsyncResult:
+    def __init__(self, task_id, backend: BaseBackend = None):
+        self.task_id = task_id
+        self.backend = backend or SQLiteBackend()
+
+    def _fetch(self):
+        return self.backend.get_task(self.task_id)
+
+    @property
+    def task_info(self):
+        return self._fetch()
+
+    @property
+    def status(self):
+        task = self._fetch()
+        return task["status"] if task else None
+
+    @property
+    def result(self):
+        task = self._fetch()
+        if task and task["result"]:
+            return json.loads(task["result"])
+        return None
+
+    @property
+    def error(self):
+        task = self._fetch()
+        return task["last_error"] if task else None
+
+    def ready(self):
+        return self.status in (
+            TaskState.SUCCESS.value,
+            TaskState.FAILED.value,
+        )
+
+    def successful(self):
+        return self.status == TaskState.SUCCESS.value
+
+    def failed(self):
+        return self.status == TaskState.FAILED.value
+
+    def get(self, timeout=None):
+        start_time = time.time()
+        while True:
+            if self.ready():
+                if self.successful():
+                    return self.result
+                else:
+                    raise Exception(self.error)
+            if timeout and time.time() - start_time > timeout:
+                raise TimeoutError("Timeout waiting for task to complete")
+            time.sleep(0.1)
+
+    def forget(self):
+        self.backend.forget(self.task_id)
+
+    def __repr__(self):
+        return f"<AsyncResult(task_id='{self.task_id}', status='{self.status}')>"

pybgworker/retry.py

@@ -0,0 +1,30 @@
+from .utils import get_conn, now
+
+
+def retry(task_id):
+    with get_conn() as conn:
+        row = conn.execute(
+            "SELECT status FROM tasks WHERE id=?",
+            (task_id,)
+        ).fetchone()
+
+        if not row:
+            print("❌ Task not found")
+            return
+
+        if row[0] != "failed":
+            print("⚠ Task is not failed")
+            return
+
+        conn.execute("""
+            UPDATE tasks
+            SET status='queued',
+                attempt=0,
+                last_error=NULL,
+                updated_at=?
+            WHERE id=?
+        """, (now().isoformat(), task_id))
+
+        conn.commit()
+
+    print("🔁 Task requeued")

pybgworker/scheduler.py

@@ -0,0 +1,56 @@
+import time
+from croniter import croniter
+from datetime import datetime, timezone
+from .task import queue
+from .utils import generate_id, now, dumps
+from .state import TaskState
+from .logger import log
+
+CRON_REGISTRY = []
+
+
+def cron(expr):
+    def decorator(func):
+        CRON_REGISTRY.append((expr, func))
+        return func
+    return decorator
+
+
+def run_scheduler():
+    log("scheduler_start")
+
+    next_run = {}
+
+    while True:
+        current = datetime.now(timezone.utc)
+
+        for expr, func in CRON_REGISTRY:
+            if expr not in next_run:
+                next_run[expr] = croniter(expr, current).get_next(datetime)
+
+            if current >= next_run[expr]:
+                task = {
+                    "id": generate_id(),
+                    "name": func.__name__,
+                    "args": dumps(()),
+                    "kwargs": dumps({}),
+                    "status": TaskState.QUEUED.value,
+                    "attempt": 0,
+                    "max_retries": 0,
+                    "run_at": now().isoformat(),
+                    "priority": 5,
+                    "locked_by": None,
+                    "locked_at": None,
+                    "last_error": None,
+                    "result": None,
+                    "created_at": now().isoformat(),
+                    "updated_at": now().isoformat(),
+                    "finished_at": None,
+                }
+
+                queue.enqueue(task)
+                log("cron_fired", task_name=func.__name__)
+
+                next_run[expr] = croniter(expr, current).get_next(datetime)
+
+        time.sleep(1)

pybgworker/sqlite_queue.py

@@ -0,0 +1,140 @@
+import sqlite3
+from datetime import timedelta
+from .queue import BaseQueue
+from .config import DB_PATH, WORKER_TIMEOUT
+from .utils import now, get_conn
+
+
+class SQLiteQueue(BaseQueue):
+
+    def __init__(self, db_path=DB_PATH):
+        self._init_db()
+
+    # ---------------- DB init ----------------
+
+    def _init_db(self):
+        with get_conn() as conn:
+            conn.execute("""
+            CREATE TABLE IF NOT EXISTS tasks (
+                id TEXT PRIMARY KEY,
+                name TEXT,
+                args TEXT,
+                kwargs TEXT,
+                status TEXT,
+                attempt INTEGER,
+                max_retries INTEGER,
+                run_at TEXT,
+                priority INTEGER DEFAULT 5,
+                locked_by TEXT,
+                locked_at TEXT,
+                last_error TEXT,
+                result TEXT,
+                created_at TEXT,
+                updated_at TEXT,
+                finished_at TEXT
+            )
+            """)
+
+            conn.execute("""
+            CREATE INDEX IF NOT EXISTS idx_tasks_priority_runat
+            ON tasks(status, priority, run_at)
+            """)
+
+            conn.execute("""
+            CREATE TABLE IF NOT EXISTS workers (
+                name TEXT PRIMARY KEY,
+                last_seen TEXT
+            )
+            """)
+
+            conn.commit()
+
+    # ---------------- enqueue ----------------
+
+    def enqueue(self, task):
+        with get_conn() as conn:
+            conn.execute("""
+                INSERT INTO tasks VALUES (?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?)
+            """, tuple(task.values()))
+            conn.commit()
+
+    # ---------------- atomic fetch ----------------
+
+    def fetch_next(self, worker):
+        stale_time = (now() - timedelta(seconds=WORKER_TIMEOUT)).isoformat()
+
+        with get_conn() as conn:
+            conn.row_factory = sqlite3.Row
+
+            row = conn.execute("""
+                UPDATE tasks
+                SET status='running',
+                    locked_by=?,
+                    locked_at=?,
+                    updated_at=?
+                WHERE id = (
+                    SELECT t.id FROM tasks t
+                    LEFT JOIN workers w ON t.locked_by = w.name
+                    WHERE
+                        (
+                            t.status IN ('queued','retrying')
+                            OR
+                            (t.status='running' AND w.last_seen < ?)
+                        )
+                    AND t.run_at <= ?
+                    ORDER BY t.priority ASC, t.run_at ASC
+                    LIMIT 1
+                )
+                RETURNING *
+            """, (
+                worker,
+                now().isoformat(),
+                now().isoformat(),
+                stale_time,
+                now().isoformat()
+            )).fetchone()
+
+            conn.commit()
+            return dict(row) if row else None
+
+    # ---------------- ack ----------------
+
+    def ack(self, task_id):
+        with get_conn() as conn:
+            conn.execute("""
+                UPDATE tasks
+                SET status='success',
+                    finished_at=?,
+                    updated_at=?
+                WHERE id=?
+            """, (now().isoformat(), now().isoformat(), task_id))
+            conn.commit()
+
+    # ---------------- fail ----------------
+
+    def fail(self, task_id, error):
+        with get_conn() as conn:
+            conn.execute("""
+                UPDATE tasks
+                SET status='failed',
+                    last_error=?,
+                    finished_at=?,
+                    updated_at=?
+                WHERE id=?
+            """, (error, now().isoformat(), now().isoformat(), task_id))
+            conn.commit()
+
+    # ---------------- retry ----------------
+
+    def reschedule(self, task_id, delay):
+        run_at = now() + timedelta(seconds=delay)
+        with get_conn() as conn:
+            conn.execute("""
+                UPDATE tasks
+                SET status='retrying',
+                    attempt=attempt+1,
+                    run_at=?,
+                    updated_at=?
+                WHERE id=?
+            """, (run_at.isoformat(), now().isoformat(), task_id))
+            conn.commit()

pybgworker/state.py

@@ -0,0 +1,27 @@
+from enum import Enum
+
+
+class TaskState(str, Enum):
+    QUEUED = "queued"
+    RUNNING = "running"
+    RETRYING = "retrying"
+    FAILED = "failed"
+    SUCCESS = "success"
+    CANCELLED = "cancelled"
+
+
+ALLOWED_TRANSITIONS = {
+    TaskState.QUEUED: {TaskState.RUNNING},
+    TaskState.RUNNING: {
+        TaskState.SUCCESS,
+        TaskState.RETRYING,
+        TaskState.FAILED,
+        TaskState.CANCELLED,
+    },
+    TaskState.RETRYING: {TaskState.RUNNING},
+}
+
+
+def validate_transition(old, new):
+    if new not in ALLOWED_TRANSITIONS.get(TaskState(old), set()):
+        raise ValueError(f"Invalid transition {old} → {new}")

pybgworker/stats.py

@@ -0,0 +1,27 @@
+from .utils import get_conn
+from datetime import datetime, timezone
+
+
+def stats():
+    with get_conn() as conn:
+        workers = conn.execute("""
+            SELECT name, last_seen FROM workers
+        """).fetchall()
+
+        queued = conn.execute("""
+            SELECT COUNT(*) FROM tasks
+            WHERE status IN ('queued', 'retrying')
+        """).fetchone()[0]
+
+    print("\n👷 Worker Stats\n")
+
+    now = datetime.now(timezone.utc)
+
+    for w in workers:
+        last_seen = datetime.fromisoformat(w[1])
+        delta = (now - last_seen).total_seconds()
+        status = "alive" if delta < 15 else "dead"
+
+        print(f"{w[0]:10} {status:5} ({int(delta)}s ago)")
+
+    print(f"\n📦 Queue depth: {queued}\n")

pybgworker/task.py

@@ -0,0 +1,63 @@
+from functools import wraps
+from datetime import timedelta
+from .sqlite_queue import SQLiteQueue
+from .utils import generate_id, dumps, now
+from .state import TaskState
+from .backends import SQLiteBackend
+
+TASK_REGISTRY = {}
+queue = SQLiteQueue()
+backend = SQLiteBackend()
+
+
+def task(name=None, retries=0, retry_delay=0, retry_for=(Exception,)):
+    if name is None:
+        raise ValueError("Task name is required to avoid __main__ issues")
+
+    def decorator(func):
+        task_name = name or f"{func.__module__}.{func.__name__}"
+
+        TASK_REGISTRY[task_name] = {
+            "func": func,
+            "retry_delay": retry_delay,
+            "retry_for": retry_for,
+        }
+
+        @wraps(func)
+        def delay(*args, countdown=None, eta=None, priority=5, **kwargs):
+            run_at = now()
+
+            if countdown:
+                run_at += timedelta(seconds=countdown)
+
+            if eta:
+                run_at = eta
+
+            task = {
+                "id": generate_id(),
+                "name": task_name,
+                "args": dumps(args),
+                "kwargs": dumps(kwargs),
+                "status": TaskState.QUEUED.value,
+                "attempt": 0,
+                "max_retries": retries,
+                "run_at": run_at.isoformat(),
+                "priority": priority,   # ⭐ NEW
+                "locked_by": None,
+                "locked_at": None,
+                "last_error": None,
+                "result": None,
+                "created_at": now().isoformat(),
+                "updated_at": now().isoformat(),
+                "finished_at": None,
+            }
+
+            queue.enqueue(task)
+
+            from .result import AsyncResult
+            return AsyncResult(task["id"], backend=backend)
+
+        func.delay = delay
+        return func
+
+    return decorator

pybgworker/utils.py

@@ -0,0 +1,31 @@
+import uuid
+import json
+import sqlite3
+from datetime import datetime, timezone
+from .config import DB_PATH
+
+
+def generate_id():
+    return str(uuid.uuid4())
+
+
+def now():
+    return datetime.now(timezone.utc)
+
+
+def dumps(obj):
+    return json.dumps(obj)
+
+
+def loads(data):
+    return json.loads(data)
+
+
+def get_conn():
+    conn = sqlite3.connect(DB_PATH, timeout=30)
+
+    # production SQLite settings
+    conn.execute("PRAGMA journal_mode=WAL;")
+    conn.execute("PRAGMA busy_timeout=30000;")  # wait 30 seconds if locked
+
+    return conn

pybgworker/worker.py

@@ -0,0 +1,122 @@
+import time
+import traceback
+import threading
+from multiprocessing import Process, Queue as MPQueue
+
+from .logger import log
+from .sqlite_queue import SQLiteQueue
+from .task import TASK_REGISTRY
+from .config import WORKER_NAME, POLL_INTERVAL, RATE_LIMIT
+from .utils import loads, get_conn, now
+from .backends import SQLiteBackend
+from .scheduler import run_scheduler
+from .ratelimit import RateLimiter
+
+
+queue = SQLiteQueue()
+backend = SQLiteBackend()
+limiter = RateLimiter(RATE_LIMIT)
+
+TASK_TIMEOUT = 150  # seconds
+
+
+def heartbeat():
+    while True:
+        try:
+            with get_conn() as conn:
+                conn.execute("""
+                    INSERT INTO workers(name, last_seen)
+                    VALUES (?, ?)
+                    ON CONFLICT(name)
+                    DO UPDATE SET last_seen=excluded.last_seen
+                """, (WORKER_NAME, now().isoformat()))
+                conn.commit()
+        except Exception as e:
+            log("heartbeat_error", error=str(e))
+
+        time.sleep(5)
+
+
+def run_task(func, args, kwargs, result_queue):
+    try:
+        result = func(*args, **kwargs)
+        result_queue.put(("success", result))
+    except Exception:
+        result_queue.put(("error", traceback.format_exc()))
+
+
+def run_worker():
+    log("worker_start", worker=WORKER_NAME)
+
+    threading.Thread(target=heartbeat, daemon=True).start()
+    threading.Thread(target=run_scheduler, daemon=True).start()
+
+    while True:
+        task = queue.fetch_next(WORKER_NAME)
+
+        if not task:
+            time.sleep(POLL_INTERVAL)
+            continue
+
+        # ⭐ rate limiting happens here
+        limiter.acquire()
+
+        meta = TASK_REGISTRY.get(task["name"])
+        if not meta:
+            queue.fail(task["id"], "Task not registered")
+            log("task_invalid", task_id=task["id"])
+            continue
+
+        func = meta["func"]
+        retry_delay = meta["retry_delay"]
+
+        args = loads(task["args"])
+        kwargs = loads(task["kwargs"])
+
+        start_time = now()
+        log("task_start", task_id=task["id"], worker=WORKER_NAME)
+
+        result_queue = MPQueue()
+        process = Process(target=run_task, args=(func, args, kwargs, result_queue))
+
+        process.start()
+        process.join(TASK_TIMEOUT)
+
+        if process.is_alive():
+            process.terminate()
+
+            info = backend.get_task(task["id"])
+            if info["status"] == "cancelled":
+                log("task_cancelled", task_id=task["id"])
+                continue
+
+            queue.fail(task["id"], "Task timeout")
+            log("task_timeout", task_id=task["id"])
+            continue
+
+        if result_queue.empty():
+            queue.fail(task["id"], "Task crashed without result")
+            log("task_crash", task_id=task["id"])
+            continue
+
+        status, payload = result_queue.get()
+        duration = (now() - start_time).total_seconds()
+
+        if status == "success":
+            backend.store_result(task["id"], payload)
+            queue.ack(task["id"])
+            log("task_success",
+                task_id=task["id"],
+                duration=duration,
+                worker=WORKER_NAME)
+
+        else:
+            if task["attempt"] < task["max_retries"]:
+                queue.reschedule(task["id"], retry_delay)
+                log("task_retry",
+                    task_id=task["id"],
+                    attempt=task["attempt"] + 1,
+                    max=task["max_retries"])
+            else:
+                queue.fail(task["id"], payload)
+                log("task_failed", task_id=task["id"])

pybgworker-0.2.1.dist-info/METADATA

@@ -0,0 +1,209 @@
+Metadata-Version: 2.4
+Name: pybgworker
+Version: 0.2.1
+Summary: Lightweight production-ready background task worker with cron, rate limiting and JSON observability
+Author: Prabhat Verma
+License: MIT
+Project-URL: Homepage, https://github.com/prabhat708/pybgworker
+Project-URL: Repository, https://github.com/prabhat708/pybgworker
+Project-URL: Issues, https://github.com/prabhat708/pybgworker/issues
+Keywords: background-jobs,task-queue,sqlite,cron,worker,job-queue
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.8
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Operating System :: OS Independent
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: croniter>=1.4.0
+Dynamic: license-file
+
+# PyBgWorker
+
+A lightweight, production-ready background task framework for Python.
+
+PyBgWorker provides a durable SQLite-backed task queue, cron scheduling,
+rate limiting, retries, and structured observability — all without external
+infrastructure.
+
+It is designed to be simple, reliable, and easy to deploy.
+
+---
+
+## ✨ Features
+
+- Persistent SQLite task queue
+- Multi-worker safe execution
+- Retry + failure handling
+- Crash isolation via subprocess
+- Cron scheduler for recurring jobs
+- JSON structured logging
+- Task duration tracking
+- Rate limiting (overload protection)
+- Heartbeat monitoring
+- CLI inspect / retry / purge / cancel
+- Production-safe worker loop
+
+---
+
+## 🚀 Installation
+
+```bash
+pip install pybgworker
+```
+
+---
+
+## 🧠 Basic Usage
+
+### Define a task
+
+```python
+from pybgworker.task import task
+
+@task(name="add")
+def add(a, b):
+    return a + b
+```
+
+### Enqueue a task
+
+```python
+add.delay(1, 2)
+```
+
+---
+
+## ▶ Run worker
+
+```bash
+python -m pybgworker.cli run --app example
+```
+
+---
+
+## ⏰ Cron Scheduler
+
+Run recurring tasks:
+
+```python
+from pybgworker.scheduler import cron
+from pybgworker.task import task
+
+@task(name="heartbeat_task")
+@cron("*/1 * * * *")
+def heartbeat():
+    print("alive")
+```
+
+Cron runs automatically inside the worker.
+
+---
+
+## 📊 JSON Logging
+
+All worker events are structured JSON:
+
+```json
+{"event":"task_start","task_id":"..."}
+{"event":"task_success","duration":0.12}
+```
+
+This enables:
+
+- monitoring
+- analytics
+- alerting
+- observability pipelines
+
+---
+
+## 🚦 Rate Limiting
+
+Protect infrastructure from overload:
+
+```python
+RATE_LIMIT = 5  # tasks per second
+```
+
+Ensures predictable execution under heavy load.
+
+---
+
+## 🔍 CLI Commands
+
+Inspect queue:
+
+```bash
+python -m pybgworker.cli inspect
+```
+
+Retry failed task:
+
+```bash
+python -m pybgworker.cli retry <task_id>
+```
+
+Cancel task:
+
+```bash
+python -m pybgworker.cli cancel <task_id>
+```
+
+Purge queued tasks:
+
+```bash
+python -m pybgworker.cli purge
+```
+
+---
+
+## 🧪 Observability
+
+PyBgWorker logs:
+
+- worker start
+- cron events
+- task start
+- success
+- retry
+- failure
+- timeout
+- crash
+- heartbeat errors
+
+All machine-readable.
+
+---
+
+## 🎯 Design Goals
+
+- zero external dependencies
+- SQLite durability
+- safe multiprocessing
+- operator-friendly CLI
+- production observability
+- infrastructure protection
+
+---
+
+## 📌 Roadmap
+
+Future upgrades may include:
+
+- dashboard web UI
+- metrics endpoint
+- Redis backend
+- workflow pipelines
+- cluster coordination
+
+---
+
+## 📄 License
+
+MIT License

pybgworker-0.2.1.dist-info/RECORD

@@ -0,0 +1,26 @@
+pybgworker/__init__.py,sha256=YyQGbGdbLNexZU3tpt-zw1ABbVoZIiAAtB0lwGV_eYg,119
+pybgworker/backends.py,sha256=vOpcY9lXfKm2-ffnFHEWcDvLAukB5KLgSGP3VO8bjEw,1239
+pybgworker/cancel.py,sha256=jNfyKrhDf8gtL3uSgLaknTKuLpsx4umJVTKYGKXs39E,703
+pybgworker/cli.py,sha256=lniULLMozN7CH9ijQqVUU6ujt_rqc6eAU5GHuxmQA3M,1576
+pybgworker/config.py,sha256=emhKOpgx0L4qOuclA_gG3mLmiyN2_4ZqC8uKBNYyYWA,316
+pybgworker/failed.py,sha256=6TB56fapJZ3tEYEM3H3FnzszoHIHRSD0oDTfd_Rbr5w,603
+pybgworker/inspect.py,sha256=pMtSUItc1VVS3sdh3Mi931Dho_RP2uPcHFJsDQT7x6w,1148
+pybgworker/logger.py,sha256=JzSJLX6NB8VXcTfiqH7NjBmwfCZ0Q6IO_2DNCkxTxl8,298
+pybgworker/purge.py,sha256=hvJhL1jIhKamElNnLpv5PH_eroDcTQc2cPZ_0MlwTzo,321
+pybgworker/queue.py,sha256=YPQgRLouqm9xXx7Azm80J19_eZ_4pkLZD4zNtJHvHEE,458
+pybgworker/ratelimit.py,sha256=p30pQXY3V8M8iXFdDXsA2OnXvrGeddp65JD7QyvIMxA,686
+pybgworker/result.py,sha256=uJzsVeA7Aj84f70vSDRxDQ68YxAI26zuXEQlgiNJ_0U,1767
+pybgworker/retry.py,sha256=OLyBqnPxjMptVJ7zVFD7Bm66kdWAJSJpbFZOnhLTir0,707
+pybgworker/scheduler.py,sha256=hJ4jK0IiEFfEjYQOVIn6XDNuWUcaDLipVK85wBtoni8,1648
+pybgworker/sqlite_queue.py,sha256=sclzIY4M9KZjM5MsVK9YMm1ezKAp0qGnwGsQitaJG-Q,4355
+pybgworker/state.py,sha256=LmUxPXSKC2GvFobOSvoHzLpFNM1M7yqtbPKgJ2Ts6Qk,650
+pybgworker/stats.py,sha256=AYrPeZsd_IsU6GpmSEhwS_NmAFwIwwm3lasmgDvu920,751
+pybgworker/task.py,sha256=l6oLVzU2Om-l_2R2HXBimPUo9OwZT2BiDpgWak_joAc,1884
+pybgworker/utils.py,sha256=w7cX28o7K0_wFpRHegtDZ44LpJgBVv7wSdzDlrILGGQ,569
+pybgworker/worker.py,sha256=wHCT-9RwM25j4dgztFgLlLrdeNzPzk6qXPjiMqJ--94,3697
+pybgworker-0.2.1.dist-info/licenses/LICENSE,sha256=eZySKOWd_q-qQa3p01Llyvu5OWqpLnQV6UXUlIaVdHg,1091
+pybgworker-0.2.1.dist-info/METADATA,sha256=0dbrYgliRgv47dGNBU9K3_ndKb7N0TVBZ5KnF49g9Oo,3780
+pybgworker-0.2.1.dist-info/WHEEL,sha256=wUyA8OaulRlbfwMtmQsvNngGrxQHAvkKcvRmdizlJi0,92
+pybgworker-0.2.1.dist-info/entry_points.txt,sha256=iJkiCne1tUtm8TlO3TnVHv1Axe81TxU3vaWK6Cusja4,51
+pybgworker-0.2.1.dist-info/top_level.txt,sha256=0vv_-19bFyP0DL0lqlcA-tvz6tISlkYl3Z3v860To-s,11
+pybgworker-0.2.1.dist-info/RECORD,,

pybgworker-0.2.1.dist-info/WHEEL

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

pybgworker-0.2.1.dist-info/entry_points.txt

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

pybgworker-0.2.1.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Prabhat Verma
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

pybgworker-0.2.1.dist-info/top_level.txt

@@ -0,0 +1 @@
+pybgworker