simple_module_background_tasks
Celery + Redis background-task module for simple_module apps. Provides a pre-configured Celery instance, a task registration hook, and an admin UI for monitoring + retrying failed/stuck tasks.
Install
pip install simple_module_background_tasks
Requires a Redis broker. The broker / result-backend URLs are module settings (broker_url, default redis://localhost:6379/0; result_backend, default redis://localhost:6379/1) configured from the DB settings store via the admin UI — they are not read from environment variables at runtime. These fields are requires_restart (changing them needs a worker/web restart).
What it provides
- Zero-config task discovery — any installed module that ships a
tasks.pyhas its tasks autodiscovered (celery.autodiscover_tasksimports<package>.tasksfor every installed module). No per-module registration hook. - Admin UI at
/admin/background-tasks— list recent runs, retry failed, inspect tracebacks (gated by thebackground_tasks.viewpermission). build_celery(settings)factory inbackground_tasks.celery_app, plusbind_task_context/get_log_context/install_log_filterexported from the package root (import namebackground_tasks, distribution namesimple_module_background_tasks).
Usage
Declare a task in a module's tasks.py with Celery's @shared_task — it's autodiscovered, no registration hook needed:
# modules/reports/reports/tasks.py
from celery import shared_task
@shared_task(name="reports.generate")
def generate_report(report_id: int) -> None: ...
Declaring background_tasks as a depends_on ensures the Celery app is built before your tasks run:
class ReportsModule(ModuleBase):
meta = ModuleMeta(name="reports", depends_on=["background_tasks"])
Enqueue from an endpoint:
generate_report.delay(report_id=42)
Run a worker locally (the scaffolded host ships a scripts/run_worker.py that builds the app via build_celery):
uv run celery -A scripts.run_worker:celery worker -l info
uv run celery -A scripts.run_worker:celery beat -l info
Worker log context
Every worker log line automatically carries the Celery task identifiers
that fired it. A LogContextFilter is attached when the Celery app is
built (build_celery) and the task_prerun / task_postrun signals
bind task_id + task_name into contextvars for the task's duration:
{"level": "INFO", "logger": "reports.tasks", "message": "ingest done",
"task_id": "9c2a…", "task_name": "reports.generate"}
Use bind_task_context(...) to attach app-level identifiers (the
domain job_id that named a Celery task is the canonical example):
from background_tasks import bind_task_context
from celery import shared_task
@shared_task
def process_dataset(job_id: int) -> None:
with bind_task_context(job_id=job_id):
logger.info("starting ingest") # now carries job_id too
Bindings nest cleanly and restore on exit. structlog users can mount the
same contextvars directly via structlog.contextvars.merge_contextvars.
Depends on
simple_module_core,simple_module_db,simple_module_hosting,simple_module_settingscelery[redis]>=5.4,redis>=5
License
MIT — see LICENSE.
1 maintainer
Metadata
1 maintainer
Release files for simple-module-background-tasks 0.0.36
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | |
|---|---|---|---|---|
| simple_module_background_tasks-0.0.36.tar.gz | 108.9 kB | With provenance | Details |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Reset |
|---|---|---|---|---|
| simple_module_background_tasks-0.0.36-py3-none-any.whl | Python 3 | none | any | Details |
Total release size: 204.4 kB
Release files / simple_module_background_tasks-0.0.36.tar.gz
| Download URL | simple_module_background_tasks-0.0.36.tar.gz |
|---|---|
| Size | 108.9 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
13f00cde4803a0aab24fcddc1c9fc55d8e62c2f478bb5925473b874f5b1e87a8
|
|
BLAKE2b-256 checksum How to use checksums |
680b7d6ce32d9d73fb724db26167e10580b0aff3e9afbc367cbd9cbd1d41043b
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Oct 13, 2026.
Transparency logRelease files / simple_module_background_tasks-0.0.36-py3-none-any.whl
| Download URL | simple_module_background_tasks-0.0.36-py3-none-any.whl |
|---|---|
| Size | 95.5 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
2577f039a697d32fcb77304d166224d54f967eef808441ccc447c5d6641852c3
|
|
BLAKE2b-256 checksum How to use checksums |
52ba48fd5de248a8a726c36179fd23f1af1293c9e6e64f93a5d96797e8cc4019
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Oct 13, 2026.
Transparency logSecurity for simple-module-background-tasks 0.0.36
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
Full provenance
All 2 files in this release have been uploaded with provenance metadata.
Attestation for simple_module_background_tasks-0.0.36.tar.gz
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Oct 13, 2026.
Transparency logA note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.
