Metadata-Version: 2.5
Name: z4j-huey
Version: 1.12.1
Summary: z4j Huey queue engine adapter (Apache 2.0)
Project-URL: Changelog, https://github.com/z4jdev/z4j-huey/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-huey/issues
Project-URL: Source, https://github.com/z4jdev/z4j-huey
Author: z4j contributors
License: Apache-2.0
License-File: LICENSE
Keywords: huey,queue,redis,sqlite,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: huey>=2.4
Requires-Dist: z4j-bare<2,>=1.12.0
Requires-Dist: z4j-core<2,>=1.12.0
Description-Content-Type: text/markdown

# z4j-huey

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

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

Streams supported Huey task lifecycle events from your consumers to the z4j
brain and accepts operator control actions from the dashboard. Pair
with z4j-hueyperiodic to surface `@periodic_task` schedules.

## What it ships

| Capability | Notes |
|---|---|
| Task lifecycle events | enqueued, started, succeeded, failed, retried, revoked |
| Timeouts and rate limits (Huey 3) | a timeout that is not retried is reported as failed, a rate limit that is not retried as revoked; either one followed by a retry is reported as the retry alone |
| Task discovery | Huey's in-process task registry |
| Submit | direct against the Huey instance |
| Retry | requires both complete operator-supplied replacement args and kwargs because Huey cannot recover the original signature by task id |
| Cancel | prevents a pending task from starting; Huey cannot interrupt already-running work |
| Reconcile task | probes Huey's result store; absence reports honest `unknown` |

Not supported (Huey's storage model can't back them faithfully, so
the adapter declines the capability instead of faking it): bulk
retry, queue purge, dead-letter requeue, worker restart, rate
limiting.
Cancel uses Huey's revoke-by-id primitive. It prevents a pending task from
starting but cannot stop running work.

## Compatibility

- Huey 2.4 and later, with no upper bound: Huey 2 and Huey 3 are both
  supported. The package's suite runs a real Huey consumer on Huey 2.4.0 and
  on Huey 3.4.0 and asserts the exact sequence of events for every lifecycle
  path on each: one terminal event per task, and never a terminal event and a
  retry for the same attempt.
- Huey older than 2.5.3 has no enqueue signal. On those releases a task first
  appears when it starts, and its arguments are not captured.
- Storage backends: redis, sqlite, in-memory
- Python 3.11+

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

### Changing the Huey major

Upgrading Huey from 2 to 3 needs nothing from the adapter: a Huey 3 consumer
reads the work a Huey 2 process enqueued.

Downgrading Huey from 3 to 2 loses queued work unless you drain first. Huey 3
writes a wider queue message than Huey 2 can read, so a Huey 2 consumer raises
`TypeError` on every task a Huey 3 process enqueued and the task is gone; a
scheduled task that has come due is dropped the same way. Before downgrading
Huey, stop enqueueing and let the queue and the schedule empty. Run one Huey
major in every process that shares a queue, including the process that hosts
the z4j agent.

This is Huey's own queue format, and z4j does not change it in either
direction: a retry or a schedule fire is enqueued through your Huey instance
in that Huey's format, and the adapter reads task state from the result store,
which both majors read from each other.

## Install

```bash
pip install z4j-huey z4j-hueyperiodic
```

Pair with a framework adapter:

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

## Pairs with

- [`z4j-hueyperiodic`](https://github.com/z4jdev/z4j-hueyperiodic), schedule adapter for Huey `@periodic_task`

## Reliability

- Lifecycle-capture failures are isolated from Huey hooks and task code;
  capture hooks make no brain network request inline.
- The in-process event queue and SQLite outbound buffer are bounded. Queue
  overflow drops new events and buffer pressure evicts oldest rows; both losses
  are logged.

## Documentation

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

## License

Apache-2.0, see [LICENSE](LICENSE).

## Links

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