plain.email 0.13.0__py3-none-any.whl

plain/email/CHANGELOG.md

@@ -0,0 +1,54 @@
+# plain-email changelog
+
+## [0.13.0](https://github.com/dropseed/plain/releases/plain-email@0.13.0) (2025-12-04)
+
+### What's changed
+
+- Internal typing improvements for better type checker compatibility ([ac1eeb0](https://github.com/dropseed/plain/commit/ac1eeb0ea05b26dfc7e32c50f2a5a5bc7e098ceb))
+
+### Upgrade instructions
+
+- No changes required
+
+## [0.12.0](https://github.com/dropseed/plain/releases/plain-email@0.12.0) (2025-11-12)
+
+### What's changed
+
+- The filebased email backend now requires `EMAIL_FILE_PATH` to be set and raises `ImproperlyConfigured` if not provided ([f4dbcef](https://github.com/dropseed/plain/commit/f4dbcefa929058be517cb1d4ab35bd73a89f26b8))
+- `BaseEmailBackend` now uses Python's abstract base class with `@abstractmethod` for better type checking ([245b5f4](https://github.com/dropseed/plain/commit/245b5f472c89178b8b764869f1624f8fc885b0f7))
+
+### Upgrade instructions
+
+- If using the filebased email backend, ensure `EMAIL_FILE_PATH` is configured in your settings or passed when initializing the backend
+
+## [0.11.1](https://github.com/dropseed/plain/releases/plain-email@0.11.1) (2025-10-06)
+
+### What's changed
+
+- Added comprehensive type annotations throughout the package for improved IDE support and type checking ([5a32120](https://github.com/dropseed/plain/commit/5a3212020c473d3a10763cedd0b0b7ca778911de))
+
+### Upgrade instructions
+
+- No changes required
+
+## [0.11.0](https://github.com/dropseed/plain/releases/plain-email@0.11.0) (2025-09-19)
+
+### What's changed
+
+- Updated Python minimum requirement to 3.13 ([d86e307](https://github.com/dropseed/plain/commit/d86e307))
+- Improved README with installation instructions and table of contents ([4ebecd1](https://github.com/dropseed/plain/commit/4ebecd1))
+- Updated package description to "Everything you need to send email in Plain" ([4ebecd1](https://github.com/dropseed/plain/commit/4ebecd1))
+
+### Upgrade instructions
+
+- Update your Python version to 3.13 or higher
+
+## [0.10.2](https://github.com/dropseed/plain/releases/plain-email@0.10.2) (2025-06-23)
+
+### What's changed
+
+- No user-facing changes. Internal documentation and tooling updates only ([82710c3](https://github.com/dropseed/plain/commit/82710c3), [9a1963d](https://github.com/dropseed/plain/commit/9a1963d), [e1f5dd3](https://github.com/dropseed/plain/commit/e1f5dd3)).
+
+### Upgrade instructions
+
+- No changes required

plain/email/README.md

@@ -0,0 +1,23 @@
+# plain.email
+
+**Everything you need to send email in Plain.**
+
+- [Installation](#installation)
+
+## Installation
+
+Install the `plain.email` package from [PyPI](https://pypi.org/project/plain.email/):
+
+```bash
+uv add plain.email
+```
+
+Add `plain.email` to your `INSTALLED_PACKAGES`:
+
+```python
+# settings.py
+INSTALLED_PACKAGES = [
+    # ...
+    "plain.email",
+]
+```

plain/email/__init__.py

@@ -0,0 +1,124 @@
+"""
+Tools for sending email.
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Any
+
+from plain.runtime import settings
+from plain.utils.module_loading import import_string
+
+if TYPE_CHECKING:
+    from .backends.base import BaseEmailBackend
+
+from .message import (
+    DEFAULT_ATTACHMENT_MIME_TYPE,
+    BadHeaderError,
+    EmailMessage,
+    EmailMultiAlternatives,
+    SafeMIMEMultipart,
+    SafeMIMEText,
+    TemplateEmail,
+    forbid_multi_line_headers,
+    make_msgid,
+)
+from .utils import DNS_NAME, CachedDnsName
+
+__all__ = [
+    "CachedDnsName",
+    "DNS_NAME",
+    "EmailMessage",
+    "EmailMultiAlternatives",
+    "TemplateEmail",
+    "SafeMIMEText",
+    "SafeMIMEMultipart",
+    "DEFAULT_ATTACHMENT_MIME_TYPE",
+    "make_msgid",
+    "BadHeaderError",
+    "forbid_multi_line_headers",
+    "get_connection",
+    "send_mail",
+    "send_mass_mail",
+]
+
+
+def get_connection(
+    backend: str | None = None, fail_silently: bool = False, **kwds: Any
+) -> BaseEmailBackend:
+    """Load an email backend and return an instance of it.
+
+    If backend is None (default), use settings.EMAIL_BACKEND.
+
+    Both fail_silently and other keyword arguments are used in the
+    constructor of the backend.
+    """
+    klass = import_string(backend or settings.EMAIL_BACKEND)
+    return klass(fail_silently=fail_silently, **kwds)
+
+
+def send_mail(
+    subject: str,
+    message: str,
+    from_email: str | None,
+    recipient_list: list[str],
+    fail_silently: bool = False,
+    auth_user: str | None = None,
+    auth_password: str | None = None,
+    connection: BaseEmailBackend | None = None,
+    html_message: str | None = None,
+) -> int:
+    """
+    Easy wrapper for sending a single message to a recipient list. All members
+    of the recipient list will see the other recipients in the 'To' field.
+
+    If from_email is None, use the EMAIL_DEFAULT_FROM setting.
+    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(
+        username=auth_user,
+        password=auth_password,
+        fail_silently=fail_silently,
+    )
+    mail = EmailMultiAlternatives(
+        subject, message, from_email, recipient_list, connection=connection
+    )
+    if html_message:
+        mail.attach_alternative(html_message, "text/html")
+
+    return mail.send()
+
+
+def send_mass_mail(
+    datatuple: tuple[tuple[str, str, str, list[str]], ...],
+    fail_silently: bool = False,
+    auth_user: str | None = None,
+    auth_password: str | None = None,
+    connection: BaseEmailBackend | None = None,
+) -> int:
+    """
+    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 EMAIL_DEFAULT_FROM 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(
+        username=auth_user,
+        password=auth_password,
+        fail_silently=fail_silently,
+    )
+    messages = [
+        EmailMessage(subject, message, sender, recipient, connection=connection)
+        for subject, message, sender, recipient in datatuple
+    ]
+    return connection.send_messages(messages)

plain/email/backends/base.py

@@ -0,0 +1,76 @@
+"""Base email backend class."""
+
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+from typing import TYPE_CHECKING, Any
+
+if TYPE_CHECKING:
+    from types import TracebackType
+
+    from ..message import EmailMessage
+
+
+class BaseEmailBackend(ABC):
+    """
+    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, **kwargs: Any) -> None:
+        self.fail_silently = fail_silently
+
+    def open(self) -> bool | None:
+        """
+        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
+
+    def close(self) -> None:
+        """Close a network connection."""
+        pass
+
+    def __enter__(self) -> BaseEmailBackend:
+        try:
+            self.open()
+        except Exception:
+            self.close()
+            raise
+        return self
+
+    def __exit__(
+        self,
+        exc_type: type[BaseException] | None,
+        exc_value: BaseException | None,
+        traceback: TracebackType | None,
+    ) -> None:
+        self.close()
+
+    @abstractmethod
+    def send_messages(self, email_messages: list[EmailMessage]) -> int:
+        """
+        Send one or more EmailMessage objects and return the number of email
+        messages sent.
+        """
+        ...

plain/email/backends/console.py

@@ -0,0 +1,55 @@
+"""
+Email backend that writes messages to console instead of sending them.
+"""
+
+from __future__ import annotations
+
+import sys
+import threading
+from typing import TYPE_CHECKING, Any
+
+from .base import BaseEmailBackend
+
+if TYPE_CHECKING:
+    from ..message import EmailMessage
+
+
+class EmailBackend(BaseEmailBackend):
+    def __init__(self, *args: Any, **kwargs: Any) -> None:
+        self.stream = kwargs.pop("stream", sys.stdout)
+        self._lock = threading.RLock()
+        super().__init__(*args, **kwargs)
+
+    def write_message(self, message: EmailMessage) -> None:
+        msg = message.message()
+        msg_data = msg.as_bytes()
+        msg_charset = msg.get_charset()
+        if msg_charset is None:
+            charset = "utf-8"
+        elif isinstance(msg_charset, str):
+            charset = msg_charset
+        else:
+            charset = msg_charset.get_output_charset() or "utf-8"
+        msg_data = msg_data.decode(charset)
+        self.stream.write(f"{msg_data}\n")
+        self.stream.write("-" * 79)
+        self.stream.write("\n")
+
+    def send_messages(self, email_messages: list[EmailMessage]) -> int:
+        """Write all messages to the stream in a thread-safe way."""
+        if not email_messages:
+            return 0
+        msg_count = 0
+        with self._lock:
+            try:
+                stream_created = self.open()
+                for message in email_messages:
+                    self.write_message(message)
+                    self.stream.flush()  # flush after each message
+                    msg_count += 1
+                if stream_created:
+                    self.close()
+            except Exception:
+                if not self.fail_silently:
+                    raise
+        return msg_count

plain/email/backends/filebased.py

@@ -0,0 +1,75 @@
+"""Email backend that writes messages to a file."""
+
+from __future__ import annotations
+
+import datetime
+import os
+from typing import TYPE_CHECKING, Any
+
+from plain.exceptions import ImproperlyConfigured
+from plain.runtime import settings
+
+from .console import EmailBackend as ConsoleEmailBackend
+
+if TYPE_CHECKING:
+    from ..message import EmailMessage
+
+
+class EmailBackend(ConsoleEmailBackend):
+    file_path: str  # Set during __init__, validated to be non-None
+
+    def __init__(self, *args: Any, file_path: str | None = None, **kwargs: Any) -> None:
+        self._fname: str | None = None
+        _file_path: str | None = file_path or getattr(settings, "EMAIL_FILE_PATH", None)
+        if not _file_path:
+            raise ImproperlyConfigured(
+                "EMAIL_FILE_PATH must be set for the filebased email backend"
+            )
+        self.file_path = os.path.abspath(_file_path)
+        try:
+            os.makedirs(self.file_path, exist_ok=True)
+        except FileExistsError:
+            raise ImproperlyConfigured(
+                f"Path for saving email messages exists, but is not a directory: {self.file_path}"
+            )
+        except OSError as err:
+            raise ImproperlyConfigured(
+                f"Could not create directory for saving email messages: {self.file_path} ({err})"
+            )
+        # Make sure that self.file_path is writable.
+        if not os.access(self.file_path, os.W_OK):
+            raise ImproperlyConfigured(
+                f"Could not write to directory: {self.file_path}"
+            )
+        # Finally, call super().
+        # Since we're using the console-based backend as a base,
+        # force the stream to be None, so we don't default to stdout
+        kwargs["stream"] = None
+        super().__init__(*args, **kwargs)
+
+    def write_message(self, message: EmailMessage) -> None:
+        assert self.stream is not None, "stream should be opened before writing"
+        self.stream.write(message.message().as_bytes() + b"\n")
+        self.stream.write(b"-" * 79)
+        self.stream.write(b"\n")
+
+    def _get_filename(self) -> str:
+        """Return a unique file name."""
+        if self._fname is None:
+            timestamp = datetime.datetime.now().strftime("%Y%m%d-%H%M%S")
+            fname = f"{timestamp}-{abs(id(self))}.log"
+            self._fname = os.path.join(self.file_path, fname)
+        return self._fname
+
+    def open(self) -> bool:
+        if self.stream is None:
+            self.stream = open(self._get_filename(), "ab")
+            return True
+        return False
+
+    def close(self) -> None:
+        try:
+            if self.stream is not None:
+                self.stream.close()
+        finally:
+            self.stream = None

plain/email/backends/smtp.py

@@ -0,0 +1,170 @@
+"""SMTP email backend class."""
+
+from __future__ import annotations
+
+import smtplib
+import ssl
+import threading
+from functools import cached_property
+from typing import TYPE_CHECKING, Any
+
+from plain.runtime import settings
+
+from ..backends.base import BaseEmailBackend
+from ..message import sanitize_address
+from ..utils import DNS_NAME
+
+if TYPE_CHECKING:
+    from ..message import EmailMessage
+
+
+class EmailBackend(BaseEmailBackend):
+    """
+    A wrapper that manages the SMTP network connection.
+    """
+
+    def __init__(
+        self,
+        host: str | None = None,
+        port: int | None = None,
+        username: str | None = None,
+        password: str | None = None,
+        use_tls: bool | None = None,
+        fail_silently: bool = False,
+        use_ssl: bool | None = None,
+        timeout: int | None = None,
+        ssl_keyfile: str | None = None,
+        ssl_certfile: str | None = None,
+        **kwargs: Any,
+    ) -> None:
+        super().__init__(fail_silently=fail_silently)
+        self.host = host or settings.EMAIL_HOST
+        self.port = port or settings.EMAIL_PORT
+        self.username = settings.EMAIL_HOST_USER if username is None else username
+        self.password = settings.EMAIL_HOST_PASSWORD if password is None else password
+        self.use_tls = settings.EMAIL_USE_TLS if use_tls is None else use_tls
+        self.use_ssl = settings.EMAIL_USE_SSL if use_ssl is None else use_ssl
+        self.timeout = settings.EMAIL_TIMEOUT if timeout is None else timeout
+        self.ssl_keyfile = (
+            settings.EMAIL_SSL_KEYFILE if ssl_keyfile is None else ssl_keyfile
+        )
+        self.ssl_certfile = (
+            settings.EMAIL_SSL_CERTFILE if ssl_certfile is None else ssl_certfile
+        )
+        if self.use_ssl and self.use_tls:
+            raise ValueError(
+                "EMAIL_USE_TLS/EMAIL_USE_SSL are mutually exclusive, so only set "
+                "one of those settings to True."
+            )
+        self.connection = None
+        self._lock = threading.RLock()
+
+    @property
+    def connection_class(self) -> type[smtplib.SMTP]:
+        return smtplib.SMTP_SSL if self.use_ssl else smtplib.SMTP
+
+    @cached_property
+    def ssl_context(self) -> ssl.SSLContext:
+        if self.ssl_certfile or self.ssl_keyfile:
+            ssl_context = ssl.SSLContext(protocol=ssl.PROTOCOL_TLS_CLIENT)
+            ssl_context.load_cert_chain(self.ssl_certfile, self.ssl_keyfile)
+            return ssl_context
+        else:
+            return ssl.create_default_context()
+
+    def open(self) -> bool | None:
+        """
+        Ensure an open connection to the email server. Return whether or not a
+        new connection was required (True or False) or None if an exception
+        passed silently.
+        """
+        if self.connection:
+            # Nothing to do if the connection is already open.
+            return False
+
+        # If local_hostname is not specified, socket.getfqdn() gets used.
+        # For performance, we use the cached FQDN for local_hostname.
+        connection_params: dict[str, Any] = {"local_hostname": DNS_NAME.get_fqdn()}
+        if self.timeout is not None:
+            connection_params["timeout"] = self.timeout
+        if self.use_ssl:
+            connection_params["context"] = self.ssl_context
+        try:
+            self.connection = self.connection_class(
+                self.host, self.port, **connection_params
+            )
+
+            # TLS/SSL are mutually exclusive, so only attempt TLS over
+            # non-secure connections.
+            if not self.use_ssl and self.use_tls:
+                self.connection.starttls(context=self.ssl_context)
+            if self.username and self.password:
+                self.connection.login(self.username, self.password)
+            return True
+        except OSError:
+            if not self.fail_silently:
+                raise
+
+    def close(self) -> None:
+        """Close the connection to the email server."""
+        if self.connection is None:
+            return None
+        try:
+            try:
+                self.connection.quit()
+            except (ssl.SSLError, smtplib.SMTPServerDisconnected):
+                # This happens when calling quit() on a TLS connection
+                # sometimes, or when the connection was already disconnected
+                # by the server.
+                self.connection.close()
+            except smtplib.SMTPException:
+                if self.fail_silently:
+                    return None
+                raise
+        finally:
+            self.connection = None
+
+    def send_messages(self, email_messages: list[EmailMessage]) -> int:
+        """
+        Send one or more EmailMessage objects and return the number of email
+        messages sent.
+        """
+        if not email_messages:
+            return 0
+        with self._lock:
+            new_conn_created = self.open()
+            if not self.connection or new_conn_created is None:
+                # We failed silently on open().
+                # Trying to send would be pointless.
+                return 0
+            num_sent = 0
+            try:
+                for message in email_messages:
+                    sent = self._send(message)
+                    if sent:
+                        num_sent += 1
+            finally:
+                if new_conn_created:
+                    self.close()
+        return num_sent
+
+    def _send(self, email_message: EmailMessage) -> bool:
+        """A helper method that does the actual sending."""
+        if not email_message.recipients():
+            return False
+        encoding = email_message.encoding or settings.DEFAULT_CHARSET
+        from_email = sanitize_address(email_message.from_email, encoding)
+        recipients = [
+            sanitize_address(addr, encoding) for addr in email_message.recipients()
+        ]
+        message = email_message.message()
+        assert self.connection is not None, "connection should be open before sending"
+        try:
+            self.connection.sendmail(
+                from_email, recipients, message.as_bytes(linesep="\r\n")
+            )
+        except smtplib.SMTPException:
+            if not self.fail_silently:
+                raise
+            return False
+        return True

plain/email/default_settings.py

@@ -0,0 +1,27 @@
+# The email backend to use. For possible shortcuts see plain.email.
+# The default is to use the SMTP backend.
+# Third-party backends can be specified by providing a Python path
+# to a module that defines an EmailBackend class.
+EMAIL_BACKEND: str
+
+EMAIL_DEFAULT_FROM: str
+
+EMAIL_DEFAULT_REPLY_TO: list[str] | None = None
+
+# Host for sending email.
+EMAIL_HOST: str = "localhost"
+
+# Port for sending email.
+EMAIL_PORT: int = 587
+
+# Whether to send SMTP 'Date' header in the local time zone or in UTC.
+EMAIL_USE_LOCALTIME: bool = False
+
+# Optional SMTP authentication information for EMAIL_HOST.
+EMAIL_HOST_USER: str = ""
+EMAIL_HOST_PASSWORD: str = ""
+EMAIL_USE_TLS: bool = True
+EMAIL_USE_SSL: bool = False
+EMAIL_SSL_CERTFILE: str | None = None
+EMAIL_SSL_KEYFILE: str | None = None
+EMAIL_TIMEOUT: int | None = None