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).enqueue_after_commit(db, task, *args, **kwargs)— publish a task only once the session's transaction commits, never on rollback.heartbeat()— called from a long task body, keeps the stuck sweep from flagging it;@shared_task(stuck_after=seconds)sets a per-task stuck threshold. See the module docs for both.
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
Routing, tuning and per-worker module subsets
A module can ship a light task_config.py (TASK_ROUTES, QUEUES, optional
BEAT_SCHEDULE) that is read without importing tasks.py. The
task_routes_override setting re-routes tasks at runtime, and the Workers page
lists the effective routes. Tuning settings (visibility_timeout_seconds,
worker_max_tasks_per_child, task_time_limit, worker_concurrency, ...) and a
raw SM_BG_TASKS_CELERY_OVERRIDES (env only, unsafe keys refused) default to Celery's own defaults.
SM_BG_TASKS_WORKER_QUEUES=gpu,default make worker consumes only those queues
and imports only the modules whose QUEUES overlap (see SM_BG_TASKS_INCLUDE_MODULES /
SM_BG_TASKS_EXCLUDE_MODULES; env only, not DB settings). Full details in docs/modules/background_tasks.md.
Durable events
This module is the transport behind bus.publish_durable(event, db): the event
is written to an outbox table in the caller's transaction and delivered by a
worker to every bus.subscribe_durable(...) handler, at least once, with
backoff, after the commit. Writes a handler makes through ctx.db land exactly
once. Undelivered and dead rows are on /admin/background-tasks/outbox. Full
details in docs/modules/background_tasks.md § Durable events.
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.37
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.37.tar.gz | 175.3 kB | With provenance | Details |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Reset |
|---|---|---|---|---|
| simple_module_background_tasks-0.0.37-py3-none-any.whl | Python 3 | none | any | Details |
Total release size: 322.7 kB
Release files / simple_module_background_tasks-0.0.37.tar.gz
| Download URL | simple_module_background_tasks-0.0.37.tar.gz |
|---|---|
| Size | 175.3 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
0c3daeeb87b99038a02b26dda83775a01ef7beb96ffa9f8f2cbb54d324966e8c
|
|
BLAKE2b-256 checksum How to use checksums |
279ff81c5b671e60521427577d06fd44296837839a49ef22296eec677d935975
|
| 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 19, 2026.
Transparency logRelease files / simple_module_background_tasks-0.0.37-py3-none-any.whl
| Download URL | simple_module_background_tasks-0.0.37-py3-none-any.whl |
|---|---|
| Size | 147.4 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
6cdddc383d877e5159c1a54d5f57e9598ef92102e50ebbd372dbbe658fc11c7e
|
|
BLAKE2b-256 checksum How to use checksums |
a8bd78f3baa52cb94d06387fcf9c6028055656b7e02da563a76b0900a2ef3115
|
| 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 19, 2026.
Transparency logSecurity for simple-module-background-tasks 0.0.37
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.37.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 19, 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.
