arq

Requires arq 0.26+ and <1, Python 3.11+. 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.

Source	z4j event
`on_job_start` hook	`task.started`
`on_job_end` (success=True)	`task.succeeded`
`on_job_end` (success=False)	`task.failed`

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 arq.connections import RedisSettings
from z4j_arq import ArqEngineAdapter, attach_to_worker_settings

async def my_task(ctx):
    ...

class WorkerSettings:
    functions = [my_task]
    redis_settings = RedisSettings()

adapter = ArqEngineAdapter(
    redis_settings=WorkerSettings.redis_settings,
    function_names=["myapp.worker.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
`submit`	`ArqRedis.enqueue_job(function_name, args, *kwargs)`
`cancel`	`Job.abort(timeout=10)`; success requires arq to confirm the abort

Retry-by-id, bulk retry, and purge are not advertised. A safe re-submission requires the function name and both complete argument collections; use submit_task with those explicit inputs.

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.
Task arguments are not read from arq's Redis job payload for lifecycle events.
Worker pool size appears as metadata.max_jobs in the agent drawer.

FastAPI auto-wire

Construct the engine adapter with redis_settings, then attach its hooks to the worker settings before arq builds the worker, as shown above.