flowbox 0.1.0__py3-none-any.whl

flowbox/__init__.py

@@ -0,0 +1,14 @@
+from flowbox._exceptions import AdapterError, MessageError, SignatureError
+from flowbox._flowbox import FlowInbox, FlowOutbox
+from flowbox._message import Address, Attachment, Message
+
+__all__ = [
+    "AdapterError",
+    "Address",
+    "Attachment",
+    "FlowInbox",
+    "FlowOutbox",
+    "Message",
+    "MessageError",
+    "SignatureError",
+]

flowbox/_exceptions.py

@@ -0,0 +1,13 @@
+from __future__ import annotations
+
+
+class AdapterError(Exception):
+    pass
+
+
+class SignatureError(AdapterError):
+    pass
+
+
+class MessageError(Exception):
+    pass

flowbox/_flowbox.py

@@ -0,0 +1,157 @@
+from __future__ import annotations
+
+from collections.abc import Mapping
+from dataclasses import replace
+from datetime import datetime
+from types import TracebackType
+from typing import TYPE_CHECKING, Self
+
+from flowbox._exceptions import MessageError
+
+if TYPE_CHECKING:
+    import ssl
+
+    from flowbox._message import Address, Message
+    from flowbox.adapters import (
+        Encryption,
+        IMAPAdapter,
+        InboxAdapterABC,
+        LettermintAdapter,
+        OutboxAdapterABC,
+        WebhookInboxAdapterABC,
+    )
+
+
+class FlowInbox[AdapterT: InboxAdapterABC | WebhookInboxAdapterABC]:
+    """Reads mail through a mailbox adapter, a webhook adapter, or one that is both.
+
+    Each method is annotated with the adapter kind it needs, so calling one the
+    adapter cannot serve -- parse_webhook() on an IMAP inbox, say -- is flagged
+    by the type checker rather than failing at runtime."""
+
+    def __init__(self, adapter: AdapterT) -> None:
+        self._adapter = adapter
+
+    @staticmethod
+    def connect_imap(
+        host: str,
+        username: str,
+        password: str,
+        port: int | None = None,
+        encryption: Encryption = "ssl",
+        timeout: float | None = 30.0,
+        ssl_context: ssl.SSLContext | None = None,
+    ) -> FlowInbox[IMAPAdapter]:
+        from flowbox.adapters import IMAPAdapter
+
+        return FlowInbox(IMAPAdapter(host, username, password, port, encryption, timeout, ssl_context))
+
+    @staticmethod
+    def connect_lettermint(
+        team_token: str | None = None,
+        webhook_secret: str | None = None,
+        project_id: str | None = None,
+        timeout: float = 30.0,
+    ) -> FlowInbox[LettermintAdapter]:
+        """``team_token`` is for retrieve_mails(), ``webhook_secret`` (``whsec_...``)
+        for parse_webhook(); pass whichever this inbox uses."""
+        from flowbox.adapters import LettermintAdapter
+
+        adapter = LettermintAdapter(
+            team_token=team_token, webhook_secret=webhook_secret, project_id=project_id, timeout=timeout
+        )
+        return FlowInbox(adapter)
+
+    @property
+    def adapter(self) -> AdapterT:
+        return self._adapter
+
+    def get_mailboxes(self: FlowInbox[InboxAdapterABC]) -> list[str]:
+        return self._adapter.get_mailboxes()
+
+    def retrieve_mails(self: FlowInbox[InboxAdapterABC], mailbox: str, from_datetime: datetime) -> list[Message]:
+        return self._adapter.retrieve_mails(mailbox, from_datetime)
+
+    def parse_webhook(self: FlowInbox[WebhookInboxAdapterABC], body: bytes, headers: Mapping[str, str]) -> Message:
+        """Pass the raw request body, before any JSON or form parsing."""
+        return self._adapter.parse_webhook(body, headers)
+
+    def close(self) -> None:
+        self._adapter.close()
+
+    def __enter__(self) -> Self:
+        return self
+
+    def __exit__(
+        self, exc_type: type[BaseException] | None, exc: BaseException | None, traceback: TracebackType | None
+    ) -> None:
+        self.close()
+
+
+class FlowOutbox:
+    def __init__(self, adapter: OutboxAdapterABC, sender: Address | None = None) -> None:
+        self._adapter = adapter
+        #: Used for every message that does not set its own sender.
+        self._sender = sender
+
+    @classmethod
+    def connect_smtp(
+        cls,
+        host: str,
+        username: str | None = None,
+        password: str | None = None,
+        port: int | None = None,
+        encryption: Encryption = "starttls",
+        timeout: float = 30.0,
+        sender: Address | None = None,
+        ssl_context: ssl.SSLContext | None = None,
+    ) -> Self:
+        from flowbox.adapters import SMTPAdapter
+
+        adapter = SMTPAdapter(host, username, password, port, encryption, timeout, ssl_context=ssl_context)
+        return cls(adapter, sender)
+
+    @classmethod
+    def connect_lettermint(
+        cls,
+        project_token: str,
+        route: str | None = None,
+        sender: Address | None = None,
+        timeout: float = 30.0,
+    ) -> Self:
+        from flowbox.adapters import LettermintAdapter
+
+        return cls(LettermintAdapter(project_token=project_token, route=route, timeout=timeout), sender)
+
+    @property
+    def adapter(self) -> OutboxAdapterABC:
+        return self._adapter
+
+    @property
+    def sender(self) -> Address | None:
+        return self._sender
+
+    def send_mail(self, message: Message) -> str:
+        """Send the message and return the provider's id for it."""
+        if message.sender is None:
+            if self._sender is None:
+                raise MessageError("the message has no sender and the outbox has no default sender")
+            message = replace(message, sender=self._sender)
+
+        if not message.to:
+            raise MessageError("the message has no recipients in 'to'")
+        if message.text is None and message.html is None:
+            raise MessageError("the message has neither a text nor an html body")
+
+        return self._adapter.send_mail(message)
+
+    def close(self) -> None:
+        self._adapter.close()
+
+    def __enter__(self) -> Self:
+        return self
+
+    def __exit__(
+        self, exc_type: type[BaseException] | None, exc: BaseException | None, traceback: TracebackType | None
+    ) -> None:
+        self.close()

