google styled doc

mail_intake/ingestion/reader.py

@@ -1,6 +1,10 @@
 """
 High-level mail ingestion orchestration for Mail Intake.
 
+---
+
+## Summary
+
 This module provides the primary, provider-agnostic entry point for
 reading and processing mail data.
 
@@ -29,19 +33,15 @@ class MailIntakeReader:
     """
     High-level read-only ingestion interface.
 
-    This class is the **primary entry point** for consumers of the Mail
-    Intake library.
+    Notes:
+        **Responsibilities:**
 
-    It orchestrates the full ingestion pipeline:
-    - Querying the adapter for message references
-    - Fetching raw provider messages
-    - Parsing and normalizing message data
-    - Constructing domain models
+            - This class is the primary entry point for consumers of the Mail Intake library
+            - It orchestrates the full ingestion pipeline: Querying the adapter for message references, fetching raw provider messages, parsing and normalizing message data, constructing domain models
 
-    This class is intentionally:
-    - Provider-agnostic
-    - Stateless beyond iteration scope
-    - Read-only
+        **Constraints:**
+        
+            - This class is intentionally: Provider-agnostic, stateless beyond iteration scope, read-only
     """
 
     def __init__(self, adapter: MailIntakeAdapter):
@@ -49,8 +49,8 @@ class MailIntakeReader:
         Initialize the mail reader.
 
         Args:
-            adapter: Mail adapter implementation used to retrieve raw
-                messages and threads from a mail provider.
+            adapter (MailIntakeAdapter):
+                Mail adapter implementation used to retrieve raw messages and threads from a mail provider.
         """
         self._adapter = adapter
 
@@ -59,13 +59,16 @@ class MailIntakeReader:
         Iterate over parsed messages matching a provider query.
 
         Args:
-            query: Provider-specific query string used to filter messages.
+            query (str):
+                Provider-specific query string used to filter messages.
 
         Yields:
-            Fully parsed and normalized `MailIntakeMessage` instances.
+            MailIntakeMessage:
+                Fully parsed and normalized `MailIntakeMessage` instances.
 
         Raises:
-            MailIntakeParsingError: If a message cannot be parsed.
+            MailIntakeParsingError:
+                If a message cannot be parsed.
         """
         for ref in self._adapter.iter_message_refs(query):
             raw = self._adapter.fetch_message(ref["message_id"])
@@ -75,17 +78,22 @@ class MailIntakeReader:
         """
         Iterate over threads constructed from messages matching a query.
 
-        Messages are grouped by `thread_id` and yielded as complete thread
-        objects containing all associated messages.
-
         Args:
-            query: Provider-specific query string used to filter messages.
+            query (str):
+                Provider-specific query string used to filter messages.
 
-        Returns:
-            An iterator of `MailIntakeThread` instances.
+        Yields:
+            MailIntakeThread:
+                An iterator of `MailIntakeThread` instances.
 
         Raises:
-            MailIntakeParsingError: If a message cannot be parsed.
+            MailIntakeParsingError:
+                If a message cannot be parsed.
+
+        Notes:
+            **Guarantees:**
+
+                - Messages are grouped by `thread_id` and yielded as complete thread objects containing all associated messages
         """
         threads: Dict[str, MailIntakeThread] = {}
 
@@ -110,14 +118,16 @@ class MailIntakeReader:
         Parse a raw provider message into a `MailIntakeMessage`.
 
         Args:
-            raw_message: Provider-native message payload.
+            raw_message (Dict[str, Any]):
+                Provider-native message payload.
 
         Returns:
-            A fully populated `MailIntakeMessage` instance.
+            MailIntakeMessage:
+                A fully populated `MailIntakeMessage` instance.
 
         Raises:
-            MailIntakeParsingError: If the message payload is missing required
-                fields or cannot be parsed.
+            MailIntakeParsingError:
+                If the message payload is missing required fields or cannot be parsed.
         """
         try:
             message_id = raw_message["id"]