google styled doc

mail_intake/auth/base.py

@@ -1,6 +1,10 @@
 """
 Authentication provider contracts for Mail Intake.
 
+---
+
+## Summary
+
 This module defines the **authentication abstraction layer** used by mail
 adapters to obtain provider-specific credentials.
 
@@ -23,15 +27,18 @@ class MailIntakeAuthProvider(ABC, Generic[T]):
     providers and mail adapters by requiring providers to explicitly
     declare the type of credentials they return.
 
-    Authentication providers encapsulate all logic required to:
-    - Acquire credentials from an external provider
-    - Refresh or revalidate credentials as needed
-    - Handle authentication-specific failure modes
-    - Coordinate with credential persistence layers where applicable
+    Notes:
+        **Responsibilities:**
 
-    Mail adapters must treat returned credentials as opaque and
-    provider-specific, relying only on the declared credential type
-    expected by the adapter.
+            - Acquire credentials from an external provider
+            - Refresh or revalidate credentials as needed
+            - Handle authentication-specific failure modes
+            - Coordinate with credential persistence layers where applicable
+
+        **Constraints:**
+        
+            - Mail adapters must treat returned credentials as opaque and provider-specific
+            - Mail adapters rely only on the declared credential type expected by the adapter
     """
 
     @abstractmethod
@@ -39,21 +46,21 @@ class MailIntakeAuthProvider(ABC, Generic[T]):
         """
         Retrieve valid, provider-specific credentials.
 
-        This method is synchronous by design and represents the sole
-        entry point through which adapters obtain authentication
-        material.
-
-        Implementations must either return credentials of the declared
-        type ``T`` that are valid at the time of return or raise an
-        authentication-specific exception.
-
         Returns:
-            Credentials of type ``T`` suitable for immediate use by the
-            corresponding mail adapter.
+            T:
+                Credentials of type ``T`` suitable for immediate use by the
+                corresponding mail adapter.
 
         Raises:
             Exception:
                 An authentication-specific exception indicating that
                 credentials could not be obtained or validated.
+
+        Notes:
+            **Guarantees:**
+
+                - This method is synchronous by design
+                - Represents the sole entry point through which adapters obtain authentication material
+                - Implementations must either return credentials of the declared type ``T`` that are valid at the time of return or raise an exception
         """
         raise NotImplementedError