flowbox/_message.py

@@ -0,0 +1,60 @@
+from __future__ import annotations
+
+import mimetypes
+from dataclasses import dataclass, field
+from datetime import datetime
+from email.utils import formataddr, parseaddr
+from pathlib import Path
+
+
+@dataclass(slots=True, frozen=True)
+class Address:
+    email: str
+    name: str | None = None
+
+    @classmethod
+    def parse(cls, value: str) -> Address:
+        """``"Jane Doe <jane@example.com>"`` or a bare ``"jane@example.com"``."""
+        name, email = parseaddr(value)
+        return cls(email=email, name=name or None)
+
+    def __str__(self) -> str:
+        return formataddr((self.name, self.email)) if self.name else self.email
+
+
+@dataclass(slots=True)
+class Attachment:
+    filename: str
+    content: bytes
+    #: Guessed from the filename when left empty.
+    content_type: str = ""
+    #: Makes the attachment inline: the HTML body references it as ``cid:<content_id>``.
+    content_id: str | None = None
+
+    def __post_init__(self) -> None:
+        if not self.content_type:
+            self.content_type = mimetypes.guess_type(self.filename)[0] or "application/octet-stream"
+
+    @classmethod
+    def from_path(cls, path: str | Path, content_id: str | None = None) -> Attachment:
+        path = Path(path)
+        return cls(filename=path.name, content=path.read_bytes(), content_id=content_id)
+
+
+@dataclass(slots=True)
+class Message:
+    subject: str
+    to: list[Address] = field(default_factory=list)
+    #: Falls back to the outbox's default sender when sending.
+    sender: Address | None = None
+    cc: list[Address] = field(default_factory=list)
+    bcc: list[Address] = field(default_factory=list)
+    reply_to: list[Address] = field(default_factory=list)
+    text: str | None = None
+    html: str | None = None
+    attachments: list[Attachment] = field(default_factory=list)
+    headers: dict[str, str] = field(default_factory=dict)
+    #: Set by the adapter on retrieved mail: the provider's id for the message.
+    id: str | None = None
+    #: Set by the adapter on retrieved mail: when the provider received it.
+    received_at: datetime | None = None

