Metadata-Version: 2.4
Name: z4j-django
Version: 1.6.0
Summary: z4j Django framework adapter (Apache 2.0)
Project-URL: Changelog, https://github.com/z4jdev/z4j-django/blob/main/CHANGELOG.md
Project-URL: Documentation, https://z4j.dev
Project-URL: Homepage, https://z4j.com
Project-URL: Issues, https://github.com/z4jdev/z4j-django/issues
Project-URL: Source, https://github.com/z4jdev/z4j-django
Author: z4j contributors
License: Apache-2.0
License-File: LICENSE
Keywords: celery,django,task,z4j
Classifier: Development Status :: 5 - Production/Stable
Classifier: Framework :: Django
Classifier: Framework :: Django :: 5.2
Classifier: Framework :: Django :: 6.0
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: Typing :: Typed
Requires-Python: >=3.11
Requires-Dist: django>=5.2.13
Requires-Dist: z4j-bare<2,>=1.4.0
Requires-Dist: z4j-core<2,>=1.4.0
Provides-Extra: all
Requires-Dist: z4j-apscheduler<2,>=1.4.0; extra == 'all'
Requires-Dist: z4j-arq<2,>=1.4.0; extra == 'all'
Requires-Dist: z4j-arqcron<2,>=1.4.0; extra == 'all'
Requires-Dist: z4j-celery<2,>=1.4.0; extra == 'all'
Requires-Dist: z4j-celerybeat<2,>=1.4.0; extra == 'all'
Requires-Dist: z4j-dramatiq<2,>=1.4.0; extra == 'all'
Requires-Dist: z4j-huey<2,>=1.4.0; extra == 'all'
Requires-Dist: z4j-hueyperiodic<2,>=1.4.0; extra == 'all'
Requires-Dist: z4j-rq<2,>=1.4.0; extra == 'all'
Requires-Dist: z4j-rqscheduler<2,>=1.4.0; extra == 'all'
Requires-Dist: z4j-taskiq<2,>=1.4.0; extra == 'all'
Requires-Dist: z4j-taskiqscheduler<2,>=1.4.0; extra == 'all'
Provides-Extra: arq
Requires-Dist: z4j-arq<2,>=1.4.0; extra == 'arq'
Requires-Dist: z4j-arqcron<2,>=1.4.0; extra == 'arq'
Provides-Extra: celery
Requires-Dist: z4j-celery<2,>=1.4.0; extra == 'celery'
Requires-Dist: z4j-celerybeat<2,>=1.4.0; extra == 'celery'
Provides-Extra: dramatiq
Requires-Dist: z4j-apscheduler<2,>=1.4.0; extra == 'dramatiq'
Requires-Dist: z4j-dramatiq<2,>=1.4.0; extra == 'dramatiq'
Provides-Extra: huey
Requires-Dist: z4j-huey<2,>=1.4.0; extra == 'huey'
Requires-Dist: z4j-hueyperiodic<2,>=1.4.0; extra == 'huey'
Provides-Extra: rq
Requires-Dist: z4j-rq<2,>=1.4.0; extra == 'rq'
Requires-Dist: z4j-rqscheduler<2,>=1.4.0; extra == 'rq'
Provides-Extra: taskiq
Requires-Dist: z4j-taskiq<2,>=1.4.0; extra == 'taskiq'
Requires-Dist: z4j-taskiqscheduler<2,>=1.4.0; extra == 'taskiq'
Description-Content-Type: text/markdown

# z4j-django

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

The Django framework adapter for [z4j](https://z4j.com).

Adds the z4j agent into your Django project as a single
`INSTALLED_APPS` entry. Auto-discovers the engine adapter you have
installed (Celery, RQ, Dramatiq, Huey, arq, TaskIQ) and streams every
task lifecycle event from your Django workers to z4j. Operator
control actions (retry, cancel, bulk retry, purge, restart) flow back
the same channel.

## What it ships

- **One-line install**, add `"z4j_django"` to `INSTALLED_APPS`; the
  agent starts when Django boots, no decorator on every task
- **Engine auto-discovery**, picks up whichever z4j engine adapter
  is installed alongside (Celery, RQ, Dramatiq, Huey, arq, TaskIQ).
  Multiple engines in the same project are first-class.
- **Schedule integration**, pair with `z4j-celerybeat` to surface
  django-celery-beat schedules on the dashboard's Schedules page
- **`@z4j_meta` decorator**, optional per-task annotations
  (`priority="critical"`, `description="..."`) that the dashboard
  honors for filtering and SLO display
- **Service-user safe**, auto-relocates the local outbound buffer
  to `$TMPDIR/z4j-{uid}` when `$HOME` is unwritable (gunicorn
  under `www-data`, `nginx`, etc.)

## Install

```bash
pip install z4j-django z4j-celery z4j-celerybeat
```

Then in `settings.py`:

```python
INSTALLED_APPS = [
    # ...
    "django_celery_beat",  # if you use celery-beat
    "z4j_django",
]
```

The agent reads its bearer token from `Z4J_AGENT_TOKEN`, z4j URL
from `Z4J_BRAIN_URL`, and the project slug from `Z4J_PROJECT`. Mint
the token from the dashboard's Agents page.

## Reliability

- No exception from the agent ever propagates back into Django request
  handlers, signals, or your worker code.
- Events buffer locally when z4j is unreachable; your application
  never blocks on network I/O.
- Agent reconnects on every transient failure with bounded backoff.

## Documentation

Full docs at [z4j.dev/frameworks/django/](https://z4j.dev/frameworks/django/).

## License

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

## Links

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