google styled doc

mail_intake/adapters/__init__.py

@@ -1,6 +1,10 @@
 """
 Mail provider adapter implementations for Mail Intake.
 
+---
+
+## Summary
+
 This package contains **adapter-layer implementations** responsible for
 interfacing with external mail providers and exposing a normalized,
 provider-agnostic contract to the rest of the system.
@@ -15,8 +19,14 @@ Provider-specific logic **must not leak** outside of adapter implementations.
 All parsings, normalizations, and transformations must be handled by downstream
 components.
 
-Public adapters exported from this package are considered the supported
-integration surface for mail providers.
+---
+
+## Public API
+
+    MailIntakeAdapter
+    MailIntakeGmailAdapter
+
+---
 """
 
 from .base import MailIntakeAdapter

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

mail_intake/adapters/gmail.py

@@ -1,6 +1,10 @@
 """
 Gmail adapter implementation for Mail Intake.
 
+---
+
+## Summary
+
 This module provides a **Gmail-specific implementation** of the
 `MailIntakeAdapter` contract.
 
@@ -30,15 +34,18 @@ class MailIntakeGmailAdapter(MailIntakeAdapter):
     Gmail REST API. It translates the generic mail intake contract into
     Gmail-specific API calls.
 
-    This class is the ONLY place where:
-    - googleapiclient is imported
-    - Gmail REST semantics are known
-    - .execute() is called
+    Notes:
+        **Responsibilities:**
 
-    Design constraints:
-    - Must remain thin and imperative
-    - Must not perform parsing or interpretation
-    - Must not expose Gmail-specific types beyond this class
+            - This class is the ONLY place where googleapiclient is imported
+            - Gmail REST semantics are known
+            - .execute() is called
+
+        **Constraints:**
+        
+            - Must remain thin and imperative
+            - Must not perform parsing or interpretation
+            - Must not expose Gmail-specific types beyond this class
     """
 
     def __init__(
@@ -50,9 +57,11 @@ class MailIntakeGmailAdapter(MailIntakeAdapter):
         Initialize the Gmail adapter.
 
         Args:
-            auth_provider: Authentication provider capable of supplying
-                valid Gmail API credentials.
-            user_id: Gmail user identifier. Defaults to `"me"`.
+            auth_provider (MailIntakeAuthProvider):
+                Authentication provider capable of supplying valid Gmail API credentials.
+
+            user_id (str):
+                Gmail user identifier. Defaults to `"me"`.
         """
         self._auth_provider = auth_provider
         self._user_id = user_id
@@ -64,10 +73,12 @@ class MailIntakeGmailAdapter(MailIntakeAdapter):
         Lazily initialize and return the Gmail API service client.
 
         Returns:
-            Initialized Gmail API service instance.
+            Any:
+                Initialized Gmail API service instance.
 
         Raises:
-            MailIntakeAdapterError: If the Gmail service cannot be initialized.
+            MailIntakeAdapterError:
+                If the Gmail service cannot be initialized.
         """
         if self._service is None:
             try:
@@ -84,15 +95,16 @@ class MailIntakeGmailAdapter(MailIntakeAdapter):
         Iterate over message references matching the query.
 
         Args:
-            query: Gmail search query string.
+            query (str):
+                Gmail search query string.
 
         Yields:
-            Dictionaries containing:
-            - ``message_id``: Gmail message ID
-            - ``thread_id``: Gmail thread ID
+            Dict[str, str]:
+                Dictionaries containing ``message_id`` and ``thread_id``.
 
         Raises:
-            MailIntakeAdapterError: If the Gmail API returns an error.
+            MailIntakeAdapterError:
+                If the Gmail API returns an error.
         """
         try:
             request = (
@@ -126,13 +138,16 @@ class MailIntakeGmailAdapter(MailIntakeAdapter):
         Fetch a full Gmail message by message ID.
 
         Args:
-            message_id: Gmail message identifier.
+            message_id (str):
+                Gmail message identifier.
 
         Returns:
-            Provider-native Gmail message payload.
+            Dict[str, Any]:
+                Provider-native Gmail message payload.
 
         Raises:
-            MailIntakeAdapterError: If the Gmail API returns an error.
+            MailIntakeAdapterError:
+                If the Gmail API returns an error.
         """
         try:
             return (
@@ -151,13 +166,16 @@ class MailIntakeGmailAdapter(MailIntakeAdapter):
         Fetch a full Gmail thread by thread ID.
 
         Args:
-            thread_id: Gmail thread identifier.
+            thread_id (str):
+                Gmail thread identifier.
 
         Returns:
-            Provider-native Gmail thread payload.
+            Dict[str, Any]:
+                Provider-native Gmail thread payload.
 
         Raises:
-            MailIntakeAdapterError: If the Gmail API returns an error.
+            MailIntakeAdapterError:
+                If the Gmail API returns an error.
         """
         try:
             return (