goatnotify-django 0.1.0__tar.gz

goatnotify_django-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Louis Midson LAJEANTY <midsonlajeanty@proton.me>
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

goatnotify_django-0.1.0/PKG-INFO

@@ -0,0 +1,33 @@
+Metadata-Version: 2.4
+Name: goatnotify-django
+Version: 0.1.0
+Summary: Django integration for GoatNotify: email backend, templates, ORM store and Django Tasks.
+Keywords: notifications,email,smtp,webhooks,asyncio,typed
+Author: Louis Midson LAJEANTY
+Author-email: Louis Midson LAJEANTY <midsonlajeanty@proton.me>
+License-Expression: MIT
+License-File: LICENSE
+Classifier: Development Status :: 3 - Alpha
+Classifier: Framework :: Django
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Typing :: Typed
+Requires-Dist: goatnotify-core==0.1.0
+Requires-Dist: asgiref>=3.9.1
+Requires-Dist: django>=6.1
+Requires-Python: >=3.14
+Project-URL: Homepage, https://github.com/goatlabshq/goatnotify
+Project-URL: Documentation, https://goatlabshq.github.io/goatnotify/
+Project-URL: Issues, https://github.com/goatlabshq/goatnotify/issues
+Description-Content-Type: text/markdown
+
+# goatnotify-django
+
+Django integration for GoatNotify: email backend, templates, ORM store and Django Tasks.
+
+```bash
+pip install goatnotify-django
+```
+
+Documentation: <https://goatlabshq.github.io/goatnotify/>

goatnotify_django-0.1.0/README.md

@@ -0,0 +1,9 @@
+# goatnotify-django
+
+Django integration for GoatNotify: email backend, templates, ORM store and Django Tasks.
+
+```bash
+pip install goatnotify-django
+```
+
+Documentation: <https://goatlabshq.github.io/goatnotify/>

goatnotify_django-0.1.0/pyproject.toml

@@ -0,0 +1,48 @@
+[project]
+name = "goatnotify-django"
+version = "0.1.0"
+description = "Django integration for GoatNotify: email backend, templates, ORM store and Django Tasks."
+readme = "README.md"
+license = "MIT"
+license-files = ["LICENSE"]
+requires-python = ">=3.14"
+keywords = [
+    "notifications",
+    "email",
+    "smtp",
+    "webhooks",
+    "asyncio",
+    "typed",
+]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Framework :: Django",
+    "Intended Audience :: Developers",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.14",
+    "Typing :: Typed",
+]
+dependencies = [
+    "goatnotify-core==0.1.0",
+    "asgiref>=3.9.1",
+    "django>=6.1",
+]
+
+[[project.authors]]
+name = "Louis Midson LAJEANTY"
+email = "midsonlajeanty@proton.me"
+
+[project.urls]
+Homepage = "https://github.com/goatlabshq/goatnotify"
+Documentation = "https://goatlabshq.github.io/goatnotify/"
+Issues = "https://github.com/goatlabshq/goatnotify/issues"
+
+[build-system]
+requires = ["uv_build>=0.12,<0.14"]
+build-backend = "uv_build"
+
+[tool.uv.build-backend]
+module-name = "goatnotify.django"
+
+[tool.uv.sources.goatnotify-core]
+workspace = true

goatnotify_django-0.1.0/pyproject.toml.orig

@@ -0,0 +1,38 @@
+[project]
+name = "goatnotify-django"
+version = "0.1.0" # x-release-please-version
+description = "Django integration for GoatNotify: email backend, templates, ORM store and Django Tasks."
+readme = "README.md"
+license = "MIT"
+license-files = ["LICENSE"]
+authors = [{ name = "Louis Midson LAJEANTY", email = "midsonlajeanty@proton.me" }]
+requires-python = ">=3.14"
+keywords = ["notifications", "email", "smtp", "webhooks", "asyncio", "typed"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Framework :: Django",
+    "Intended Audience :: Developers",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.14",
+    "Typing :: Typed",
+]
+dependencies = [
+    "goatnotify-core==0.1.0", # x-release-please-version
+    "asgiref>=3.9.1",
+    "django>=6.1",
+]
+
+[project.urls]
+Homepage = "https://github.com/goatlabshq/goatnotify"
+Documentation = "https://goatlabshq.github.io/goatnotify/"
+Issues = "https://github.com/goatlabshq/goatnotify/issues"
+
+[build-system]
+requires = ["uv_build>=0.12,<0.14"]
+build-backend = "uv_build"
+
+[tool.uv.build-backend]
+module-name = "goatnotify.django"
+
+[tool.uv.sources]
+goatnotify-core = { workspace = true }

goatnotify_django-0.1.0/src/goatnotify/django/apps.py

@@ -0,0 +1,18 @@
+from django.apps import AppConfig
+from django.core import checks
+from django.core.signals import setting_changed
+
+
+class GoatNotifyConfig(AppConfig):
+    name = "goatnotify.django"
+    label = "goatnotify"
+    verbose_name = "GoatNotify"
+    default_auto_field = "django.db.models.BigAutoField"
+
+    def ready(self) -> None:
+        # Imported late: the notifier module loads models, which requires a ready app registry.
+        from goatnotify.django.checks import check_settings  # noqa: PLC0415
+        from goatnotify.django.notifier import reset_notifier_on_setting_change  # noqa: PLC0415
+
+        setting_changed.connect(reset_notifier_on_setting_change)
+        checks.register(check_settings)

goatnotify_django-0.1.0/src/goatnotify/django/checks.py

@@ -0,0 +1,61 @@
+from django.conf import settings
+from django.core.checks import CheckMessage, Error
+from django.core.mail import mailers
+from django.core.mail.handler import DEFAULT_MAILER_ALIAS
+from django.utils.module_loading import import_string
+from goatnotify.core.errors import InvalidMessageError
+from goatnotify.core.mail.message import Address
+
+HINT_FACTORY = "Set GOATNOTIFY_NOTIFIER to the dotted path of a function returning a Notifier."
+
+
+def check_settings(**_: object) -> list[CheckMessage]:
+    path: object = getattr(settings, "GOATNOTIFY_NOTIFIER", None)
+    if path is None:
+        return _default_notifier_errors()
+    if not isinstance(path, str):
+        return [
+            Error("GOATNOTIFY_NOTIFIER must be a string.", hint=HINT_FACTORY, id="goatnotify.E001")
+        ]
+    try:
+        factory: object = import_string(path)
+    except ImportError as error:
+        return [
+            Error(
+                f"GOATNOTIFY_NOTIFIER cannot be imported: {error}",
+                hint=HINT_FACTORY,
+                id="goatnotify.E002",
+            )
+        ]
+    if not callable(factory):
+        return [
+            Error(
+                f"GOATNOTIFY_NOTIFIER {path!r} is not callable.",
+                hint=HINT_FACTORY,
+                id="goatnotify.E003",
+            )
+        ]
+    return []
+
+
+def _default_notifier_errors() -> list[CheckMessage]:
+    errors: list[CheckMessage] = []
+    try:
+        Address.parse(settings.DEFAULT_FROM_EMAIL)
+    except InvalidMessageError:
+        errors.append(
+            Error(
+                f"DEFAULT_FROM_EMAIL {settings.DEFAULT_FROM_EMAIL!r} is not an email address.",
+                hint='Use "noreply@example.com" or "Name <noreply@example.com>".',
+                id="goatnotify.E004",
+            )
+        )
+    if hasattr(settings, "MAILERS") and DEFAULT_MAILER_ALIAS not in mailers:
+        errors.append(
+            Error(
+                "MAILERS has no 'default' mailer, which the default notifier sends email through.",
+                hint="Add a 'default' entry to MAILERS or set GOATNOTIFY_NOTIFIER.",
+                id="goatnotify.E005",
+            )
+        )
+    return errors

goatnotify_django-0.1.0/src/goatnotify/django/mail.py

