1"""Base email backend class."""
 2
 3from __future__ import annotations
 4
 5from abc import ABC, abstractmethod
 6from typing import TYPE_CHECKING, Self
 7
 8if TYPE_CHECKING:
 9    from types import TracebackType
10
11    from ..message import EmailMessage
12
13__all__ = ["BaseEmailBackend"]
14
15
16class BaseEmailBackend(ABC):
17    """
18    Base class for email backend implementations.
19
20    Subclasses must at least overwrite send_messages().
21
22    open() and close() can be called indirectly by using a backend object as a
23    context manager:
24
25       with backend as connection:
26           # do something with connection
27           pass
28    """
29
30    def open(self) -> bool:
31        """
32        Open a network connection.
33
34        This method can be overwritten by backend implementations to
35        open a network connection.
36
37        It's up to the backend implementation to track the status of
38        a network connection if it's needed by the backend.
39
40        This method can be called by applications to force a single
41        network connection to be used when sending mails. See the
42        send_messages() method of the SMTP backend for a reference
43        implementation.
44
45        The default implementation does nothing.
46        """
47        return False
48
49    def close(self) -> None:
50        """Close a network connection."""
51
52    def __enter__(self) -> Self:
53        try:
54            self.open()
55        except Exception:
56            self.close()
57            raise
58        return self
59
60    def __exit__(
61        self,
62        exc_type: type[BaseException] | None,
63        exc_value: BaseException | None,
64        traceback: TracebackType | None,
65    ) -> None:
66        self.close()
67
68    @abstractmethod
69    def send_messages(self, email_messages: list[EmailMessage]) -> int:
70        """
71        Send one or more EmailMessage objects and return the number of email
72        messages sent.
73        """
74        ...