mailsuite 2.3.2__tar.gz → 2.3.3__tar.gz

{mailsuite-2.3.2 → mailsuite-2.3.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: mailsuite
-Version: 2.3.2
+Version: 2.3.3
 Summary: A Python package for retrieving, parsing, and sending emails
 Project-URL: Homepage, https://github.com/seanthegeek/mailsuite/
 Project-URL: Documentation, https://seanthegeek.net/mailsuite/

{mailsuite-2.3.2 → mailsuite-2.3.3}/mailsuite/__init__.py

@@ -1,3 +1,3 @@
 """A Python package to simplify receiving, parsing, and sending email"""
 
-__version__ = "2.3.2"
+__version__ = "2.3.3"

{mailsuite-2.3.2 → mailsuite-2.3.3}/mailsuite/imap.py

@@ -190,6 +190,7 @@ class IMAPClient(imapclient.IMAPClient):
         oauth2_mechanism: str = "XOAUTH2",
         oauth2_vendor: str | None = None,
         config_reloading: Callable[[], bool] | None = None,
+        starttls: bool | None = None,
     ):
         """
         Connects to an IMAP server
@@ -219,6 +220,15 @@ class IMAPClient(imapclient.IMAPClient):
                 ``"OAUTHBEARER"`` (Gmail's standards-track replacement).
             oauth2_vendor: Optional vendor string required by Yahoo's
                 XOAUTH2 implementation.
+            starttls: Whether to upgrade a plain-text (``ssl=False``)
+                connection with STARTTLS. ``None`` (default) upgrades when
+                the server advertises STARTTLS; ``False`` never upgrades, so
+                the connection stays plain text even when STARTTLS is
+                advertised (credentials are then sent unencrypted);
+                ``True`` requires the upgrade and raises
+                :class:`imapclient.exceptions.IMAPClientError` if the server
+                does not advertise STARTTLS. Ignored when ``ssl=True``,
+                because the connection is already TLS.
 
         For Google Workspace and Microsoft 365 the higher-level
         :class:`mailsuite.mailbox.GmailConnection` and
@@ -262,6 +272,7 @@ class IMAPClient(imapclient.IMAPClient):
             "oauth2_token_provider": oauth2_token_provider,
             "oauth2_mechanism": oauth2_mechanism,
             "oauth2_vendor": oauth2_vendor,
+            "starttls": starttls,
         }
         self.max_retries = max_retries
         self.idle_callback = idle_callback
@@ -281,9 +292,21 @@ class IMAPClient(imapclient.IMAPClient):
             timeout=timeout,
         )
         try:
-            if not ssl and b"STARTTLS" in self.capabilities():
-                logger.info("IMAP server supports STARTTLS ... activating now")
-                self.starttls(ssl_context=ssl_context)
+            if not ssl:
+                starttls_advertised = b"STARTTLS" in self.capabilities()
+                if starttls is False:
+                    if starttls_advertised:
+                        logger.info(
+                            "IMAP server supports STARTTLS, but it is disabled"
+                            " ... staying in plain text"
+                        )
+                elif starttls_advertised:
+                    logger.info("IMAP server supports STARTTLS ... activating now")
+                    self.starttls(ssl_context=ssl_context)
+                elif starttls:
+                    raise imapclient.exceptions.IMAPClientError(
+                        "STARTTLS required but not supported by the server"
+                    )
             if using_oauth:
                 token = (
                     oauth2_token_provider()
@@ -376,6 +399,7 @@ class IMAPClient(imapclient.IMAPClient):
             oauth2_token_provider=self._init_args["oauth2_token_provider"],  # pyright: ignore[reportArgumentType]
             oauth2_mechanism=self._init_args["oauth2_mechanism"],  # pyright: ignore[reportArgumentType]
             oauth2_vendor=self._init_args["oauth2_vendor"],  # pyright: ignore[reportArgumentType]
+            starttls=self._init_args["starttls"],  # pyright: ignore[reportArgumentType]
         )
 
     def fetch_message(

{mailsuite-2.3.2 → mailsuite-2.3.3}/mailsuite/mailbox/imap.py

@@ -42,6 +42,7 @@ class IMAPConnection(MailboxConnection):
         oauth2_token_provider: Callable[[], str] | None = None,
         oauth2_mechanism: str = "XOAUTH2",
         oauth2_vendor: str | None = None,
+        starttls: bool | None = None,
     ):
         """
         Args:
@@ -60,6 +61,15 @@ class IMAPConnection(MailboxConnection):
                 ``oauth2_token`` for long-running watch loops.
             oauth2_mechanism: ``"XOAUTH2"`` (default) or ``"OAUTHBEARER"``
             oauth2_vendor: Optional vendor string for Yahoo's XOAUTH2
+            starttls: Whether to upgrade a plain-text (``ssl=False``)
+                connection with STARTTLS. ``None`` (default) upgrades when
+                the server advertises STARTTLS; ``False`` never upgrades, so
+                the connection stays plain text even when STARTTLS is
+                advertised (credentials are then sent unencrypted);
+                ``True`` requires the upgrade and raises
+                :class:`imapclient.exceptions.IMAPClientError` if the server
+                does not advertise STARTTLS. Ignored when ``ssl=True``,
+                because the connection is already TLS.
         """
         self._username = user
         self._password = password
@@ -68,6 +78,7 @@ class IMAPConnection(MailboxConnection):
         self._oauth2_token_provider = oauth2_token_provider
         self._oauth2_mechanism = oauth2_mechanism
         self._oauth2_vendor = oauth2_vendor
+        self._starttls = starttls
         self._client = IMAPClient(
             host,
             user,
@@ -81,6 +92,7 @@ class IMAPConnection(MailboxConnection):
             oauth2_token_provider=oauth2_token_provider,
             oauth2_mechanism=oauth2_mechanism,
             oauth2_vendor=oauth2_vendor,
+            starttls=starttls,
         )
 
     def create_folder(self, folder_name: str) -> None:
@@ -175,6 +187,7 @@ class IMAPConnection(MailboxConnection):
                     oauth2_mechanism=self._oauth2_mechanism,
                     oauth2_vendor=self._oauth2_vendor,
                     config_reloading=config_reloading,
+                    starttls=self._starttls,
                 )
             except (TimeoutError, IMAPClientError):
                 logger.warning("IMAP connection timeout. Reconnecting...")

{mailsuite-2.3.2 → mailsuite-2.3.3}/mailsuite/mailbox/maildir.py

@@ -117,28 +117,80 @@ class MaildirConnection(MailboxConnection):
         return list(self._active_folder.keys())
 
     def fetch_message(self, message_id: Any, **kwargs: Any) -> str:
-        msg = self._active_folder.get(message_id)
-        if msg is None:
+        """
+        Return the message's stored bytes decoded as UTF-8 (undecodable bytes
+        replaced), the same decoding
+        ``mailsuite.imap.IMAPClient.fetch_message(parse=False)``
+        applies to the IMAP backend's raw fetch. The file is not parsed or
+        re-serialized, so a message ``email`` can parse but not generate
+        (e.g. a ``\\x1c`` in a nested header, or deep ``multipart`` nesting)
+        is returned as-is. ``Maildir.get_bytes`` converts ``os.linesep`` to
+        ``\\n``, which is a no-op on POSIX. Returns ``""`` for an unknown
+        ``message_id``.
+
+        With ``mark_read=True`` the file is renamed into ``cur/`` with the
+        ``S`` (Seen) flag added to its info suffix, which is what the Maildir
+        spec defines a flag change to be; the content is untouched.
+        """
+        folder = self._active_folder
+        try:
+            msg_str = folder.get_bytes(message_id).decode("utf-8", "replace")
+        except KeyError:
             return ""
-        msg_str = msg.as_string()
         if kwargs.get("mark_read"):
-            # Maildir spec: a message is "read" once it has been moved out of
-            # new/ into cur/ with the "S" (Seen) flag set in its info field.
-            msg.set_subdir("cur")
-            msg.add_flag("S")
-            self._active_folder[message_id] = msg
-        return msg_str or ""
+            # mailbox.Maildir has no public way to get a message's on-disk
+            # name (or its own path) without parsing the message; _lookup(),
+            # _path, and _toc are what its own get_bytes/remove/__setitem__
+            # use. _lookup() only rescans a stale name when _refresh() sees
+            # the directory as changed, so record the new name in _toc the
+            # way CPython 3.13+'s Maildir.set_info() does after its rename.
+            subpath = folder._lookup(message_id)  # pyright: ignore[reportAttributeAccessIssue]
+            name = os.path.basename(subpath)
+            flags = mailbox.MaildirMessage()
+            if folder.colon in name:
+                flags.set_info(name.split(folder.colon)[-1])
+            flags.add_flag("S")
+            new_subpath = os.path.join(
+                "cur", message_id + folder.colon + flags.get_info()
+            )
+            os.rename(
+                os.path.join(folder._path, subpath),
+                os.path.join(folder._path, new_subpath),
+            )
+            folder._toc[message_id] = new_subpath  # pyright: ignore[reportAttributeAccessIssue]
+        return msg_str
 
     def delete_message(self, message_id: Any) -> None:
         self._active_folder.remove(message_id)
 
     def move_message(self, message_id: Any, folder_name: str) -> None:
-        message_data = self._active_folder.get(message_id)
-        if message_data is None:
+        """
+        Move the message's file into the same subdirectory (``new``/``cur``)
+        of ``folder_name``, keeping its filename, flags, and bytes, instead of
+        re-serializing it through ``Maildir.add``. Maildir++ folders live
+        under the same root, so this is a same-filesystem rename; if a folder
+        is a separate mount, ``os.rename`` raises ``OSError`` (``EXDEV``).
+        Raises ``mailbox.ExternalClashError`` rather than overwriting if the
+        destination already holds a message with the same key (including a
+        move into the active folder itself).
+        """
+        folder = self._active_folder
+        try:
+            subpath = folder._lookup(message_id)  # pyright: ignore[reportAttributeAccessIssue]
+        except KeyError:
             return
         dest = self._get_folder(folder_name)
-        dest.add(message_data)
-        self._active_folder.remove(message_id)
+        if message_id in dest:
+            raise mailbox.ExternalClashError(
+                f"Folder {folder_name} already contains message {message_id}"
+            )
+        os.rename(
+            os.path.join(folder._path, subpath),
+            os.path.join(dest._path, subpath),
+        )
+        # Keep both tables of contents current; see fetch_message's mark_read.
+        folder._toc.pop(message_id, None)  # pyright: ignore[reportAttributeAccessIssue]
+        dest._toc[message_id] = subpath  # pyright: ignore[reportAttributeAccessIssue]
 
     def keepalive(self) -> None:
         return

{mailsuite-2.3.2 → mailsuite-2.3.3}/mailsuite/smtp.py

@@ -62,6 +62,7 @@ def send_email(
     dkim_selector: str | None = None,
     dkim_domain: str | None = None,
     dkim_additional_headers: list[str] | None = None,
+    starttls: bool | None = None,
 ):
     """
     Send an email using a SMTP relay
