arq

Requires arq 0.26+ and <1, Python 3.10+. See the compatibility matrix for the full pin string.

Install

pip install z4j-arq

What it captures

arq doesn’t expose signals. z4j uses worker on_job_start / on_job_end hooks and wraps the enqueue_job method.

Source	z4j event
`ArqRedis.enqueue_job`	`task_sent`
`on_job_start` hook	`task_started`
`on_job_end` (success=True)	`task_succeeded`
`on_job_end` (success=False)	`task_failed`
retries (tried > 1)	`task_retry` (synthetic)

Wiring

arq’s config is a WorkerSettings class. attach_to_worker_settings chains z4j’s on_job_start and on_job_end hooks onto either a class (before arq builds the Worker) or a Worker instance (from inside on_startup):

from z4j_arq import ArqEngineAdapter, attach_to_worker_settings

adapter = ArqEngineAdapter()

class WorkerSettings:
    functions = [my_task, ...]

# Chain z4j's hooks onto the class BEFORE arq instantiates the Worker.
attach_to_worker_settings(WorkerSettings, adapter=adapter)

If you need to call it from inside on_startup instead (e.g. when the Worker is constructed via the arq CLI), pass ctx['worker'] as the target. The call is idempotent.

Actions

Verb	How
`retry`	polyfill - `arq_redis.enqueue_job(function_name, *args)` with original payload
`cancel`	`arq_redis.abort_job(job_id)` - works pre-start; mid-run relies on your function’s cancellation cooperation
`purge_queue`	`arq_redis.flushdb()` (scoped to arq prefix)

Cron jobs

arq’s cron jobs are defined in WorkerSettings.cron_jobs. Same as Huey - code-only discovery, read-only. See scheduler: arq-cron.

Caveats

No chord/group.
Max job size limited by Redis payload; large pickled args may be truncated in events (see redaction).
Worker pool size appears as metadata.max_jobs in the agent drawer.

FastAPI auto-wire

z4j-fastapi’s attach_z4j lifespan helper accepts an arq_redis_settings kwarg (an arq.RedisSettings or a live pool); pass it once and the framework adapter calls attach_to_worker_settings for you. If z4j-arq is not installed, the kwarg is rejected with a clear error.