google styled doc

mail_intake/adapters/base.py

@@ -1,6 +1,10 @@
 """
 Mail provider adapter contracts for Mail Intake.
 
+---
+
+## Summary
+
 This module defines the **provider-agnostic adapter interface** used for
 read-only mail ingestion.
 
@@ -17,12 +21,16 @@ 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
+    Notes:
+        **Guarantees:**
 
-    Adapters are intentionally read-only and must not mutate provider state.
+            - discover messages matching a query
+            - retrieve full message payloads
+            - retrieve full thread payloads
+
+        **Lifecycle:**
+
+            - adapters are intentionally read-only and must not mutate provider state
     """
 
     @abstractmethod
@@ -30,21 +38,26 @@ class MailIntakeAdapter(ABC):
         """
         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.
+            query (str):
+                Provider-specific query string used to filter messages.
 
         Yields:
-            Dictionaries containing message and thread identifiers.
+            Dict[str, str]:
+                Dictionaries containing message and thread identifiers.
 
-        Example yield:
-            {
-                "message_id": "...",
-                "thread_id": "..."
-            }
+        Notes:
+            **Guarantees:**
+
+                - Implementations must yield dictionaries containing at least ``message_id`` and ``thread_id``
+
+        Example:
+            Typical yield:
+
+                {
+                    "message_id": "...",
+                    "thread_id": "..."
+                }
         """
         raise NotImplementedError
 
@@ -54,11 +67,12 @@ class MailIntakeAdapter(ABC):
         Fetch a full raw message by message identifier.
 
         Args:
-            message_id: Provider-specific message identifier.
+            message_id (str):
+                Provider-specific message identifier.
 
         Returns:
-            Provider-native message payload
-            (e.g., Gmail message JSON structure).
+            Dict[str, Any]:
+                Provider-native message payload (e.g., Gmail message JSON structure).
         """
         raise NotImplementedError
 
@@ -68,9 +82,11 @@ class MailIntakeAdapter(ABC):
         Fetch a full raw thread by thread identifier.
 
         Args:
-            thread_id: Provider-specific thread identifier.
+            thread_id (str):
+                Provider-specific thread identifier.
 
         Returns:
-            Provider-native thread payload.
+            Dict[str, Any]:
+                Provider-native thread payload.
         """
         raise NotImplementedError