Metadata-Version: 2.4
Name: django-absurd
Version: 0.1.0a5
Summary: Django integration for Absurd, the Postgres-native workflow engine.
Project-URL: Homepage, https://github.com/lincolnloop/django-absurd
Project-URL: Issues, https://github.com/lincolnloop/django-absurd/issues
Project-URL: Repository, https://github.com/lincolnloop/django-absurd
Author-email: Marc Gibbons <marc@lincolnloop.com>, Lincoln Loop <info@lincolnloop.com>
License-Expression: MIT
License-File: LICENSE
Keywords: absurd,background-jobs,django,postgres,queue,tasks,workflow,workflow-engine
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Web Environment
Classifier: Framework :: Django
Classifier: Framework :: Django :: 6.0
Classifier: Intended Audience :: Developers
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Software Development :: Libraries
Classifier: Topic :: System :: Distributed Computing
Classifier: Typing :: Typed
Requires-Python: >=3.12
Requires-Dist: absurd-sdk<0.5.0,>=0.4.0
Requires-Dist: croniter>=3.0
Requires-Dist: django>=6.0
Description-Content-Type: text/markdown

# django-absurd

Django integration for [Absurd](https://earendil-works.github.io/absurd/), the
Postgres-native workflow engine. Runs Django's
[Tasks](https://docs.djangoproject.com/en/6.0/topics/tasks/) framework on Postgres — no
separate broker — reusing Django's own database connection.

> **Alpha.** APIs and behavior may change between releases.

## Requirements

- Python 3.12+, Django 6.0+
- PostgreSQL with the **psycopg (v3)** Django backend (the Absurd SDK reuses Django's
  connection and requires psycopg3)

## Install

```console
pip install django-absurd
```

## Quickstart

Add the app and point Django's `TASKS` setting at the backend:

```python
# settings.py
INSTALLED_APPS = [
    # ...
    "django_absurd",
]

TASKS = {
    "default": {
        "BACKEND": "django_absurd.backends.AbsurdBackend",
    },
}
```

```console
python manage.py migrate          # create the Absurd schema
python manage.py absurd_worker    # run a worker (consumes the "default" queue)
```

Define a task with Django's Tasks API and enqueue it — the `"default"` queue is
**created automatically** on first use:

```python
from django.tasks import task


@task
def add(a: int, b: int) -> int:
    return a + b


result = add.enqueue(2, 3)  # returns a TaskResult; the worker runs it
```

## Documentation

- **[Documentation](docs/web/index.md)** — full configuration and `OPTIONS`, workers,
  task parameters, retrieving results, admin introspection, querying queue state with
  the ORM, deployment notes, and adopting an existing Absurd database. Includes
  [scheduling recurring tasks](docs/web/cron-jobs.md) (beat and pg_cron schedulers) and
  [durable workflows — steps, sleep, and events](docs/web/workflows.md).
- **[Runnable examples](examples/)** — three dockerized nanodjango demos (`web`
  enqueue+result, `beat`, and `pg_cron`), each with one `docker compose up`.

## License

MIT — see [LICENSE](LICENSE).
