Metadata-Version: 2.5
Name: z4j-rq
Version: 1.13.0
Summary: z4j RQ queue engine adapter (Apache 2.0)
Project-URL: Changelog, https://github.com/z4jdev/z4j-rq/blob/main/CHANGELOG.md
Project-URL: Documentation, https://docs.z4j.com
Project-URL: Homepage, https://z4j.com
Project-URL: Issues, https://github.com/z4jdev/z4j-rq/issues
Project-URL: Source, https://github.com/z4jdev/z4j-rq
Author: z4j contributors
License: Apache-2.0
License-File: LICENSE
Keywords: queue,redis,rq,task,z4j
Classifier: Development Status :: 5 - Production/Stable
Classifier: Framework :: AsyncIO
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: System :: Distributed Computing
Classifier: Typing :: Typed
Requires-Python: >=3.11
Requires-Dist: rq>=1.10.1
Requires-Dist: z4j-bare<2,>=1.13.0
Requires-Dist: z4j-core<2,>=1.13.0
Description-Content-Type: text/markdown

# z4j-rq

[![PyPI version](https://img.shields.io/pypi/v/z4j-rq.svg)](https://pypi.org/project/z4j-rq/)
[![Python](https://img.shields.io/pypi/pyversions/z4j-rq.svg)](https://pypi.org/project/z4j-rq/)
[![License](https://img.shields.io/pypi/l/z4j-rq.svg)](https://github.com/z4jdev/z4j-rq/blob/main/LICENSE)

The RQ engine adapter for [z4j](https://z4j.com).

Streams supported RQ job lifecycle events from your workers to z4j
and accepts operator control actions from the dashboard. Pair with
z4j-rqscheduler to manage periodic schedules.

## Compatibility

- RQ 1.10.1+ (no upper bound)
- Python 3.11+

Full per-adapter matrix at <https://docs.z4j.com/reference/compatibility/>.

## What it ships

| Capability | Notes |
|---|---|
| Job lifecycle events | started, succeeded, failed (a stopped job is reported as failed; revoked only through the opt-in `capture_stopped` job callback) |
| Job discovery | task names observed in recent jobs on each known queue and in its started, finished and failed registries |
| Submit / retry / cancel | direct against the RQ queue |
| Bulk retry | retries brain-resolved, project-owned explicit IDs by reference; never sweeps the broker-wide failed registry |
| Purge queue | with confirm-token guard |
| Reconcile task | via Redis-backed job hash lookup |

## Install

```bash
pip install z4j-rq z4j-rqscheduler
```

Pair with a framework adapter:

```bash
pip install z4j-django  z4j-rq z4j-rqscheduler   # Django
pip install z4j-flask   z4j-rq z4j-rqscheduler   # Flask
pip install z4j-fastapi z4j-rq z4j-rqscheduler   # FastAPI
pip install z4j-bare    z4j-rq z4j-rqscheduler   # framework-free worker
```

## Pairs with

- [`z4j-rqscheduler`](https://github.com/z4jdev/z4j-rqscheduler), schedule adapter for rq-scheduler

## Reliability

- For POSIX fork workers, select the memory-corrected worker through RQ's
  standard CLI extension point:

  ```bash
  rq worker --worker-class z4j_rq.worker.Worker default
  ```

  Keep your existing queues, Redis options, settings module and z4j startup
  integration. In Python, import `Worker` from `z4j_rq.worker` instead of `rq`.
  The worker sets each job's environment only in its child process, preventing
  the parent-side native allocation growth reproduced with stock RQ on glibc.
  RQ retains execution, monitoring, timeout, retry and shutdown handling; the
  RQ 1.x session and RQ 2.x process-group behavior are preserved.
- Selecting this class is explicit. Installing the adapter alone does not
  replace stock or custom workers. `SimpleWorker`, `SpawnWorker` and Windows
  workers are outside this fork-worker repair. If you retain an affected stock
  fork worker, use `--max-jobs 50000` with a process manager configured to
  restart successful exits. Normal supervision and application memory limits
  remain useful with either worker.
- Lifecycle-capture failures are isolated from RQ workers and job hooks;
  capture hooks make no brain network request inline.
- The in-process event queue and SQLite outbound buffer are bounded. A full
  queue evicts its oldest queued event to admit the new one, up to three
  times. Queue overflow drops new events only if that cannot make room.
  Buffer pressure evicts oldest rows. Every loss is logged.

## Documentation

Full docs at [docs.z4j.com/engines/rq/](https://docs.z4j.com/engines/rq/).

## License

Apache-2.0, see [LICENSE](https://github.com/z4jdev/z4j-rq/blob/main/LICENSE).
The fork boundary adapted from RQ retains its BSD-2-Clause notice in
[`RQ_LICENSE`](https://github.com/z4jdev/z4j-rq/blob/main/src/z4j_rq/RQ_LICENSE), included in the installed package.

## Links

- Homepage: https://z4j.com
- Documentation: https://docs.z4j.com
- PyPI: https://pypi.org/project/z4j-rq/
- Issues: https://github.com/z4jdev/z4j-rq/issues
- Changelog: [CHANGELOG.md](https://github.com/z4jdev/z4j-rq/blob/main/CHANGELOG.md)
- Security: security@z4j.com (see [SECURITY.md](https://github.com/z4jdev/z4j-rq/blob/main/SECURITY.md))
