plain.email 0.11.0__tar.gz → 0.12.0__tar.gz

{plain_email-0.11.0 → plain_email-0.12.0}/.gitignore

@@ -1,5 +1,5 @@
 .venv
-.env
+/.env
 *.egg-info
 *.py[co]
 __pycache__
@@ -8,10 +8,12 @@ __pycache__
 # Test apps
 plain*/tests/.plain
 
-# Ottobot
-.aider*
+# Agent scratch files
+/scratch
 
 # Plain temp dirs
 .plain
 
 .vscode
+/.claude
+/.benchmarks

{plain_email-0.11.0 → plain_email-0.12.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: plain.email
-Version: 0.11.0
+Version: 0.12.0
 Summary: Everything you need to send email in Plain.
 Author-email: Dave Gaeddert <dave.gaeddert@dropseed.dev>
 License-Expression: BSD-3-Clause

plain_email-0.12.0/plain/email/CHANGELOG.md

@@ -0,0 +1,44 @@
+# plain-email changelog
+
+## [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-0.11.0 → plain_email-0.12.0}/plain/email/__init__.py

@@ -2,9 +2,16 @@
 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,
@@ -36,7 +43,9 @@ __all__ = [
 ]
 
 
-def get_connection(backend=None, fail_silently=False, **kwds):
+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.
@@ -49,16 +58,16 @@ def get_connection(backend=None, fail_silently=False, **kwds):
 
 
 def send_mail(
-    subject,
-    message,
-    from_email,
-    recipient_list,
-    fail_silently=False,
-    auth_user=None,
-    auth_password=None,
-    connection=None,
-    html_message=None,
-):
+    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.
@@ -85,8 +94,12 @@ def send_mail(
 
 
 def send_mass_mail(
-    datatuple, fail_silently=False, auth_user=None, auth_password=None, connection=None
-):
+    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.

{plain_email-0.11.0 → plain_email-0.12.0}/plain/email/backends/base.py

@@ -1,7 +1,17 @@
 """Base email backend class."""
 
+from __future__ import annotations
 
-class BaseEmailBackend:
+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.
 
@@ -15,10 +25,10 @@ class BaseEmailBackend:
            pass
     """
 
-    def __init__(self, fail_silently=False, **kwargs):
+    def __init__(self, fail_silently: bool = False, **kwargs: Any) -> None:
         self.fail_silently = fail_silently
 
-    def open(self):
+    def open(self) -> None:
         """
         Open a network connection.
 
@@ -37,11 +47,11 @@ class BaseEmailBackend:
         """
         pass
 
-    def close(self):
+    def close(self) -> None:
         """Close a network connection."""
         pass
 
-    def __enter__(self):
+    def __enter__(self) -> BaseEmailBackend:
         try:
             self.open()
         except Exception:
@@ -49,14 +59,18 @@ class BaseEmailBackend:
             raise
         return self
 
-    def __exit__(self, exc_type, exc_value, traceback):
+    def __exit__(
+        self,
+        exc_type: type[BaseException] | None,
+        exc_value: BaseException | None,
+        traceback: TracebackType | None,
+    ) -> None:
         self.close()
 
-    def send_messages(self, email_messages):
+    @abstractmethod
+    def send_messages(self, email_messages: list[EmailMessage]) -> int:
         """
         Send one or more EmailMessage objects and return the number of email
         messages sent.
         """
-        raise NotImplementedError(
-            "subclasses of BaseEmailBackend must override send_messages() method"
-        )
+        ...

{plain_email-0.11.0 → plain_email-0.12.0}/plain/email/backends/console.py

@@ -2,19 +2,25 @@
 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, **kwargs):
+    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):
+    def write_message(self, message: EmailMessage) -> None:
         msg = message.message()
         msg_data = msg.as_bytes()
         charset = (
@@ -25,10 +31,10 @@ class EmailBackend(BaseEmailBackend):
         self.stream.write("-" * 79)
         self.stream.write("\n")
 
-    def send_messages(self, email_messages):
+    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
+            return 0
         msg_count = 0
         with self._lock:
             try:

{plain_email-0.11.0 → plain_email-0.12.0}/plain/email/backends/filebased.py

@@ -1,21 +1,31 @@
 """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):
-    def __init__(self, *args, file_path=None, **kwargs):
+    def __init__(self, *args: Any, file_path: str | None = None, **kwargs: Any) -> None:
         self._fname = None
         if file_path is not None:
             self.file_path = file_path
         else:
             self.file_path = getattr(settings, "EMAIL_FILE_PATH", None)
+        if not self.file_path:
+            raise ImproperlyConfigured(
+                "EMAIL_FILE_PATH must be set for the filebased email backend"
+            )
         self.file_path = os.path.abspath(self.file_path)
         try:
             os.makedirs(self.file_path, exist_ok=True)
@@ -38,12 +48,13 @@ class EmailBackend(ConsoleEmailBackend):
         kwargs["stream"] = None
         super().__init__(*args, **kwargs)
 
-    def write_message(self, message):
+    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):
+    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")
@@ -51,13 +62,13 @@ class EmailBackend(ConsoleEmailBackend):
             self._fname = os.path.join(self.file_path, fname)
         return self._fname
 
