mailsuite 2.2.1__tar.gz → 2.3.0__tar.gz

{mailsuite-2.2.1 → mailsuite-2.3.0}/.gitignore

@@ -109,6 +109,4 @@ venv.bak/
 private/
 *.eml
 *.msg
-# Sanitized sample messages used as test fixtures are tracked despite *.eml
-!samples/failure_report_samples/*.eml
 scratch.py

{mailsuite-2.2.1 → mailsuite-2.3.0}/PKG-INFO

@@ -1,9 +1,9 @@
-Metadata-Version: 2.4
+Metadata-Version: 2.5
 Name: mailsuite
-Version: 2.2.1
+Version: 2.3.0
 Summary: A Python package for retrieving, parsing, and sending emails
 Project-URL: Homepage, https://github.com/seanthegeek/mailsuite/
-Project-URL: Documentation, https://seanthegeek.github.io/mailsuite/
+Project-URL: Documentation, https://seanthegeek.net/mailsuite/
 Project-URL: Issues, https://github.com/seanthegeek/mailsuite/issues
 Project-URL: Changelog, https://github.com/seanthegeek/mailsuite/blob/master/CHANGELOG.md
 Author-email: Sean Whalen <whalenster@gmail.com>
@@ -16,15 +16,20 @@ Classifier: Intended Audience :: Information Technology
 Classifier: License :: OSI Approved :: Apache Software License
 Classifier: Operating System :: OS Independent
 Classifier: Programming Language :: Python :: 3
-Requires-Python: >=3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Requires-Python: >=3.10
 Requires-Dist: authres>=1.2.0
-Requires-Dist: cryptography>=41.0.0
+Requires-Dist: cryptography>=50.0.0
 Requires-Dist: dkimpy>=1.1.0
 Requires-Dist: dnspython>=2.0.0
 Requires-Dist: expiringdict==1.2.2
 Requires-Dist: html2text>=2020.1.16
 Requires-Dist: imapclient>=3.1.0
-Requires-Dist: mail-parser>=4.2.1
+Requires-Dist: mail-parser>=4.6.2
 Requires-Dist: publicsuffix2>=2.20190812
 Provides-Extra: all
 Requires-Dist: azure-identity>=1.15.0; extra == 'all'
@@ -50,6 +55,20 @@ A Python package for retrieving, parsing, and sending emails.
 
 ## Features
 
+- Simplified IMAP client (`mailsuite.imap.IMAPClient`) — usable on its own,
+  and the engine behind the mailbox abstraction's IMAP backend
+  - Automatic reconnection and retries after dropped connections and timeouts
+  - Watch a folder for new messages with `IDLE` callbacks, including periodic
+    session refresh
+  - Username/password or OAuth2 (XOAUTH2 / OAUTHBEARER) login
+  - Always uses `/` as the folder hierarchy separator, converting to the
+    server's separator and prepending its namespace automatically, and
+    stripping folder-name characters that collide with the separator
+  - Works around server quirks across Gmail, Microsoft 365, Exchange,
+    Dovecot, and DavMail, including:
+    - Gmail / Google Workspace returning an empty `IDLE` response
+    - Random Microsoft 365 / Exchange `BAD` / "unexpected response" errors
+    - Nonstandard hierarchy separators and namespaces
 - Provider-agnostic mailbox abstraction (`mailsuite.mailbox`)
   - Single `MailboxConnection` interface for IMAP, Microsoft Graph, Gmail,
     and on-disk Maildir
@@ -58,33 +77,32 @@ A Python package for retrieving, parsing, and sending emails.
   - Folder management across every backend — create, rename, move, merge,
     delete, and existence checks, with consistent `FolderExistsError` /
     `FolderNotFoundError` semantics
-  - Watch a folder for new messages — the IMAP `IDLE` command (with periodic
-    session refresh) on the IMAP backend, polling on the cloud backends
+  - Watch a folder for new messages — the IMAP `IDLE` command on the IMAP
+    backend, polling on the cloud backends
   - Unified `send_message()` on backends that support sending (Microsoft
     Graph, Gmail) — IMAP and Maildir users send through
     `mailsuite.smtp.send_email`
-  - Username/password or OAuth2 (XOAUTH2 / OAUTHBEARER) login for IMAP and SMTP
-  - Automatic IMAP reconnection after dropped connections and timeouts
-  - Always uses `/` as the folder hierarchy separator, converting to the
-    server's separator and prepending its namespace automatically, and
-    stripping folder-name characters that collide with the separator
-  - Works around backend quirks across Gmail, Microsoft 365, Exchange,
-    Dovecot, and DavMail, including:
-    - Gmail / Google Workspace returning an empty `IDLE` response
-    - Random Microsoft 365 / Exchange `BAD` / "unexpected response" errors
-    - Nonstandard hierarchy separators and namespaces
-- Consistent email parsing
+- Consistent email parsing (`mailsuite.utils`)
+  - Parse RFC 822 messages from a string, bytes, or file path into
+    consistent dictionaries, with HTML bodies also converted to Markdown
   - SHA256 hashes of attachments
   - Parsed `Authentication-Results` and `DKIM-Signature` headers
+  - Email address parsing into display name, local part, domain, and
+    second-level domain, tolerating noncompliant addresses
+  - Check whether a message passed DKIM or DMARC as a trusted domain
+    (`from_trusted_domain`)
+  - Forward and reverse DNS lookup helpers
   - Parse Microsoft Outlook `.msg` files using `msgconvert`
-- Simplified email creation and sending
+- Simplified email creation and sending (`mailsuite.smtp`)
   - Easily add attachments, plain text, and HTML
+  - Optional DKIM signing of outgoing mail
   - Uses opportunistic encryption (`STARTTLS`) with SMTP by default
-- DKIM signing and verification
+  - Username/password or OAuth2 (XOAUTH2 / OAUTHBEARER) login
+- DKIM signing and verification (`mailsuite.dkim`)
   - Generate RSA keypairs and the matching DNS TXT record
   - Sign outbound mail with a sensible default header set
   - Verify one or many `DKIM-Signature` headers on a received message
-- ARC (Authenticated Received Chain) sealing and verification
+- ARC (Authenticated Received Chain) sealing and verification (`mailsuite.arc`)
   - Seal forwarded mail with an ARC set, extending an existing chain
   - Verify the ARC chain on a received message and read its `cv` result
 

{mailsuite-2.2.1 → mailsuite-2.3.0}/README.md

@@ -7,6 +7,20 @@ A Python package for retrieving, parsing, and sending emails.
 
 ## Features
 
+- Simplified IMAP client (`mailsuite.imap.IMAPClient`) — usable on its own,
+  and the engine behind the mailbox abstraction's IMAP backend
+  - Automatic reconnection and retries after dropped connections and timeouts
+  - Watch a folder for new messages with `IDLE` callbacks, including periodic
+    session refresh
+  - Username/password or OAuth2 (XOAUTH2 / OAUTHBEARER) login
+  - Always uses `/` as the folder hierarchy separator, converting to the
+    server's separator and prepending its namespace automatically, and
+    stripping folder-name characters that collide with the separator
+  - Works around server quirks across Gmail, Microsoft 365, Exchange,
+    Dovecot, and DavMail, including:
+    - Gmail / Google Workspace returning an empty `IDLE` response
+    - Random Microsoft 365 / Exchange `BAD` / "unexpected response" errors
+    - Nonstandard hierarchy separators and namespaces
 - Provider-agnostic mailbox abstraction (`mailsuite.mailbox`)
   - Single `MailboxConnection` interface for IMAP, Microsoft Graph, Gmail,
     and on-disk Maildir
@@ -15,33 +29,32 @@ A Python package for retrieving, parsing, and sending emails.
   - Folder management across every backend — create, rename, move, merge,
     delete, and existence checks, with consistent `FolderExistsError` /
     `FolderNotFoundError` semantics
-  - Watch a folder for new messages — the IMAP `IDLE` command (with periodic
-    session refresh) on the IMAP backend, polling on the cloud backends
+  - Watch a folder for new messages — the IMAP `IDLE` command on the IMAP
+    backend, polling on the cloud backends
   - Unified `send_message()` on backends that support sending (Microsoft
     Graph, Gmail) — IMAP and Maildir users send through
     `mailsuite.smtp.send_email`
-  - Username/password or OAuth2 (XOAUTH2 / OAUTHBEARER) login for IMAP and SMTP
-  - Automatic IMAP reconnection after dropped connections and timeouts
-  - Always uses `/` as the folder hierarchy separator, converting to the
-    server's separator and prepending its namespace automatically, and
-    stripping folder-name characters that collide with the separator
-  - Works around backend quirks across Gmail, Microsoft 365, Exchange,
-    Dovecot, and DavMail, including:
-    - Gmail / Google Workspace returning an empty `IDLE` response
-    - Random Microsoft 365 / Exchange `BAD` / "unexpected response" errors
-    - Nonstandard hierarchy separators and namespaces
-- Consistent email parsing
+- Consistent email parsing (`mailsuite.utils`)
+  - Parse RFC 822 messages from a string, bytes, or file path into
+    consistent dictionaries, with HTML bodies also converted to Markdown
   - SHA256 hashes of attachments
   - Parsed `Authentication-Results` and `DKIM-Signature` headers
+  - Email address parsing into display name, local part, domain, and
+    second-level domain, tolerating noncompliant addresses
+  - Check whether a message passed DKIM or DMARC as a trusted domain
+    (`from_trusted_domain`)
+  - Forward and reverse DNS lookup helpers
   - Parse Microsoft Outlook `.msg` files using `msgconvert`
-- Simplified email creation and sending
+- Simplified email creation and sending (`mailsuite.smtp`)
   - Easily add attachments, plain text, and HTML
+  - Optional DKIM signing of outgoing mail
   - Uses opportunistic encryption (`STARTTLS`) with SMTP by default
-- DKIM signing and verification
+  - Username/password or OAuth2 (XOAUTH2 / OAUTHBEARER) login
+- DKIM signing and verification (`mailsuite.dkim`)
   - Generate RSA keypairs and the matching DNS TXT record
   - Sign outbound mail with a sensible default header set
   - Verify one or many `DKIM-Signature` headers on a received message
-- ARC (Authenticated Received Chain) sealing and verification
+- ARC (Authenticated Received Chain) sealing and verification (`mailsuite.arc`)
   - Seal forwarded mail with an ARC set, extending an existing chain
   - Verify the ARC chain on a received message and read its `cv` result
 

{mailsuite-2.2.1 → mailsuite-2.3.0}/mailsuite/__init__.py

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

{mailsuite-2.2.1 → mailsuite-2.3.0}/mailsuite/arc.py

@@ -18,7 +18,8 @@ like :mod:`mailsuite.dkim`.
 """
 
 import logging
-from typing import Any, Callable, List, Optional, Union
+from collections.abc import Callable
+from typing import Any
 
 import dkim as _dkim
 
@@ -31,14 +32,14 @@ class ARCError(RuntimeError):
 
 
 def seal_email(
-    message: Union[str, bytes],
+    message: str | bytes,
     selector: str,
     domain: str,
-    private_key: Union[str, bytes],
+    private_key: str | bytes,
     authserv_id: str,
-    signed_headers: Optional[List[str]] = None,
-    timestamp: Optional[int] = None,
-) -> Union[str, bytes]:
+    signed_headers: list[str] | None = None,
+    timestamp: int | None = None,
+) -> str | bytes:
     """
     Adds an ARC set (seal) to an email and returns the sealed RFC 822 message
 
@@ -123,9 +124,9 @@ def seal_email(
 
 
 def verify_arc_chain(
-    message: Union[str, bytes],
+    message: str | bytes,
     minkey: int = 1024,
-    dns_func: Optional[Callable[[str], bytes]] = None,
+    dns_func: Callable[[str], bytes] | None = None,
 ) -> dict:
     """
     Verifies the ARC chain on an RFC 822 message

{mailsuite-2.2.1 → mailsuite-2.3.0}/mailsuite/dkim.py

@@ -3,7 +3,7 @@
 import base64
 import email
 import logging
-from typing import Callable, Optional, Tuple, Union
+from collections.abc import Callable
 
 import dkim as _dkim
 from cryptography.hazmat.primitives import serialization
@@ -58,7 +58,7 @@ def generate_dkim_private_key(key_size: int = 2048) -> str:
     return pem.decode("ascii")
 
 
-def get_dkim_public_key(private_key: Union[str, bytes]) -> str:
+def get_dkim_public_key(private_key: str | bytes) -> str:
     """
     Derives the DKIM public key from a private key
 
@@ -74,7 +74,7 @@ def get_dkim_public_key(private_key: Union[str, bytes]) -> str:
         key_bytes = bytes(private_key)
     try:
         key = serialization.load_pem_private_key(key_bytes, password=None)
-    except Exception as e:
+    except Exception as e:  # noqa: BLE001
         raise DKIMError(f"Failed to load private key: {e}")
     der = key.public_key().public_bytes(
         encoding=serialization.Encoding.DER,
@@ -83,7 +83,7 @@ def get_dkim_public_key(private_key: Union[str, bytes]) -> str:
     return base64.b64encode(der).decode("ascii")
 
 
-def generate_dkim_keypair(key_size: int = 2048) -> Tuple[str, str]:
+def generate_dkim_keypair(key_size: int = 2048) -> tuple[str, str]:
     """
     Generates a DKIM RSA keypair
 
@@ -98,11 +98,11 @@ def generate_dkim_keypair(key_size: int = 2048) -> Tuple[str, str]:
 
 
 def generate_dkim_txt_record(
-    public_key: Union[str, bytes],
+    public_key: str | bytes,
     selector: str = "default",
-    domain: Optional[str] = None,
-    flags: Optional[str] = None,
-    note: Optional[str] = None,
+    domain: str | None = None,
+    flags: str | None = None,
+    note: str | None = None,
 ) -> str:
     """
     Generates a DKIM TXT record
@@ -134,7 +134,7 @@ def generate_dkim_txt_record(
     elif "BEGIN" in key_str and "PUBLIC KEY" in key_str:
         try:
             pub = serialization.load_pem_public_key(key_str.encode("ascii"))
-        except Exception as e:
+        except Exception as e:  # noqa: BLE001
             raise DKIMError(f"Failed to load public key: {e}")
         der = pub.public_bytes(
             encoding=serialization.Encoding.DER,
@@ -159,14 +159,14 @@ def generate_dkim_txt_record(
 
 
 def sign_email(
-    message: Union[str, bytes],
+    message: str | bytes,
     selector: str,
     domain: str,
-    private_key: Union[str, bytes],
-    additional_headers: Optional[list[str]] = None,
-    canonicalize: Tuple[bytes, bytes] = (b"relaxed", b"relaxed"),
-    identity: Optional[str] = None,
-) -> Union[str, bytes]:
+    private_key: str | bytes,
+    additional_headers: list[str] | None = None,
+    canonicalize: tuple[bytes, bytes] = (b"relaxed", b"relaxed"),
+    identity: str | None = None,
+) -> str | bytes:
     """
     DKIM-signs an email and returns the signed RFC 822 message
 
@@ -210,7 +210,7 @@ def sign_email(
         headers_to_sign.extend(additional_headers)
 
     parsed = email.message_from_bytes(message_bytes)
-    present = {key.lower() for key in parsed.keys()}
+    present = {key.lower() for key in parsed}
 
     include = [
         header.encode("ascii")
@@ -243,10 +243,10 @@ def sign_email(
 
 
 def verify_email(
-    message: Union[str, bytes],
+    message: str | bytes,
     timeout: float = 5.0,
     minkey: int = 1024,
-    dns_func: Optional[Callable[[str], bytes]] = None,
+    dns_func: Callable[[str], bytes] | None = None,
 ) -> dict:
     """
     Verifies the DKIM signature(s) on an RFC 822 message
@@ -318,7 +318,7 @@ def verify_email(
                 sig_info["error"] = "Signature did not verify"
         except _dkim.DKIMException as e:
             sig_info["error"] = str(e)
-        except Exception as e:
+        except Exception as e:  # noqa: BLE001
             sig_info["error"] = f"Verification error: {e}"
 
         if sig_info["valid"]: