duva-django 0.1.0__tar.gz

duva_django-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,29 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+permissions:
+  contents: read
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        include:
+          - { python: "3.10", django: "5.2.*" }
+          - { python: "3.13", django: "6.1.*" }
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          persist-credentials: false
+      - uses: astral-sh/setup-uv@c18668ad3cf93ea998bef934396af7bb5c839dc7 # v10.2.0
+      - name: Tests, types et style sur Django ${{ matrix.django }}
+        run: |
+          uv run --python ${{ matrix.python }} --extra dev --with "django==${{ matrix.django }}" pytest -q
+          uv run --python ${{ matrix.python }} --extra dev --with "django==${{ matrix.django }}" mypy
+          uv run --python ${{ matrix.python }} --extra dev ruff check .
+          uv run --python ${{ matrix.python }} --extra dev ruff format --check .

duva_django-0.1.0/.github/workflows/release.yml

@@ -0,0 +1,75 @@
+# Publication de `duva-django` sur PyPI.
+#
+# Déclencheur : l'étiquette Git `vX.Y.Z` (la version de pyproject.toml DOIT être celle de l'étiquette), ou « Run
+# workflow » à la main, qui ne publie JAMAIS sauf si on décoche `dry_run` sur une étiquette.
+#
+# Authentification : « trusted publishing » de PyPI (OIDC, aucun jeton stocké). À déclarer UNE fois sur pypi.org
+# (pour un projet qui n'existe pas encore : Account > Publishing > « Add a new pending publisher ») : projet
+# duva-django, propriétaire `duva-mail`, dépôt `duva-django`, workflow `release.yml`, environnement `publication`.
+name: Release
+
+on:
+  push:
+    tags: ["v*"]
+  workflow_dispatch:
+    inputs:
+      dry_run:
+        description: "Construire et contrôler seulement (ne rien publier)"
+        type: boolean
+        default: true
+
+permissions:
+  contents: read
+
+jobs:
+  verify:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        include:
+          - { python: "3.10", django: "5.2.*" }
+          - { python: "3.13", django: "6.1.*" }
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          persist-credentials: false
+      - uses: astral-sh/setup-uv@c18668ad3cf93ea998bef934396af7bb5c839dc7 # v10.2.0
+      - name: La version de pyproject.toml est celle de l'étiquette
+        if: startsWith(github.ref, 'refs/tags/v')
+        run: |
+          version=$(sed -n 's/^version = "\(.*\)"/\1/p' pyproject.toml | head -n 1)
+          [ "v${version}" = "${GITHUB_REF_NAME}" ] || { echo "pyproject=${version}, étiquette=${GITHUB_REF_NAME}" >&2; exit 1; }
+      - name: Tests, types et style sur Django ${{ matrix.django }}
+        run: |
+          uv run --python ${{ matrix.python }} --extra dev --with "django==${{ matrix.django }}" pytest -q
+          uv run --python ${{ matrix.python }} --extra dev --with "django==${{ matrix.django }}" mypy
+          uv run --python ${{ matrix.python }} --extra dev ruff check .
+          uv run --python ${{ matrix.python }} --extra dev ruff format --check .
+
+  build:
+    needs: verify
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          persist-credentials: false
+      - uses: astral-sh/setup-uv@c18668ad3cf93ea998bef934396af7bb5c839dc7 # v10.2.0
+      - run: uv build
+      - uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
+        with:
+          name: dist
+          path: dist/
+
+  publish:
+    needs: build
+    if: startsWith(github.ref, 'refs/tags/v') && (github.event_name == 'push' || inputs.dry_run == false)
+    runs-on: ubuntu-latest
+    environment: publication
+    permissions:
+      id-token: write # trusted publishing
+    steps:
+      - uses: actions/download-artifact@3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c # v8.0.1
+        with:
+          name: dist
+          path: dist/
+      - uses: pypa/gh-action-pypi-publish@dc37677b2e1c63e2034f94d8a5b11f265b73ba33 # v1.14.2

duva_django-0.1.0/.gitignore

@@ -0,0 +1,10 @@
+__pycache__/
+*.pyc
+.venv/
+dist/
+*.egg-info/
+.mypy_cache/
+.ruff_cache/
+.pytest_cache/
+uv.lock
+.DS_Store

duva_django-0.1.0/CHANGELOG.md

@@ -0,0 +1,5 @@
+# Changelog
+
+## 0.1.0
+
+- First release: `duva_django.EmailBackend`, a Django email backend for Duva, built on `duva-mail`.

duva_django-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 9573-4562 Québec inc.
+
+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.

duva_django-0.1.0/PKG-INFO

