MailToolsBox 1.1.0__tar.gz → 3.0.0__tar.gz

mailtoolsbox-3.0.0/MailToolsBox/__init__.py

@@ -0,0 +1,48 @@
+"""MailToolsBox — modern sync/async SMTP sending and IMAP reading for Python."""
+
+from ._version import __version__
+from .exceptions import (
+    AuthenticationError,
+    ConfigurationError,
+    ConnectionError,
+    EmailValidationError,
+    IMAPError,
+    MailToolsBoxError,
+    SendError,
+)
+from .imapClient import (
+    ImapAgent,
+    ImapClient,
+    MailAddress,
+    MailItem,
+    MailPart,
+)
+from .mailSender import EmailSender, SendAgent, SmtpSession
+from .retry import RateLimiter, RetryPolicy
+from .security import SecurityMode
+
+__all__ = [
+    "__version__",
+    # SMTP
+    "EmailSender",
+    "SmtpSession",
+    "SendAgent",
+    # IMAP
+    "ImapClient",
+    "ImapAgent",
+    "MailItem",
+    "MailAddress",
+    "MailPart",
+    # Shared
+    "SecurityMode",
+    "RetryPolicy",
+    "RateLimiter",
+    # Exceptions
+    "MailToolsBoxError",
+    "ConfigurationError",
+    "ConnectionError",
+    "AuthenticationError",
+    "SendError",
+    "IMAPError",
+    "EmailValidationError",
+]

mailtoolsbox-3.0.0/MailToolsBox/_version.py

@@ -0,0 +1,3 @@
+"""Single source of truth for the package version."""
+
+__version__ = "3.0.0"

mailtoolsbox-3.0.0/MailToolsBox/exceptions.py

@@ -0,0 +1,40 @@
+"""Structured exception hierarchy for MailToolsBox.
+
+All errors raised by the library derive from :class:`MailToolsBoxError`, so
+callers can catch everything with a single ``except`` while still being able to
+distinguish connection, authentication, send, and validation failures.
+"""
+
+from __future__ import annotations
+
+
+class MailToolsBoxError(Exception):
+    """Base class for every error raised by MailToolsBox."""
+
+
+class ConfigurationError(MailToolsBoxError):
+    """Invalid or missing configuration (bad arguments, env vars, etc.)."""
+
+
+class EmailValidationError(MailToolsBoxError, ValueError):
+    """An email address failed validation/normalization."""
+
+
+class ConnectionError(MailToolsBoxError):
+    """Failed to establish or maintain a server connection."""
+
+
+class AuthenticationError(MailToolsBoxError):
+    """The server rejected the supplied credentials or OAuth2 token."""
+
+
+class SendError(MailToolsBoxError):
+    """A message could not be sent."""
+
+    def __init__(self, message: str, *, recipient: str | None = None) -> None:
+        super().__init__(message)
+        self.recipient = recipient
+
+
+class IMAPError(MailToolsBoxError):
+    """An IMAP operation failed."""

{mailtoolsbox-1.1.0 → mailtoolsbox-3.0.0}/MailToolsBox/imapClient.py

@@ -1,31 +1,31 @@
 from __future__ import annotations
 
-import imaplib
+import base64
+import datetime as dt
 import email
-import ssl
-import os
+import imaplib
 import json
-import datetime as dt
-import base64
+import logging
+import os
+import re
+import ssl
+from contextlib import contextmanager
 from dataclasses import dataclass, field
-from typing import List, Optional, Iterable, Tuple, Dict, Any
-from pathlib import Path
-from enum import Enum
 from email.header import decode_header, make_header
 from email.message import Message
+from pathlib import Path
+from typing import Any, Dict, Iterable, Iterator, List, Optional, Set, Tuple
 
+from .exceptions import AuthenticationError, IMAPError
+from .security import SecurityMode, build_ssl_context
 