flowbox/_mime.py

@@ -0,0 +1,135 @@
+from __future__ import annotations
+
+from datetime import datetime
+from email import message_from_bytes, policy
+from email.headerregistry import AddressHeader
+from email.message import EmailMessage
+from email.utils import formatdate
+
+from flowbox._message import Address, Attachment, Message
+
+
+def to_mime(message: Message, sender: Address, message_id: str) -> EmailMessage:
+    """Bcc is deliberately left out of the headers: SMTP hands it to the server
+    as envelope recipients only, so the other recipients never see it."""
+    mime = EmailMessage()
+    mime["Subject"] = message.subject
+    mime["From"] = str(sender)
+    mime["Date"] = formatdate(localtime=True)
+    mime["Message-ID"] = message_id
+
+    for header, addresses in (("To", message.to), ("Cc", message.cc), ("Reply-To", message.reply_to)):
+        if addresses:
+            mime[header] = ", ".join(str(address) for address in addresses)
+
+    for name, value in message.headers.items():
+        if name.lower() == "message-id":
+            continue
+        mime[name] = value
+
+    if message.text is not None:
+        mime.set_content(message.text)
+        if message.html is not None:
+            mime.add_alternative(message.html, subtype="html")
+    else:
+        mime.set_content(message.html or "", subtype="html")
+
+    inline = [attachment for attachment in message.attachments if attachment.content_id is not None]
+    regular = [attachment for attachment in message.attachments if attachment.content_id is None]
+
+    html_part = mime.get_body(("html",)) if message.html is not None else None
+
+    for attachment in inline:
+        maintype, subtype = _split_content_type(attachment.content_type)
+        # Without an html body there is nothing to relate to, so it becomes a plain attachment.
+        target = html_part if isinstance(html_part, EmailMessage) else mime
+        add = target.add_related if target is html_part else target.add_attachment
+        add(
+            attachment.content,
+            maintype,
+            subtype,
+            cid=f"<{attachment.content_id}>",
+            filename=attachment.filename,
+            disposition="inline",
+        )
+
+    for attachment in regular:
+        maintype, subtype = _split_content_type(attachment.content_type)
+        mime.add_attachment(attachment.content, maintype, subtype, filename=attachment.filename)
+
+    return mime
+
+
+def from_mime(raw: bytes) -> Message:
+    mime = message_from_bytes(raw, policy=policy.default)
+    assert isinstance(mime, EmailMessage)
+
+    senders = _addresses(mime, "From")
+    text_part = mime.get_body(("plain",))
+    html_part = mime.get_body(("html",))
+
+    return Message(
+        subject=str(mime.get("Subject", "")),
+        sender=senders[0] if senders else None,
+        to=_addresses(mime, "To"),
+        cc=_addresses(mime, "Cc"),
+        reply_to=_addresses(mime, "Reply-To"),
+        text=text_part.get_content() if isinstance(text_part, EmailMessage) else None,
+        html=html_part.get_content() if isinstance(html_part, EmailMessage) else None,
+        attachments=[_attachment(part) for part in _attachment_parts(mime, (text_part, html_part))],
+        headers={name: str(value) for name, value in mime.items()},
+        received_at=_date(mime),
+    )
+
+
+def _addresses(mime: EmailMessage, header: str) -> list[Address]:
+    value = mime.get(header)
+    if not isinstance(value, AddressHeader):
+        return []
+    return [Address(email=address.addr_spec, name=address.display_name or None) for address in value.addresses]
+
+
+def _attachment_parts(part: EmailMessage, body_parts: tuple[object, ...]) -> list[EmailMessage]:
+    """Every leaf part except the chosen text and html bodies.
+
+    ``iter_attachments()`` is not enough: it treats the inline images of a
+    ``multipart/related`` body as part of that body. An attached email stays one
+    attachment rather than being opened up into its own parts."""
+    if any(part is body for body in body_parts):
+        return []
+    if part.get_content_type() == "message/rfc822" or not part.is_multipart():
+        return [part]
+
+    parts: list[EmailMessage] = []
+    for child in part.iter_parts():
+        if isinstance(child, EmailMessage):
+            parts.extend(_attachment_parts(child, body_parts))
+    return parts
+
+
+def _attachment(part: EmailMessage) -> Attachment:
+    content_id = part.get("Content-ID")
+    if part.get_content_type() == "message/rfc822":
+        inner = part.get_payload(0)
+        payload: object = inner.as_bytes() if isinstance(inner, EmailMessage) else b""
+    else:
+        payload = part.get_payload(decode=True)
+
+    return Attachment(
+        filename=part.get_filename() or ("message.eml" if part.get_content_type() == "message/rfc822" else "attachment"),
+        content=payload if isinstance(payload, bytes) else b"",
+        content_type=part.get_content_type(),
+        content_id=str(content_id).strip().strip("<>") if content_id else None,
+    )
+
+
+def _date(mime: EmailMessage) -> datetime | None:
+    """A malformed Date header parses to a header without a datetime rather than
+    raising, so a missing value is the only failure to handle."""
+    value = mime.get("Date")
+    return getattr(value, "datetime", None)
+
+
+def _split_content_type(content_type: str) -> tuple[str, str]:
+    maintype, _, subtype = content_type.partition("/")
+    return (maintype, subtype) if subtype else ("application", "octet-stream")

