Skip to content
z4j docs

Dramatiq

Requires Dramatiq 1.14+ and <3, Python 3.11+. See the compatibility matrix for the full pin string.

Install

Section titled “Install”
Terminal window
pip install z4j-dramatiq

What it captures

Section titled “What it captures”

z4j registers a Middleware on the broker:

from dramatiq import get_broker
from z4j_dramatiq import DramatiqEngineAdapter


broker = get_broker()
adapter = DramatiqEngineAdapter(broker=broker)
adapter.connect_signals()

The framework adapters do this automatically. For bare usage, add it yourself.

Middleware hook z4j event
after_enqueue task.received
before_process_message task.started
after_process_message (no exception) task.succeeded
retry chosen by Retries task.retried
exhausted exception task.failed

Actions

Section titled “Actions”
Verb How
submit sends through the registered actor, or a raw message for a remote actor
retry re-sends only complete operator-supplied replacement args and kwargs
cancel prevents pending work from starting, but only with z4j-dramatiq[abort] and a real dramatiq_abort.Abortable middleware in this broker's stack
purge_queue broker.flush(queue_name)

Stock Dramatiq does not advertise cancel. The adapter promotes it only when the abort extra is installed and the broker contains a real dramatiq_abort.Abortable instance. Configure that middleware using dramatiq-abort's event backend before constructing the adapter. z4j always requests its pending-only AbortMode.CANCEL: a pending message is prevented from starting, but running work is never interrupted. Without both the package and middleware, a direct cancel call fails closed.

Bulk retry and dead-letter replay remain unavailable because Dramatiq has no portable primitive that satisfies those z4j contracts.

Middleware ordering

Section titled “Middleware ordering”

Use DramatiqEngineAdapter.connect_signals(). It inserts Z4JMiddleware before Retries in the stored list because Dramatiq runs after_* hooks in reverse order. This lets Retries make its decision before z4j classifies the attempt.

adapter = DramatiqEngineAdapter(broker=broker)
adapter.connect_signals()

Caveats

Section titled “Caveats”
  • No chord/group primitive in Dramatiq, so there is no chord-aware UI.
  • z4j rejects submit or retry requests carrying eta or priority; the adapter cannot honor those options portably across its supported brokers.

Config

Section titled “Config”
# Django settings
Z4J = {
    ...,
    "dramatiq": {"broker": "myapp.broker.redis_broker"},
}

See scheduler: APScheduler - the typical scheduler for Dramatiq apps.