django-domain-events

A Django domain-event log with in-process fan-out.

fire() records a typed event to a database table inside the caller's transaction; a relay delivers it to registered receivers afterwards, at-least-once, with per-receiver retry and dead-lettering. The event exists if and only if the change committed.

This is not a signals replacement. A database write per event rules out chatty notification use, and buys three things signals cannot give you: a crash story, durable attribution for who caused what, and an event log you can query.

Install

pip install django-domain-events

Nested event payloads need the decode half of the codec:

pip install "django-domain-events[dacite]"

Quickstart

Declare an event and something that listens for it:

# orders/events.py
from dataclasses import dataclass

from django_domain_events import DURABLE, event, receiver


@event
@dataclass(frozen=True, slots=True)
class OrderPlaced:
    order_id: int
    total_cents: int


@receiver(OrderPlaced, mode=DURABLE)
def reserve_stock(evt: OrderPlaced) -> None: ...

Fire it inside the transaction that makes the change:

with transaction.atomic():
    order = Order.objects.create(...)
    fire(OrderPlaced(order_id=order.id, total_cents=order.total_cents))

The event row and one delivery row per durable receiver are written in that same transaction. Deliver what is owed with python manage.py deliver_events --once.

In tests, drain_outbox() runs the real delivery path to completion, and assert_fired(OrderPlaced, times=1) reads the log rather than a mock.

Delivery modes

Two independent knobs, not one enum. Timing is what a receiver promises about the transaction; where its code runs is a separate question, and only meaningful for DURABLE.

Mode	Runs	Can veto	Recoverable
`INLINE`	inside the transaction	yes, by raising	not needed: its failure is a rollback
`ON_COMMIT`	after commit, in the firing process	no	no
`DURABLE` (default)	after commit, at-least-once, retried	no	yes

For a receiver that touches only this database, the work and the acknowledgement commit together, so delivery is effectively once: the duplicate an at-least-once system owes you cannot be observed. Receivers with side effects outside the database are at-least-once, as promised.

Status

Early development. The API is not stable and the package is not yet usable; see the changelog for what has landed.

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

django_domain_events-0.1.0.tar.gz (129.9 kB view details)

Uploaded Aug 31, 2026 Source

Built Distribution

If you're not sure about the file name format, learn more about wheel file names.

The dropdown lists show the available interpreters, ABIs, and platforms. Enable javascript to be able to filter the list of wheel files.

django_domain_events-0.1.0-py3-none-any.whl (28.1 kB view details)

Uploaded Aug 31, 2026 Python 3

File details

Details for the file django_domain_events-0.1.0.tar.gz.

File metadata

Download URL: django_domain_events-0.1.0.tar.gz
Upload date: Aug 31, 2026
Size: 129.9 kB
Tags: Source
Uploaded using Trusted Publishing? Yes
Uploaded via: twine/7.0.0 CPython/3.13.14

File hashes

Hashes for django_domain_events-0.1.0.tar.gz
Algorithm	Hash digest
SHA256	`6e428b96e3e165bb43cb91fb78e33be4c46edf9d7c19b1869df07f376ea89379`
MD5	`8e4adddf6c004982dae0b0b338a465eb`
BLAKE2b-256	`29c889208ee4be30bfa3cff2dc6892405fbaffe11ab1559a97294f19a6d7df3c`

See more details on using hashes here.

Provenance

The following attestation bundles were made for django_domain_events-0.1.0.tar.gz:

Publisher: release.yml on Artui/django-domain-events

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

Statement:
- Statement type: https://in-toto.io/Statement/v1
- Predicate type: https://docs.pypi.org/attestations/publish/v1
- Subject name: django_domain_events-0.1.0.tar.gz
- Subject digest: 6e428b96e3e165bb43cb91fb78e33be4c46edf9d7c19b1869df07f376ea89379
- Sigstore transparency entry: 2663946002
- Sigstore integration time: Aug 31, 2026
Source repository:
- Permalink: Artui/django-domain-events@fcd59c3c97d34ebe93381840a1892505dbcd6a1c
- Branch / Tag: refs/heads/main
- Owner: https://github.com/Artui
- Access: public
Publication detail:
- Token Issuer: https://token.actions.githubusercontent.com
- Runner Environment: github-hosted
- Publication workflow: release.yml@fcd59c3c97d34ebe93381840a1892505dbcd6a1c
- Trigger Event: push