google styled doc

mail_intake/auth/google.py

@@ -1,6 +1,10 @@
 """
 Google authentication provider implementation for Mail Intake.
 
+---
+
+## Summary
+
 This module provides a **Google OAuth–based authentication provider**
 used primarily for Gmail access.
 
@@ -33,13 +37,17 @@ class MailIntakeGoogleAuth(MailIntakeAuthProvider):
     This provider implements the `MailIntakeAuthProvider` interface using
     Google's OAuth 2.0 flow and credential management libraries.
 
-    Responsibilities:
-    - Load cached credentials from a credential store when available
-    - Refresh expired credentials when possible
-    - Initiate an interactive OAuth flow only when required
-    - Persist refreshed or newly obtained credentials via the store
+    Notes:
+        **Responsibilities:**
 
-    This class is synchronous by design and maintains a minimal internal state.
+            - Load cached credentials from a credential store when available
+            - Refresh expired credentials when possible
+            - Initiate an interactive OAuth flow only when required
+            - Persist refreshed or newly obtained credentials via the store
+
+        **Guarantees:**
+
+            - This class is synchronous by design and maintains a minimal internal state
     """
 
     def __init__(
@@ -52,15 +60,13 @@ class MailIntakeGoogleAuth(MailIntakeAuthProvider):
         Initialize the Google authentication provider.
 
         Args:
-            credentials_path:
-                Path to the Google OAuth client secrets file used to
-                initiate the OAuth 2.0 flow.
+            credentials_path (str):
+                Path to the Google OAuth client secrets file used to initiate the OAuth 2.0 flow.
 
-            store:
-                Credential store responsible for persisting and
-                retrieving Google OAuth credentials.
+            store (CredentialStore[Credentials]):
+                Credential store responsible for persisting and retrieving Google OAuth credentials.
 
-            scopes:
+            scopes (Sequence[str]):
                 OAuth scopes required for Gmail access.
         """
         self.credentials_path = credentials_path
@@ -71,19 +77,23 @@ class MailIntakeGoogleAuth(MailIntakeAuthProvider):
         """
         Retrieve valid Google OAuth credentials.
 
-        This method attempts to:
-        1. Load cached credentials from the configured credential store
-        2. Refresh expired credentials when possible
-        3. Perform an interactive OAuth login as a fallback
-        4. Persist valid credentials for future use
-
         Returns:
-            A ``google.oauth2.credentials.Credentials`` instance suitable
-            for use with Google API clients.
+            Credentials:
+                A ``google.oauth2.credentials.Credentials`` instance suitable
+                for use with Google API clients.
 
         Raises:
-            MailIntakeAuthError: If credentials cannot be loaded, refreshed,
+            MailIntakeAuthError:
+                If credentials cannot be loaded, refreshed,
                 or obtained via interactive authentication.
+
+        Notes:
+            **Lifecycle:**
+
+                - Load cached credentials from the configured credential store
+                - Refresh expired credentials when possible
+                - Perform an interactive OAuth login as a fallback
+                - Persist valid credentials for future use
         """
         creds = self.store.load()