pybgworker 0.2.1__tar.gz

pybgworker-0.2.1/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/PKG-INFO

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

@@ -0,0 +1,184 @@
+# 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/pybgworker/__init__.py

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

pybgworker-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-0.2.1/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-0.2.1/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-0.2.1/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-0.2.1/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-0.2.1/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-0.2.1/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-0.2.1/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-0.2.1/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