openmail 0.1.5__py3-none-any.whl

openmail/imap/fetch_response.py

@@ -0,0 +1,115 @@
+# openmail/imap/fetch_response.py
+from __future__ import annotations
+
+import re
+from dataclasses import dataclass
+from typing import Iterator, Optional, Sequence, Tuple
+
+UID_RE = re.compile(r"UID\s+(\d+)", re.IGNORECASE)
+INTERNALDATE_RE = re.compile(r'INTERNALDATE\s+"([^"]+)"', re.IGNORECASE)
+FLAGS_RE = re.compile(r"FLAGS\s*\(([^)]*)\)", re.IGNORECASE)
+
+# Used for parsing FETCH section results
+MIME_TOKEN_RE = re.compile(r"BODY\[(\d+(?:\.\d+)*)\.MIME\]", re.IGNORECASE)
+BODY_TOKEN_RE = re.compile(r"BODY\[(\d+(?:\.\d+)*)\]", re.IGNORECASE)
+HEADER_PEEK_RE = re.compile(r"BODY\[HEADER\]", re.IGNORECASE)
+
+
+@dataclass(frozen=True)
+class FetchPiece:
+    """
+    A normalized piece of a FETCH response.
+
+    meta: decoded string metadata from the FETCH tuple element.
+    payload: bytes payload (if present), else None.
+    """
+
+    meta: str
+    payload: Optional[bytes]
+
+
+def _extract_payload_from_fetch_item(
+    item: tuple, data: Sequence[object], i: int
+) -> Tuple[Optional[bytes], bool]:
+    """
+    Returns (payload_bytes, used_next_element).
+
+    imaplib can return:
+      - (meta, payload)
+      - (meta, None) then payload as next bytes item
+    """
+    raw = item[1] if len(item) > 1 and isinstance(item[1], (bytes, bytearray)) else None
+    used_next = False
+    if raw is None and i + 1 < len(data) and isinstance(data[i + 1], (bytes, bytearray)):
+        raw = data[i + 1]
+        used_next = True
+    return (bytes(raw) if isinstance(raw, (bytes, bytearray)) else None), used_next
+
+
+def iter_fetch_pieces(data: Sequence[object]) -> Iterator[FetchPiece]:
+    """
+    Normalize imaplib FETCH response data into (meta_str, payload_bytes?) pieces.
+
+    Skips non-tuple elements except tuple metadata; ignores the b")" terminators.
+    """
+    i = 0
+    n = len(data)
+    while i < n:
+        item = data[i]
+
+        # b")" terminator or other raw bytes => skip
+        if isinstance(item, (bytes, bytearray)):
+            i += 1
+            continue
+
+        if not isinstance(item, tuple) or not item:
+            i += 1
+            continue
+
+        meta_raw = item[0]
+        if not isinstance(meta_raw, (bytes, bytearray)):
+            i += 1
+            continue
+
+        meta_str = meta_raw.decode(errors="ignore")
+        payload, used_next = _extract_payload_from_fetch_item(item, data, i)
+        yield FetchPiece(meta=meta_str, payload=payload)
+
+        i += 2 if used_next else 1
+
+
+def parse_uid(meta: str) -> Optional[int]:
+    m = UID_RE.search(meta)
+    return int(m.group(1)) if m else None
+
+
+def parse_internaldate(meta: str) -> Optional[str]:
+    m = INTERNALDATE_RE.search(meta)
+    return m.group(1) if m else None
+
+
+def parse_flags(meta: str) -> set[str]:
+    m = FLAGS_RE.search(meta)
+    if not m:
+        return set()
+    flags_str = m.group(1).strip()
+    return {f for f in flags_str.split() if f} if flags_str else set()
+
+
+def has_header_peek(meta: str) -> bool:
+    return bool(HEADER_PEEK_RE.search(meta))
+
+
+def match_section_mime(meta: str) -> Optional[str]:
+    m = MIME_TOKEN_RE.search(meta)
+    return m.group(1) if m else None
+
+
+def match_section_body(meta: str) -> Optional[str]:
+    """
+    Returns section id for BODY[...] but NOT BODY[...MIME].
+    """
+    if MIME_TOKEN_RE.search(meta):
+        return None
+    m = BODY_TOKEN_RE.search(meta)
+    return m.group(1) if m else None

openmail/imap/inline_cid.py

