Metadata-Version: 2.4
Name: z4j-django
Version: 1.0.7
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>=1.0.7
Requires-Dist: z4j-core>=1.0.5
Provides-Extra: all
Requires-Dist: z4j-apscheduler>=1.0.1; extra == 'all'
Requires-Dist: z4j-arq>=1.0.1; extra == 'all'
Requires-Dist: z4j-arqcron>=1.0.1; extra == 'all'
Requires-Dist: z4j-celery>=1.0.2; extra == 'all'
Requires-Dist: z4j-celerybeat>=1.0.2; extra == 'all'
Requires-Dist: z4j-dramatiq>=1.0.1; extra == 'all'
Requires-Dist: z4j-huey>=1.0.1; extra == 'all'
Requires-Dist: z4j-hueyperiodic>=1.0.1; extra == 'all'
Requires-Dist: z4j-rq>=1.0.1; extra == 'all'
Requires-Dist: z4j-rqscheduler>=1.0.1; extra == 'all'
Requires-Dist: z4j-taskiq>=1.0.1; extra == 'all'
Requires-Dist: z4j-taskiqscheduler>=1.0.1; extra == 'all'
Provides-Extra: arq
Requires-Dist: z4j-arq>=1.0.1; extra == 'arq'
Requires-Dist: z4j-arqcron>=1.0.1; extra == 'arq'
Provides-Extra: celery
Requires-Dist: z4j-celery>=1.0.2; extra == 'celery'
Requires-Dist: z4j-celerybeat>=1.0.2; extra == 'celery'
Provides-Extra: dramatiq
Requires-Dist: z4j-apscheduler>=1.0.1; extra == 'dramatiq'
Requires-Dist: z4j-dramatiq>=1.0.1; extra == 'dramatiq'
Provides-Extra: huey
Requires-Dist: z4j-huey>=1.0.1; extra == 'huey'
Requires-Dist: z4j-hueyperiodic>=1.0.1; extra == 'huey'
Provides-Extra: rq
Requires-Dist: z4j-rq>=1.0.1; extra == 'rq'
Requires-Dist: z4j-rqscheduler>=1.0.1; extra == 'rq'
Provides-Extra: taskiq
Requires-Dist: z4j-taskiq>=1.0.1; extra == 'taskiq'
Requires-Dist: z4j-taskiqscheduler>=1.0.1; extra == 'taskiq'
Description-Content-Type: text/markdown

# z4j-django

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


**License:** Apache 2.0

Django framework adapter for [z4j](https://z4j.com). Drops into any
Django project via `INSTALLED_APPS` and bootstraps a z4j agent on
Django startup - no boilerplate, no signal wiring, no custom management
commands.

## Install

Pick your task engine and install with the matching extra. Each extra
pulls the engine adapter AND its companion scheduler in one shot, so
a fresh install never needs a second command.

```bash
pip install z4j-django[celery]      # Celery + celery-beat
pip install z4j-django[rq]          # RQ + rq-scheduler
pip install z4j-django[dramatiq]    # Dramatiq + APScheduler
pip install z4j-django[huey]        # Huey + huey-periodic
pip install z4j-django[arq]         # arq + arq-cron
pip install z4j-django[taskiq]      # TaskIQ + taskiq-scheduler
pip install z4j-django[all]         # every engine (CI / kitchen sink)
```

`pip install z4j-django` (no extra) installs only the framework adapter.
That's useful if you already manage engine packages elsewhere; otherwise
always pick an engine extra.

## Configure

Add `z4j_django` to your installed apps and set the `Z4J` dict in Django
settings:

```python
# settings.py
INSTALLED_APPS = [
    # ... your apps ...
    "z4j_django",
]

Z4J = {
    "brain_url": env("Z4J_BRAIN_URL"),   # e.g. "https://z4j.internal"
    "token":     env("Z4J_TOKEN"),       # minted in the brain dashboard
    "project_id": env("Z4J_PROJECT_ID", default="default"),
}
```

On `python manage.py runserver` (or `gunicorn`, `daphne`, `uvicorn`, ...)
the agent starts, connects to the brain, and z4j's dashboard populates
with every `@shared_task` and `@task` it discovers in your INSTALLED_APPS.

## What it does

| Piece | Purpose |
|---|---|
| `Z4JDjangoConfig.ready()` | Boots the agent once Django is fully loaded (after `INSTALLED_APPS` is populated) |
| Five-layer task discovery | Walks `INSTALLED_APPS` to find `@shared_task` / `@app.task` declarations |
| Django auth bridge | Maps the signed-in Django user to `z4j_core.User` for audit-log stamping |
| `django.core.checks` | Surfaces misconfiguration at `manage.py check` time |
| Optional admin embed | Renders a read-only "z4j agent status" panel in the Django admin |

## Reliability

`z4j-django` follows the project-wide safety rule: **z4j never breaks
your Django process**. Agent failures are caught at the boundary, logged,
and swallowed. Your runserver, gunicorn, and ASGI workers are never
affected by a z4j issue.

## Documentation

- [Quickstart (Django)](https://z4j.dev/getting-started/quickstart-django/)
- [Install guide](https://z4j.dev/getting-started/install/)
- [Architecture](https://z4j.dev/concepts/architecture/)

## License

Apache 2.0 - see [LICENSE](LICENSE). Your Django application is never
AGPL-tainted by importing `z4j_django`.

## Links

- Homepage: <https://z4j.com>
- Documentation: <https://z4j.dev>
- Issues: <https://github.com/z4jdev/z4j-django/issues>
- Changelog: [CHANGELOG.md](CHANGELOG.md)
- Security: `security@z4j.com` (see [SECURITY.md](SECURITY.md))
