реализована отпарвки электронных писем

Author: albertalexandrov

README.md

@@ -18,6 +18,7 @@
 - [Валидация входящих данных](./docs/Валидация%20входящих%20данных.md)
 - [Фильтрация, пагинация, сортировка.md](docs/%D0%A4%D0%B8%D0%BB%D1%8C%D1%82%D1%80%D0%B0%D1%86%D0%B8%D1%8F%2C%20%D0%BF%D0%B0%D0%B3%D0%B8%D0%BD%D0%B0%D1%86%D0%B8%D1%8F%2C%20%D1%81%D0%BE%D1%80%D1%82%D0%B8%D1%80%D0%BE%D0%B2%D0%BA%D0%B0.md)
 - [Логгирование](docs/Логирование.md)
+- [Отправка электронных писем](docs/%D0%9E%D1%82%D0%BF%D1%80%D0%B0%D0%B2%D0%BA%D0%B0%20%D1%8D%D0%BB%D0%B5%D0%BA%D1%82%D1%80%D0%BE%D0%BD%D0%BD%D1%8B%D1%85%20%D0%BF%D0%B8%D1%81%D0%B5%D0%BC.md)
 - [TODO](#todo)
 
 ## TODO
@@ -27,7 +28,7 @@
 и который является входной точкой в приложение)
 -  [ ] прикинуть, какие еще консольные команды могут пригодиться (напр., миграции)
 -  [x] репозитории
--  [ ] http-исключения
+-  [x] http-исключения
 -  [ ] разработать формат ошибок (ошибки для тоста, ошибки валидации)
 -  [x] интегрировать https://github.com/albertalexandrov/django-like-repositories
 -  [x] работа с БД не только в рамках апишки, но в рамках напр. асинхронных задач
@@ -40,3 +41,4 @@
 -  [ ] расширяемость либы как в django
 -  [x] Пермишены
 -  [x] Аутентификация
+-  [x] Отправка электронных писем (мультибекенды)

docs/Отправка электронных писем.md

