How it works¶

django-absurd is a thin layer: Django's task API on top, Absurd's engine underneath. You mostly write plain Django tasks — this page explains what's happening below, and links to the source docs for each piece.

The flow¶

You enqueue a task onto a queue. A worker claims it and creates a run. The task can be broken into steps (checkpoints) whose results are saved so they don't re-execute on retry. A task can also sleep or wait for an event, suspending until it's time to resume.

→ Absurd: Concepts (durable execution, tasks, steps, runs, events, retries).

Queues¶

A named lane tasks flow through. Declare them in your configuration; they're provisioned at migrate and on worker start. Queues are unpartitioned by default. Partitioned storage is declarable but experimental — not tested yet, and its partition lifecycle (provisioning + detaching old partitions) is not automated; don't rely on it in production.

→ Absurd: Storage (queue types, partitioning, retention).

Runs, retries & checkpoints¶

Each attempt at a task is a run. A failed task is retried up to its max_attempts. Work wrapped in a step is checkpointed — its result is persisted and skipped on the next run — so retries and resumes don't redo completed work.

→ Absurd: Concepts.

Events & waits¶

A task can suspend until a named event is emitted, or sleep until a time, then resume where it left off (the worker wakes it — no external scheduler).

→ Absurd: Concepts.

Workers¶

python manage.py absurd_worker --queue reports

One worker runs both sync and async def tasks (async on an event loop, sync in a thread pool). On start it does a full sync — provisioning every declared queue and rebuilding the admin views — then polls for work.

Admin & ORM introspection¶

When django.contrib.admin is installed, django-absurd registers read-only admin pages for Tasks, Runs, Checkpoints, Events, Waits, and the Queues catalog — each spanning all queues, filterable by queue. The same models are public for querying:

from django_absurd.models import Task

Task.objects.filter(queue="reports", state="failed")

→ Django: The admin site.

Schema & migrations¶

Absurd's schema ships as a Django migration (offline — the SQL comes from the pinned Absurd version, never fetched at migrate time). migrate installs it and provisions declared queues.

→ Absurd: Database setup.