Source code for mailsuite.mailbox.gmail

"""Gmail mailbox backend"""

from __future__ import annotations

import base64
import logging
from collections.abc import Callable
from functools import lru_cache
from pathlib import Path
from time import sleep
from typing import Any

from mailsuite.mailbox.base import (
    FolderNotFoundError,
    MailboxConnection,
)
from mailsuite.utils import create_email

try:
    from google.auth.transport.requests import Request
    from google.oauth2 import service_account
    from google.oauth2.credentials import Credentials
    from google_auth_oauthlib.flow import InstalledAppFlow
    from googleapiclient.discovery import build
    from googleapiclient.errors import HttpError
except ImportError as e:
    raise ImportError(
        "GmailConnection requires the 'gmail' extra: pip install mailsuite[gmail]"
    ) from e

logger = logging.getLogger(__name__)


def _get_creds(
    token_file: str,
    credentials_file: str,
    scopes: list[str],
    oauth2_port: int,
    auth_mode: str = "installed_app",
    service_account_user: str | None = None,
):
    normalized_auth_mode = (auth_mode or "installed_app").strip().lower()
    if normalized_auth_mode == "service_account":
        creds = service_account.Credentials.from_service_account_file(
            credentials_file,
            scopes=scopes,
        )
        if service_account_user:
            creds = creds.with_subject(service_account_user)
        return creds
    if normalized_auth_mode != "installed_app":
        raise ValueError(
            f"Unsupported Gmail auth_mode '{auth_mode}'. "
            "Expected 'installed_app' or 'service_account'."
        )

    creds = None
    if Path(token_file).exists():
        creds = Credentials.from_authorized_user_file(token_file, scopes)

    if not creds or not creds.valid:
        if creds and creds.expired and creds.refresh_token:
            creds.refresh(Request())
        else:
            flow = InstalledAppFlow.from_client_secrets_file(credentials_file, scopes)
            creds = flow.run_local_server(open_browser=False, port=oauth2_port)
        Path(token_file).parent.mkdir(parents=True, exist_ok=True)
        with Path(token_file).open("w") as token:
            token.write(creds.to_json())
    return creds