-# ----------------------------- Security -----------------------------
-
-class SecurityMode(str, Enum):
-    AUTO = "auto"       # 993 -> SSL on connect, else try STARTTLS if server advertises it
-    STARTTLS = "starttls"
-    SSL = "ssl"         # implicit TLS on connect
-    NONE = "none"       # plaintext, only for trusted LANs
+logger = logging.getLogger(__name__)
+logger.addHandler(logging.NullHandler())
 
 
 # ----------------------------- Models -------------------------------
 
+
 @dataclass
 class MailAddress:
     name: Optional[str]
@@ -58,6 +58,7 @@ class MailItem:
 
 # --------------------------- Utilities ------------------------------
 
+
 def _decode_header_value(value: Optional[str]) -> str:
     if not value:
         return ""
@@ -66,6 +67,16 @@ def _decode_header_value(value: Optional[str]) -> str:
     except Exception:
         return value
 
+
+def _decode_filename(value: Optional[str]) -> str:
+    if not value:
+        return ""
+    try:
+        return str(make_header(decode_header(value)))
+    except Exception:
+        return value
+
+
 def _parse_addresses(value: Optional[str]) -> List[MailAddress]:
     if not value:
         return []
@@ -75,21 +86,25 @@ def _parse_addresses(value: Optional[str]) -> List[MailAddress]:
         out.append(MailAddress(_decode_header_value(name) or None, addr or None))
     return out
 
+
 def _to_local_datetime(date_hdr: Optional[str]) -> Optional[dt.datetime]:
     if not date_hdr:
         return None
     try:
-        t = email.utils.parsedate_tz(date_hdr)
-        if not t:
+        dt_obj = email.utils.parsedate_to_datetime(date_hdr)
+        if dt_obj is None:
             return None
-        timestamp = email.utils.mktime_tz(t)
-        return dt.datetime.fromtimestamp(timestamp)
+        # Assume UTC when timezone missing to keep comparisons consistent.
+        if dt_obj.tzinfo is None:
+            dt_obj = dt_obj.replace(tzinfo=dt.timezone.utc)
+        return dt_obj
     except Exception:
         return None
 
 
 # ----------------------------- Client --------------------------------
 
+
 class ImapClient:
     """
     Improved IMAP client with:
@@ -122,11 +137,7 @@ class ImapClient:
         self.oauth2_access_token = oauth2_access_token
         self.timeout = timeout
 
-        ctx = ssl_context or ssl.create_default_context()
-        if allow_invalid_certs:
-            ctx.check_hostname = False
-            ctx.verify_mode = ssl.CERT_NONE
-        self.ssl_context = ctx
+        self.ssl_context = build_ssl_context(ssl_context, allow_invalid_certs=allow_invalid_certs)
 
         self.conn: Optional[imaplib.IMAP4] = None
         self.selected_mailbox: Optional[str] = None
@@ -134,7 +145,7 @@ class ImapClient:
     # --------- factories
 
     @classmethod
-    def from_env(cls) -> "ImapClient":
+    def from_env(cls) -> ImapClient:
         """
         Required: IMAP_EMAIL, IMAP_SERVER
         Optional: IMAP_PASSWORD, IMAP_PORT, IMAP_SECURITY, IMAP_OAUTH2_TOKEN, IMAP_ALLOW_INVALID_CERTS
@@ -159,7 +170,7 @@ class ImapClient:
 
     # --------- context manager
 
-    def __enter__(self) -> "ImapClient":
+    def __enter__(self) -> ImapClient:
         self.login()
         return self
 
@@ -180,7 +191,9 @@ class ImapClient:
 
         conn = imaplib.IMAP4(self.server_address, self.port)
         conn.timeout = self.timeout
-        if mode == SecurityMode.STARTTLS or (mode == SecurityMode.AUTO and "STARTTLS" in conn.capabilities):
+        if mode == SecurityMode.STARTTLS or (
+            mode == SecurityMode.AUTO and "STARTTLS" in conn.capabilities
+        ):
             conn.starttls(self.ssl_context)
             # capabilities may change after STARTTLS
             conn.capabilities = conn.capability()[1][0].split()  # refresh
