simple-module-background-tasks 0.0.1__py3-none-any.whl

background_tasks/tasks.py

@@ -0,0 +1,105 @@
+"""Internal Celery tasks registered by the background_tasks module itself.
+
+- ``sweep_stuck_tasks`` flips ``running`` rows whose heartbeat has gone stale
+  to ``stuck`` so the UI surfaces them and they become eligible for retry.
+- ``purge_old_executions`` deletes terminal rows older than the configured
+  retention so the history table stays bounded.
+
+Both are driven by Celery beat; see :mod:`.celery_app`.
+"""
+
+from __future__ import annotations
+
+import logging
+import os
+from datetime import UTC, datetime, timedelta
+
+from celery import shared_task
+from sqlalchemy import delete, update
+
+from background_tasks.constants import (
+    DEFAULT_RETENTION_DAYS,
+    DEFAULT_STUCK_AFTER_SECONDS,
+    DEMO_ECHO_TASK,
+    INTERNAL_TASK_PURGE_OLD,
+    INTERNAL_TASK_SWEEP_STUCK,
+    TERMINAL_STATUSES,
+    TaskStatus,
+)
+from background_tasks.models import TaskExecution
+from background_tasks.settings import BackgroundTasksSettings
+from background_tasks.sync_db import sync_session
+
+logger = logging.getLogger(__name__)
+
+
+def _load_settings() -> BackgroundTasksSettings:
+    """Build settings inside the worker process.
+
+    The web-process ``register_settings`` attached them to ``app.state``,
+    but the worker never sees that ``app.state``. Re-parsing from env here
+    is the same deterministic source of truth.
+    """
+    return BackgroundTasksSettings()
+
+
+@shared_task(name=DEMO_ECHO_TASK)
+def demo_echo(message: str = "hello") -> dict[str, str]:
+    """Trivial task used for end-to-end smoke tests of the Celery pipeline.
+
+    Returns the input wrapped with a worker timestamp so a successful
+    execution produces a non-empty ``result`` column in the admin UI.
+    """
+    logger.info("demo_echo received message=%r", message)
+    return {"message": message, "at": datetime.now(UTC).isoformat()}
+
+
+@shared_task(name=INTERNAL_TASK_SWEEP_STUCK)
+def sweep_stuck_tasks() -> int:
+    """Flip ``running`` rows with stale heartbeats to ``stuck``.
+
+    Returns the number of rows flipped — handy for metrics/log scraping.
+    """
+    # Avoid import-time coupling to settings (beat schedules this task
+    # before the worker has hydrated settings in some edge cases).
+    stuck_after = int(
+        os.environ.get("SM_BG_TASKS_STUCK_AFTER_SECONDS", DEFAULT_STUCK_AFTER_SECONDS)
+    )
+    cutoff = datetime.now(UTC) - timedelta(seconds=stuck_after)
+
+    with sync_session() as session:
+        stmt = (
+            update(TaskExecution)
+            .where(
+                TaskExecution.status == TaskStatus.RUNNING,
+                TaskExecution.heartbeat_at < cutoff,
+            )
+            .values(status=TaskStatus.STUCK, finished_at=datetime.now(UTC))
+        )
+        result = session.execute(stmt)
+        count = result.rowcount or 0
+        if count:
+            logger.warning("sweep_stuck_tasks flipped %d row(s) to stuck", count)
+        return count
+
+
+@shared_task(name=INTERNAL_TASK_PURGE_OLD)
+def purge_old_executions() -> int:
+    """Delete terminal rows older than the retention window."""
+    retention_days = int(os.environ.get("SM_BG_TASKS_RETENTION_DAYS", DEFAULT_RETENTION_DAYS))
+    cutoff = datetime.now(UTC) - timedelta(days=retention_days)
+
+    with sync_session() as session:
+        result = session.execute(
+            delete(TaskExecution)
+            .where(TaskExecution.status.in_(list(TERMINAL_STATUSES)))
+            .where(TaskExecution.finished_at < cutoff)
+        )
+        count = result.rowcount or 0
+        if count:
+            logger.info(
+                "purge_old_executions removed %d row(s) older than %d days",
+                count,
+                retention_days,
+            )
+        return count

simple_module_background_tasks-0.0.1.dist-info/METADATA

@@ -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.dist-info/RECORD

