simple-module-background-tasks 0.0.1__tar.gz

simple_module_background_tasks-0.0.1/.gitignore

@@ -0,0 +1,59 @@
+# Python
+__pycache__/
+*.py[cod]
+*.egg-info/
+dist/
+build/
+.venv/
+*.egg
+
+# UV
+uv.lock
+
+# Node
+node_modules/
+
+# IDE
+.idea/
+.vscode/
+*.swp
+*.swo
+
+# Environment
+.env
+
+# Database
+*.db
+*.sqlite3
+
+# Module-managed runtime state (e.g. uploaded dataset files,
+# default storage_dir for SM_DATASETS_STORAGE_DIR).
+var/
+
+# file_storage filesystem backend default root (override via SM_FILE_STORAGE_FS_ROOT_PATH).
+uploads/
+
+# Vite
+host/static/dist/
+
+# Auto-generated frontend module manifest (regenerated by the host at boot
+# or via `make gen-pages`).
+host/client_app/modules.manifest.json
+host/client_app/modules.generated.ts
+host/client_app/modules.generated.css
+
+# Worktrees
+.worktrees/
+
+# Performance profiles
+.memray/
+.benchmarks/
+
+# OS
+.DS_Store
+Thumbs.db
+
+.playwright-cli/*
+.playwright-mcp/*
+host/client_app/.playwright-cli/*
+.superpowers/

simple_module_background_tasks-0.0.1/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Anto Subash
+
+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.

simple_module_background_tasks-0.0.1/PKG-INFO

@@ -0,0 +1,92 @@
+Metadata-Version: 2.4
+Name: simple_module_background_tasks
+Version: 0.0.1
+Summary: Celery + Redis task queue with admin UI for monitoring and retrying failed/stuck tasks
+Project-URL: Homepage, https://github.com/antosubash/simple_module_python
+Project-URL: Repository, https://github.com/antosubash/simple_module_python
+Project-URL: Issues, https://github.com/antosubash/simple_module_python/issues
+Project-URL: Changelog, https://github.com/antosubash/simple_module_python/blob/main/CHANGELOG.md
+Author-email: Anto Subash <antosubash@live.com>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: background-jobs,celery,redis,simple-module,task-queue
+Classifier: Development Status :: 3 - Alpha
+Classifier: Framework :: FastAPI
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Internet :: WWW/HTTP
+Classifier: Topic :: Software Development :: Libraries :: Application Frameworks
+Classifier: Typing :: Typed
+Requires-Python: >=3.12
+Requires-Dist: celery[redis]>=5.4
+Requires-Dist: redis>=5
+Requires-Dist: simple-module-core==0.0.1
+Requires-Dist: simple-module-db==0.0.1
+Requires-Dist: simple-module-hosting==0.0.1
+Description-Content-Type: text/markdown
+
+# simple_module_background_tasks
+
+Celery + Redis background-task module for [simple_module](https://github.com/antosubash/simple_module_python) apps. Provides a pre-configured Celery instance, a task registration hook, and an admin UI for monitoring + retrying failed/stuck tasks.
+
+## Install
+
+```bash
+pip install simple_module_background_tasks
+```
+
+Requires a Redis broker — set `SM_CELERY_BROKER_URL` (default `redis://localhost:6379/0`).
+
+## What it provides
+
+- `register_background_tasks()` module hook — modules declare tasks here; the registry wires them into the Celery app at boot.
+- Admin UI at `/background-tasks/admin` — list recent runs, retry failed, inspect tracebacks.
+- Shared Celery app accessible via `from background_tasks import celery_app` (import name `background_tasks`, distribution name `simple_module_background_tasks`).
+
+## Usage
+
+Declare a task in a module:
+
+```python
+# modules/reports/reports/tasks.py
+from background_tasks import celery_app   # type: ignore[import-not-found]
+
+
+@celery_app.task(name="reports.generate")
+def generate_report(report_id: int) -> None:
+    ...
+```
+
+Register it:
+
+```python
+class ReportsModule(ModuleBase):
+    meta = ModuleMeta(name="reports", depends_on=["background_tasks"])
+
+    def register_background_tasks(self):
+        from . import tasks  # noqa: F401 — side-effect: registers tasks
+```
+
+Enqueue from an endpoint:
+
+```python
+generate_report.delay(report_id=42)
+```
+
+Run a worker locally:
+
+```bash
+uv run celery -A background_tasks.celery_app worker --loglevel=info
+```
+
+## Depends on
+
+- `simple_module_core`, `simple_module_db`, `simple_module_hosting`
+- `celery[redis]>=5.4`, `redis>=5`
+
+## License
+
+MIT — see [LICENSE](https://github.com/antosubash/simple_module_python/blob/main/LICENSE).

simple_module_background_tasks-0.0.1/README.md

@@ -0,0 +1,62 @@
+# simple_module_background_tasks
+
+Celery + Redis background-task module for [simple_module](https://github.com/antosubash/simple_module_python) apps. Provides a pre-configured Celery instance, a task registration hook, and an admin UI for monitoring + retrying failed/stuck tasks.
+
+## Install
+
+```bash
+pip install simple_module_background_tasks
+```
+
+Requires a Redis broker — set `SM_CELERY_BROKER_URL` (default `redis://localhost:6379/0`).
+
+## What it provides
+
+- `register_background_tasks()` module hook — modules declare tasks here; the registry wires them into the Celery app at boot.
+- Admin UI at `/background-tasks/admin` — list recent runs, retry failed, inspect tracebacks.
+- Shared Celery app accessible via `from background_tasks import celery_app` (import name `background_tasks`, distribution name `simple_module_background_tasks`).
+
+## Usage
+
+Declare a task in a module:
+
+```python
+# modules/reports/reports/tasks.py
+from background_tasks import celery_app   # type: ignore[import-not-found]
+
+
+@celery_app.task(name="reports.generate")
+def generate_report(report_id: int) -> None:
+    ...
+```
+
+Register it:
+
+```python
+class ReportsModule(ModuleBase):
+    meta = ModuleMeta(name="reports", depends_on=["background_tasks"])
+
+    def register_background_tasks(self):
+        from . import tasks  # noqa: F401 — side-effect: registers tasks
+```
+
+Enqueue from an endpoint:
+
+```python
+generate_report.delay(report_id=42)
+```
+
+Run a worker locally:
+
+```bash
+uv run celery -A background_tasks.celery_app worker --loglevel=info
+```
+
+## Depends on
+
+- `simple_module_core`, `simple_module_db`, `simple_module_hosting`
+- `celery[redis]>=5.4`, `redis>=5`
+
+## License
+
+MIT — see [LICENSE](https://github.com/antosubash/simple_module_python/blob/main/LICENSE).

simple_module_background_tasks-0.0.1/background_tasks/__init__.py

@@ -0,0 +1 @@
+"""BackgroundTasks module — Celery + Redis task queue with admin UI."""

simple_module_background_tasks-0.0.1/background_tasks/_signal_support.py

@@ -0,0 +1,105 @@
+"""Signal-handler helpers shared across :mod:`background_tasks.signals`.
+
+Kept in a separate module so :mod:`.signals` stays under the 300-line cap.
+These helpers are intentionally side-effect-free except for the DB write in
+``upsert_by_celery_id`` — signal handlers compose them.
+"""
+
+from __future__ import annotations
+
+import traceback as tb_mod
+from datetime import UTC, datetime
+from typing import Any
+
+from sqlalchemy import select
+from sqlalchemy.orm import Session
+
+from background_tasks.models import TaskExecution
+
+
+def now_utc() -> datetime:
+    return datetime.now(UTC)
+
+
+def coerce_args_kwargs(args: Any, kwargs: Any) -> tuple[list[Any], dict[str, Any]]:
+    """Normalise Celery args/kwargs payloads to JSON-ready shapes.
+
+    Celery sometimes hands us tuples/frozensets that our JSON column can't
+    store; also tolerates ``None`` so a partial payload won't wedge the row.
+    """
+    safe_args: list[Any] = list(args) if args else []
+    safe_kwargs: dict[str, Any] = dict(kwargs) if kwargs else {}
+    return safe_args, safe_kwargs
+
+
+def upsert_by_celery_id(
+    session: Session,
+    *,
+    celery_task_id: str | None,
+    defaults: dict[str, Any],
+) -> TaskExecution:
+    """Fetch the row for ``celery_task_id``, or create it from ``defaults``.
+
+    ``defaults`` must include ``task_name`` (it's NOT NULL on the table).
+    Handlers never race on the same row within a worker process — Celery
+    serialises per-task signals — so this is upsert-by-read, no advisory
+    locks needed.
+    """
+    row: TaskExecution | None = None
+    if celery_task_id:
+        stmt = select(TaskExecution).where(TaskExecution.celery_task_id == celery_task_id)
+        row = session.execute(stmt).scalar_one_or_none()
+    if row is None:
+        row = TaskExecution(celery_task_id=celery_task_id, **defaults)
+        session.add(row)
+    else:
+        for key, value in defaults.items():
+            setattr(row, key, value)
+    return row
+
+
+def task_name_of(sender: Any, task: Any = None) -> str:
+    """Best-effort resolution of a task's registered name from signal args."""
+    return (
+        (isinstance(sender, str) and sender)
+        or getattr(task, "name", None)
+        or getattr(sender, "name", None)
+        or "unknown"
+    )
+
+
+def task_id_from(sender: Any = None, request: Any = None) -> str | None:
+    """Pull the Celery task UUID out of whichever signal-arg carries it.
+
+    Celery's signals pass the task id via three different shapes depending
+    on the signal: ``task_id=`` kwarg, ``request.id``, or ``sender.request.id``.
+    Centralising the probe keeps the per-handler code boring.
+    """
+    if request is not None:
+        tid = getattr(request, "id", None)
+        if tid:
+            return tid
+    sender_request = getattr(sender, "request", None)
+    return getattr(sender_request, "id", None) if sender_request is not None else None
+
+
+def jsonable_result(result: Any) -> dict[str, Any] | None:
+    """Wrap arbitrary task results in a JSON-storable shape."""
+    if result is None:
+        return None
+    if isinstance(result, dict):
+        return result
+    try:
+        return {"value": result}
+    except Exception:
+        return {"value": repr(result)}
+
+
+def render_traceback(einfo: Any, exception: BaseException | None) -> str | None:
+    """Prefer Celery's pre-formatted traceback; fall back to the live exception."""
+    tb = getattr(einfo, "traceback", None)
+    if tb:
+        return str(tb)
+    if exception is not None:
+        return "".join(tb_mod.format_exception(type(exception), exception, exception.__traceback__))
+    return None

simple_module_background_tasks-0.0.1/background_tasks/celery_app.py

@@ -0,0 +1,95 @@
+"""Build and configure the Celery application.
+
+Invoked from two places:
+
+- :meth:`BackgroundTasksModule.on_startup` in the web process, so the API
+  can enqueue tasks via ``app.state.background_tasks.celery.send_task(...)``.
+- ``scripts/run_worker.py`` at worker boot, so the worker process uses an
+  identical config (broker URL, signal handlers, autodiscovered tasks).
+
+Task discovery uses :py:meth:`celery.Celery.autodiscover_tasks` with the
+top-level package name of every installed module (enumerated via the
+``simple_module`` entry-point group). Any module that ships a ``tasks.py``
+is picked up automatically — no framework hook, no per-module registration.
+"""
+
+from __future__ import annotations
+
+import logging
+from importlib.metadata import entry_points
+
+from celery import Celery
+from celery.schedules import schedule
+from simple_module_core.discovery import ENTRY_POINT_GROUP
+
+from background_tasks.constants import (
+    INTERNAL_TASK_PURGE_OLD,
+    INTERNAL_TASK_SWEEP_STUCK,
+    MODULE_NAME,
+)
+from background_tasks.settings import BackgroundTasksSettings
+
+logger = logging.getLogger(__name__)
+
+
+def _discover_task_packages() -> list[str]:
+    """Return the top-level package name of every installed simple_module.
+
+    Celery's ``autodiscover_tasks`` imports ``<package>.tasks`` for each name
+    returned here, so any module that ships a ``tasks.py`` registers its
+    tasks without a per-module hook.
+    """
+    packages: set[str] = set()
+    for ep in entry_points(group=ENTRY_POINT_GROUP):
+        module_path = ep.value.split(":", 1)[0]
+        top_level = module_path.split(".", 1)[0]
+        packages.add(top_level)
+    return sorted(packages)
+
+
+def build_celery(settings: BackgroundTasksSettings) -> Celery:
+    """Construct a Celery app wired to the project's Redis broker."""
+    celery = Celery(MODULE_NAME)
+
+    celery.conf.update(
+        broker_url=settings.broker_url,
+        result_backend=settings.result_backend,
+        task_default_queue=settings.task_default_queue,
+        # ``task_track_started`` gives us the ``STARTED`` state so
+        # ``task_prerun`` can flip our row to ``running``.
+        task_track_started=True,
+        # ``task_acks_late`` + ``worker_prefetch_multiplier=1`` gives us
+        # at-least-once semantics, which matches how the admin UI asks users
+        # to think about retries — duplicates beat lost work.
+        task_acks_late=True,
+        worker_prefetch_multiplier=1,
+        task_serializer="json",
+        result_serializer="json",
+        accept_content=["json"],
+        timezone="UTC",
+        enable_utc=True,
+        broker_connection_retry_on_startup=True,
+        beat_schedule={
+            "background-tasks-sweep-stuck": {
+                "task": INTERNAL_TASK_SWEEP_STUCK,
+                "schedule": schedule(settings.stuck_sweep_interval_seconds),
+            },
+            "background-tasks-purge-old": {
+                "task": INTERNAL_TASK_PURGE_OLD,
+                "schedule": schedule(settings.purge_interval_seconds),
+            },
+        },
+        beat_scheduler="celery.beat:PersistentScheduler",
+    )
+
+    # Autodiscover across every installed simple_module — a module just ships
+    # a `tasks.py` and the worker picks it up.
+    packages = _discover_task_packages()
+    logger.info("Celery autodiscover_tasks across: %s", packages)
+    celery.autodiscover_tasks(packages, related_name="tasks", force=True)
+
+    # Side-effect import: connects signal handlers to this Celery instance's
+    # ``celery.signals.*`` globals. Safe to import repeatedly.
+    from background_tasks import signals  # noqa: F401
+
+    return celery

simple_module_background_tasks-0.0.1/background_tasks/constants.py

@@ -0,0 +1,75 @@
+"""Single source of truth for background_tasks module string literals.
+
+Anything that would otherwise become a magic string — table names, env-var
+prefixes, permission codes, route segments, page identifiers, task-status
+values — lives here so models, signals, services, endpoints, tests, and
+the frontend all agree on one spelling.
+"""
+
+from __future__ import annotations
+
+from enum import StrEnum
+
+# ── Module identity ─────────────────────────────────────────────
+MODULE_NAME = "background_tasks"
+MODULE_DISPLAY_NAME = "BackgroundTasks"
+TABLE_PREFIX = "background_tasks_"
+TABLE_TASK_EXECUTION = f"{TABLE_PREFIX}task_execution"
+
+# ── Env / settings ──────────────────────────────────────────────
+ENV_PREFIX = "SM_BG_TASKS_"
+
+# ── Permissions ─────────────────────────────────────────────────
+PERM_GROUP = "Background Tasks"
+PERM_VIEW = "background_tasks.view"
+PERM_MANAGE = "background_tasks.manage"
+
+# ── Routes ──────────────────────────────────────────────────────
+API_PREFIX = "/api/background_tasks"
+VIEW_PREFIX = "/admin/background-tasks"
+ADMIN_ROUTER_PREFIX = "/admin"
+
+# ── Menu ────────────────────────────────────────────────────────
+MENU_LABEL = "Background Tasks"
+MENU_ICON = "activity"
+MENU_ORDER = 80
+
+# ── Page identifiers ────────────────────────────────────────────
+# Kept as literals at the call site (see endpoints/views.py) so
+# ``make doctor``'s SM003/SM004 static analysis can match pages to renders.
+
+
+# ── Task statuses ───────────────────────────────────────────────
+class TaskStatus(StrEnum):
+    """Lifecycle state of a single task execution row."""
+
+    PENDING = "pending"
+    RUNNING = "running"
+    SUCCESS = "success"
+    FAILED = "failed"
+    STUCK = "stuck"
+    REVOKED = "revoked"
+    RETRYING = "retrying"
+
+
+RETRYABLE_STATUSES: frozenset[TaskStatus] = frozenset({TaskStatus.FAILED, TaskStatus.STUCK})
+TERMINAL_STATUSES: frozenset[TaskStatus] = frozenset(
+    {TaskStatus.SUCCESS, TaskStatus.FAILED, TaskStatus.STUCK, TaskStatus.REVOKED}
+)
+
+# ── Defaults ────────────────────────────────────────────────────
+DEFAULT_QUEUE = "default"
+DEFAULT_BROKER_URL = "redis://localhost:6379/0"
+DEFAULT_RESULT_BACKEND = "redis://localhost:6379/1"
+DEFAULT_STUCK_AFTER_SECONDS = 300
+DEFAULT_STUCK_SWEEP_INTERVAL_SECONDS = 60
+DEFAULT_PURGE_INTERVAL_SECONDS = 60 * 60 * 24
+DEFAULT_RETENTION_DAYS = 14
+DEFAULT_MAX_RETRIES = 3
+
+# ── Internal task names ─────────────────────────────────────────
+INTERNAL_TASK_SWEEP_STUCK = "background_tasks.sweep_stuck_tasks"
+INTERNAL_TASK_PURGE_OLD = "background_tasks.purge_old_executions"
+# Harmless round-trip task; only wired into CI smoke tests and local dev —
+# not scheduled, not invoked by other modules.
+DEMO_ECHO_TASK = "background_tasks.demo_echo"

simple_module_background_tasks-0.0.1/background_tasks/contracts/__init__.py

@@ -0,0 +1 @@
+"""Public contracts for the BackgroundTasks module."""

simple_module_background_tasks-0.0.1/background_tasks/contracts/events.py

@@ -0,0 +1,26 @@
+"""Public events emitted by the BackgroundTasks module."""
+
+from __future__ import annotations
+
+import uuid
+from dataclasses import dataclass
+
+from simple_module_core.events import Event
+
+
+@dataclass
+class TaskFailed(Event):
+    """A task transitioned to ``failed`` — subscribers may alert/log."""
+
+    task_execution_id: uuid.UUID
+    task_name: str
+    exception_type: str | None
+
+
+@dataclass
+class TaskRetried(Event):
+    """A failed/stuck task was manually retried via the admin UI."""
+
+    original_id: uuid.UUID
+    new_id: uuid.UUID
+    task_name: str

simple_module_background_tasks-0.0.1/background_tasks/contracts/schemas.py

@@ -0,0 +1,66 @@
+"""DTOs returned by the BackgroundTasks admin API / views."""
+
+from __future__ import annotations
+
+import uuid
+from datetime import datetime
+from typing import Any
+
+from pydantic import ConfigDict
+from sqlmodel import SQLModel
+
+from background_tasks.constants import TaskStatus
+
+
+class TaskExecutionListItem(SQLModel):
+    """Compact row for the admin listing table."""
+
+    model_config = ConfigDict(from_attributes=True)
+
+    id: uuid.UUID
+    celery_task_id: str | None = None
+    task_name: str
+    status: TaskStatus
+    queue: str
+    retries: int
+    worker: str | None = None
+    queued_at: datetime | None = None
+    started_at: datetime | None = None
+    finished_at: datetime | None = None
+    exception_type: str | None = None
+    retried_from_id: uuid.UUID | None = None
+
+
+class TaskExecutionDetail(SQLModel):
+    """Full row for the detail page (adds args/kwargs/result/traceback)."""
+
+    model_config = ConfigDict(from_attributes=True)
+
+    id: uuid.UUID
+    celery_task_id: str | None = None
+    task_name: str
+    status: TaskStatus
+    queue: str
+    args: list[Any] = []
+    kwargs: dict[str, Any] = {}
+    result: dict[str, Any] | None = None
+    traceback: str | None = None
+    exception_type: str | None = None
+    worker: str | None = None
+    retries: int = 0
+    retried_from_id: uuid.UUID | None = None
+    queued_at: datetime | None = None
+    started_at: datetime | None = None
+    finished_at: datetime | None = None
+    heartbeat_at: datetime | None = None
+
+
+class TaskExecutionListResponse(SQLModel):
+    """Paginated response shape used by both the API and Inertia views."""
+
+    items: list[TaskExecutionListItem]
+    total: int
+    page: int
+    per_page: int
+    status: TaskStatus | None = None
+    task_name: str | None = None

simple_module_background_tasks-0.0.1/background_tasks/deps.py

@@ -0,0 +1,19 @@
+"""FastAPI dependencies for the BackgroundTasks module."""
+
+from __future__ import annotations
+
+from fastapi import Depends, Request
+from simple_module_core.events import EventBus
+from simple_module_db.deps import get_db
+from sqlalchemy.ext.asyncio import AsyncSession
+
+from background_tasks.service import BackgroundTaskService
+
+
+async def get_background_task_service(
+    request: Request,
+    db: AsyncSession = Depends(get_db),
+) -> BackgroundTaskService:
+    services = request.app.state.background_tasks
+    bus: EventBus = request.app.state.sm.event_bus
+    return BackgroundTaskService(db=db, celery=services.celery, event_bus=bus)