Vishesh 'ironeagle' Bangotra
f22af90e98
- docs(mail_intake/__init__.py): document module-based public API and usage patterns - docs(mail_intake/ingestion/reader.py): document high-level ingestion orchestration - docs(mail_intake/adapters/base.py): document adapter contract for mail providers - docs(mail_intake/adapters/gmail.py): document Gmail adapter implementation and constraints - docs(mail_intake/auth/base.py): document authentication provider contract - docs(mail_intake/auth/google.py): document Google OAuth authentication provider - docs(mail_intake/models/message.py): document canonical email message model - docs(mail_intake/models/thread.py): document canonical email thread model - docs(mail_intake/parsers/body.py): document message body extraction logic - docs(mail_intake/parsers/headers.py): document message header normalization utilities - docs(mail_intake/parsers/subject.py): document subject normalization utilities - docs(mail_intake/config.py): document global configuration model - docs(mail_intake/exceptions.py): document library exception hierarchy
77 lines
2.2 KiB
Python
77 lines
2.2 KiB
Python
"""
|
|
Mail provider adapter contracts for Mail Intake.
|
|
|
|
This module defines the **provider-agnostic adapter interface** used for
|
|
read-only mail ingestion.
|
|
|
|
Adapters encapsulate all provider-specific access logic and expose a
|
|
minimal, normalized contract to the rest of the system. No provider-specific
|
|
types or semantics should leak beyond implementations of this interface.
|
|
"""
|
|
|
|
from abc import ABC, abstractmethod
|
|
from typing import Iterator, Dict, Any
|
|
|
|
|
|
class MailIntakeAdapter(ABC):
|
|
"""
|
|
Base adapter interface for mail providers.
|
|
|
|
This interface defines the minimal contract required to:
|
|
- Discover messages matching a query
|
|
- Retrieve full message payloads
|
|
- Retrieve full thread payloads
|
|
|
|
Adapters are intentionally read-only and must not mutate provider state.
|
|
"""
|
|
|
|
@abstractmethod
|
|
def iter_message_refs(self, query: str) -> Iterator[Dict[str, str]]:
|
|
"""
|
|
Iterate over lightweight message references matching a query.
|
|
|
|
Implementations must yield dictionaries containing at least:
|
|
- ``message_id``: Provider-specific message identifier
|
|
- ``thread_id``: Provider-specific thread identifier
|
|
|
|
Args:
|
|
query: Provider-specific query string used to filter messages.
|
|
|
|
Yields:
|
|
Dictionaries containing message and thread identifiers.
|
|
|
|
Example yield:
|
|
{
|
|
"message_id": "...",
|
|
"thread_id": "..."
|
|
}
|
|
"""
|
|
raise NotImplementedError
|
|
|
|
@abstractmethod
|
|
def fetch_message(self, message_id: str) -> Dict[str, Any]:
|
|
"""
|
|
Fetch a full raw message by message identifier.
|
|
|
|
Args:
|
|
message_id: Provider-specific message identifier.
|
|
|
|
Returns:
|
|
Provider-native message payload
|
|
(e.g., Gmail message JSON structure).
|
|
"""
|
|
raise NotImplementedError
|
|
|
|
@abstractmethod
|
|
def fetch_thread(self, thread_id: str) -> Dict[str, Any]:
|
|
"""
|
|
Fetch a full raw thread by thread identifier.
|
|
|
|
Args:
|
|
thread_id: Provider-specific thread identifier.
|
|
|
|
Returns:
|
|
Provider-native thread payload.
|
|
"""
|
|
raise NotImplementedError
|