@@ -0,0 +1,86 @@
+import email.policy
+import smtplib
+from email.message import EmailMessage as MimeMessage
+from email.policy import Policy
+from email.utils import make_msgid
+from typing import override
+
+from asgiref.sync import sync_to_async
+
+from django.core.mail import EmailMultiAlternatives
+from django.core.mail.handler import DEFAULT_MAILER_ALIAS
+from goatnotify.core.errors import PermanentError
+from goatnotify.core.mail.message import Address, Attachment, EmailMessage
+from goatnotify.core.mail.smtp import classify_smtp_error
+
+
+def _formatted(addresses: tuple[Address, ...]) -> list[str]:
+    return [str(address) for address in addresses]
+
+
+def _pop_message_id(headers: dict[str, str]) -> str | None:
+    name = next((name for name in headers if name.lower() == "message-id"), None)
+    return None if name is None else headers.pop(name)
+
+
+class _EmailWithInlineImages(EmailMultiAlternatives):
+    # Django has no inline-image API; message() is the public hook to wrap the HTML body.
+    inline: tuple[Attachment, ...] = ()
+
+    @override
+    def message(self, *, policy: Policy | None = email.policy.default) -> MimeMessage:
+        mime = super().message(policy=policy)
+        html = mime.get_body(("html",))
+        if html is None:
+            return mime
+        for attachment in self.inline:
+            maintype, subtype = attachment.mimetype.split("/")
+            html.add_related(
+                attachment.content,
+                maintype=maintype,
+                subtype=subtype,
+                cid=f"<{attachment.filename}>",
+                filename=attachment.filename,
+                disposition="inline",
+            )
+        return mime
+
+
+class DjangoEmailTransport:
+    def __init__(self, *, mailer: str = DEFAULT_MAILER_ALIAS) -> None:
+        self._mailer = mailer
+
+    async def send(self, message: EmailMessage) -> str | None:
+        # Off the shared sync thread: a slow SMTP server would stall every sync view and ORM call.
+        return await sync_to_async(self._send, thread_sensitive=False)(message)
+
+    def _send(self, message: EmailMessage) -> str:
+        headers = dict(message.headers)
+        message_id = _pop_message_id(headers) or make_msgid(
+            domain=message.sender.email.rpartition("@")[2]
+        )
+        outgoing = _EmailWithInlineImages(
+            subject=message.subject,
+            body=message.text if message.text is not None else message.html or "",
+            from_email=str(message.sender),
+            to=_formatted(message.to),
+            cc=_formatted(message.cc),
+            bcc=_formatted(message.bcc),
+            reply_to=_formatted(message.reply_to),
+            headers={**headers, "Message-ID": message_id},
+        )
+        if message.text is None:
+            outgoing.content_subtype = "html"
+        elif message.html is not None:
+            outgoing.attach_alternative(message.html, "text/html")
+        outgoing.inline = tuple(a for a in message.attachments if a.inline)
+        for attachment in message.attachments:
+            if not attachment.inline:
+                outgoing.attach(attachment.filename, attachment.content, attachment.mimetype)
+        try:
+            sent = outgoing.send(using=self._mailer)
+        except (smtplib.SMTPException, OSError) as error:
+            raise classify_smtp_error(error) from error
+        if sent == 0:
+            raise PermanentError("The Django email backend accepted no message")
+        return message_id

goatnotify_django-0.1.0/src/goatnotify/django/migrations/0001_initial.py

@@ -0,0 +1,50 @@
+# Generated by Django 6.1.1 on 2026-09-25 22:39
+
+import uuid
+
+import django.db.models.deletion
+import django.utils.timezone
+from django.db import migrations, models
+
+
+class Migration(migrations.Migration):
+    initial = True
+
+    dependencies = [
+        ("contenttypes", "0002_remove_content_type_name"),
+    ]
+
+    operations = [
+        migrations.CreateModel(
+            name="NotificationRecord",
+            fields=[
+                (
+                    "id",
+                    models.UUIDField(
+                        default=uuid.uuid4, editable=False, primary_key=True, serialize=False
+                    ),
+                ),
+                ("object_id", models.CharField(max_length=255)),
+                ("kind", models.CharField(max_length=255)),
+                ("data", models.JSONField(default=dict)),
+                ("created_at", models.DateTimeField(default=django.utils.timezone.now)),
+                ("read_at", models.DateTimeField(blank=True, null=True)),
+                (
+                    "content_type",
+                    models.ForeignKey(
+                        on_delete=django.db.models.deletion.CASCADE, to="contenttypes.contenttype"
+                    ),
+                ),
+            ],
+            options={
+                "db_table": "goatnotify_notification",
+                "ordering": ("-created_at",),
+                "indexes": [
+                    models.Index(
+                        fields=["content_type", "object_id", "-created_at"],
+                        name="goatnotify_recipient_idx",
+                    )
+                ],
+            },
+        ),
+    ]

goatnotify_django-0.1.0/src/goatnotify/django/migrations/0002_delivery_receipt.py