@@ -0,0 +1,76 @@
+# Отправка электронных писем
+
+Реализована поддержка отправки электронных писем через множество провайдеров (которая заедет в Django 6, 
+см. PR https://github.com/django/django/pull/18421/)
+
+Во многом все как в Django. Много скопированого кода.
+
+## Настройки
+
+Настройки провайдеров хранятся в настройке `EMAIL_PROVIDERS`:
+
+```python
+EMAIL_PROVIDERS = {
+    'console': {
+        'BACKEND': 'fastapi_django.mail.backends.console.EmailBackend',
+    },
+    'dummy': {
+        'BACKEND': 'fastapi_django.mail.backends.dummy.EmailBackend',
+    },
+    'filebased': {
+        'BACKEND': 'fastapi_django.mail.backends.filebased.EmailBackend',
+        "OPTIONS": {
+            "file_path": "mails",
+        }
+    },
+    'locmem': {
+        'BACKEND': 'fastapi_django.mail.backends.locmem.EmailBackend',
+    },
+    'smtpsrv': {
+        'BACKEND': 'fastapi_django.mail.backends.smtp.EmailBackend',
+        "HOST": env.str("SMTPSRV_HOST"),
+        "PORT": env.str("SMTPSRV_PORT"),
+        "OPTIONS": {
+            "username": env.str("SMTPSRV_USERNAME"),
+            "password": env.str("SMTPSRV_PASSWORD"),
+            "from_email": env.str("SMTPSRV_FROM_EMAIL"),
+        },
+    },
+}
+```
+
+## Отправка электронных писем
+
+Для отправки элеектронных писем реализована функция `fastapi_django.mail.send_mail`. Чтобы отправить письмо через 
+конкретный провайдер, необходимо передать его алиас в параметр `provider`:
+
+```python
+from fastapi_django.mail import send_mail
+await send_mail(
+    subject="Тема письма", 
+    body="Тело письма", 
+    recipient_list=["[email protected]"], 
+    provider="smtpsrv"
+)
+```
+
+## Реализации в сторонних библиотеках
+
+Чтобы написать свой бэкенд, необходимо отнаследоваться от базового класса `fastapi_django.mail.backends.base.BaseEmailBackend` 
+и реализовать необходимые методы.
+
+### Нестандартные способы отправки писем
+
+См. библиотеки fastapi-django-kz и fastapi-django-nkz.
+
+## TODO
+
+1. Фикстуры для работы с почтой https://pytest-django.readthedocs.io/en/stable/helpers.html#clearing-of-mail-outbox
+2. Показалась интересной библиотека, которая реализует бекенд, который отправляет письмо в рамках серели таски https://pypi.org/project/django-celery-email/
+
+## Ссылки
+
+1. Поддержка множества бекендов отправки почты в Django https://code.djangoproject.com/ticket/35514#ticket, PR https://github.com/django/django/pull/18421
+2. https://pypi.org/project/django-celery-email/
+3. https://github.com/django-ses/django-ses/tree/main
+4. 

fastapi_django/conf/global_settings.py

@@ -32,5 +32,13 @@
 
 MANAGEMENT: list[dict] = []
 
-# Custom logging configuration.
 LOGGING: dict[str, Any] = {}
+
+EMAIL_PROVIDERS: dict[str, Any] = {}
+
+DEFAULT_CHARSET = "utf-8"
+
+# Whether to send SMTP 'Date' header in the local time zone or in UTC.
+EMAIL_USE_LOCALTIME = False
+
+DEFAULT_EMAIL_PROVIDER_ALIAS = "default"

fastapi_django/mail/__init__.py

@@ -0,0 +1,99 @@
+"""
+Tools for sending email.
+"""
+from typing import Any, Iterable, Sequence
+
+from fastapi_django.conf import settings
+# Imported for backwards compatibility and for the sake
+# of a cleaner namespace. These symbols used to be in
+# fastapi_django/core/mail.py before the introduction of email
+# backends and the subsequent reorganization (See #10355)
+from fastapi_django.mail.message import (
+    DEFAULT_ATTACHMENT_MIME_TYPE,
+    BadHeaderError,
+    EmailAlternative,
+    EmailAttachment,
+    EmailMessage,
+    EmailMultiAlternatives,
+    SafeMIMEMultipart,
+    SafeMIMEText,
+    forbid_multi_line_headers,
+    make_msgid,
+)
+from fastapi_django.mail.utils import DNS_NAME, CachedDnsName, get_provider, get_required, get_option
+
+__all__ = [
+    "CachedDnsName",
+    "DNS_NAME",
+    "EmailMessage",
+    "EmailMultiAlternatives",
+    "SafeMIMEText",
+    "SafeMIMEMultipart",
+    "DEFAULT_ATTACHMENT_MIME_TYPE",
+    "make_msgid",
+    "BadHeaderError",
+    "forbid_multi_line_headers",
+    "get_connection",
+    "send_mail",
+    "send_mass_mail",
+    "EmailAlternative",
+    "EmailAttachment",
+    "outbox"
+]
+
+from fastapi_django.utils.module_loading import import_string
+
+outbox: list = []
+
+
+def get_connection(fail_silently: bool = False, provider: str = settings.DEFAULT_EMAIL_PROVIDER_ALIAS, **kw: Any):
+    backend = get_required(provider, "BACKEND")
+    klass = import_string(backend)
+    return klass(fail_silently=fail_silently, provider=provider, **kw)
+
+
+async def send_mail(
+    subject: str,
+    body: str,
+    recipient_list: Sequence[str],
+    from_email: str | None = None,
+    fail_silently: bool = False,
+    html_message=None,
+    connection=None,
+    provider: str = settings.DEFAULT_EMAIL_PROVIDER_ALIAS,
+):
+    """
+    Если передан connection, то using игнорируется
+    """
+    connection = connection or get_connection(fail_silently=fail_silently, provider=provider)
+    from_email = from_email or get_option(provider, "from_email")
+    mail = EmailMultiAlternatives(
+        subject, body, from_email, recipient_list, connection=connection
+    )
+    if html_message:
+        mail.attach_alternative(html_message, "text/html")
+
+    return await mail.send()
+
+
+async def send_mass_mail(
+    datatuple, fail_silently=False, connection=None, provider: str = settings.DEFAULT_EMAIL_PROVIDER_ALIAS,
+):
+    """
+    Given a datatuple of (subject, message, from_email, recipient_list), send
+    each message to each recipient list. Return the number of emails sent.
+
+    If from_email is None, use the DEFAULT_FROM_EMAIL setting.
+    If auth_user and auth_password are set, use them to log in.
+    If auth_user is None, use the EMAIL_HOST_USER setting.
+    If auth_password is None, use the EMAIL_HOST_PASSWORD setting.
+
+    Note: The API for this method is frozen. New code wanting to extend the
+    functionality should use the EmailMessage class directly.
+    """
+    connection = connection or get_connection(fail_silently=fail_silently, provider=provider)
+    messages = [
+        EmailMessage(subject, body, sender, recipient, connection=connection, prodiver=provider)
+        for subject, body, sender, recipient in datatuple
+    ]
+    return await connection.send_messages(messages)

fastapi_django/mail/backends/__init__.py

@@ -0,0 +1 @@
+# Mail backends shipped with Django.

fastapi_django/mail/backends/base.py

@@ -0,0 +1,67 @@
+"""Base email backend class."""
+from typing import Any
+
+from fastapi_django.conf import settings
+from fastapi_django.mail import get_provider
+
+
+class BaseEmailBackend:
+    """
+    Base class for email backend implementations.
+
+    Subclasses must at least overwrite send_messages().
+
+    open() and close() can be called indirectly by using a backend object as a
+    context manager:
+
+       with backend as connection:
+           # do something with connection
+           pass
+    """
+
+    def __init__(self, fail_silently: bool = False, provider: str = settings.DEFAULT_EMAIL_PROVIDER_ALIAS, **kw: Any) -> None:
+        self.fail_silently = fail_silently
+        self.provider = provider
+
+    async def open(self):
+        """
+        Open a network connection.
+
+        This method can be overwritten by backend implementations to
+        open a network connection.
+
+        It's up to the backend implementation to track the status of
+        a network connection if it's needed by the backend.
+
+        This method can be called by applications to force a single
+        network connection to be used when sending mails. See the
+        send_messages() method of the SMTP backend for a reference
+        implementation.
+
+        The default implementation does nothing.
+        """
+        pass
+
+    async def close(self):
+        """Close a network connection."""
+        pass
+
+    async def __aenter__(self):
+        try:
+            await self.open()
+        except Exception:
+            await self.close()
+            raise
+        return self
+
+    async def __aexit__(self, exc_type, exc_value, traceback):
+        await self.close()
+
+    async def send_messages(self, email_messages):
+        """
+        Send one or more EmailMessage objects and return the number of email
+        messages sent.
+        """
+        raise NotImplementedError(
+            "subclasses of BaseEmailBackend must override send_messages() method"
+        )

fastapi_django/mail/backends/console.py

@@ -0,0 +1,48 @@
+"""
+Email backend that writes messages to console instead of sending them.
+"""
+
+import sys
+import threading
+
+from fastapi_django.mail.backends.base import BaseEmailBackend
+
+
+class EmailBackend(BaseEmailBackend):
+    """
+    TODO: нужно что то в асинхронное переделывать?
+    """
+    def __init__(self, *args, **kwargs):
+        super().__init__(*args, **kwargs)
+        self.stream = kwargs.pop("stream", sys.stdout)
+        self._lock = threading.RLock()
+
+    def write_message(self, message):
+        msg = message.message()
+        msg_data = msg.as_bytes()
+        charset = (
+            msg.get_charset().get_output_charset() if msg.get_charset() else "utf-8"
+        )
+        msg_data = msg_data.decode(charset)
+        self.stream.write("%s\n" % msg_data)
+        self.stream.write("-" * 79)
+        self.stream.write("\n")
+
+    async def send_messages(self, email_messages):
+        """Write all messages to the stream in a thread-safe way."""
+        if not email_messages:
+            return
+        msg_count = 0
+        with self._lock:
+            try:
+                stream_created = await self.open()
+                for message in email_messages:
+                    self.write_message(message)
+                    self.stream.flush()  # flush after each message
+                    msg_count += 1
+                if stream_created:
+                    await self.close()
+            except Exception:
+                if not self.fail_silently:
+                    raise
+        return msg_count

fastapi_django/mail/backends/dummy.py

@@ -0,0 +1,10 @@
+"""
+Dummy email backend that does nothing.
+"""
+
+from fastapi_django.mail.backends.base import BaseEmailBackend
+
+
+class EmailBackend(BaseEmailBackend):
+    async def send_messages(self, email_messages):
+        return len(list(email_messages))