-    def open(self):
+    def open(self) -> bool:
         if self.stream is None:
             self.stream = open(self._get_filename(), "ab")
             return True
         return False
 
-    def close(self):
+    def close(self) -> None:
         try:
             if self.stream is not None:
                 self.stream.close()

{plain_email-0.11.0 → plain_email-0.12.0}/plain/email/backends/smtp.py

@@ -1,9 +1,12 @@
 """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
 
@@ -11,6 +14,9 @@ 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):
     """
@@ -19,18 +25,18 @@ class EmailBackend(BaseEmailBackend):
 
     def __init__(
         self,
-        host=None,
-        port=None,
-        username=None,
-        password=None,
-        use_tls=None,
-        fail_silently=False,
-        use_ssl=None,
-        timeout=None,
-        ssl_keyfile=None,
-        ssl_certfile=None,
-        **kwargs,
-    ):
+        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
@@ -54,11 +60,11 @@ class EmailBackend(BaseEmailBackend):
         self._lock = threading.RLock()
 
     @property
-    def connection_class(self):
+    def connection_class(self) -> type[smtplib.SMTP]:
         return smtplib.SMTP_SSL if self.use_ssl else smtplib.SMTP
 
     @cached_property
-    def ssl_context(self):
+    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)
@@ -66,7 +72,7 @@ class EmailBackend(BaseEmailBackend):
         else:
             return ssl.create_default_context()
 
-    def open(self):
+    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
@@ -78,7 +84,7 @@ class EmailBackend(BaseEmailBackend):
 
         # If local_hostname is not specified, socket.getfqdn() gets used.
         # For performance, we use the cached FQDN for local_hostname.
-        connection_params = {"local_hostname": DNS_NAME.get_fqdn()}
+        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:
@@ -99,10 +105,10 @@ class EmailBackend(BaseEmailBackend):
             if not self.fail_silently:
                 raise
 
-    def close(self):
+    def close(self) -> None:
         """Close the connection to the email server."""
         if self.connection is None:
-            return
+            return None
         try:
             try:
                 self.connection.quit()
@@ -113,12 +119,12 @@ class EmailBackend(BaseEmailBackend):
                 self.connection.close()
             except smtplib.SMTPException:
                 if self.fail_silently:
-                    return
+                    return None
                 raise
         finally:
             self.connection = None
 