@@ -0,0 +1,35 @@
+# Generated by Django 6.1.2 on 2026-10-19 02:38
+
+import django.utils.timezone
+from django.db import migrations, models
+
+
+class Migration(migrations.Migration):
+    dependencies = [
+        ("goatnotify", "0001_initial"),
+    ]
+
+    operations = [
+        migrations.CreateModel(
+            name="DeliveryReceipt",
+            fields=[
+                (
+                    "id",
+                    models.BigAutoField(
+                        auto_created=True, primary_key=True, serialize=False, verbose_name="ID"
+                    ),
+                ),
+                ("job_id", models.UUIDField()),
+                ("position", models.PositiveIntegerField()),
+                ("delivered_at", models.DateTimeField(default=django.utils.timezone.now)),
+            ],
+            options={
+                "db_table": "goatnotify_delivery_receipt",
+                "constraints": [
+                    models.UniqueConstraint(
+                        fields=("job_id", "position"), name="goatnotify_receipt_unique"
+                    )
+                ],
+            },
+        ),
+    ]

goatnotify_django-0.1.0/src/goatnotify/django/models.py

@@ -0,0 +1,84 @@
+import uuid
+from datetime import datetime
+from typing import Self
+
+from django.contrib.contenttypes.fields import GenericForeignKey
+from django.contrib.contenttypes.models import ContentType
+from django.db import models
+from django.utils import timezone
+
+
+class NotificationRecordQuerySet(models.QuerySet["NotificationRecord"]):
+    def for_recipient(self, recipient: models.Model) -> Self:
+        return self.filter(
+            content_type=ContentType.objects.get_for_model(recipient),
+            object_id=str(recipient.pk),
+        )
+
+    def unread(self) -> Self:
+        return self.filter(read_at__isnull=True)
+
+    def mark_as_read(self) -> int:
+        return self.unread().update(read_at=timezone.now())
+
+
+class NotificationRecordManager(models.Manager["NotificationRecord"]):
+    def get_queryset(self) -> NotificationRecordQuerySet:
+        return NotificationRecordQuerySet(self.model, using=self._db)
+
+    def for_recipient(self, recipient: models.Model) -> NotificationRecordQuerySet:
+        return self.get_queryset().for_recipient(recipient)
+
+
+class NotificationRecord(models.Model):
+    id: models.UUIDField[uuid.UUID, uuid.UUID] = models.UUIDField(
+        primary_key=True, default=uuid.uuid4, editable=False
+    )
+    content_type: models.ForeignKey[ContentType, ContentType] = models.ForeignKey(
+        ContentType, on_delete=models.CASCADE
+    )
+    content_type_id: int
+    object_id: models.CharField[str, str] = models.CharField(max_length=255)
+    recipient = GenericForeignKey("content_type", "object_id")
+    kind: models.CharField[str, str] = models.CharField(max_length=255)
+    data = models.JSONField(default=dict)
+    created_at: models.DateTimeField[datetime, datetime] = models.DateTimeField(
+        default=timezone.now
+    )
+    read_at: models.DateTimeField[datetime | None, datetime | None] = models.DateTimeField(
+        null=True, blank=True
+    )
+
+    objects = NotificationRecordManager()
+
+    class Meta:
+        db_table = "goatnotify_notification"
+        ordering = ("-created_at",)
+        indexes = (
+            models.Index(
+                fields=("content_type", "object_id", "-created_at"),
+                name="goatnotify_recipient_idx",
+            ),
+        )
+
+    def __str__(self) -> str:
+        return f"{self.kind} for {self.content_type_id}:{self.object_id}"
+
+
+class DeliveryReceipt(models.Model):
+    job_id: models.UUIDField[uuid.UUID, uuid.UUID] = models.UUIDField()
+    position: models.PositiveIntegerField[int, int] = models.PositiveIntegerField()
+    delivered_at: models.DateTimeField[datetime, datetime] = models.DateTimeField(
+        default=timezone.now
+    )
+
+    class Meta:
+        db_table = "goatnotify_delivery_receipt"
+        constraints = (
+            models.UniqueConstraint(
+                fields=("job_id", "position"), name="goatnotify_receipt_unique"
+            ),
+        )
+
+    def __str__(self) -> str:
+        return f"{self.job_id}#{self.position}"

goatnotify_django-0.1.0/src/goatnotify/django/notifiable.py

@@ -0,0 +1,6 @@
+class NotifiableModel:
+    def route_notification(self, channel: str) -> str | None:
+        if channel != "email":
+            return None
+        email = getattr(self, "email", None)
+        return email if isinstance(email, str) and email else None

