"""Abstract base class for mailbox connections"""
from __future__ import annotations
from abc import ABC
from collections.abc import Callable
from typing import Any
[docs]
class FolderExistsError(RuntimeError):
"""Raised when a folder/label operation targets a name that is already
taken — e.g. :meth:`MailboxConnection.rename_folder` or
:meth:`MailboxConnection.move_folder` onto an existing name."""
[docs]
class FolderNotFoundError(RuntimeError):
"""Raised when a folder/label referenced by an operation does not exist —
e.g. the source of a :meth:`MailboxConnection.move_folder` /
:meth:`MailboxConnection.merge_folders`, or a destination when its
``create`` parameter is left ``False``."""
[docs]
class MailboxConnection(ABC):
"""
A provider-agnostic interface for a mailbox
Subclasses implement the methods for a specific protocol (IMAP, Microsoft
Graph, Gmail, Maildir, etc.). Methods that don't apply to a given backend
raise :class:`NotImplementedError`.
"""
[docs]
def create_folder(self, folder_name: str) -> None:
"""Create a folder/label in the mailbox"""
raise NotImplementedError
[docs]
def delete_folder(self, folder_name: str) -> None:
"""Delete a folder/label from the mailbox"""
raise NotImplementedError
[docs]
def rename_folder(self, old_name: str, new_name: str) -> None:
"""
Rename a folder/label in the mailbox
Implementations call :meth:`_ensure_no_folder_conflict` first, so a
rename onto an existing name raises :class:`FolderExistsError`
consistently rather than each backend's native behavior.
Args:
old_name: The current folder/label name (or path)
new_name: The new folder/label name
Raises:
FolderExistsError: If ``new_name`` already exists.
"""
raise NotImplementedError
[docs]
def folder_exists(self, folder_name: str) -> bool:
"""
Return ``True`` if the named folder/label exists in the mailbox
Args:
folder_name: The folder/label name (or path) to check
"""
raise NotImplementedError
def _ensure_no_folder_conflict(self, folder_name: str) -> None:
"""Raise :class:`FolderExistsError` if ``folder_name`` already exists.
Backends call this from :meth:`rename_folder` so a name collision
fails uniformly, instead of each provider's native behavior — Graph
silently creating a second folder with a duplicate display name,
Maildir replacing an empty target directory, IMAP/Gmail raising
provider-specific errors. Best-effort: a folder created between this
check and the rename still falls back to the backend's behavior.
"""
if self.folder_exists(folder_name):
raise FolderExistsError(
f"cannot rename to {folder_name!r}: a folder or label with "
"that name already exists"
)
[docs]
def move_folder(
self,
source: str,
new_path: str | None = None,
new_parent: str | None = None,
create: bool = False,
) -> None:
"""
Relocate a folder (and its contents) to a new location
Give exactly one of ``new_path`` or ``new_parent``:
* ``new_path`` is the folder's complete new path, e.g.
``move_folder("Archive/Forensic", new_path="Reports/Failure")``.
* ``new_parent`` is the folder to move ``source`` under, keeping its
own leaf name, e.g. ``move_folder("Archive/Forensic",
new_parent="Reports")`` yields ``Reports/Forensic``.
Args:
source: Path of the folder to move. Must exist.
new_path: The complete new path for the folder.
new_parent: The parent folder to move ``source`` under (its leaf
name is preserved). Use ``""`` for the mailbox root.
create: Create the destination's parent path if it doesn't
already exist. When ``False`` (default), a missing parent
raises :class:`FolderNotFoundError`.
Raises:
ValueError: If not exactly one of ``new_path`` / ``new_parent``
is given.
FolderNotFoundError: If ``source`` (or, with ``create=False``,
the destination parent) does not exist.
FolderExistsError: If the target path is already taken.
Note:
On Gmail there are no real folders — only labels nested by a
``/`` naming convention — so a move renames the label's path and
does not relocate independent descendant labels.
"""
if (new_path is None) == (new_parent is None):
raise ValueError("provide exactly one of new_path or new_parent")
if not self.folder_exists(source):
raise FolderNotFoundError(f"folder {source!r} not found")
if new_parent is not None:
src_leaf = source.rpartition("/")[2]
target_parent = new_parent
target_path = f"{new_parent}/{src_leaf}" if new_parent else src_leaf
else:
assert new_path is not None
target_parent = new_path.rpartition("/")[0]
target_path = new_path
if target_parent and not self.folder_exists(target_parent):
if create:
self.create_folder(target_parent)
else:
raise FolderNotFoundError(
f"destination parent {target_parent!r} not found "
"(pass create=True to create it)"
)
self._ensure_no_folder_conflict(target_path)
self._do_move_folder(source, target_parent, target_path)
[docs]
def merge_folders(
self,
sources: str | list[str],
destination: str,
create: bool = False,
keep_source_folders: bool = False,
) -> None:
"""
Move the contents of one or more folders into another
Every message in each source folder is moved into ``destination``.
Args:
sources: A source folder path, or a list of them.
destination: The folder to move messages into.
create: Create ``destination`` if it doesn't already exist. When
``False`` (default), a missing destination raises
:class:`FolderNotFoundError`.
keep_source_folders: Leave the emptied source folders in place.
When ``False`` (default), each source folder is deleted after
its messages have been moved.
Raises:
FolderNotFoundError: If a source (or, with ``create=False``, the
destination) does not exist.
"""
if isinstance(sources, str):
sources = [sources]
if not self.folder_exists(destination):
if create:
self.create_folder(destination)
else:
raise FolderNotFoundError(
f"destination {destination!r} not found "
"(pass create=True to create it)"
)
for source in sources:
if source == destination:
continue
if not self.folder_exists(source):
raise FolderNotFoundError(f"folder {source!r} not found")
for message_id in self.fetch_messages(source):
self._move_message_from(message_id, source, destination)
if not keep_source_folders:
self.delete_folder(source)
def _do_move_folder(
self, source: str, target_parent: str, target_path: str
) -> None:
"""Backend-specific folder relocation, called by :meth:`move_folder`
after it has validated existence, created any missing parent, and
checked for a conflict. ``target_parent`` is ``""`` for the mailbox
root."""
raise NotImplementedError
def _move_message_from(
self, message_id: Any, source: str, destination: str
) -> None:
"""Move a single message from ``source`` to ``destination`` during a
:meth:`merge_folders`. Defaults to :meth:`move_message`; backends
whose ``move_message`` doesn't key off the message's current folder
(Gmail labels) override this to drop the source label explicitly."""
del source
self.move_message(message_id, destination)
[docs]
def fetch_messages(self, reports_folder: str, **kwargs: Any) -> list:
"""Return a list of message identifiers in the given folder"""
raise NotImplementedError
[docs]
def fetch_message(self, message_id: Any, **kwargs: Any) -> str:
"""Fetch the raw RFC 822 contents of a message by identifier"""
raise NotImplementedError
[docs]
def delete_message(self, message_id: Any) -> None:
"""Permanently delete a message by identifier"""
raise NotImplementedError
[docs]
def move_message(self, message_id: Any, folder_name: str) -> None:
"""Move a message to the named folder"""
raise NotImplementedError
[docs]
def keepalive(self) -> None:
"""Send a no-op to keep the connection alive (if applicable)"""
raise NotImplementedError
[docs]
def watch(
self,
check_callback: Callable[[MailboxConnection], None],
check_timeout: int,
config_reloading: Callable[[], bool] | None = None,
) -> None:
"""
Watch the mailbox for new messages, invoking ``check_callback`` when
new mail arrives or on a polling interval
Args:
check_callback: Called with this :class:`MailboxConnection`
instance whenever the watcher fires.
check_timeout: Polling interval (or IDLE timeout) in seconds.
config_reloading: Optional zero-argument callable. When it returns
a truthy value, the watcher exits cleanly so the caller can
reload configuration.
"""
raise NotImplementedError
[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 this mailbox's native send API (when supported)
Backends without a native send (IMAP, Maildir) raise
:class:`NotImplementedError`. Use :func:`mailsuite.smtp.send_email`
directly when you need to send mail without a mailbox.
Args:
message_from: The value of the ``From`` header
message_to: A list of recipient addresses
message_cc: A list of Cc addresses
message_bcc: A list of Bcc addresses
subject: The message subject
message_headers: Additional headers
attachments: A list of ``(filename, bytes)`` tuples
plain_message: The plain-text body
html_message: The HTML body
save_to_sent_items: Whether to save a copy to Sent Items
(Microsoft Graph only; Gmail always saves a copy).
Default ``True`` for backward compatibility.
Returns:
A provider-specific message identifier when available, otherwise
``None``.
"""
raise NotImplementedError