@@ -189,17 +202,19 @@ class ImapClient:
     def _auth(self, conn: imaplib.IMAP4) -> None:
         if self.oauth2_access_token:
             # XOAUTH2: base64("user=<email>\x01auth=Bearer <token>\x01\x01")
-            raw = f"user={self.email_account}\x01auth=Bearer {self.oauth2_access_token}\x01\x01".encode("utf-8")
+            raw = f"user={self.email_account}\x01auth=Bearer {self.oauth2_access_token}\x01\x01".encode()
             xoauth = base64.b64encode(raw).decode("ascii")
             typ, resp = conn.authenticate("XOAUTH2", lambda _: xoauth)
             if typ != "OK":
-                raise RuntimeError(f"XOAUTH2 failed: {resp}")
+                raise AuthenticationError(f"XOAUTH2 failed: {resp!r}")
             return
         if self.password is None:
-            raise RuntimeError("No password or OAuth2 token provided for IMAP authentication")
+            raise AuthenticationError(
+                "No password or OAuth2 token provided for IMAP authentication"
+            )
         typ, resp = conn.login(self.email_account, self.password)
         if typ != "OK":
-            raise RuntimeError(f"IMAP login failed: {resp}")
+            raise AuthenticationError(f"IMAP login failed: {resp!r}")
 
     def login(self) -> None:
         if self.conn:
@@ -232,8 +247,12 @@ class ImapClient:
             # format: b'(\\HasNoChildren) "/" "INBOX/Sub"'
             if not line:
                 continue
-            parts = line.decode("utf-8", errors="ignore").split(" ")
-            name = parts[-1].strip('"')
+            decoded = line.decode("utf-8", errors="ignore")
+            match = re.search(r'"((?:\\.|[^"])*)"$', decoded)
+            if match:
+                name = match.group(1).replace(r"\"", '"')
+            else:
+                name = decoded.split(" ", 1)[-1].strip('"')
             names.append(name)
         return names
 
@@ -241,7 +260,7 @@ class ImapClient:
         self._ensure()
         typ, _ = self.conn.select(mailbox, readonly=readonly)
         if typ != "OK":
-            raise RuntimeError(f"Cannot select mailbox {mailbox}")
+            raise IMAPError(f"Cannot select mailbox {mailbox}")
         self.selected_mailbox = mailbox
 
     # --------- search and fetch
@@ -265,7 +284,7 @@ class ImapClient:
         self._ensure_selected()
         typ, data = self.conn.uid("fetch", uid, "(RFC822 FLAGS)")
         if typ != "OK" or not data or not isinstance(data[0], tuple):
-            raise RuntimeError(f"Failed to fetch UID {uid}")
+            raise IMAPError(f"Failed to fetch UID {uid}")
         raw: bytes = data[0][1]
         # FLAGS come in a separate item depending on server, normalize
         flags: List[str] = []
@@ -276,7 +295,7 @@ class ImapClient:
                     start = flags_blob.find("(")
                     end = flags_blob.find(")")
                     if start >= 0 and end > start:
-                        flags = flags_blob[start + 1:end].split()
+                        flags = flags_blob[start + 1 : end].split()
                         break
         except Exception:
             flags = []
@@ -293,18 +312,34 @@ class ImapClient:
         text_body: Optional[str] = None
         html_body: Optional[str] = None
         attachments: List[MailPart] = []
+        used_names: Set[str] = set()
 
         if msg.is_multipart():
             for part in msg.walk():
                 ctype = part.get_content_type()
                 dispo = str(part.get("Content-Disposition") or "")