goatnotify_django-0.1.0/src/goatnotify/django/notifier.py

@@ -0,0 +1,67 @@
+from functools import cache
+from typing import Final
+
+from asgiref.sync import async_to_sync
+
+from django.conf import settings
+from django.utils.module_loading import import_string
+from goatnotify.core.channels.database import DatabaseChannel
+from goatnotify.core.channels.email import EmailChannel
+from goatnotify.core.channels.webhook import WebhookChannel
+from goatnotify.core.errors import ConfigurationError
+from goatnotify.core.mail.mailer import Mailer
+from goatnotify.core.notification import Notifiable, Notification
+from goatnotify.core.notifier import Notifier
+from goatnotify.core.results import NotificationResult
+from goatnotify.django.mail import DjangoEmailTransport
+from goatnotify.django.queue import DjangoTasksQueue
+from goatnotify.django.store import DjangoNotificationStore
+from goatnotify.django.templates import DjangoTemplateRenderer
+
+WATCHED_SETTINGS: Final = frozenset(
+    {"GOATNOTIFY_NOTIFIER", "DEFAULT_FROM_EMAIL", "MAILERS", "TASKS", "TEMPLATES"}
+)
+
+
+def default_notifier() -> Notifier:
+    mailer = Mailer(
+        DjangoEmailTransport(),
+        sender=settings.DEFAULT_FROM_EMAIL,
+        renderer=DjangoTemplateRenderer(),
+    )
+    return Notifier(
+        [EmailChannel(mailer), DatabaseChannel(DjangoNotificationStore()), WebhookChannel()],
+        queue=DjangoTasksQueue(),
+    )
+
+
+@cache
+def get_notifier() -> Notifier:
+    path: object = getattr(settings, "GOATNOTIFY_NOTIFIER", None)
+    if path is None:
+        return default_notifier()
+    if not isinstance(path, str):
+        raise ConfigurationError("GOATNOTIFY_NOTIFIER must be a dotted path to a factory")
+    notifier: object = import_string(path)()
+    if not isinstance(notifier, Notifier):
+        raise ConfigurationError(f"{path} must return a Notifier")
+    return notifier
+
+
+def reset_notifier_on_setting_change(*, setting: str, **_: object) -> None:
+    if setting in WATCHED_SETTINGS:
+        get_notifier.cache_clear()
+
+
+# Notifier.notify_sync() uses asyncio.run(), which deadlocks inside Django's thread-sensitive
+# sync views (ASGI); async_to_sync lets the adapters' sync_to_async calls run inline instead.
+def notify_sync[R: Notifiable](
+    notifiable: R, notification: Notification[R], *, raise_on_failure: bool = True
+) -> NotificationResult:
+    return async_to_sync(get_notifier().notify)(
+        notifiable, notification, raise_on_failure=raise_on_failure
+    )
+
+
+def enqueue_sync[R: Notifiable](notifiable: R, notification: Notification[R]) -> None:
+    async_to_sync(get_notifier().enqueue)(notifiable, notification)

goatnotify_django-0.1.0/src/goatnotify/django/queue.py

@@ -0,0 +1,31 @@
+from uuid import uuid4
+
+from django.db import models
+from goatnotify.core.errors import ConfigurationError
+from goatnotify.core.notification import Notifiable
+from goatnotify.core.queue import NotificationJob
+from goatnotify.django.serialization import dump_model, dump_notification
+from goatnotify.django.tasks import deliver_notification
+
+
+class DjangoTasksQueue:
+    def __init__(
+        self,
+        *,
+        queue_name: str | None = None,
+        priority: int | None = None,
+        backend: str | None = None,
+    ) -> None:
+        self._queue_name = queue_name
+        self._priority = priority
+        self._backend = backend
+
+    async def enqueue[R: Notifiable](self, job: NotificationJob[R]) -> None:
+        if not isinstance(job.notifiable, models.Model):
+            raise ConfigurationError("DjangoTasksQueue needs a Django model instance as notifiable")
+        notifiable = dump_model(job.notifiable)
+        notification = dump_notification(job.notification)
+        task = deliver_notification.using(
+            queue_name=self._queue_name, priority=self._priority, backend=self._backend
+        )
+        await task.aenqueue(notifiable, notification, job_id=str(uuid4()))

goatnotify_django-0.1.0/src/goatnotify/django/serialization.py