-    def send_messages(self, email_messages):
+    def send_messages(self, email_messages: list[EmailMessage]) -> int:
         """
         Send one or more EmailMessage objects and return the number of email
         messages sent.
@@ -142,7 +148,7 @@ class EmailBackend(BaseEmailBackend):
                     self.close()
         return num_sent
 
-    def _send(self, email_message):
+    def _send(self, email_message: EmailMessage) -> bool:
         """A helper method that does the actual sending."""
         if not email_message.recipients():
             return False
@@ -152,6 +158,7 @@ class EmailBackend(BaseEmailBackend):
             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")

{plain_email-0.11.0 → plain_email-0.12.0}/plain/email/default_settings.py

@@ -6,7 +6,7 @@ EMAIL_BACKEND: str
 
 EMAIL_DEFAULT_FROM: str
 
-EMAIL_DEFAULT_REPLY_TO: list[str] = None
+EMAIL_DEFAULT_REPLY_TO: list[str] | None = None
 
 # Host for sending email.
 EMAIL_HOST: str = "localhost"
@@ -22,6 +22,6 @@ EMAIL_HOST_USER: str = ""
 EMAIL_HOST_PASSWORD: str = ""
 EMAIL_USE_TLS: bool = True
 EMAIL_USE_SSL: bool = False
-EMAIL_SSL_CERTFILE: str = None
-EMAIL_SSL_KEYFILE: str = None
-EMAIL_TIMEOUT: int = None
+EMAIL_SSL_CERTFILE: str | None = None
+EMAIL_SSL_KEYFILE: str | None = None
+EMAIL_TIMEOUT: int | None = None

{plain_email-0.11.0 → plain_email-0.12.0}/plain/email/message.py

@@ -1,10 +1,15 @@
+from __future__ import annotations
+
 import mimetypes
 from email import charset as Charset
 from email import encoders as Encoders
 from email import generator, message_from_string
 from email.errors import HeaderParseError
 from email.header import Header
-from email.headerregistry import Address, parser
+from email.headerregistry import Address
+from email.headerregistry import (
+    parser as headerregistry_parser,  # type: ignore[attr-defined]
+)
 from email.message import Message
 from email.mime.base import MIMEBase
 from email.mime.message import MIMEMessage
@@ -13,6 +18,7 @@ from email.mime.text import MIMEText
 from email.utils import formataddr, formatdate, getaddresses, make_msgid
 from io import BytesIO, StringIO
 from pathlib import Path
+from typing import TYPE_CHECKING, Any
 
 from plain.runtime import settings
 from plain.templates import Template, TemplateFileMissing
@@ -21,10 +27,15 @@ from plain.utils.html import strip_tags
 
 from .utils import DNS_NAME
 
+if TYPE_CHECKING:
+    from os import PathLike
+
+    from .backends.base import BaseEmailBackend
+
 # Don't BASE64-encode UTF-8 messages so that we avoid unwanted attention from
 # some spam filters.
 utf8_charset = Charset.Charset("utf-8")
-utf8_charset.body_encoding = None  # Python defaults to BASE64
+utf8_charset.body_encoding = None  # type: ignore[assignment]  # Python defaults to BASE64
 utf8_charset_qp = Charset.Charset("utf-8")
 utf8_charset_qp.body_encoding = Charset.QP
 
@@ -55,7 +66,9 @@ ADDRESS_HEADERS = {
 }
 
 
-def forbid_multi_line_headers(name, val, encoding):
+def forbid_multi_line_headers(
+    name: str, val: str, encoding: str | None
+) -> tuple[str, str]:
     """Forbid multi-line headers to prevent header injection."""
     encoding = encoding or settings.DEFAULT_CHARSET
     val = str(val)  # val may be lazy
@@ -78,7 +91,7 @@ def forbid_multi_line_headers(name, val, encoding):
     return name, val
 
 
-def sanitize_address(addr, encoding):
+def sanitize_address(addr: str | tuple[str, str], encoding: str) -> str:
     """
     Format a pair of (name, address) or an email address string.
     """
@@ -86,7 +99,7 @@ def sanitize_address(addr, encoding):
     if not isinstance(addr, tuple):
         addr = force_str(addr)
         try:
-            token, rest = parser.get_mailbox(addr)
+            token, rest = headerregistry_parser.get_mailbox(addr)
         except (HeaderParseError, ValueError, IndexError):
             raise ValueError(f'Invalid address "{addr}"')
         else:
@@ -123,7 +136,7 @@ def sanitize_address(addr, encoding):
 
 
 class MIMEMixin:
-    def as_string(self, unixfrom=False, linesep="\n"):
+    def as_string(self, unixfrom: bool = False, linesep: str = "\n") -> str:
         """Return the entire formatted message as a string.
         Optional `unixfrom' when True, means include the Unix From_ envelope
         header.
@@ -136,7 +149,7 @@ class MIMEMixin:
         g.flatten(self, unixfrom=unixfrom, linesep=linesep)
         return fp.getvalue()
 
-    def as_bytes(self, unixfrom=False, linesep="\n"):
+    def as_bytes(self, unixfrom: bool = False, linesep: str = "\n") -> bytes:
         """Return the entire formatted message as bytes.
         Optional `unixfrom' when True, means include the Unix From_ envelope
         header.
