Metadata-Version: 2.4
Name: simple_module_background_tasks
Version: 0.0.7
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.7
Requires-Dist: simple-module-db==0.0.7
Requires-Dist: simple-module-hosting==0.0.7
Requires-Dist: simple-module-settings==0.0.7
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).