@@ -0,0 +1,109 @@
+import dataclasses
+import importlib
+import math
+from collections.abc import Mapping
+from typing import Any, Final, cast
+
+from django.apps import apps
+from django.db import models
+from goatnotify.core._json import JsonValue
+from goatnotify.core.errors import ConfigurationError
+from goatnotify.core.notification import Notifiable, Notification
+
+MODEL_TAG: Final = "model"
+JSON_TAG: Final = "json"
+JSON_SCALARS: Final = (str, int, float, bool, type(None))
+
+
+def dump_model(instance: models.Model) -> dict[str, JsonValue]:
+    if instance.pk is None:
+        raise ConfigurationError(f"{type(instance).__qualname__} must be saved before it is queued")
+    pk: object = instance.pk
+    json_pk: JsonValue = pk if isinstance(pk, str | int) and type(pk) is not bool else str(pk)
+    return {"label": instance._meta.label_lower, "pk": json_pk}
+
+
+def load_model(reference: Mapping[str, JsonValue]) -> models.Model:
+    label = reference.get("label")
+    if not isinstance(label, str):
+        raise ConfigurationError("Malformed queued model reference")
+    return apps.get_model(label)._default_manager.get(pk=reference.get("pk"))
+
+
+def load_notifiable(reference: Mapping[str, JsonValue]) -> Notifiable:
+    instance = load_model(reference)
+    if not callable(getattr(instance, "route_notification", None)):
+        raise ConfigurationError(f"{type(instance).__qualname__} is not notifiable")
+    return cast("Notifiable", instance)
+
+
+def dump_notification(notification: Notification[Any]) -> dict[str, JsonValue]:
+    cls = type(notification)
+    if not dataclasses.is_dataclass(notification) or "<locals>" in cls.__qualname__:
+        raise ConfigurationError(
+            f"{cls.__qualname__} must be a module-level dataclass to be queued with Django Tasks"
+        )
+    fields: dict[str, JsonValue] = {}
+    for field in dataclasses.fields(notification):
+        if not field.init:
+            continue
+        value: object = getattr(notification, field.name)
+        if isinstance(value, models.Model):
+            fields[field.name] = {MODEL_TAG: dump_model(value)}
+        elif _round_trips(value):
+            fields[field.name] = {JSON_TAG: cast("JsonValue", value)}
+        else:
+            raise ConfigurationError(
+                f"{cls.__qualname__}.{field.name} must be plain JSON (str, int, float, bool, "
+                "None, list, dict with str keys) or a saved model instance"
+            )
+    return {"class": f"{cls.__module__}:{cls.__qualname__}", "fields": fields}
+
+
+def load_notification(payload: Mapping[str, JsonValue]) -> Notification[Any]:
+    path, fields = payload.get("class"), payload.get("fields")
+    if not isinstance(path, str) or not isinstance(fields, dict):
+        raise ConfigurationError("Malformed queued notification")
+    module_name, _, qualname = path.partition(":")
+    # Task payloads may sit in a database table, so only installed apps' modules are importable.
+    if not _in_installed_app(module_name):
+        raise ConfigurationError(f"{module_name!r} is not part of an installed app")
+    target: object = importlib.import_module(module_name)  # nosemgrep
+    for part in qualname.split("."):
+        target = getattr(target, part)
+    if not (isinstance(target, type) and issubclass(target, Notification)):
+        raise ConfigurationError(f"{path} is not a Notification")
+    arguments = {name: _load_field(value) for name, value in fields.items()}
+    return cast("type[Notification[Any]]", target)(**arguments)
+
+
+def _round_trips(value: object) -> bool:
+    # Exact types: tuples, enums and other subclasses would come back as plain JSON values.
+    if type(value) is float:
+        return math.isfinite(value)
+    if type(value) in JSON_SCALARS:
+        return True
+    if type(value) is list:
+        return all(_round_trips(item) for item in cast("list[object]", value))
+    if type(value) is dict:
+        items = cast("dict[object, object]", value).items()
+        return all(type(key) is str and _round_trips(item) for key, item in items)
+    return False
+
+
+def _load_field(encoded: JsonValue) -> object:
+    if not isinstance(encoded, dict) or len(encoded) != 1:
+        raise ConfigurationError("Malformed queued notification field")
+    ((tag, value),) = encoded.items()
+    if tag == JSON_TAG:
+        return value
+    if tag == MODEL_TAG and isinstance(value, dict):
+        return load_model(value)
+    raise ConfigurationError("Malformed queued notification field")
+
+
+def _in_installed_app(module_name: str) -> bool:
+    return any(
+        module_name == config.name or module_name.startswith(f"{config.name}.")
+        for config in apps.get_app_configs()
+    )