@@ -0,0 +1,136 @@
+Metadata-Version: 2.5
+Name: duva-django
+Version: 0.1.0
+Summary: Django email backend for Duva, the transactional email API hosted in Canada.
+Project-URL: Homepage, https://duva.ca
+Project-URL: Documentation, https://duva.ca/en/docs
+Project-URL: Repository, https://github.com/duva-mail/duva-django
+Project-URL: Changelog, https://github.com/duva-mail/duva-django/blob/main/CHANGELOG.md
+Author: 9573-4562 Québec inc.
+License-Expression: MIT
+License-File: LICENSE
+Keywords: django,duva,email,email-backend,transactional-email
+Classifier: Development Status :: 4 - Beta
+Classifier: Framework :: Django
+Classifier: Framework :: Django :: 5.2
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Requires-Dist: django>=5.2
+Requires-Dist: duva-mail<1,>=0.2
+Provides-Extra: dev
+Requires-Dist: django-stubs>=5.1; extra == 'dev'
+Requires-Dist: mypy>=1.13; extra == 'dev'
+Requires-Dist: pytest>=8.3; extra == 'dev'
+Requires-Dist: ruff>=0.7; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# duva-django
+
+Django email backend for [Duva](https://duva.ca), the transactional email API hosted in Canada. Use `send_mail()`,
+`EmailMessage` and `EmailMultiAlternatives` as usual; the messages go out through Duva.
+
+Requires Python 3.10+ and Django 5.2 or later (including the `MAILERS` setting of Django 6.1). Built on
+[`duva-mail`](https://pypi.org/project/duva-mail/).
+
+```bash
+pip install duva-django
+# or: uv add duva-django
+```
+
+You also need a Duva API key and a verified domain ([documentation](https://duva.ca/en/docs)).
+
+## Configure
+
+Django 5.2 and later, with `EMAIL_BACKEND`:
+
+```python
+# settings.py
+EMAIL_BACKEND = "duva_django.EmailBackend"
+DUVA_API_KEY = os.environ["DUVA_API_KEY"]
+DUVA_DOMAIN = "example.com"
+DEFAULT_FROM_EMAIL = "Example <notifications@example.com>"
+```
+
+Django 6.1 and later, with `MAILERS` (`EMAIL_BACKEND` is deprecated there):
+
+```python
+MAILERS = {
+    "default": {
+        "BACKEND": "duva_django.EmailBackend",
+        "OPTIONS": {"api_key": os.environ["DUVA_API_KEY"], "domain": "example.com"},
+    },
+}
+```
+
+Options (`OPTIONS`, or the setting of the same name in capitals prefixed by `DUVA_`): `api_key`, `domain`, `base_url`
+(default `https://api.duva.ca`), `timeout` (seconds, default 10), `max_retries` (default 2). `DUVA_API_KEY` and
+`DUVA_DOMAIN` can also come from the environment. The `From` address must belong to the configured domain.
+
+## What is sent
+
+| Django | Duva |
+|---|---|
+| `from_email`, `to`, `cc`, `bcc`, `reply_to` | `from`, `to`, `cc`, `bcc`, `reply_to` |
+| Plain body, `content_subtype = "html"`, `attach_alternative(html, "text/html")` | `text`, `html` |
+| `attach()` files and inline images (`Content-ID`) | `attachments` (inline ones keep their `content_id`) |
+| `message.tags = [...]` | `tags` |
+| `message.metadata = {...}` | `metadata` |
+| `List-Unsubscribe`, `List-Unsubscribe-Post`, `List-Id`, `In-Reply-To`, `References`, `Auto-Submitted`, `Precedence`, `Importance`, `Feedback-ID`, and `X-*` headers in `headers` | `headers` |
+
+(`tags` and `metadata` follow the django-anymail convention, so code written for it keeps working.)
+
+Notes:
+
+- Other headers are not forwarded (Duva rejects them), nor are `X-Duva*`, `X-Kumo*`, `X-Tenant*` and `X-Campaign*`.
+- A display name Duva refuses (it contains `@`, quotes, `<>`, control characters or an encoded word `=?…?=`) is dropped;
+  the address is kept.
+- Delivery is asynchronous: a successful send means Duva accepted the message, not that it was delivered. After a send,
+  `message.duva_result` holds the `duva.SendMessageResult` (`id`, `status`, `replayed`). Use Duva's webhooks or events
+  for the outcome.
+- A Duva error (`duva.DuvaError` and its subclasses) is raised, unless `fail_silently=True`, in which case the message is
+  not counted in the return value of `send_mail()`. A missing key or domain raises `ImproperlyConfigured`.
+
+### Idempotency
+
+A retried task builds a new message, so it would be sent twice. Set a stable key for it (an order ID, for example):
+
+```python
+EmailMessage(
+    subject,
+    body,
+    from_email,
+    [to],
+    headers={"X-Idempotency-Key": f"order-{order.id}"},
+).send()
+```
+
+The header is read by the backend and never sent. Duva ignores a second message with the same key.
+
+## Testing your application
+
+Django's test runner swaps the backend for the in-memory one, so `mail.outbox` works as usual. To exercise this backend
+without a network, give it a client built on a fake HTTP transport:
+
+```python
+import duva, httpx
+from duva_django import EmailBackend
+
+client = duva.Duva(
+    api_key="dv_test",
+    domain="example.com",
+    http_client=httpx.Client(transport=httpx.MockTransport(handler)),
+)
+EmailBackend(client=client).send_messages([message])
+```
+
+## License
+
+MIT.

duva_django-0.1.0/README.md

@@ -0,0 +1,102 @@
+# duva-django
+
+Django email backend for [Duva](https://duva.ca), the transactional email API hosted in Canada. Use `send_mail()`,
+`EmailMessage` and `EmailMultiAlternatives` as usual; the messages go out through Duva.
+
+Requires Python 3.10+ and Django 5.2 or later (including the `MAILERS` setting of Django 6.1). Built on
+[`duva-mail`](https://pypi.org/project/duva-mail/).
+
+```bash
+pip install duva-django
+# or: uv add duva-django
+```
+
+You also need a Duva API key and a verified domain ([documentation](https://duva.ca/en/docs)).
+
+## Configure
+
+Django 5.2 and later, with `EMAIL_BACKEND`:
+
+```python
+# settings.py
+EMAIL_BACKEND = "duva_django.EmailBackend"
+DUVA_API_KEY = os.environ["DUVA_API_KEY"]
+DUVA_DOMAIN = "example.com"
+DEFAULT_FROM_EMAIL = "Example <notifications@example.com>"
+```
+
+Django 6.1 and later, with `MAILERS` (`EMAIL_BACKEND` is deprecated there):
+
+```python
+MAILERS = {
+    "default": {
+        "BACKEND": "duva_django.EmailBackend",
+        "OPTIONS": {"api_key": os.environ["DUVA_API_KEY"], "domain": "example.com"},
+    },
+}
+```
+
+Options (`OPTIONS`, or the setting of the same name in capitals prefixed by `DUVA_`): `api_key`, `domain`, `base_url`
+(default `https://api.duva.ca`), `timeout` (seconds, default 10), `max_retries` (default 2). `DUVA_API_KEY` and
+`DUVA_DOMAIN` can also come from the environment. The `From` address must belong to the configured domain.
+
+## What is sent
+
+| Django | Duva |
+|---|---|
+| `from_email`, `to`, `cc`, `bcc`, `reply_to` | `from`, `to`, `cc`, `bcc`, `reply_to` |
+| Plain body, `content_subtype = "html"`, `attach_alternative(html, "text/html")` | `text`, `html` |
+| `attach()` files and inline images (`Content-ID`) | `attachments` (inline ones keep their `content_id`) |
+| `message.tags = [...]` | `tags` |
+| `message.metadata = {...}` | `metadata` |
+| `List-Unsubscribe`, `List-Unsubscribe-Post`, `List-Id`, `In-Reply-To`, `References`, `Auto-Submitted`, `Precedence`, `Importance`, `Feedback-ID`, and `X-*` headers in `headers` | `headers` |
+
+(`tags` and `metadata` follow the django-anymail convention, so code written for it keeps working.)
+
+Notes:
+
+- Other headers are not forwarded (Duva rejects them), nor are `X-Duva*`, `X-Kumo*`, `X-Tenant*` and `X-Campaign*`.
+- A display name Duva refuses (it contains `@`, quotes, `<>`, control characters or an encoded word `=?…?=`) is dropped;
+  the address is kept.
+- Delivery is asynchronous: a successful send means Duva accepted the message, not that it was delivered. After a send,
+  `message.duva_result` holds the `duva.SendMessageResult` (`id`, `status`, `replayed`). Use Duva's webhooks or events
+  for the outcome.
+- A Duva error (`duva.DuvaError` and its subclasses) is raised, unless `fail_silently=True`, in which case the message is
+  not counted in the return value of `send_mail()`. A missing key or domain raises `ImproperlyConfigured`.
+
+### Idempotency
+
+A retried task builds a new message, so it would be sent twice. Set a stable key for it (an order ID, for example):
+
+```python
+EmailMessage(
+    subject,
+    body,
+    from_email,
+    [to],
+    headers={"X-Idempotency-Key": f"order-{order.id}"},
+).send()
+```
+
+The header is read by the backend and never sent. Duva ignores a second message with the same key.
+
+## Testing your application
+
+Django's test runner swaps the backend for the in-memory one, so `mail.outbox` works as usual. To exercise this backend
+without a network, give it a client built on a fake HTTP transport:
+
+```python
+import duva, httpx
+from duva_django import EmailBackend
+
+client = duva.Duva(
+    api_key="dv_test",
+    domain="example.com",
+    http_client=httpx.Client(transport=httpx.MockTransport(handler)),
+)
+EmailBackend(client=client).send_messages([message])
+```
+
+## License
+
+MIT.

duva_django-0.1.0/pyproject.toml

@@ -0,0 +1,62 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "duva-django"
+version = "0.1.0"
+description = "Django email backend for Duva, the transactional email API hosted in Canada."
+readme = "README.md"
+license = "MIT"
+license-files = ["LICENSE"]
+requires-python = ">=3.10"
+authors = [{ name = "9573-4562 Québec inc." }]
+keywords = ["duva", "django", "email", "email-backend", "transactional-email"]
+classifiers = [
+  "Development Status :: 4 - Beta",
+  "Framework :: Django",
+  "Framework :: Django :: 5.2",
+  "Intended Audience :: Developers",
+  "License :: OSI Approved :: MIT License",
+  "Operating System :: OS Independent",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3.10",
+  "Programming Language :: Python :: 3.11",
+  "Programming Language :: Python :: 3.12",
+  "Programming Language :: Python :: 3.13",
+  "Typing :: Typed",
+]
+dependencies = ["django>=5.2", "duva-mail>=0.2,<1"]
+
+[project.urls]
+Homepage = "https://duva.ca"
+Documentation = "https://duva.ca/en/docs"
+Repository = "https://github.com/duva-mail/duva-django"
+Changelog = "https://github.com/duva-mail/duva-django/blob/main/CHANGELOG.md"
+
+[project.optional-dependencies]
+dev = ["pytest>=8.3", "mypy>=1.13", "ruff>=0.7", "django-stubs>=5.1"]
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/duva_django"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+
+[tool.mypy]
+python_version = "3.10"
+strict = true
+packages = ["duva_django"]
+mypy_path = "src"
+explicit_package_bases = true
+plugins = ["mypy_django_plugin.main"]
+
+[tool.django-stubs]
+django_settings_module = "tests.settings"
+
+[tool.ruff]
+line-length = 100
+target-version = "py310"
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "UP", "B", "SIM"]

duva_django-0.1.0/src/duva_django/__init__.py

@@ -0,0 +1,6 @@
+"""Django email backend for Duva. Use `EMAIL_BACKEND = "duva_django.EmailBackend"`."""
+
+from duva_django.backend import IDEMPOTENCY_HEADER, EmailBackend
+
+__all__ = ["IDEMPOTENCY_HEADER", "EmailBackend"]
+__version__ = "0.1.0"

duva_django-0.1.0/src/duva_django/backend.py

@@ -0,0 +1,247 @@
+"""Django email backend for Duva: `duva_django.EmailBackend`.
+
+Duva refuses a few things Django allows, and this backend translates rather than failing late: a
+display name Duva would reject is dropped (the address is kept), and only the headers Duva accepts
+are forwarded. `tags` and `metadata` attributes on the message (the django-anymail convention)
+become Duva's `tags` and `metadata`.
+"""
+
+from __future__ import annotations
+
+import re
+from collections.abc import Sequence
+from email.message import Message
+from email.utils import parseaddr
+from typing import Any
+
+import duva
+from django.conf import settings
+from django.core.exceptions import ImproperlyConfigured
+from django.core.mail import EmailMessage, EmailMultiAlternatives
+from django.core.mail.backends.base import BaseEmailBackend
+
+# Duva headers allowlist (docs/api.md); any other `X-*` is allowed except the reserved prefixes.
+_ALLOWED_HEADERS = frozenset(
+    {
+        "list-unsubscribe",
+        "list-unsubscribe-post",
+        "list-id",
+        "in-reply-to",
+        "references",
+        "auto-submitted",
+        "precedence",
+        "importance",
+        "feedback-id",
+    }
+)
+_RESERVED_PREFIXES = ("x-kumo", "x-duva", "x-tenant", "x-campaign")
+# A name Duva refuses: `@`, quotes, angle brackets, backslash, control characters, encoded words.
+_UNSAFE_NAME = re.compile(r'[@"<>\\\x00-\x1f\x7f]|=\?')
+
+#: Read by this backend, never forwarded: a stable key so a retried task sends only once.
+IDEMPOTENCY_HEADER = "X-Idempotency-Key"
+
+
+class EmailBackend(BaseEmailBackend):
+    """Sends `EmailMessage` objects through the Duva API.
+
+    Configuration, in order of precedence: the options given to the backend (`OPTIONS` of a
+    `MAILERS` entry, Django 6.1+), then the settings `DUVA_API_KEY`, `DUVA_DOMAIN`, `DUVA_BASE_URL`,
+    `DUVA_TIMEOUT`, `DUVA_MAX_RETRIES`, then the environment variables `DUVA_API_KEY` and
+    `DUVA_DOMAIN`. The options are `api_key`, `domain`, `base_url`, `timeout`, `max_retries`.
+
+    After a successful send, `message.duva_result` holds the `duva.SendMessageResult`
+    (`id`, `status`, `replayed`).
+    """
+
+    def __init__(
+        self,
+        fail_silently: bool = False,
+        *,
+        alias: str | None = None,
+        api_key: str | None = None,
+        domain: str | None = None,
+        base_url: str | None = None,
+        timeout: float | None = None,
+        max_retries: int | None = None,
+        client: duva.Duva | None = None,
+        **kwargs: Any,
+    ) -> None:
+        # `alias` exists from Django 6.1 only, and `fail_silently` is deprecated there as a base
+        # argument: this backend keeps its own attribute.
+        extra: dict[str, Any] = {"alias": alias} if alias is not None else {}
+        super().__init__(**extra, **kwargs)
+        self.fail_silently = fail_silently
+        self._options = {
+            "api_key": api_key,
+            "domain": domain,
+            "base_url": base_url,
+            "timeout": timeout,
+            "max_retries": max_retries,
+        }
+        self._client = client
+        self._owns_client = client is None
+
+    def open(self) -> bool:
+        if self._client is not None:
+            return False
+        options = self._options
+
+        def pick(name: str, setting: str, default: Any = None) -> Any:
+            value = options[name]
+            return value if value is not None else getattr(settings, setting, default)
+
+        self._client = duva.Duva(
+            api_key=pick("api_key", "DUVA_API_KEY"),
+            domain=pick("domain", "DUVA_DOMAIN"),
+            base_url=pick("base_url", "DUVA_BASE_URL", "https://api.duva.ca"),
+            timeout=float(pick("timeout", "DUVA_TIMEOUT", 10.0)),
+            max_retries=int(pick("max_retries", "DUVA_MAX_RETRIES", 2)),
+        )
+        return True
+
+    def close(self) -> None:
+        if self._client is not None and self._owns_client:
+            self._client.close()
+            self._client = None
+
+    def send_messages(self, email_messages: Sequence[EmailMessage]) -> int:
+        if not email_messages:
+            return 0
+        opened = False
+        try:
+            if self._client is None:
+                try:
+                    opened = self.open()
+                except (TypeError, ValueError) as error:
+                    # Missing key or domain: a configuration error, not a delivery failure.
+                    if not self.fail_silently:
+                        raise ImproperlyConfigured(str(error)) from error
+                    return 0
+            sent = 0
+            for message in email_messages:
+                if self._send(message):
+                    sent += 1
+            return sent
+        finally:
+            if opened:
+                self.close()
+
+    def _send(self, message: EmailMessage) -> bool:
+        assert self._client is not None
+        try:
+            params = _params(message)
+            result = self._client.messages.send(**params)
+        except (duva.DuvaError, ValueError):
+            if not self.fail_silently:
+                raise
+            return False
+        message.duva_result = result  # type: ignore[attr-defined]
+        return True
+
+
+def _params(message: EmailMessage) -> dict[str, Any]:
+    to = _addresses(message.to)
+    cc = _addresses(message.cc)
+    bcc = _addresses(message.bcc)
+    if not (to or cc or bcc):
+        raise ValueError("Duva: the message has no recipient")
+    if not message.from_email:
+        raise ValueError("Duva: the message has no from address")
+
+    params: dict[str, Any] = {
+        "from_": _address(message.from_email),
+        # Duva requires `to`; a message with only cc/bcc is not accepted by the API either.
+        "to": to,
+        "subject": message.subject,
+    }
+    if cc:
+        params["cc"] = cc
+    if bcc:
+        params["bcc"] = bcc
+
+    html, text = _bodies(message)
+    if html is not None:
+        params["html"] = html
+    if text is not None:
+        params["text"] = text
+    if message.reply_to:
+        params["reply_to"] = _address(message.reply_to[0])
+
+    headers: dict[str, str] = {}
+    for name, value in message.extra_headers.items():
+        lower = name.lower()
+        if lower == IDEMPOTENCY_HEADER.lower():
+            params["idempotency_key"] = str(value)
+        elif _forwardable(lower):
+            headers[name] = str(value)
+    if headers:
+        params["headers"] = headers
+
+    tags = getattr(message, "tags", None)
+    if tags:
+        params["tags"] = [str(tag) for tag in tags]
+    metadata = getattr(message, "metadata", None)
+    if metadata:
+        params["metadata"] = {str(key): str(value) for key, value in metadata.items()}
+
+    attachments = [_attachment(item) for item in message.attachments]
+    if attachments:
+        params["attachments"] = attachments
+    return params
+
+
+def _bodies(message: EmailMessage) -> tuple[str | None, str | None]:
+    """`(html, text)`. The body is HTML when `content_subtype == "html"`; a `text/html`
+    alternative (`EmailMultiAlternatives`) is the HTML otherwise."""
+    html: str | None = None
+    text: str | None = None
+    if message.content_subtype == "html":
+        html = str(message.body) or None
+    else:
+        text = str(message.body) or None
+    if isinstance(message, EmailMultiAlternatives):
+        for content, mimetype in message.alternatives:
+            if mimetype == "text/html" and html is None and isinstance(content, str):
+                html = content
+    return html, text
+
+
+def _forwardable(lower_name: str) -> bool:
+    if lower_name in _ALLOWED_HEADERS:
+        return True
+    return lower_name.startswith("x-") and not lower_name.startswith(_RESERVED_PREFIXES)
+
+
+def _address(value: str) -> str:
+    """`Name <address>`, or the bare address when Duva would refuse the name."""
+    name, address = parseaddr(value)
+    if not address:
+        return value.strip()
+    if not name or _UNSAFE_NAME.search(name):
+        return address
+    return duva.format_address(address, name)
+
+
+def _addresses(values: Sequence[str]) -> list[str]:
+    return [_address(value) for value in values]
+
+
+def _attachment(item: Any) -> duva.Attachment:
+    if isinstance(item, Message):
+        content = item.get_payload(decode=True)
+        if not isinstance(content, bytes):
+            raise ValueError("Duva: this attachment has no readable content")
+        content_id = item.get("Content-ID")
+        disposition = str(item.get("Content-Disposition", "")).lower()
+        return duva.Attachment.from_bytes(
+            item.get_filename() or "attachment",
+            content,
+            content_type=item.get_content_type(),
+            content_id=str(content_id).strip("<>")
+            if content_id and "inline" in disposition
+            else None,
+        )
+    filename, content, mimetype = item
+    data = content.encode() if isinstance(content, str) else bytes(content)
+    return duva.Attachment.from_bytes(filename or "attachment", data, content_type=mimetype)

duva_django-0.1.0/tests/conftest.py

@@ -0,0 +1,3 @@
+import os
+
+os.environ.setdefault("DJANGO_SETTINGS_MODULE", "tests.settings")

duva_django-0.1.0/tests/settings.py

@@ -0,0 +1,6 @@
+SECRET_KEY = "test"
+USE_TZ = True
+INSTALLED_APPS: list[str] = []
+EMAIL_BACKEND = "duva_django.EmailBackend"
+DUVA_API_KEY = "dv_test"
+DUVA_DOMAIN = "example.com"

duva_django-0.1.0/tests/test_backend.py

@@ -0,0 +1,275 @@
+from __future__ import annotations
+
+import base64
+import json
+from email.mime.image import MIMEImage
+from typing import Any
+
+import django
+import duva
+import httpx
+import pytest
+from django.core import mail
+from django.core.exceptions import ImproperlyConfigured
+from django.core.mail import EmailMessage, EmailMultiAlternatives, get_connection
+from django.test import override_settings
+
+from duva_django import EmailBackend
+
+
+class Recorder:
+    """A fake Duva API: records every request, answers with `handler`."""
+
+    def __init__(self, handler: Any = None) -> None:
+        self.requests: list[httpx.Request] = []
+        self._handler = handler or (
+            lambda request: httpx.Response(
+                202, json={"id": "msg_" + "0" * 31 + "1", "status": "queued"}
+            )
+        )
+
+    def __call__(self, request: httpx.Request) -> httpx.Response:
+        self.requests.append(request)
+        return self._handler(request)
+
+    @property
+    def body(self) -> dict[str, Any]:
+        assert len(self.requests) == 1
+        return json.loads(self.requests[0].content)
+
+    def backend(self, **kwargs: Any) -> EmailBackend:
+        client = duva.Duva(
+            api_key="dv_test",
+            domain="example.com",
+            max_retries=0,
+            http_client=httpx.Client(transport=httpx.MockTransport(self)),
+        )
+        return EmailBackend(client=client, **kwargs)
+
+
+@pytest.fixture
+def api() -> Recorder:
+    return Recorder()
+
+
+def test_maps_a_message_to_the_duva_request(api: Recorder) -> None:
+    message = EmailMultiAlternatives(
+        "Order",
+        "Plain text",
+        "Shop <shop@example.com>",
+        ["Client <a@example.org>"],
+        cc=["cc@example.org"],
+        bcc=["hidden@example.org"],
+        reply_to=["Support <help@example.com>"],
+    )
+    message.attach_alternative("<p>Hi</p>", "text/html")
+
+    assert api.backend().send_messages([message]) == 1
+
+    request = api.requests[0]
+    assert request.method == "POST"
+    assert request.url.path == "/v1/example.com/messages"
+    assert request.headers["authorization"] == "Bearer dv_test"
+    assert api.body == {
+        "from": "Shop <shop@example.com>",
+        "to": ["Client <a@example.org>"],
+        "cc": ["cc@example.org"],
+        "bcc": ["hidden@example.org"],
+        "subject": "Order",
+        "text": "Plain text",
+        "html": "<p>Hi</p>",
+        "reply_to": "Support <help@example.com>",
+    }
+
+
+def test_an_html_body_is_sent_as_html(api: Recorder) -> None:
+    message = EmailMessage("S", "<b>x</b>", "shop@example.com", ["a@example.org"])
+    message.content_subtype = "html"
+
+    api.backend().send_messages([message])
+
+    assert api.body["html"] == "<b>x</b>"
+    assert "text" not in api.body
+
+
+def test_reports_duvas_result_on_the_message(api: Recorder) -> None:
+    message = EmailMessage("S", "x", "shop@example.com", ["a@example.org"])
+
+    api.backend().send_messages([message])
+
+    assert message.duva_result.id == "msg_" + "0" * 31 + "1"  # type: ignore[attr-defined]
+    assert message.duva_result.status == "queued"  # type: ignore[attr-defined]
+
+
+def test_drops_a_display_name_duva_would_refuse_but_keeps_the_address(api: Recorder) -> None:
+    message = EmailMessage(
+        "S",
+        "x",
+        "shop@example.com",
+        ['"Mallory @ evil.com" <a@example.org>', "Foo <b@example.org>"],
+        cc=["=?UTF-8?B?Zm9v?= <c@example.org>"],
+    )
+
+    api.backend().send_messages([message])
+
+    assert api.body["to"] == ["a@example.org", "Foo <b@example.org>"]
+    assert api.body["cc"] == ["c@example.org"]
+
+
+def test_forwards_tags_metadata_and_allowed_headers_only(api: Recorder) -> None:
+    message = EmailMessage(
+        "S",
+        "x",
+        "shop@example.com",
+        ["a@example.org"],
+        headers={
+            "List-Unsubscribe": "<https://example.com/u/1>",
+            "X-Custom": "yes",
+            "X-Duva-Secret": "no",
+            "Organization": "Acme",
+            "Message-ID": "<x@y>",
+        },
+    )
+    message.tags = ["welcome"]  # type: ignore[attr-defined]
+    message.metadata = {"order_id": 42}  # type: ignore[attr-defined]
+
+    api.backend().send_messages([message])
+
+    assert api.body["tags"] == ["welcome"]
+    assert api.body["metadata"] == {"order_id": "42"}
+    assert api.body["headers"] == {
+        "List-Unsubscribe": "<https://example.com/u/1>",
+        "X-Custom": "yes",
+    }
+
+
+def test_the_idempotency_header_becomes_the_key_and_is_not_forwarded(api: Recorder) -> None:
+    message = EmailMessage(
+        "S", "x", "shop@example.com", ["a@example.org"], headers={"X-Idempotency-Key": "order-42"}
+    )
+
+    api.backend().send_messages([message])
+
+    assert api.requests[0].headers["idempotency-key"] == "order-42"
+    assert "headers" not in api.body
+
+
+def test_attachments_and_inline_images(api: Recorder) -> None:
+    message = EmailMessage("S", "x", "shop@example.com", ["a@example.org"])
+    message.attach("note.txt", "hello", "text/plain")
+    image = MIMEImage(b"\x89PNG\r\n\x1a\n" + b"0" * 16, "png")
+    image.add_header("Content-ID", "<logo>")
+    image.add_header("Content-Disposition", "inline", filename="logo.png")
+    message.attach(image)
+
+    api.backend().send_messages([message])
+
+    by_name = {a["filename"]: a for a in api.body["attachments"]}
+    assert base64.b64decode(by_name["note.txt"]["content"]) == b"hello"
+    assert by_name["note.txt"]["content_type"] == "text/plain"
+    assert by_name["note.txt"]["content_id"] is None
+    assert by_name["logo.png"]["content_id"] == "logo"
+    assert by_name["logo.png"]["content_type"] == "image/png"
+
+
+def test_a_duva_error_is_raised_unless_fail_silently() -> None:
+    rejected = Recorder(
+        lambda request: httpx.Response(
+            422, json={"error": {"code": "invalid_request", "message": "Invalid message"}}
+        )
+    )
+    message = EmailMessage("S", "x", "shop@example.com", ["a@example.org"])
+
+    with pytest.raises(duva.ValidationError):
+        rejected.backend().send_messages([message])
+    assert rejected.backend(fail_silently=True).send_messages([message]) == 0
+
+
+def test_counts_only_the_messages_that_were_accepted() -> None:
+    calls = {"n": 0}
+
+    def handler(request: httpx.Request) -> httpx.Response:
+        calls["n"] += 1
+        if calls["n"] == 1:
+            return httpx.Response(422, json={"error": {"code": "invalid_request", "message": "x"}})
+        return httpx.Response(202, json={"id": "msg_" + "0" * 32, "status": "queued"})
+
+    api = Recorder(handler)
+    messages = [EmailMessage("S", "x", "shop@example.com", [f"{i}@example.org"]) for i in range(2)]
+
+    assert api.backend(fail_silently=True).send_messages(messages) == 1
+
+
+def test_a_message_without_recipient_is_refused() -> None:
+    api = Recorder()
+
+    with pytest.raises(ValueError, match="no recipient"):
+        api.backend().send_messages([EmailMessage("S", "x", "shop@example.com", [])])
+    assert api.requests == []
+
+
+def test_django_send_mail_uses_the_configured_backend() -> None:
+    api = Recorder()
+    connection = get_connection("duva_django.EmailBackend", client=api.backend()._client)
+
+    sent = mail.send_mail(
+        "Hi", "Body", "shop@example.com", ["a@example.org"], connection=connection
+    )
+
+    assert sent == 1
+    assert api.body["subject"] == "Hi"
+
+
+@override_settings(DUVA_API_KEY=None, DUVA_DOMAIN=None)
+def test_missing_configuration_is_an_error_not_a_silent_loss(
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    monkeypatch.delenv("DUVA_API_KEY", raising=False)
+    monkeypatch.delenv("DUVA_DOMAIN", raising=False)
+    message = EmailMessage("S", "x", "shop@example.com", ["a@example.org"])
+
+    with pytest.raises(ImproperlyConfigured, match="API key"):
+        EmailBackend().send_messages([message])
+    assert EmailBackend(fail_silently=True).send_messages([message]) == 0
+
+
+def test_options_win_over_settings_and_reach_the_client(monkeypatch: pytest.MonkeyPatch) -> None:
+    captured: dict[str, Any] = {}
+
+    class FakeDuva:
+        def __init__(self, **kwargs: Any) -> None:
+            captured.update(kwargs)
+            self.messages = self
+
+        def send(self, **params: Any) -> Any:
+            return duva.SendMessageResult(id="m", status="queued", replayed=False, location=None)
+
+        def close(self) -> None:
+            captured["closed"] = True
+
+    monkeypatch.setattr(duva, "Duva", FakeDuva)
+    backend = EmailBackend(api_key="dv_opt", domain="opt.example", timeout=3, max_retries=5)
+
+    assert backend.send_messages([EmailMessage("S", "x", "a@opt.example", ["b@example.org"])]) == 1
+    assert captured["api_key"] == "dv_opt" and captured["domain"] == "opt.example"
+    assert captured["timeout"] == 3.0 and captured["max_retries"] == 5
+    assert captured["base_url"] == "https://api.duva.ca"
+    assert captured["closed"] is True
+
+
+@pytest.mark.skipif(django.VERSION < (6, 1), reason="MAILERS arrives in Django 6.1")
+def test_works_as_a_mailers_entry() -> None:
+    from django.core.mail import mailers
+
+    with override_settings(
+        MAILERS={
+            "default": {
+                "BACKEND": "duva_django.EmailBackend",
+                "OPTIONS": {"api_key": "dv_x", "domain": "example.com"},
+            }
+        }
+    ):
+        backend = mailers["default"]
+
+        assert isinstance(backend, EmailBackend)
+        assert backend.alias == "default"