@@ -151,22 +164,26 @@ class MIMEMixin:
 
 
 class SafeMIMEMessage(MIMEMixin, MIMEMessage):
-    def __setitem__(self, name, val):
+    def __setitem__(self, name: str, val: str) -> None:
         # message/rfc822 attachments must be ASCII
         name, val = forbid_multi_line_headers(name, val, "ascii")
         MIMEMessage.__setitem__(self, name, val)
 
 
 class SafeMIMEText(MIMEMixin, MIMEText):
-    def __init__(self, _text, _subtype="plain", _charset=None):
+    def __init__(
+        self, _text: str, _subtype: str = "plain", _charset: str | None = None
+    ) -> None:
         self.encoding = _charset
         MIMEText.__init__(self, _text, _subtype=_subtype, _charset=_charset)
 
-    def __setitem__(self, name, val):
+    def __setitem__(self, name: str, val: str) -> None:
         name, val = forbid_multi_line_headers(name, val, self.encoding)
         MIMEText.__setitem__(self, name, val)
 
-    def set_payload(self, payload, charset=None):
+    def set_payload(
+        self, payload: str, charset: str | Charset.Charset | None = None
+    ) -> None:
         if charset == "utf-8" and not isinstance(charset, Charset.Charset):
             has_long_lines = any(
                 len(line.encode()) > RFC5322_EMAIL_LINE_LENGTH_LIMIT
@@ -180,12 +197,17 @@ class SafeMIMEText(MIMEMixin, MIMEText):
 
 class SafeMIMEMultipart(MIMEMixin, MIMEMultipart):
     def __init__(
-        self, _subtype="mixed", boundary=None, _subparts=None, encoding=None, **_params
-    ):
+        self,
+        _subtype: str = "mixed",
+        boundary: str | None = None,
+        _subparts: list[Message] | None = None,
+        encoding: str | None = None,
+        **_params: Any,
+    ) -> None:
         self.encoding = encoding
         MIMEMultipart.__init__(self, _subtype, boundary, _subparts, **_params)
 
-    def __setitem__(self, name, val):
+    def __setitem__(self, name: str, val: str) -> None:
         name, val = forbid_multi_line_headers(name, val, self.encoding)
         MIMEMultipart.__setitem__(self, name, val)
 
@@ -195,21 +217,21 @@ class EmailMessage:
 
     content_subtype = "plain"
     mixed_subtype = "mixed"
-    encoding = None  # None => use settings default
+    encoding: str | None = None  # None => use settings default
 
     def __init__(
         self,
-        subject="",
-        body="",
-        from_email=None,
-        to=None,
-        bcc=None,
-        connection=None,
-        attachments=None,
-        headers=None,
-        cc=None,
-        reply_to=None,
-    ):
+        subject: str = "",
+        body: str = "",
+        from_email: str | None = None,
+        to: list[str] | tuple[str, ...] | None = None,
+        bcc: list[str] | tuple[str, ...] | None = None,
+        connection: BaseEmailBackend | None = None,
+        attachments: list[MIMEBase | tuple[str, str, str]] | None = None,
+        headers: dict[str, str] | None = None,
+        cc: list[str] | tuple[str, ...] | None = None,
+        reply_to: list[str] | tuple[str, ...] | None = None,
+    ) -> None:
         """
         Initialize a single email message (which can be sent to multiple
         recipients).
@@ -251,14 +273,14 @@ class EmailMessage:
         self.extra_headers = headers or {}
         self.connection = connection
 
-    def get_connection(self, fail_silently=False):
+    def get_connection(self, fail_silently: bool = False) -> BaseEmailBackend:
         from . import get_connection
 
         if not self.connection:
             self.connection = get_connection(fail_silently=fail_silently)
         return self.connection
 
-    def message(self):
+    def message(self) -> SafeMIMEText | SafeMIMEMultipart:
         encoding = self.encoding or settings.DEFAULT_CHARSET
         msg = SafeMIMEText(self.body, self.content_subtype, encoding)
         msg = self._create_message(msg)
@@ -279,20 +301,20 @@ class EmailMessage:
             msg["Date"] = formatdate(localtime=settings.EMAIL_USE_LOCALTIME)
         if "message-id" not in header_names:
             # Use cached DNS_NAME for performance
-            msg["Message-ID"] = make_msgid(domain=DNS_NAME)
+            msg["Message-ID"] = make_msgid(domain=str(DNS_NAME))
         for name, value in self.extra_headers.items():
             if name.lower() != "from":  # From is already handled
                 msg[name] = value
         return msg
 
-    def recipients(self):
+    def recipients(self) -> list[str]:
         """
         Return a list of all recipients of the email (includes direct
         addressees as well as Cc and Bcc entries).
         """
         return [email for email in (self.to + self.cc + self.bcc) if email]
 
-    def send(self, fail_silently=False):
+    def send(self, fail_silently: bool = False) -> int:
         """Send the email message."""
         if not self.recipients():
             # Don't bother creating the network connection if there's nobody to
@@ -300,7 +322,12 @@ class EmailMessage:
             return 0
         return self.get_connection(fail_silently).send_messages([self])
 
-    def attach(self, filename=None, content=None, mimetype=None):
+    def attach(
+        self,
+        filename: MIMEBase | str | None = None,
+        content: str | bytes | None = None,
+        mimetype: str | None = None,
+    ) -> None:
         """
         Attach a file with the given filename and content. The filename can
         be omitted and the mimetype is guessed, if not provided.
@@ -340,7 +367,9 @@ class EmailMessage:
 
             self.attachments.append((filename, content, mimetype))
 
-    def attach_file(self, path, mimetype=None):
+    def attach_file(
+        self, path: str | PathLike[str], mimetype: str | None = None
+    ) -> None:
         """
         Attach a file from the filesystem.
 
@@ -356,10 +385,12 @@ class EmailMessage:
             content = file.read()
             self.attach(path.name, content, mimetype)
 
-    def _create_message(self, msg):
+    def _create_message(self, msg: SafeMIMEText) -> SafeMIMEText | SafeMIMEMultipart:
         return self._create_attachments(msg)
 
-    def _create_attachments(self, msg):
+    def _create_attachments(
+        self, msg: SafeMIMEText | SafeMIMEMultipart
+    ) -> SafeMIMEText | SafeMIMEMultipart:
         if self.attachments:
             encoding = self.encoding or settings.DEFAULT_CHARSET
             body_msg = msg
@@ -373,7 +404,9 @@ class EmailMessage:
                     msg.attach(self._create_attachment(*attachment))
         return msg
 
-    def _create_mime_attachment(self, content, mimetype):
+    def _create_mime_attachment(
+        self, content: str | bytes | EmailMessage | Message, mimetype: str
+    ) -> SafeMIMEText | SafeMIMEMessage | MIMEBase:
         """
         Convert the content, mimetype pair into a MIME attachment object.
 