flowbox/adapters/__init__.py

@@ -0,0 +1,23 @@
+from flowbox.adapters._abc import (
+    AdapterABC,
+    Encryption,
+    InboxAdapterABC,
+    OutboxAdapterABC,
+    WebhookInboxAdapterABC,
+)
+from flowbox.adapters._imap import IMAPAdapter
+from flowbox.adapters._lettermint import LettermintAdapter
+from flowbox.adapters._log import LogAdapter
+from flowbox.adapters._smtp import SMTPAdapter
+
+__all__ = [
+    "AdapterABC",
+    "Encryption",
+    "IMAPAdapter",
+    "InboxAdapterABC",
+    "LettermintAdapter",
+    "LogAdapter",
+    "OutboxAdapterABC",
+    "SMTPAdapter",
+    "WebhookInboxAdapterABC",
+]

flowbox/adapters/_abc.py

@@ -0,0 +1,61 @@
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+from collections.abc import Mapping
+from datetime import datetime
+from typing import Literal
+
+from flowbox._exceptions import MessageError
+from flowbox._message import Address, Message
+
+#: How IMAP and SMTP connections are secured: TLS from the first byte, an upgrade
+#: of a plain connection, or (local test servers only) not at all.
+Encryption = Literal["ssl", "starttls", "none"]
+
+
+class AdapterABC(ABC):
+    def __init__(self, driver_name: str) -> None:
+        self._driver_name = driver_name
+
+    @property
+    def driver_name(self) -> str:
+        return self._driver_name
+
+    def close(self) -> None:
+        """Drop any open connection. Stateless adapters have nothing to close."""
+
+
+class InboxAdapterABC(AdapterABC):
+    @abstractmethod
+    def get_mailboxes(self) -> list[str]: ...
+
+    @abstractmethod
+    def retrieve_mails(self, mailbox: str, from_datetime: datetime) -> list[Message]:
+        """Every message received in ``mailbox`` at or after ``from_datetime``,
+        oldest first. A naive ``from_datetime`` is taken as local time."""
+
+
+class WebhookInboxAdapterABC(AdapterABC):
+    """For providers that push received mail to an HTTP endpoint instead of (or
+    besides) keeping it in a mailbox. Each provider signs and shapes its
+    webhooks differently; the adapter verifies and translates them."""
+
+    @abstractmethod
+    def parse_webhook(self, body: bytes, headers: Mapping[str, str]) -> Message:
+        """Verify the request and translate it into a message.
+
+        ``body`` must be the raw request body, before any JSON or form parsing:
+        signatures are computed over the exact bytes. Raises SignatureError when
+        the request is not from the provider."""
+
+
+class OutboxAdapterABC(AdapterABC):
+    @abstractmethod
+    def send_mail(self, message: Message) -> str:
+        """Send the message and return the provider's id for it."""
+
+
+def require_sender(message: Message) -> Address:
+    if message.sender is None:
+        raise MessageError("the message has no sender")
+    return message.sender