-                filename = part.get_filename()
+                filename_raw = part.get_filename()
+                filename = _decode_filename(filename_raw)
+                if filename:
+                    filename = Path(filename).name
+                    if filename in used_names:
+                        stem = Path(filename).stem
+                        suffix = Path(filename).suffix
+                        counter = 1
+                        candidate = f"{stem}_{counter}{suffix}"
+                        while candidate in used_names:
+                            counter += 1
+                            candidate = f"{stem}_{counter}{suffix}"
+                        filename = candidate
+                    used_names.add(filename)
                 is_attach = "attachment" in dispo.lower() or bool(filename)
                 charset = part.get_content_charset() or "utf-8"
 
                 if is_attach:
                     payload = part.get_payload(decode=True) or b""
-                    attachments.append(MailPart(ctype, charset, payload, filename=filename, is_attachment=True))
+                    attachments.append(
+                        MailPart(ctype, charset, payload, filename=filename, is_attachment=True)
+                    )
                     continue
 
                 if ctype == "text/plain":
@@ -355,7 +390,8 @@ class ImapClient:
         for uid in uids:
             try:
                 out.append(self.fetch(uid))
-            except Exception:
+            except Exception as exc:
+                logger.warning("Failed to fetch UID %s: %s", uid, exc)
                 continue
         return out
 
@@ -410,11 +446,23 @@ class ImapClient:
 
     # --------- legacy style exports (modernized)
 