goatnotify_django-0.1.0/src/goatnotify/django/store.py

@@ -0,0 +1,28 @@
+from asgiref.sync import sync_to_async
+
+from django.contrib.contenttypes.models import ContentType
+from django.db import models
+from goatnotify.core.channels.database import StoredNotification
+from goatnotify.core.errors import ConfigurationError
+from goatnotify.core.notification import Notifiable
+from goatnotify.django.models import NotificationRecord
+
+
+class DjangoNotificationStore:
+    async def store(self, notifiable: Notifiable, record: StoredNotification) -> None:
+        if not isinstance(notifiable, models.Model) or notifiable.pk is None:
+            kind = type(notifiable).__qualname__
+            raise ConfigurationError(
+                f"DjangoNotificationStore needs a saved model instance, not {kind}"
+            )
+        await sync_to_async(self._store)(notifiable, record)
+
+    def _store(self, recipient: models.Model, record: StoredNotification) -> None:
+        NotificationRecord.objects.create(
+            id=record.id,
+            content_type=ContentType.objects.get_for_model(recipient),
+            object_id=str(recipient.pk),
+            kind=record.kind,
+            data=dict(record.data),
+            created_at=record.created_at,
+        )

goatnotify_django-0.1.0/src/goatnotify/django/tasks.py

@@ -0,0 +1,57 @@
+import logging
+from typing import Final
+from uuid import UUID
+
+from asgiref.sync import sync_to_async
+
+from django.core.exceptions import ObjectDoesNotExist
+from django.tasks import task
+from goatnotify.core._json import JsonValue
+from goatnotify.core.results import DeliveryStatus, NotificationResult
+from goatnotify.django.models import DeliveryReceipt
+from goatnotify.django.serialization import load_notifiable, load_notification
+
+logger: Final = logging.getLogger("goatnotify")
+DONE: Final = frozenset({DeliveryStatus.SENT, DeliveryStatus.SKIPPED})
+
+
+@task
+async def deliver_notification(
+    notifiable: dict[str, JsonValue],
+    notification: dict[str, JsonValue],
+    job_id: str | None = None,
+) -> None:
+    # Imported here because the default notifier builds a DjangoTasksQueue that enqueues this task.
+    from goatnotify.django.notifier import get_notifier  # noqa: PLC0415
+
+    try:
+        recipient = await sync_to_async(load_notifiable)(notifiable)
+    except ObjectDoesNotExist:
+        logger.warning(
+            "Skipped a queued notification: its recipient %s no longer exists", notifiable
+        )
+        return
+    instance = await sync_to_async(load_notification)(notification)
+    job = None if job_id is None else UUID(job_id)
+    delivered: set[int] = set() if job is None else await sync_to_async(_delivered_positions)(job)
+    result = await get_notifier().notify(
+        recipient, instance, raise_on_failure=False, skip=delivered
+    )
+    if job is not None:
+        await sync_to_async(_record)(job, delivered, result)
+    result.raise_for_failures()
+
+
+def _delivered_positions(job: UUID) -> set[int]:
+    return set(DeliveryReceipt.objects.filter(job_id=job).values_list("position", flat=True))
+
+
+def _record(job: UUID, already: set[int], result: NotificationResult) -> None:
+    DeliveryReceipt.objects.bulk_create(
+        [
+            DeliveryReceipt(job_id=job, position=position)
+            for position, delivery in enumerate(result.deliveries)
+            if delivery.status in DONE and position not in already
+        ],
+        ignore_conflicts=True,
+    )

goatnotify_django-0.1.0/src/goatnotify/django/templates.py

@@ -0,0 +1,13 @@
+from collections.abc import Mapping
+
+from asgiref.sync import sync_to_async
+
+from django.template.loader import render_to_string
+
+
+class DjangoTemplateRenderer:
+    def __init__(self, *, using: str | None = None) -> None:
+        self._using = using
+
+    async def render(self, template: str, context: Mapping[str, object]) -> str:
+        return await sync_to_async(render_to_string)(template, dict(context), using=self._using)