@@ -0,0 +1,33 @@
+background_tasks/__init__.py,sha256=60_v6M-VjBdOGQ4fcXqol8-Y3I5Jks1FGW28HYicjdM,74
+background_tasks/_signal_support.py,sha256=lVkUJVETou-6JbNx0PWYUYftuxDZHJdK8m0usPlE7sk,3592
+background_tasks/celery_app.py,sha256=wYJ_lYJhL47eKRTra5YXRTViGEmUvFD1vonhsBzBSUc,3637
+background_tasks/constants.py,sha256=hU1ixbdDO2ljrRVSl8GtffTZ5jmev6gyQ61lK5IWbio,3622
+background_tasks/deps.py,sha256=lIeYAF1LpH1V0TmA1En837dctwG1Us9ofj9Mao4XFN4,640
+background_tasks/models.py,sha256=03LFc5Mwwt1b2YIXxsqC5eJabGqY0daMaXq7SwctINo,3119
+background_tasks/module.py,sha256=cjigSk2NLw5q6Q6tNNiCk0SZH2alm4FKMSzm_P8-Gt4,4167
+background_tasks/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+background_tasks/service.py,sha256=SGqxmX4qcU5Lxlp1ryc-lK8YBXCwQl6KB_KJBaonGWE,4629
+background_tasks/services.py,sha256=qcozJCqz-uk-l3B0ia2nbAMVJlnRMpB8qqQABBPtap4,719
+background_tasks/settings.py,sha256=cfhxR29OVPFf4efec9v_JhcHfXYh1x-J-Y6Pe43RG5k,3476
+background_tasks/signals.py,sha256=-U55iJZWi8olA7xgXEXXFhIiyVce1hAVka7RVAI1E34,9028
+background_tasks/sync_db.py,sha256=yCsaMTlVh6-ts4-SVudwjaGozy4ldkIdC0DSQiHSzgQ,2713
+background_tasks/tasks.py,sha256=i_XKnLsFh4bol-p1RYw5O7LmzYL5aZkZ2W6bxckoBT0,3656
+background_tasks/contracts/__init__.py,sha256=sqrpzp0NbQstATtJL9DeZEPHCZCbAA1kGAI1ws4ONU8,55
+background_tasks/contracts/events.py,sha256=03pbS_ZuD1PR_psChc9s847IGS3Q91njf5XLgkE7wtM,561
+background_tasks/contracts/schemas.py,sha256=YCoYjc_IoMw_E3IL6h8bNkj7ju_nn23qgUHPGeyo40k,1766
+background_tasks/endpoints/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+background_tasks/endpoints/api_admin.py,sha256=YQIDdfUID2grjHifQ3xbSuiBb6yW1PB5FlVXJuSmkM8,1993
+background_tasks/endpoints/views.py,sha256=B5LNvuQ5uhJgGhaOJk5IQEBvWHTOKloxHhRxz_amCeI,2140
+background_tasks/locales/en.json,sha256=T2EZWSVf26winxDH3f-cBOCpnNDff5Hj4Xqs5NMm4W8,1576
+background_tasks/pages/Detail.tsx,sha256=6ED26ixYl5PPoKvAegJAfA-7HwcJdXdK-hdDbttiWlI,6279
+background_tasks/pages/Index.tsx,sha256=g7dIR733475v9UxkYyXI6VMYX3Ot8Mrn_il5FyuksvY,6341
+background_tasks/pages/constants.ts,sha256=lQCkUOcq7rwRWj2xHxdvMZH7KAx4RJuPK9CgfCcg2eg,1357
+background_tasks/pages/retry.ts,sha256=duQKWwZm4Q5WEXrT9m3XQHU_qBVg8MIGldFQSkXzHd4,1280
+background_tasks/pages/components/ExecutionRow.tsx,sha256=emw_NWVXgjZzsS7n5NgygogvZr4OIrby02l_21EUHTg,2911
+background_tasks/pages/components/RetryConfirmDialog.tsx,sha256=DLW_5V8SahdBdsUEtMMOQ4575S0oPzknA1UjhCcoO5s,1118
+background_tasks/package.json,sha256=CPFVBDyd3BL5Y1903hPyTOeLBoVeeiIQsDBDqZgAIcg,394
+simple_module_background_tasks-0.0.1.dist-info/METADATA,sha256=KFE6tswrIg9Kw0ayoj9Sn93vxuhxR70Mh3HuipI5n_A,3142
+simple_module_background_tasks-0.0.1.dist-info/WHEEL,sha256=QccIxa26bgl1E6uMy58deGWi-0aeIkkangHcxk2kWfw,87
+simple_module_background_tasks-0.0.1.dist-info/entry_points.txt,sha256=b3_GVa5rtiTO0l6bM04dIXQNT208aQ48BGFVqwhbXxs,81
+simple_module_background_tasks-0.0.1.dist-info/licenses/LICENSE,sha256=Yn66lhLklsF5p7pa85_ksQrJ79Q-FgOaUAHevLBjer4,1068
+simple_module_background_tasks-0.0.1.dist-info/RECORD,,

simple_module_background_tasks-0.0.1.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.29.0
+Root-Is-Purelib: true
+Tag: py3-none-any

simple_module_background_tasks-0.0.1.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[simple_module]
+background_tasks = background_tasks.module:BackgroundTasksModule

simple_module_background_tasks-0.0.1.dist-info/licenses/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.