-    def download_mail_text(self, path: str = "", mailbox: str = "INBOX") -> Path:
-        """
-        Dump all messages in a mailbox to a single UTF-8 text file.
+    @contextmanager
+    def _managed_session(self) -> Iterator[None]:
+        """Ensure a connection for the duration of a one-shot export.
+
+        Only tears the connection down if *this* call opened it; a connection
+        the caller already established (e.g. inside ``with ImapClient(...)``)
+        is left open.
         """
-        self.login()
+        owned = self.conn is None
+        self._ensure()
+        try:
+            yield
+        finally:
+            if owned:
+                self.logout()
+
+    def _dump_text(self, path: str, mailbox: str) -> Path:
         self.select(mailbox)
         uids = self.search("ALL")
         lines: List[str] = []
@@ -429,21 +477,14 @@ class ImapClient:
             )
         out = Path(path) / "email.txt"
         out.write_text("".join(lines), encoding="utf-8")
-        self.logout()
         return out
 
-    def download_mail_json(
-        self,
-        lookup: str = "ALL",
-        save: bool = False,
-        path: str = "",
-        file_name: str = "mail.json",
-        mailbox: str = "INBOX",
-    ) -> str:
-        """
-        Return JSON of selected messages. Optionally save to disk.
-        """
-        self.login()
+    def download_mail_text(self, path: str = "", mailbox: str = "INBOX") -> Path:
+        """Dump all messages in a mailbox to a single UTF-8 text file."""
+        with self._managed_session():
+            return self._dump_text(path, mailbox)
+
+    def _dump_json(self, lookup: str, save: bool, path: str, file_name: str, mailbox: str) -> str:
         self.select(mailbox)
         uids = self.search(lookup)
         items = self.fetch_many(uids)
@@ -467,14 +508,21 @@ class ImapClient:
         if save:
             out = Path(path) / file_name
             out.write_text(s, encoding="utf-8")
-        self.logout()
         return s
 
-    def download_mail_eml(self, directory: str = "", lookup: str = "ALL", mailbox: str = "INBOX") -> List[Path]:
-        """
-        Save each selected message as an .eml file.
-        """
-        self.login()
+    def download_mail_json(
+        self,
+        lookup: str = "ALL",
+        save: bool = False,
+        path: str = "",
+        file_name: str = "mail.json",
+        mailbox: str = "INBOX",
+    ) -> str:
+        """Return JSON of selected messages. Optionally save to disk."""
+        with self._managed_session():
+            return self._dump_json(lookup, save, path, file_name, mailbox)
+
+    def _dump_eml(self, directory: str, lookup: str, mailbox: str) -> List[Path]:
         self.select(mailbox)
         uids = self.search(lookup)
         out_paths: List[Path] = []
@@ -486,9 +534,15 @@ class ImapClient:
             out = target_dir / file_name
             out.write_bytes(item.raw)
             out_paths.append(out)
-        self.logout()
         return out_paths
 
+    def download_mail_eml(
+        self, directory: str = "", lookup: str = "ALL", mailbox: str = "INBOX"
+    ) -> List[Path]:
+        """Save each selected message as an .eml file."""
+        with self._managed_session():
+            return self._dump_eml(directory, lookup, mailbox)
+
     # --------- internal guards
 
     def _ensure(self) -> None:
@@ -499,3 +553,112 @@ class ImapClient:
         self._ensure()
         if not self.selected_mailbox:
             self.select("INBOX")
+
+
+# ----------------------------- Legacy shim -----------------------------
+
+
+class ImapAgent(ImapClient):
+    """
+    Backward compatible adapter that mirrors the old ImapAgent API
+    on top of the modern ImapClient.
+    """
+
+    def __init__(
+        self,
+        email_account: str,
+        password: Optional[str],
+        server_address: str,
+        *,
+        port: int = 993,
+        security_mode: SecurityMode = SecurityMode.SSL,
+        oauth2_access_token: Optional[str] = None,
+        ssl_context: Optional[ssl.SSLContext] = None,
+        allow_invalid_certs: bool = False,
+        timeout: int = 30,
+    ) -> None:
+        super().__init__(
+            email_account=email_account,
+            password=password,
+            server_address=server_address,
+            port=port,
+            security_mode=security_mode,
+            oauth2_access_token=oauth2_access_token,
+            ssl_context=ssl_context,
+            allow_invalid_certs=allow_invalid_certs,
+            timeout=timeout,
+        )
+        self.mail: Optional[imaplib.IMAP4] = None
+
+    def login_account(self) -> imaplib.IMAP4:
+        self.login()
+        self.mail = self.conn
+        return self.mail
+
+    def logout_account(self) -> None:
+        self.logout()
+        self.mail = None
+
+    def __enter__(self) -> ImapAgent:
+        self.login_account()
+        return self
+
+    def __exit__(self, exc_type, exc, tb) -> None:
+        self.logout_account()
+
+    def _sync_mail_alias(self) -> None:
+        if self.mail and self.conn is None:
+            self.conn = self.mail
+
+    def logout(self) -> None:
+        super().logout()
+        self.mail = None
+
+    # Legacy semantics: these one-shot exports always close the connection
+    # when done (the modern ImapClient versions leave a caller-owned
+    # connection open).
+
+    def download_mail_text(self, path: str = "", mailbox: str = "INBOX") -> Path:
+        self._sync_mail_alias()
+        self.login()
+        try:
+            return self._dump_text(path, mailbox)
+        finally:
+            self.logout()
+
+    def download_mail_json(
+        self,
+        lookup: str = "ALL",
+        save: bool = False,
+        path: str = "",
+        file_name: str = "mail.json",
+        mailbox: str = "INBOX",
+    ) -> str:
+        self._sync_mail_alias()
+        self.login()
+        try:
+            return self._dump_json(lookup, save, path, file_name, mailbox)
+        finally:
+            self.logout()
+
+    def download_mail_msg(
+        self, path: str = "", lookup: str = "ALL", mailbox: str = "INBOX"
+    ) -> List[Path]:
+        """Save each selected message as a .msg file (wrapper over .eml bytes)."""
+        self._sync_mail_alias()
+        self.login()
+        try:
+            self.select(mailbox)
+            uids = self.search(lookup)
+            out_paths: List[Path] = []
+            target_dir = Path(path or ".")
+            target_dir.mkdir(parents=True, exist_ok=True)
+            for i, uid in enumerate(uids):
+                item = self.fetch(uid)
+                file_name = f"email_{i}.msg"
+                out = target_dir / file_name
+                out.write_bytes(item.raw)
+                out_paths.append(out)
+            return out_paths
+        finally:
+            self.logout()