@@ -102,6 +103,15 @@ def send_email(
             ``dkim_domain`` is not)
         dkim_additional_headers: Additional header names to include in the
             DKIM signature. Headers not present in the message are skipped.
+        starttls: Whether to upgrade a plain-text
+            (``require_encryption=False``) connection with STARTTLS.
+            ``None`` (default) upgrades when the server advertises
+            STARTTLS; ``False`` never upgrades, so the connection stays
+            plain text even when STARTTLS is advertised (credentials are
+            then sent unencrypted); ``True`` requires the upgrade and raises
+            :class:`SMTPError` if the server does not advertise STARTTLS.
+            Ignored when ``require_encryption=True``, because the
+            connection is already TLS.
     """
 
     using_oauth = oauth2_token is not None or oauth2_token_provider is not None
@@ -150,9 +160,18 @@ def send_email(
             server = smtplib.SMTP(host, port=port)
             server.connect(host, port)
             server.ehlo_or_helo_if_needed()
-            if server.has_extn("starttls"):
+            starttls_advertised = server.has_extn("starttls")
+            if starttls is False:
+                if starttls_advertised:
+                    logger.info(
+                        "SMTP server supports STARTTLS, but it is disabled"
+                        " ... staying in plain text"
+                    )
+            elif starttls_advertised:
                 server.starttls(context=ssl_context)
                 server.ehlo()
+            elif starttls:
+                raise SMTPError("STARTTLS required but not supported by the server")
             else:
                 logger.warning(
                     "SMTP server does not support STARTTLS. Proceeding in plain text!"