@@ -0,0 +1,106 @@
+from __future__ import annotations
+
+import base64
+import imaplib
+import re
+from typing import Dict, Iterable, Optional
+from urllib.parse import unquote
+
+from openmail.models import AttachmentMeta
+
+_IMG_SRC_RE = re.compile(r'(<img\b[^>]*\bsrc=["\'])([^"\']+)(["\'])', re.IGNORECASE)
+
+
+def _cid_variants(cid_src: str) -> list[str]:
+    """
+    Turn 'cid:image001.png@01DC....' into candidates:
+      - image001.png@01DC...
+      - image001.png
+    Also handles <...> and urlencoding.
+    """
+    s = cid_src.strip()
+    if s.lower().startswith("cid:"):
+        s = s[4:].strip()
+
+    s = unquote(s)
+    s = s.strip().strip("<>").strip()
+    if not s:
+        return []
+
+    out = [s, s.lower()]
+    if "@" in s:
+        base = s.split("@", 1)[0]
+        out.extend([base, base.lower()])
+
+    # de-dupe preserving order
+    seen = set()
+    uniq: list[str] = []
+    for x in out:
+        if x and x not in seen:
+            seen.add(x)
+            uniq.append(x)
+    return uniq
+
+
+def build_inline_index(atts: Iterable[AttachmentMeta]) -> Dict[str, AttachmentMeta]:
+    """
+    Index inline-ish image attachments by content_id (+ variants).
+    """
+    idx: Dict[str, AttachmentMeta] = {}
+    for a in atts:
+        if not a.content_type.lower().startswith("image/"):
+            continue
+        # Use your is_inline signal OR content_id presence (both are useful)
+        if not (a.is_inline or a.content_id):
+            continue
+
+        if a.content_id:
+            key = a.content_id.strip().strip("<>").strip()
+            for k in _cid_variants(key):
+                idx.setdefault(k, a)
+    return idx
+
+
+def inline_cids_as_data_uris(
+    *,
+    conn: imaplib.IMAP4,
+    uid: int,
+    html: str,
+    attachment_metas: list[AttachmentMeta],
+    fetch_part_bytes,  # callable(part: str) -> bytes
+) -> str:
+    """
+    Rewrite <img src="cid:..."> to data: URIs by fetching the bytes via IMAP.
+    """
+    if not html or not attachment_metas:
+        return html
+
+    idx = build_inline_index(attachment_metas)
+
+    def repl(m: re.Match) -> str:
+        prefix, src, suffix = m.group(1), m.group(2), m.group(3)
+        if not src.lower().startswith("cid:"):
+            return m.group(0)
+
+        hit: Optional[AttachmentMeta] = None
+        for k in _cid_variants(src):
+            hit = idx.get(k)
+            if hit:
+                break
+        if not hit:
+            return m.group(0)
+
+        try:
+            data = fetch_part_bytes(conn, uid=uid, part=hit.part)
+        except Exception:
+            return m.group(0)
+
+        if not data:
+            return m.group(0)
+
+        ctype = (hit.content_type or "application/octet-stream").lower()
+        b64 = base64.b64encode(data).decode("ascii")
+        data_uri = f"data:{ctype};base64,{b64}"
+        return f"{prefix}{data_uri}{suffix}"
+
+    return _IMG_SRC_RE.sub(repl, html)

openmail/imap/pagination.py

@@ -0,0 +1,16 @@
+from dataclasses import dataclass
+from typing import List, Optional
+
+from openmail.types import EmailRef
+
+
+@dataclass
+class PagedSearchResult:
+    refs: List["EmailRef"]
+    next_before_uid: Optional[int] = None
+    prev_after_uid: Optional[int] = None
+    newest_uid: Optional[int] = None
+    oldest_uid: Optional[int] = None
+    total: Optional[int] = None
+    has_next: bool = False
+    has_prev: bool = False

openmail/imap/parser.py

@@ -0,0 +1,298 @@
+from __future__ import annotations
+
+import base64
+import email
+import quopri
+from datetime import datetime
+from email import policy
+from email.header import decode_header, make_header
+from email.message import Message as PyMessage
+from email.parser import BytesParser
+from email.policy import default as default_policy
+from email.utils import getaddresses
+from typing import Dict, List, Optional, Tuple
+
+from openmail.errors import ParseError
+from openmail.models import Attachment, EmailAddress, EmailMessage, EmailOverview
+from openmail.types import EmailRef
+from openmail.utils import best_effort_date
+
+_INTERNALDATE_FMTS = [
+    "%d-%b-%Y %H:%M:%S %z",  # standard INTERNALDATE
+]
+
+
+def parse_internaldate(internaldate_raw: Optional[str]) -> Optional[datetime]:
+    if not internaldate_raw:
+        return None
+    s = internaldate_raw.strip().strip('"')
+    for fmt in _INTERNALDATE_FMTS:
+        try:
+            return datetime.strptime(s, fmt)
+        except Exception:
+            pass
+    return None
+
+
+def _decode_header_value(value: Optional[str]) -> str:
+    if not value:
+        return ""
+    try:
+        return str(make_header(decode_header(value)))
+    except Exception:
+        return value
+
+
+def decode_transfer(payload: bytes, cte: str | None) -> bytes:
+    if not cte:
+        return payload
+    cte = cte.strip().lower()
+
+    if cte == "base64":
+        return base64.b64decode(payload, validate=False)
+    if cte in ("quoted-printable", "quopri"):
+        return quopri.decodestring(payload)
+    return payload
+
+
+def decode_body_chunk(chunk: bytes, msg: PyMessage) -> str:
+    """
+    Decode a body chunk using Content-Transfer-Encoding and charset
+    from the given (headers-only) message.
+    """
+    charset = msg.get_content_charset() or "utf-8"
+    cte = (msg.get("Content-Transfer-Encoding") or "").lower()
+
+    raw = chunk
+    try:
+        if cte == "base64":
+            raw = base64.b64decode(raw, validate=False)
+        elif cte in ("quoted-printable", "quotedprintable"):
+            raw = quopri.decodestring(raw)
+    except Exception:
+        raw = chunk
+
+    try:
+        return raw.decode(charset, errors="replace")
+    except Exception:
+        return raw.decode("utf-8", errors="replace")
+
+
+def _parse_addr_list(header_val: Optional[str]) -> List[EmailAddress]:
+    if not header_val:
+        return []
+    out: List[EmailAddress] = []
+    for name, addr in getaddresses([header_val]):
+        name_decoded = _decode_header_value(name).strip()
+        addr = (addr or "").strip()
+        if not addr and not name_decoded:
+            continue
+        out.append(EmailAddress(email=addr or "", name=name_decoded or None))
+    return out
+
+
+def _parse_single_addr(header_val: Optional[str]) -> EmailAddress:
+    addrs = _parse_addr_list(header_val)
+    return addrs[0] if addrs else EmailAddress(email="", name=None)
+
+
+def _extract_parts(msg: PyMessage) -> Tuple[Optional[str], Optional[str], List[Attachment]]:
+    text: Optional[str] = None
+    html: Optional[str] = None
+    atts: List[Attachment] = []
+    attachment_idx = 0
+
+    if msg.is_multipart():
+        for part in msg.walk():
+            if part.is_multipart():
+                continue
+
+            ctype = part.get_content_type()
+            disp = (part.get("Content-Disposition") or "").lower()
+
+            filename = part.get_filename()
+            if filename:
+                filename = _decode_header_value(filename)
+
+            payload = part.get_payload(decode=True) or b""
+
+            content_id = part.get("Content-ID")
+            if content_id:
+                content_id = content_id.strip().strip("<>").strip() or None
+
+            is_inline_image = ctype.startswith("image/") and (
+                ("inline" in disp) or bool(content_id)
+            )
+
+            # Attachment (explicit disposition or filename)
+            if filename or "attachment" in disp:
+                atts.append(
+                    Attachment(
+                        idx=attachment_idx,
+                        filename=filename or "attachment",
+                        content_type=ctype,
+                        data=payload,
+                        size=len(payload),
+                        content_id=content_id,
+                        disposition=(
+                            "inline"
+                            if is_inline_image
+                            else ("attachment" if "attachment" in disp else None)
+                        ),
+                        is_inline=is_inline_image,
+                    )
+                )
+                attachment_idx += 1
+                continue
+
+            if ctype in ("text/plain", "text/html"):
+                charset = part.get_content_charset() or "utf-8"
+                body = payload.decode(charset, errors="replace")
+
+                if ctype == "text/plain" and text is None:
+                    text = body
+                elif ctype == "text/html" and html is None:
+                    html = body
+    else:
+        payload = msg.get_payload(decode=True) or b""
+        charset = msg.get_content_charset() or "utf-8"
+        body = payload.decode(charset, errors="replace")
+        if msg.get_content_type() == "text/html":
+            html = body
+        else:
+            text = body
+
+    return text, html, atts
+
+
+def decode_section(mime_bytes: Optional[bytes], body_bytes: Optional[bytes]) -> str:
+    if not body_bytes:
+        return ""
+    if not mime_bytes:
+        try:
+            return body_bytes.decode("utf-8", errors="replace")
+        except Exception:
+            return body_bytes.decode("latin-1", errors="replace")
+
+    msg = BytesParser(policy=default_policy).parsebytes(mime_bytes)
+    return decode_body_chunk(body_bytes, msg)
+
+
+def parse_rfc822(
+    ref: EmailRef,
+    raw: bytes,
+    *,
+    include_attachments: bool = False,
+    internaldate_raw: Optional[str] = None,
+) -> EmailMessage:
+    try:
+        pymsg: PyMessage = email.message_from_bytes(raw, policy=policy.default)
+
+        text, html, atts = _extract_parts(pymsg)
+        if not include_attachments:
+            atts = []
+
+        headers: Dict[str, str] = {k: _decode_header_value(str(v)) for k, v in pymsg.items()}
+
+        raw_date = pymsg.get("Date")
+        received_at = parse_internaldate(internaldate_raw)
+        sent_at = best_effort_date(raw_date, None)
+
+        return EmailMessage(
+            ref=ref,
+            subject=_decode_header_value(pymsg.get("Subject")),
+            from_email=_parse_single_addr(pymsg.get("From")),
+            to=_parse_addr_list(pymsg.get("To")),
+            cc=_parse_addr_list(pymsg.get("Cc")),
+            bcc=_parse_addr_list(pymsg.get("Bcc")),
+            text=text,
+            html=html,
+            attachments=atts,
+            received_at=received_at,
+            sent_at=sent_at,
+            message_id=_decode_header_value(pymsg.get("Message-ID")),
+            headers=headers,
+        )
+    except Exception as e:
+        raise ParseError(f"Failed to parse RFC822: {e}") from e
+
+
+def parse_headers_and_bodies(
+    ref: EmailRef,
+    header_bytes: bytes,
+    *,
+    text: str,
+    html: str,
+    attachments,
+    internaldate_raw: Optional[str] = None,
+) -> EmailMessage:
+    try:
+        msg_headers = BytesParser(policy=default_policy).parsebytes(header_bytes or b"")
+
+        headers: Dict[str, str] = {k: _decode_header_value(str(v)) for k, v in msg_headers.items()}
+        raw_date = msg_headers.get("Date")
+        received_at = parse_internaldate(internaldate_raw)
+        sent_at = best_effort_date(raw_date, None)
+
+        return EmailMessage(
+            ref=ref,
+            subject=_decode_header_value(msg_headers.get("Subject")),
+            from_email=_parse_single_addr(msg_headers.get("From")),
+            to=_parse_addr_list(msg_headers.get("To")),
+            cc=_parse_addr_list(msg_headers.get("Cc")),
+            bcc=_parse_addr_list(msg_headers.get("Bcc")),
+            text=text or None,
+            html=html or None,
+            attachments=attachments,
+            received_at=received_at,
+            sent_at=sent_at,
+            message_id=_decode_header_value(msg_headers.get("Message-ID")),
+            headers=headers,
+        )
+    except Exception as e:
+        raise ParseError(f"Failed to parse headers/bodies: {e}") from e
+
+
+def parse_overview(
+    ref: EmailRef,
+    flags: set,
+    header_bytes: bytes | bytearray,
+    *,
+    internaldate_raw: Optional[str] = None,
+) -> EmailOverview:
+    try:
+        subject = ""
+        from_addr = EmailAddress(email="", name=None)
+        to_addrs: List[EmailAddress] = []
+        headers: Dict[str, str] = {}
+        date_header_raw: Optional[str] = None
+
+        if isinstance(header_bytes, (bytes, bytearray)):
+            msg_headers = BytesParser(policy=default_policy).parsebytes(bytes(header_bytes))
+
+            subject = _decode_header_value(msg_headers.get("Subject"))
+            from_addr = _parse_single_addr(msg_headers.get("From"))
+            date_header_raw = msg_headers.get("Date")
+
+            to_raw_list = msg_headers.get_all("To", [])
+            if to_raw_list:
+                to_addrs = _parse_addr_list(", ".join(to_raw_list))
+
+            for k, v in msg_headers.items():
+                headers[k] = _decode_header_value(str(v))
+
+        received_at = parse_internaldate(internaldate_raw)
+        sent_at = best_effort_date(date_header_raw, None)
+
+        return EmailOverview(
+            ref=ref,
+            subject=subject or "",
+            from_email=from_addr or EmailAddress(email="", name=None),
+            to=to_addrs,
+            flags=flags,
+            received_at=received_at,
+            sent_at=sent_at,
+            headers=headers,
+        )
+    except Exception as e:
+        raise ParseError(f"Failed to parse Email Overview: {e}") from e