@@ -383,6 +416,8 @@ class EmailMessage:
         basetype, subtype = mimetype.split("/", 1)
         if basetype == "text":
             encoding = self.encoding or settings.DEFAULT_CHARSET
+            if not isinstance(content, str):
+                content = force_str(content)
             attachment = SafeMIMEText(content, subtype, encoding)
         elif basetype == "message" and subtype == "rfc822":
             # Bug #18967: Per RFC 2046 Section 5.2.1, message/rfc822
@@ -403,7 +438,9 @@ class EmailMessage:
             Encoders.encode_base64(attachment)
         return attachment
 
-    def _create_attachment(self, filename, content, mimetype=None):
+    def _create_attachment(
+        self, filename: str | None, content: str | bytes, mimetype: str
+    ) -> SafeMIMEText | SafeMIMEMessage | MIMEBase:
         """
         Convert the filename, content, mimetype triple into a MIME attachment
         object.
@@ -412,14 +449,20 @@ class EmailMessage:
         if filename:
             try:
                 filename.encode("ascii")
+                encoded_filename: str | tuple[str, str, str] = filename
             except UnicodeEncodeError:
-                filename = ("utf-8", "", filename)
+                encoded_filename = ("utf-8", "", filename)
             attachment.add_header(
-                "Content-Disposition", "attachment", filename=filename
+                "Content-Disposition", "attachment", filename=encoded_filename
             )
         return attachment
 
-    def _set_list_header_if_not_empty(self, msg, header, values):
+    def _set_list_header_if_not_empty(
+        self,
+        msg: SafeMIMEText | SafeMIMEMultipart,
+        header: str,
+        values: list[str],
+    ) -> None:
         """
         Set msg's header, either from self.extra_headers, if present, or from
         the values argument.
@@ -443,18 +486,18 @@ class EmailMultiAlternatives(EmailMessage):
 
     def __init__(
         self,
-        subject="",
-        body="",
-        from_email=None,
-        to=None,
-        bcc=None,
-        connection=None,
-        attachments=None,
-        headers=None,
-        alternatives=None,
-        cc=None,
-        reply_to=None,
-    ):
+        subject: str = "",
+        body: str = "",
+        from_email: str | None = None,
+        to: list[str] | tuple[str, ...] | None = None,
+        bcc: list[str] | tuple[str, ...] | None = None,
+        connection: BaseEmailBackend | None = None,
+        attachments: list[MIMEBase | tuple[str, str, str]] | None = None,
+        headers: dict[str, str] | None = None,
+        alternatives: list[tuple[str, str]] | None = None,
+        cc: list[str] | tuple[str, ...] | None = None,
+        reply_to: list[str] | tuple[str, ...] | None = None,
+    ) -> None:
         """
         Initialize a single email message (which can be sent to multiple
         recipients).
@@ -473,16 +516,18 @@ class EmailMultiAlternatives(EmailMessage):
         )
         self.alternatives = alternatives or []
 
-    def attach_alternative(self, content, mimetype):
+    def attach_alternative(self, content: str, mimetype: str) -> None:
         """Attach an alternative content representation."""
         if content is None or mimetype is None:
             raise ValueError("Both content and mimetype must be provided.")
         self.alternatives.append((content, mimetype))
 
-    def _create_message(self, msg):
+    def _create_message(self, msg: SafeMIMEText) -> SafeMIMEText | SafeMIMEMultipart:
         return self._create_attachments(self._create_alternatives(msg))
 
-    def _create_alternatives(self, msg):
+    def _create_alternatives(
+        self, msg: SafeMIMEText | SafeMIMEMultipart
+    ) -> SafeMIMEText | SafeMIMEMultipart:
         encoding = self.encoding or settings.DEFAULT_CHARSET
         if self.alternatives:
             body_msg = msg
@@ -500,19 +545,19 @@ class TemplateEmail(EmailMultiAlternatives):
     def __init__(
         self,
         *,
-        template,
-        context=None,
-        subject="",
-        from_email=None,
-        to=None,
-        bcc=None,
-        connection=None,
-        attachments=None,
-        headers=None,
-        alternatives=None,
-        cc=None,
-        reply_to=None,
-    ):
+        template: str,
+        context: dict[str, Any] | None = None,
+        subject: str = "",
+        from_email: str | None = None,
+        to: list[str] | tuple[str, ...] | None = None,
+        bcc: list[str] | tuple[str, ...] | None = None,
+        connection: BaseEmailBackend | None = None,
+        attachments: list[MIMEBase | tuple[str, str, str]] | None = None,
+        headers: dict[str, str] | None = None,
+        alternatives: list[tuple[str, str]] | None = None,
+        cc: list[str] | tuple[str, ...] | None = None,
+        reply_to: list[str] | tuple[str, ...] | None = None,
+    ) -> None:
         self.template = template
         self.context = context or {}
 
@@ -540,11 +585,11 @@ class TemplateEmail(EmailMultiAlternatives):
 
         self.attach_alternative(self.body_html, "text/html")
 
-    def get_template_context(self):
+    def get_template_context(self) -> dict[str, Any]:
         """Subclasses can override this method to add context data."""
         return self.context
 
-    def render_content(self, context):
+    def render_content(self, context: dict[str, Any]) -> tuple[str, str]:
         html_content = self.render_html(context)
 
         try:
@@ -554,24 +599,24 @@ class TemplateEmail(EmailMultiAlternatives):
 
         return html_content, plain_content
 
-    def render_plain(self, context):
+    def render_plain(self, context: dict[str, Any]) -> str:
         return Template(self.get_plain_template_name()).render(context)
 
-    def render_html(self, context):
+    def render_html(self, context: dict[str, Any]) -> str:
         return Template(self.get_html_template_name()).render(context)
 
-    def render_subject(self, context):
+    def render_subject(self, context: dict[str, Any]) -> str:
         try:
             subject = Template(self.get_subject_template_name()).render(context)
             return subject.strip()
         except TemplateFileMissing:
             return ""
 
-    def get_plain_template_name(self):
+    def get_plain_template_name(self) -> str:
         return f"email/{self.template}.txt"
 
-    def get_html_template_name(self):
+    def get_html_template_name(self) -> str:
         return f"email/{self.template}.html"
 
-    def get_subject_template_name(self):
+    def get_subject_template_name(self) -> str:
         return f"email/{self.template}.subject.txt"

{plain_email-0.11.0 → plain_email-0.12.0}/plain/email/utils.py

@@ -2,6 +2,8 @@
 Email message and email sending related helper functions.
 """
 
+from __future__ import annotations
+
 import socket
 
 from plain.utils.encoding import punycode
@@ -10,10 +12,10 @@ from plain.utils.encoding import punycode
 # Cache the hostname, but do it lazily: socket.getfqdn() can take a couple of
 # seconds, which slows down the restart of the server.
 class CachedDnsName:
-    def __str__(self):
+    def __str__(self) -> str:
         return self.get_fqdn()
 
-    def get_fqdn(self):
+    def get_fqdn(self) -> str:
         if not hasattr(self, "_fqdn"):
             self._fqdn = punycode(socket.getfqdn())
         return self._fqdn

{plain_email-0.11.0 → plain_email-0.12.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "plain.email"
-version = "0.11.0"
+version = "0.12.0"
 description = "Everything you need to send email in Plain."
 authors = [{name = "Dave Gaeddert", email = "dave.gaeddert@dropseed.dev"}]
 license = "BSD-3-Clause"

plain_email-0.11.0/plain/email/CHANGELOG.md

@@ -1,23 +0,0 @@
-# plain-email changelog
-
-## [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