[docs] class GmailConnection(MailboxConnection): """ A :class:`MailboxConnection` backed by the Gmail API Sends mail through ``users.messages.send`` with the message built by :func:`mailsuite.utils.create_email`. Sending requires a scope that includes the send permission (``gmail.send``, ``gmail.modify``, or full ``mail.google.com``). Requires the ``gmail`` extra:: pip install mailsuite[gmail] """ def __init__( self, token_file: str, credentials_file: str, scopes: list[str], include_spam_trash: bool, reports_folder: str, oauth2_port: int, paginate_messages: bool, auth_mode: str = "installed_app", service_account_user: str | None = None, ): creds = _get_creds( token_file, credentials_file, scopes, oauth2_port, auth_mode=auth_mode, service_account_user=service_account_user, ) self.service = build("gmail", "v1", credentials=creds) self.include_spam_trash = include_spam_trash self.reports_label_id = self._find_label_id_for_label(reports_folder) self.paginate_messages = paginate_messages
[docs] def create_folder(self, folder_name: str) -> None: # Gmail uses labels; "Archive" isn't a real Gmail concept if folder_name == "Archive": return logger.debug("Creating label %s", folder_name) request_body = {"name": folder_name, "messageListVisibility": "show"} try: self.service.users().labels().create( userId="me", body=request_body ).execute() except HttpError as e: if e.status_code == 409: logger.debug("Folder %s already exists, skipping creation", folder_name) else: raise # The label now exists; drop any cached "missing" (empty-id) result so # subsequent lookups resolve it (matches rename/delete/move_folder). self._find_label_id_for_label.cache_clear()
[docs] def rename_folder(self, old_name: str, new_name: str) -> None: """ Rename a label Gmail has no folders — only labels — so this backend maps the :class:`MailboxConnection` "folder" concept onto labels. Renaming patches the label's display name; the label's *immutable id* is preserved, so existing message associations (and any cached id) stay valid. Only user labels can be renamed. Renaming a system label (``INBOX``, ``SENT``, ``SPAM``, etc.) is rejected by Gmail and surfaces as a :class:`googleapiclient.errors.HttpError`. Nested labels are independent: renaming ``Work`` does not touch a label named ``Work/Projects``. Args: old_name: The current label name (or id) new_name: The new label display name Raises: FolderExistsError: If a label named ``new_name`` already exists. """ self._ensure_no_folder_conflict(new_name) label_id = self._find_label_id_for_label(old_name) if not label_id: # Without this guard we'd PATCH id="" and get a confusing API error # instead of a clear "doesn't exist" signal. raise FolderNotFoundError(f"label {old_name} not found") logger.debug("Renaming label %s to %s", old_name, new_name) self.service.users().labels().patch( userId="me", id=label_id, body={"name": new_name} ).execute() # Only the name→id cache is stale now; the label id itself is unchanged. self._find_label_id_for_label.cache_clear()
[docs] def delete_folder(self, folder_name: str) -> None: label_id = self._find_label_id_for_label(folder_name) if not label_id: raise FolderNotFoundError(f"label {folder_name} not found") logger.debug("Deleting label %s", folder_name) self.service.users().labels().delete(userId="me", id=label_id).execute() self._find_label_id_for_label.cache_clear()
[docs] def folder_exists(self, folder_name: str) -> bool: # _find_label_id_for_label returns "" when no label matches the name/id. return bool(self._find_label_id_for_label(folder_name))
def _do_move_folder( self, source: str, target_parent: str, target_path: str ) -> None: # Gmail has no real folders: relocating is just renaming the label's # "/"-path string. The label keeps its (immutable) id, so its messages # follow, but any independently-named descendant labels do not. del target_parent label_id = self._find_label_id_for_label(source) if not label_id: raise FolderNotFoundError(f"label {source} not found") self.service.users().labels().patch( userId="me", id=label_id, body={"name": target_path} ).execute() self._find_label_id_for_label.cache_clear() def _move_message_from( self, message_id: Any, source: str, destination: str ) -> None: # move_message drops the configured reports label; for a merge we must # drop the actual source label instead. src_label = self._find_label_id_for_label(source) dest_label = self._find_label_id_for_label(destination) request_body = { "addLabelIds": [dest_label], "removeLabelIds": [src_label], } self.service.users().messages().modify( userId="me", id=message_id, body=request_body ).execute() def _fetch_all_message_ids( self, reports_label_id: str, page_token: str | None = None, since: str | None = None, ): if since: results = ( self.service.users() .messages() .list( userId="me", includeSpamTrash=self.include_spam_trash, labelIds=[reports_label_id], pageToken=page_token, q=f"after:{since}", ) .execute() ) else: results = ( self.service.users() .messages() .list( userId="me", includeSpamTrash=self.include_spam_trash, labelIds=[reports_label_id], pageToken=page_token, ) .execute() ) for message in results.get("messages", []): yield message["id"] if "nextPageToken" in results and self.paginate_messages: yield from self._fetch_all_message_ids( reports_label_id, results["nextPageToken"], since=since )
[docs] def fetch_messages(self, reports_folder: str, **kwargs: Any) -> list[str]: reports_label_id = self._find_label_id_for_label(reports_folder) since = kwargs.get("since") if since: return list(self._fetch_all_message_ids(reports_label_id, since=since)) return list(self._fetch_all_message_ids(reports_label_id))
[docs] def fetch_message(self, message_id: Any, **kwargs: Any) -> str: msg = ( self.service.users() .messages() .get(userId="me", id=message_id, format="raw") .execute() ) return base64.urlsafe_b64decode(msg["raw"]).decode(errors="replace")
[docs] def delete_message(self, message_id: Any) -> None: self.service.users().messages().delete(userId="me", id=message_id).execute()
[docs] def move_message(self, message_id: Any, folder_name: str) -> None: label_id = self._find_label_id_for_label(folder_name) logger.debug("Moving message UID %s to %s", message_id, folder_name) request_body = { "addLabelIds": [label_id], "removeLabelIds": [self.reports_label_id], } self.service.users().messages().modify( userId="me", id=message_id, body=request_body ).execute()
[docs] def keepalive(self) -> None: return
[docs] def watch( self, check_callback: Callable[[MailboxConnection], None], check_timeout: int, config_reloading: Callable[[], bool] | None = None, ) -> None: """Poll the mailbox at ``check_timeout``-second intervals""" while True: if config_reloading and config_reloading(): return sleep(check_timeout) if config_reloading and config_reloading(): return check_callback(self)
[docs] def send_message( self, message_from: str, message_to: list[str] | None = None, message_cc: list[str] | None = None, message_bcc: list[str] | None = None, subject: str | None = None, message_headers: dict | None = None, attachments: list[tuple[str, bytes]] | None = None, plain_message: str | None = None, html_message: str | None = None, save_to_sent_items: bool = True, ) -> str | None: """Send a message through the Gmail API. The ``save_to_sent_items`` parameter is accepted for API parity with :meth:`MSGraphConnection.send_message` but is ignored — Gmail always saves a copy to Sent Mail. """ del save_to_sent_items # Gmail always saves to Sent Mail raw = create_email( message_from=message_from, message_to=message_to, message_cc=message_cc, subject=subject, message_headers=message_headers, attachments=attachments, plain_message=plain_message, html_message=html_message, ) encoded = base64.urlsafe_b64encode(raw.encode("utf-8")).decode("ascii") body: dict = {"raw": encoded} sent = ( self.service.users() .messages() .send(userId="me", body=body) .execute() ) return sent.get("id")
@lru_cache(maxsize=10) # noqa: B019 def _find_label_id_for_label(self, label_name: str) -> str: results = self.service.users().labels().list(userId="me").execute() for label in results.get("labels", []): if label_name == label["id"] or label_name == label["name"]: return label["id"] return ""