ntc-dev-kit 1.0.0__py3-none-any.whl

ntc/templates/drf_structure/templates/core/services/azure/email/backend.py

@@ -0,0 +1,108 @@
+"""Django email backend that sends through Azure Communication Services.
+
+Configure with:
+
+    EMAIL_BACKEND = 'core.services.azure.email.backend.AzureCommunicationEmailBackend'
+
+This backend is a drop-in replacement for the SMTP / console backends.
+It supports ``EmailMessage`` and ``EmailMultiAlternatives`` (HTML +
+text). When ``fail_silently=False`` (the default), Azure errors bubble
+up; otherwise they are logged and counted as 0 successful sends.
+"""
+from __future__ import annotations
+
+import logging
+from typing import Iterable
+
+from django.core.mail.backends.base import BaseEmailBackend
+from django.core.mail.message import EmailMessage, EmailMultiAlternatives
+
+from core.services.azure.email.client import (
+    AzureEmailClient,
+    AzureEmailNotConfigured,
+    AzureEmailSendError,
+    EmailMessageSpec,
+    EmailRecipient,
+)
+
+logger = logging.getLogger(__name__)
+
+
+def _to_recipients(addresses: Iterable[str]):
+    return [EmailRecipient(address=a) for a in addresses if a]
+
+
+def _split_html_text(message: EmailMessage):
+    """Return ``(plain_text, html)`` from a Django ``EmailMessage``."""
+    plain = None
+    html = None
+    if isinstance(message, EmailMultiAlternatives):
+        plain = message.body or None
+        for content, mime in message.alternatives or []:
+            if mime == 'text/html':
+                html = content
+                break
+    else:
+        if (message.content_subtype or 'plain') == 'html':
+            html = message.body or None
+        else:
+            plain = message.body or None
+    return plain, html
+
+
+class AzureCommunicationEmailBackend(BaseEmailBackend):
+    """Send Django ``EmailMessage`` instances through Azure ACS Email."""
+
+    def __init__(self, fail_silently: bool = False, **kwargs):
+        super().__init__(fail_silently=fail_silently)
+        self._client = AzureEmailClient()
+
+    def send_messages(self, email_messages):
+        if not email_messages:
+            return 0
+
+        sent = 0
+        for message in email_messages:
+            if self._send(message):
+                sent += 1
+        return sent
+
+    # ── Internal ──────────────────────────────────────────────────────────
+    def _send(self, message: EmailMessage) -> bool:
+        if not message.recipients():
+            return False
+
+        plain, html = _split_html_text(message)
+        spec = EmailMessageSpec(
+            subject=message.subject or '(no subject)',
+            to=_to_recipients(message.to),
+            cc=_to_recipients(message.cc),
+            bcc=_to_recipients(message.bcc),
+            reply_to=_to_recipients(message.reply_to),
+            sender=message.from_email or None,
+            plain_text=plain,
+            html=html,
+            headers=dict(message.extra_headers or {}),
+        )
+
+        try:
+            self._client.send(spec)
+            return True
+        except AzureEmailNotConfigured:
+            if not self.fail_silently:
+                raise
+            logger.warning(
+                'Azure ACS email is not configured; dropping message to %s',
+                message.to,
+            )
+            return False
+        except AzureEmailSendError as exc:
+            if not self.fail_silently:
+                raise
+            logger.error('ACS email send failed: %s', exc)
+            return False
+        except Exception as exc:  # pragma: no cover - defensive
+            if not self.fail_silently:
+                raise
+            logger.exception('Unexpected error sending ACS email: %s', exc)
+            return False

ntc/templates/drf_structure/templates/core/services/azure/email/client.py

