mailsuite 2.0.0__tar.gz → 2.0.2__tar.gz

{mailsuite-2.0.0 → mailsuite-2.0.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: mailsuite
-Version: 2.0.0
+Version: 2.0.2
 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/
@@ -119,3 +119,30 @@ different cache name can pass it through `token_cache_name=` so existing
 cached `AuthenticationRecord`s and tokens continue to work — for
 example, `token_cache_name="parsedmarc"` keeps users authenticated
 across the migration.
+
+### Microsoft Graph permissions
+
+Grant the appropriate Microsoft Graph **API permissions** on the app
+registration based on which `MSGraphConnection` operations you need.
+Combine permissions across rows when you need multiple capabilities —
+e.g., to both read and send mail in a delegated flow against your own
+mailbox, grant `Mail.ReadWrite` and `Mail.Send`.
+
+| Use case | Delegated (own mailbox) | Delegated (shared mailbox) | App-only |
+| --- | --- | --- | --- |
+| Read messages only (`fetch_message`, `fetch_messages`) | `Mail.Read` | `Mail.Read.Shared` | `Mail.Read` |
+| Read + modify (mark read, delete, move, create folder) | `Mail.ReadWrite` | `Mail.ReadWrite.Shared` | `Mail.ReadWrite` |
+| Send mail (`send_message`) | `Mail.Send` | `Mail.Send.Shared` | `Mail.Send` |
+
+Delegated flows (`DeviceCode`, `UsernamePassword`) targeting a shared
+mailbox — i.e. when the `mailbox` argument differs from `username` —
+use the `.Shared` variants. App-only flows (`ClientSecret`,
+`Certificate`) do not need the `.Shared` variants since application
+permissions span every mailbox in the tenant (unless restricted by an
+[Application Access Policy](https://learn.microsoft.com/en-us/graph/auth-limit-mailbox-access)).
+
+For delegated flows, `MSGraphConnection` requests `Mail.ReadWrite` (or
+`Mail.ReadWrite.Shared`) at authenticate time, so even read-only
+callers must consent to at least `Mail.ReadWrite`. App-only flows
+authenticate with `https://graph.microsoft.com/.default`, which grants
+whichever permissions the app registration has consented.

{mailsuite-2.0.0 → mailsuite-2.0.2}/README.md

@@ -77,3 +77,30 @@ different cache name can pass it through `token_cache_name=` so existing
 cached `AuthenticationRecord`s and tokens continue to work — for
 example, `token_cache_name="parsedmarc"` keeps users authenticated
 across the migration.
+
+### Microsoft Graph permissions
+
+Grant the appropriate Microsoft Graph **API permissions** on the app
+registration based on which `MSGraphConnection` operations you need.
+Combine permissions across rows when you need multiple capabilities —
+e.g., to both read and send mail in a delegated flow against your own
+mailbox, grant `Mail.ReadWrite` and `Mail.Send`.
+
+| Use case | Delegated (own mailbox) | Delegated (shared mailbox) | App-only |
+| --- | --- | --- | --- |
+| Read messages only (`fetch_message`, `fetch_messages`) | `Mail.Read` | `Mail.Read.Shared` | `Mail.Read` |
+| Read + modify (mark read, delete, move, create folder) | `Mail.ReadWrite` | `Mail.ReadWrite.Shared` | `Mail.ReadWrite` |
+| Send mail (`send_message`) | `Mail.Send` | `Mail.Send.Shared` | `Mail.Send` |
+
+Delegated flows (`DeviceCode`, `UsernamePassword`) targeting a shared
+mailbox — i.e. when the `mailbox` argument differs from `username` —
+use the `.Shared` variants. App-only flows (`ClientSecret`,
+`Certificate`) do not need the `.Shared` variants since application
+permissions span every mailbox in the tenant (unless restricted by an
+[Application Access Policy](https://learn.microsoft.com/en-us/graph/auth-limit-mailbox-access)).
+
+For delegated flows, `MSGraphConnection` requests `Mail.ReadWrite` (or
+`Mail.ReadWrite.Shared`) at authenticate time, so even read-only
+callers must consent to at least `Mail.ReadWrite`. App-only flows
+authenticate with `https://graph.microsoft.com/.default`, which grants
+whichever permissions the app registration has consented.

{mailsuite-2.0.0 → mailsuite-2.0.2}/mailsuite/__init__.py

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

{mailsuite-2.0.0 → mailsuite-2.0.2}/mailsuite/imap.py

@@ -1,5 +1,5 @@
 import logging
-from typing import Union, List, Dict, Optional, cast
+from typing import Callable, Union, List, Dict, Optional, cast
 import time
 import socket
 from ssl import (
@@ -58,6 +58,17 @@ class IMAPClient(imapclient.IMAPClient):
             return str(result)
 
         folder_name = folder_name.rstrip("/")
+
+        # If the path is already inside a non-personal namespace (other-users
+        # or shared per RFC 2342), pass it through without applying the
+        # personal-namespace prefix. Otherwise paths like "user/colleague/Inbox"
+        # would get rewritten to "INBOX/user/colleague/Inbox".
+        if any(folder_name.startswith(p) for p in self._other_namespace_prefixes):
+            result = imapclient.IMAPClient._normalise_folder(self, folder_name)
+            if isinstance(result, bytes):
+                return result.decode("utf-8", "replace")
+            return str(result)
+
         folder_name = folder_name.replace(self._path_prefix, "")
         if not self._hierarchy_separator == "/":
             folder_name = folder_name.replace(self._hierarchy_separator, "")
@@ -126,9 +137,9 @@ class IMAPClient(imapclient.IMAPClient):
     def __init__(
         self,
         host: str,
-        username: str,
-        password: str,
-        port: int = 933,
+        username: Optional[str] = None,
+        password: Optional[str] = None,
+        port: int = 993,
         ssl: bool = True,
         ssl_context: Optional[SSLContext] = None,
         verify: bool = True,
@@ -137,14 +148,18 @@ class IMAPClient(imapclient.IMAPClient):
         initial_folder: str = "INBOX",
         idle_callback=None,
         idle_timeout: int = 30,
+        oauth2_token: Optional[str] = None,
+        oauth2_token_provider: Optional[Callable[[], str]] = None,
+        oauth2_mechanism: str = "XOAUTH2",
+        oauth2_vendor: Optional[str] = None,
     ):
         """
         Connects to an IMAP server
 
         Args:
             host: The server hostname or IP address
-            username: The username
-            password: The password
+            username: The username (or OAuth2 identity / email address)
+            password: The password (omit when using OAuth2)
             port: The port
             ssl: Use SSL or TLS
             ssl_context: For more advanced TLS options
@@ -155,6 +170,25 @@ class IMAPClient(imapclient.IMAPClient):
             idle_callback: The function to call when new messages are detected
             idle_timeout: Number of seconds to wait for an IDLE
                                   response
+            oauth2_token: A static OAuth2 access token. For long-running
+                connections (IDLE, reconnects after timeouts) prefer
+                ``oauth2_token_provider`` so a fresh token is fetched on
+                reconnect.
+            oauth2_token_provider: A zero-arg callable returning a current
+                OAuth2 access token. Invoked on every (re)connect, so the
+                callable is responsible for refreshing the token when
+                needed.
+            oauth2_mechanism: ``"XOAUTH2"`` (default — Gmail/Yahoo/M365) or
+                ``"OAUTHBEARER"`` (Gmail's standards-track replacement).
+            oauth2_vendor: Optional vendor string required by Yahoo's
+                XOAUTH2 implementation.
+
+        For Google Workspace and Microsoft 365 the higher-level
+        :class:`mailsuite.mailbox.GmailConnection` and
+        :class:`mailsuite.mailbox.MSGraphConnection` backends are usually
+        a better fit — they speak the providers' native APIs and handle
+        token refresh end-to-end. Generic IMAP OAuth2 is intended for
+        other providers (Yahoo, self-hosted, etc.).
         """
 
         if ssl_context is None:
@@ -162,6 +196,18 @@ class IMAPClient(imapclient.IMAPClient):
         if verify is False:
             ssl_context.check_hostname = False
             ssl_context.verify_mode = CERT_NONE
+        using_oauth = (
+            oauth2_token is not None or oauth2_token_provider is not None
+        )
+        if using_oauth and not username:
+            raise ValueError(
+                "username is required when authenticating with OAuth2"
+            )
+        if not using_oauth and (username is None or password is None):
+            raise ValueError(
+                "either password or an OAuth2 token / token_provider must be "
+                "provided"
+            )
         self._init_args = dict(
             host=host,
             username=username,
@@ -175,11 +221,16 @@ class IMAPClient(imapclient.IMAPClient):
             initial_folder=initial_folder,
             idle_callback=idle_callback,
             idle_timeout=idle_timeout,
+            oauth2_token=oauth2_token,
+            oauth2_token_provider=oauth2_token_provider,
+            oauth2_mechanism=oauth2_mechanism,
+            oauth2_vendor=oauth2_vendor,
         )
         self.max_retries = max_retries
         self.idle_callback = idle_callback
         self.idle_timeout = idle_timeout
         self._path_prefix = ""
+        self._other_namespace_prefixes: List[str] = []
         self._hierarchy_separator = ""
         if not ssl:
             logger.info("Connecting to IMAP over plain text")
@@ -196,7 +247,23 @@ class IMAPClient(imapclient.IMAPClient):
             if not ssl and b"STARTTLS" in self.capabilities():
                 logger.info("IMAP server supports STARTTLS ... activating now")
                 self.starttls(ssl_context=ssl_context)
-            self.login(username, password)
+            if using_oauth:
+                token = (
+                    oauth2_token_provider()
+                    if oauth2_token_provider is not None
+                    else oauth2_token
+                )
+                if oauth2_mechanism.upper() == "OAUTHBEARER":
+                    self.oauthbearer_login(username, token)
+                else:
+                    self.oauth2_login(
+                        cast(str, username),
+                        cast(str, token),
+                        mech=oauth2_mechanism,
+                        vendor=oauth2_vendor,
+                    )
+            else:
+                self.login(cast(str, username), cast(str, password))
             self.server_capabilities = self.capabilities()
             self._move_supported = b"MOVE" in self.server_capabilities
             self._idle_supported = b"IDLE" in self.server_capabilities
@@ -217,6 +284,16 @@ class IMAPClient(imapclient.IMAPClient):
                         self._path_prefix = personal_namespace[0][0]
                         if type(self._path_prefix) is bytes:
                             self._path_prefix = self._path_prefix.decode("utf-8")
+                # Track non-personal namespace prefixes (other-users, shared)
+                # so _normalise_folder can recognise paths that already live
+                # in a different namespace and leave them alone.
+                for ns in (self._namespace.other, self._namespace.shared):
+                    for entry in ns or ():
+                        prefix = entry[0]
+                        if isinstance(prefix, bytes):
+                            prefix = prefix.decode("utf-8")
+                        if prefix:
+                            self._other_namespace_prefixes.append(prefix)
             else:
                 self._namespace = None
             self.select_folder(initial_folder)
@@ -244,13 +321,17 @@ class IMAPClient(imapclient.IMAPClient):
             self._init_args["password"],  # pyright: ignore[reportArgumentType]
             port=self._init_args["port"],  # pyright: ignore[reportArgumentType]
             ssl=self._init_args["ssl"],  # pyright: ignore[reportArgumentType]
-            ssl_context=self._init_args["ssl_context"],
+            ssl_context=self._init_args["ssl_context"],  # pyright: ignore[reportArgumentType]
             verify=self._init_args["verify"],  # pyright: ignore[reportArgumentType]
             timeout=self._init_args["timeout"],  # pyright: ignore[reportArgumentType]
             max_retries=self._init_args["max_retries"],  # pyright: ignore[reportArgumentType]
             initial_folder=self._init_args["initial_folder"],  # pyright: ignore[reportArgumentType]
             idle_callback=self._init_args["idle_callback"],
             idle_timeout=self._init_args["idle_timeout"],  # pyright: ignore[reportArgumentType]
+            oauth2_token=self._init_args["oauth2_token"],  # pyright: ignore[reportArgumentType]
+            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]
         )
 
     def fetch_message(

{mailsuite-2.0.0 → mailsuite-2.0.2}/mailsuite/mailbox/graph.py

@@ -147,16 +147,35 @@ def _generate_credential(auth_method: str, token_path: Path, **kwargs):
     raise RuntimeError(f"Auth method {auth_method} not found")
 
 
+_persistent_loop: Optional[asyncio.AbstractEventLoop] = None
+
+
 def _run(coro):
-    """Run a coroutine to completion. Refuses to nest in a running loop."""
+    """Run a coroutine to completion on a persistent event loop.
+
+    Refuses to nest in a running loop. We retain a single persistent
+    loop across calls because the Graph SDK's underlying
+    ``httpx.AsyncClient`` keeps connection-pool resources bound to the
+    loop that issued the first request — closing the loop between calls
+    (as ``asyncio.run`` does) invalidates those resources and surfaces
+    on the next call as ``RuntimeError: Event loop is closed``. See
+    https://github.com/domainaware/parsedmarc/issues/742.
+    """
+    global _persistent_loop
     try:
         asyncio.get_running_loop()
     except RuntimeError:
-        return asyncio.run(coro)
-    raise RuntimeError(
-        "MSGraphConnection cannot be called from inside a running event loop. "
-        "Use msgraph.GraphServiceClient directly from async code."
-    )
+        pass
+    else:
+        raise RuntimeError(
+            "MSGraphConnection cannot be called from inside a running event loop. "
+            "Use msgraph.GraphServiceClient directly from async code."
+        )
+
+    if _persistent_loop is None or _persistent_loop.is_closed():
+        _persistent_loop = asyncio.new_event_loop()
+        asyncio.set_event_loop(_persistent_loop)
+    return _persistent_loop.run_until_complete(coro)
 
 
 class MSGraphConnection(MailboxConnection):
@@ -168,6 +187,25 @@ class MSGraphConnection(MailboxConnection):
     ``/users/{mailbox}/sendMail`` with a structured ``Message`` body
     (Graph automatically saves a copy to Sent Items).
 
+    Required Microsoft Graph **API permissions** on the app registration
+    (combine as needed):
+
+    * Read-only (``fetch_message``, ``fetch_messages``): ``Mail.Read``
+    * Read + modify (mark read, delete, move, create folder):
+      ``Mail.ReadWrite``
+    * Send mail (``send_message``): ``Mail.Send``
+
+    Delegated flows (``DeviceCode``, ``UsernamePassword``) targeting a
+    shared mailbox (i.e. ``mailbox != username``) use the ``.Shared``
+    variants — ``Mail.Read.Shared``, ``Mail.ReadWrite.Shared``,
+    ``Mail.Send.Shared``. App-only flows (``ClientSecret``,
+    ``Certificate``) do not need the ``.Shared`` variants. See the
+    README "Microsoft Graph permissions" section for the full mapping.
+
+    Note: delegated flows always request ``Mail.ReadWrite`` at
+    authenticate time, so even read-only callers must consent to at
+    least ``Mail.ReadWrite``.
+
     Requires the ``msgraph`` extra::
 
         pip install mailsuite[msgraph]
@@ -289,8 +327,7 @@ class MSGraphConnection(MailboxConnection):
                 )
             logger.debug("Created folder %s", folder_name)
         except Exception as e:
-            # 409 / "already exists" is normal — surface other errors
-            if "already exists" in str(e).lower() or "ErrorFolderExists" in str(e):
+            if getattr(e, "response_status_code", None) == 409:
                 logger.debug("Folder %s already exists, skipping", folder_name)
                 return
             raise
@@ -347,8 +384,6 @@ class MSGraphConnection(MailboxConnection):
             self.mark_message_read(str(message_id))
         if raw is None:
             return ""
-        if isinstance(raw, str):
-            return raw
         return bytes(raw).decode("utf-8", errors="replace")
 
     def mark_message_read(self, message_id: str) -> None:
@@ -503,9 +538,11 @@ class MSGraphConnection(MailboxConnection):
     def _list_folders_filtered(
         self, folder_name: str, parent_folder_id: Optional[str]
     ) -> List[MailFolder]:
+        # OData string-literal escape: single quotes are doubled.
+        escaped = folder_name.replace("'", "''")
         if parent_folder_id is None:
             query = MailFoldersRequestBuilder.MailFoldersRequestBuilderGetQueryParameters(
-                filter=f"displayName eq '{folder_name}'"
+                filter=f"displayName eq '{escaped}'"
             )
             config = MailFoldersRequestBuilder.MailFoldersRequestBuilderGetRequestConfiguration(
                 query_parameters=query
@@ -517,7 +554,7 @@ class MSGraphConnection(MailboxConnection):
             )
         else:
             child_query = ChildFoldersRequestBuilder.ChildFoldersRequestBuilderGetQueryParameters(
-                filter=f"displayName eq '{folder_name}'"
+                filter=f"displayName eq '{escaped}'"
             )
             child_config = ChildFoldersRequestBuilder.ChildFoldersRequestBuilderGetRequestConfiguration(
                 query_parameters=child_query

{mailsuite-2.0.0 → mailsuite-2.0.2}/mailsuite/mailbox/imap.py

@@ -32,16 +32,42 @@ class IMAPConnection(MailboxConnection):
         self,
         host: str,
         user: str,
-        password: str,
+        password: Optional[str] = None,
         port: int = 993,
         ssl: bool = True,
         verify: bool = True,
         timeout: int = 30,
         max_retries: int = 4,
+        oauth2_token: Optional[str] = None,
+        oauth2_token_provider: Optional[Callable[[], str]] = None,
+        oauth2_mechanism: str = "XOAUTH2",
+        oauth2_vendor: Optional[str] = None,
     ):
+        """
+        Args:
+            host: IMAP server hostname
+            user: Username (or OAuth2 identity / email address)
+            password: Password (omit when using OAuth2)
+            port: Server port
+            ssl: Use SSL/TLS
+            verify: Verify the server's TLS certificate
+            timeout: Per-operation timeout in seconds
+            max_retries: Retries after a timeout
+            oauth2_token: Static OAuth2 access token
+            oauth2_token_provider: Zero-arg callable returning a current
+                token. Re-invoked on reconnect, so the callable is
+                responsible for refreshing the token. Prefer this over
+                ``oauth2_token`` for long-running watch loops.
+            oauth2_mechanism: ``"XOAUTH2"`` (default) or ``"OAUTHBEARER"``
+            oauth2_vendor: Optional vendor string for Yahoo's XOAUTH2
+        """
         self._username = user
         self._password = password
         self._verify = verify
+        self._oauth2_token = oauth2_token
+        self._oauth2_token_provider = oauth2_token_provider
+        self._oauth2_mechanism = oauth2_mechanism
+        self._oauth2_vendor = oauth2_vendor
         self._client = IMAPClient(
             host,
             user,
@@ -51,6 +77,10 @@ class IMAPConnection(MailboxConnection):
             verify=verify,
             timeout=timeout,
             max_retries=max_retries,
+            oauth2_token=oauth2_token,
+            oauth2_token_provider=oauth2_token_provider,
+            oauth2_mechanism=oauth2_mechanism,
+            oauth2_vendor=oauth2_vendor,
         )
 
     def create_folder(self, folder_name: str) -> None:
@@ -121,6 +151,10 @@ class IMAPConnection(MailboxConnection):
                     verify=self._verify,
                     idle_callback=idle_callback_wrapper,
                     idle_timeout=check_timeout,
+                    oauth2_token=self._oauth2_token,
+                    oauth2_token_provider=self._oauth2_token_provider,
+                    oauth2_mechanism=self._oauth2_mechanism,
+                    oauth2_vendor=self._oauth2_vendor,
                 )
             except (timeout, IMAPClientError):
                 logger.warning("IMAP connection timeout. Reconnecting...")