@@ -0,0 +1,296 @@
+"""Thin wrapper around Azure Communication Services Email.
+
+This module hides the Azure SDK behind a small, mockable surface so the
+rest of the codebase only has to know about :class:`AzureEmailClient`.
+
+Configuration (read from ``django.conf.settings``):
+
+- ``AZURE_COMMUNICATION_ENDPOINT`` (e.g. ``https://xxx.communication.azure.com``)
+- ``AZURE_COMMUNICATION_ACCESS_KEY``
+- ``AZURE_COMMUNICATION_EMAIL_SENDER`` (the verified MailFrom address,
+  e.g. ``DoNotReply@xxxxxxxx.azurecomm.net``) — or the per-purpose
+  ``AZURE_COMMUNICATION_EMAIL_SENDER_*`` slots resolved via
+  :func:`resolve_sender`.
+
+Optional tuning:
+
+- ``AZURE_COMMUNICATION_EMAIL_POLLING_INTERVAL_SECONDS`` (default ``2``)
+- ``AZURE_COMMUNICATION_EMAIL_TIMEOUT_SECONDS`` (default ``60``)
+
+When the endpoint or access key is missing, the client raises
+:class:`AzureEmailNotConfigured` so callers (or the Django backend) can
+fall back to ``django.core.mail.backends.console.EmailBackend`` in dev.
+"""
+from __future__ import annotations
+
+import logging
+import time
+from dataclasses import dataclass, field
+from typing import Iterable, List, Optional
+
+from django.conf import settings
+
+logger = logging.getLogger(__name__)
+
+
+class AzureEmailNotConfigured(RuntimeError):
+    """Raised when the Azure Communication Services email client is used
+    without a connection string + sender configured."""
+
+
+class AzureEmailSendError(RuntimeError):
+    """Raised when Azure rejects a send or polling fails."""
+
+
+@dataclass
+class EmailRecipient:
+    """An ACS recipient row (``{address, displayName}``)."""
+
+    address: str
+    display_name: str = ''
+
+    def to_dict(self) -> dict:
+        d = {'address': self.address}
+        if self.display_name:
+            d['displayName'] = self.display_name
+        return d
+
+
+@dataclass
+class EmailMessageSpec:
+    """Strict, validated message spec passed to :meth:`AzureEmailClient.send`.
+
+    Bodies are optional individually but at least one of ``html`` / ``plain_text``
+    must be set.
+    """
+
+    subject: str
+    to: List[EmailRecipient]
+    plain_text: Optional[str] = None
+    html: Optional[str] = None
+    cc: List[EmailRecipient] = field(default_factory=list)
+    bcc: List[EmailRecipient] = field(default_factory=list)
+    reply_to: List[EmailRecipient] = field(default_factory=list)
+    sender: Optional[str] = None
+    headers: dict = field(default_factory=dict)
+
+    def to_acs_payload(self, default_sender: str) -> dict:
+        if not self.subject:
+            raise ValueError('subject is required')
+        if not self.to:
+            raise ValueError('at least one "to" recipient is required')
+        if not self.html and not self.plain_text:
+            raise ValueError('one of html or plain_text body is required')
+
+        content: dict = {'subject': self.subject}
+        if self.plain_text:
+            content['plainText'] = self.plain_text
+        if self.html:
+            content['html'] = self.html
+
+        recipients: dict = {'to': [r.to_dict() for r in self.to]}
+        if self.cc:
+            recipients['cc'] = [r.to_dict() for r in self.cc]
+        if self.bcc:
+            recipients['bcc'] = [r.to_dict() for r in self.bcc]
+
+        message: dict = {
+            'senderAddress': self.sender or default_sender,
+            'content': content,
+            'recipients': recipients,
+        }
+        if self.reply_to:
+            message['replyTo'] = [r.to_dict() for r in self.reply_to]
+        if self.headers:
+            # ACS exposes headers under ``content`` for some SDK versions; we
+            # keep them as ``headers`` which the SDK normalises.
+            message['headers'] = [
+                {'name': k, 'value': v} for k, v in self.headers.items()
+            ]
+        return message
+
+
+def _coerce_recipients(addresses: Iterable[str]) -> List[EmailRecipient]:
+    return [EmailRecipient(address=a) for a in addresses if a]
+
+
+# Canonical sender purposes. Keep in sync with
+# ``settings.AZURE_COMMUNICATION_EMAIL_SENDERS``.
+SENDER_NO_REPLY = 'no_reply'
+SENDER_NOTIFICATION = 'notification'
+SENDER_SUPPORT = 'support'
+SENDER_MARKETING = 'marketing'
+VALID_SENDER_KEYS = frozenset({
+    SENDER_NO_REPLY, SENDER_NOTIFICATION, SENDER_SUPPORT, SENDER_MARKETING,
+})
+
+
+def resolve_sender(sender: Optional[str]) -> str:
+    """Turn a purpose keyword or literal address into a concrete MailFrom.
+
+    - ``None`` → default sender (``AZURE_COMMUNICATION_EMAIL_DEFAULT_SENDER_KEY``
+      or legacy ``AZURE_COMMUNICATION_EMAIL_SENDER``).
+    - A key in ``VALID_SENDER_KEYS`` → looked up in
+      ``AZURE_COMMUNICATION_EMAIL_SENDERS``.
+    - Anything containing ``@`` → treated as a literal address and
+      returned verbatim.
+    - Unknown keys → ``ValueError``.
+    """
+    senders = getattr(settings, 'AZURE_COMMUNICATION_EMAIL_SENDERS', {}) or {}
+    default_key = getattr(
+        settings, 'AZURE_COMMUNICATION_EMAIL_DEFAULT_SENDER_KEY', 'notification',
+    )
+    legacy = getattr(settings, 'AZURE_COMMUNICATION_EMAIL_SENDER', '') or ''
+
+    if sender is None or sender == '':
+        return senders.get(default_key) or legacy
+
+    if '@' in sender:
+        return sender
+
+    if sender not in VALID_SENDER_KEYS:
+        raise ValueError(
+            f'Unknown sender key {sender!r}. Expected one of '
+            f'{sorted(VALID_SENDER_KEYS)} or an email address.'
+        )
+    resolved = senders.get(sender) or legacy
+    if not resolved:
+        raise ValueError(
+            f'Sender {sender!r} is not configured. Set '
+            f'AZURE_COMMUNICATION_EMAIL_SENDER_{sender.upper()}.'
+        )
+    return resolved
+
+
+class AzureEmailClient:
+    """Wraps :class:`azure.communication.email.EmailClient`.
+
+    The client is lazily instantiated so importing this module never
+    forces an Azure SDK dependency check at start-up.
+    """
+
+    def __init__(
+        self,
+        endpoint: Optional[str] = None,
+        access_key: Optional[str] = None,
+        sender: Optional[str] = None,
+        polling_interval_seconds: Optional[int] = None,
+        timeout_seconds: Optional[int] = None,
+    ):
+        self._endpoint = endpoint if endpoint is not None else getattr(
+            settings, 'AZURE_COMMUNICATION_ENDPOINT', '',
+        )
+        self._access_key = access_key if access_key is not None else getattr(
+            settings, 'AZURE_COMMUNICATION_ACCESS_KEY', '',
+        )
+        self._sender = sender or getattr(
+            settings, 'AZURE_COMMUNICATION_EMAIL_SENDER', '',
+        )
+        self._polling_interval = polling_interval_seconds or getattr(
+            settings, 'AZURE_COMMUNICATION_EMAIL_POLLING_INTERVAL_SECONDS', 2,
+        )
+        self._timeout = timeout_seconds or getattr(
+            settings, 'AZURE_COMMUNICATION_EMAIL_TIMEOUT_SECONDS', 60,
+        )
+        self._client = None
+
+    # ── Internal ──────────────────────────────────────────────────────────
+    def _has_credentials(self) -> bool:
+        return bool(self._endpoint and self._access_key)
+
+    def _ensure_client(self):
+        if self._client is not None:
+            return self._client
+
+        if not self._has_credentials() or not self._sender:
+            raise AzureEmailNotConfigured(
+                'Azure Communication Services email is not configured. '
+                'Set AZURE_COMMUNICATION_ENDPOINT, '
+                'AZURE_COMMUNICATION_ACCESS_KEY and '
+                'AZURE_COMMUNICATION_EMAIL_SENDER (or one of the '
+                'per-purpose AZURE_COMMUNICATION_EMAIL_SENDER_* slots).'
+            )
+
+        # Imported lazily so the rest of the codebase doesn't hard-fail
+        # if the Azure SDK ever gets removed.
+        from azure.communication.email import EmailClient
+        from azure.core.credentials import AzureKeyCredential
+
+        self._client = EmailClient(
+            endpoint=self._endpoint,
+            credential=AzureKeyCredential(self._access_key),
+        )
+        return self._client
+
+    # ── Public ────────────────────────────────────────────────────────────
+    @property
+    def is_configured(self) -> bool:
+        return self._has_credentials() and bool(self._sender)
+
+    def send(self, message: EmailMessageSpec) -> str:
+        """Send ``message`` via ACS and return the operation ``messageId``.
+
+        Blocks (politely) until ACS reports the operation completed or
+        the timeout is reached.
+        """
+        client = self._ensure_client()
+        payload = message.to_acs_payload(default_sender=self._sender)
+
+        try:
+            poller = client.begin_send(payload)
+        except Exception as exc:
+            raise AzureEmailSendError(f'ACS rejected message: {exc}') from exc
+
+        # ``begin_send`` returns an LRO poller. ``result`` blocks until done.
+        deadline = time.monotonic() + self._timeout
+        while not poller.done():
+            if time.monotonic() > deadline:
+                raise AzureEmailSendError(
+                    f'ACS send polling timed out after {self._timeout}s',
+                )
+            time.sleep(self._polling_interval)
+
+        result = poller.result()
+        # ``result`` is a dict-like with at least ``id`` and ``status``.
+        status = (result.get('status') or '').lower() if isinstance(result, dict) else ''
+        msg_id = (result.get('id') if isinstance(result, dict) else None) or ''
+        if status not in ('', 'succeeded'):
+            raise AzureEmailSendError(
+                f'ACS send finished with status={status!r} id={msg_id!r}',
+            )
+        return msg_id
+
+    # ── Convenience wrapper ───────────────────────────────────────────────
+    def send_simple(
+        self,
+        *,
+        subject: str,
+        to: Iterable[str],
+        html: Optional[str] = None,
+        text: Optional[str] = None,
+        cc: Iterable[str] = (),
+        bcc: Iterable[str] = (),
+        reply_to: Iterable[str] = (),
+        headers: Optional[dict] = None,
+    ) -> str:
+        return self.send(EmailMessageSpec(
+            subject=subject,
+            to=_coerce_recipients(to),
+            cc=_coerce_recipients(cc),
+            bcc=_coerce_recipients(bcc),
+            reply_to=_coerce_recipients(reply_to),
+            html=html,
+            plain_text=text,
+            headers=headers or {},
+        ))
+
+
+_default_client: Optional[AzureEmailClient] = None
+
+
+def get_default_client() -> AzureEmailClient:
+    """Process-global singleton, lazily constructed."""
+    global _default_client
+    if _default_client is None:
+        _default_client = AzureEmailClient()
+    return _default_client

ntc/templates/drf_structure/templates/core/services/azure/email/notifier.py

@@ -0,0 +1,102 @@
+"""High-level templated email sender.
+
+The rest of the codebase should call :func:`send_template_email` rather
+than touching the Azure SDK or :class:`EmailMultiAlternatives` directly.
+The function renders ``<template>.html`` and (optionally) ``<template>.txt``
+under the configured template loader and sends through Django's
+``EMAIL_BACKEND`` — which is wired to Azure ACS in production.
+"""
+from __future__ import annotations
+
+import logging
+from typing import Iterable, Optional
+
+from django.conf import settings
+from django.core.mail import EmailMultiAlternatives
+from django.template import TemplateDoesNotExist
+from django.template.loader import render_to_string
+
+from core.services.azure.email.client import resolve_sender
+
+logger = logging.getLogger(__name__)
+
+
+def send_template_email(
+    *,
+    subject: str,
+    to: Iterable[str] | str,
+    template: str,
+    context: Optional[dict] = None,
+    cc: Iterable[str] = (),
+    bcc: Iterable[str] = (),
+    reply_to: Iterable[str] = (),
+    from_email: Optional[str] = None,
+    sender: Optional[str] = None,
+    headers: Optional[dict] = None,
+    fail_silently: bool = False,
+) -> int:
+    """Render ``template`` and send the resulting message.
+
+    ``template`` is a basename. The function looks up
+    ``<template>.html`` (required) and ``<template>.txt`` (optional).
+    If the ``.txt`` file is missing, a stripped-text fallback is
+    generated from the HTML so non-HTML clients still see something.
+
+    Sender resolution (in order of precedence):
+
+    1. Explicit ``from_email`` (literal address).
+    2. ``sender`` keyword — one of ``no_reply`` / ``notification`` /
+       ``support`` / ``marketing`` — resolved against
+       ``settings.AZURE_COMMUNICATION_EMAIL_SENDERS``.
+    3. ``settings.AZURE_COMMUNICATION_EMAIL_DEFAULT_SENDER_KEY`` →
+       ``AZURE_COMMUNICATION_EMAIL_SENDERS`` lookup.
+    4. ``settings.DEFAULT_FROM_EMAIL``.
+
+    Returns the number of messages successfully delivered (0 or 1).
+    """
+    context = context or {}
+    if isinstance(to, str):
+        to_list = [to]
+    else:
+        to_list = [addr for addr in to if addr]
+    if not to_list:
+        logger.warning('send_template_email called without recipients')
+        return 0
+
+    try:
+        html_body = render_to_string(f'{template}.html', context)
+    except TemplateDoesNotExist:
+        # Re-raise loudly: a missing HTML template is a programmer error.
+        raise
+
+    try:
+        text_body = render_to_string(f'{template}.txt', context)
+    except TemplateDoesNotExist:
+        # Lightweight HTML→text fallback. Avoids a html2text dependency
+        # while still beating "no plain part at all".
+        from html import unescape
+        import re
+
+        text_body = unescape(re.sub(r'<[^>]+>', '', html_body)).strip()
+
+    if from_email:
+        resolved_from = from_email
+    else:
+        try:
+            resolved_from = resolve_sender(sender) or settings.DEFAULT_FROM_EMAIL
+        except ValueError as exc:
+            logger.error('send_template_email: %s', exc)
+            resolved_from = settings.DEFAULT_FROM_EMAIL
+
+    msg = EmailMultiAlternatives(
+        subject=subject,
+        body=text_body,
+        from_email=resolved_from,
+        to=to_list,
+        cc=list(cc) or None,
+        bcc=list(bcc) or None,
+        reply_to=list(reply_to) or None,
+        headers=headers or None,
+    )
+    msg.attach_alternative(html_body, 'text/html')
+    return msg.send(fail_silently=fail_silently)