google styled doc

mail_intake/credentials/redis.py

@@ -1,6 +1,10 @@
 """
 Redis-backed credential persistence for Mail Intake.
 
+---
+
+## Summary
+
 This module provides a Redis-based implementation of the
 ``CredentialStore`` abstraction, enabling credential persistence
 across distributed and horizontally scaled deployments.
@@ -37,14 +41,16 @@ class RedisCredentialStore(CredentialStore[T]):
     distributed and horizontally scaled deployments where credentials
     must be shared across multiple processes or nodes.
 
-    The store is intentionally generic and delegates all serialization
-    concerns to caller-provided functions. This avoids unsafe mechanisms
-    such as pickle and allows credential formats to be explicitly
-    controlled and audited.
+    Notes:
+        **Responsibilities:**
 
-    This class is responsible only for persistence and retrieval.
-    It does not interpret, validate, refresh, or otherwise manage
-    the lifecycle of the credentials being stored.
+            - This class is responsible only for persistence and retrieval
+            - It does not interpret, validate, refresh, or otherwise manage the lifecycle of the credentials being stored
+
+        **Guarantees:**
+
+            - The store is intentionally generic and delegates all serialization concerns to caller-provided functions
+            - This avoids unsafe mechanisms such as pickle and allows credential formats to be explicitly controlled and audited
     """
 
     def __init__(
@@ -59,31 +65,20 @@ class RedisCredentialStore(CredentialStore[T]):
         Initialize a Redis-backed credential store.
 
         Args:
-            redis_client:
-                An initialized Redis client instance (for example,
-                ``redis.Redis`` or a compatible interface) used to
-                communicate with the Redis server.
+            redis_client (Any):
+                An initialized Redis client instance (for example, ``redis.Redis`` or a compatible interface) used to communicate with the Redis server.
 
-            key:
-                The Redis key under which credentials are stored.
-                Callers are responsible for applying appropriate
-                namespacing to avoid collisions.
+            key (str):
+                The Redis key under which credentials are stored. Callers are responsible for applying appropriate namespacing to avoid collisions.
 
-            serialize:
-                A callable that converts a credential object of type
-                ``T`` into a ``bytes`` representation suitable for
-                storage in Redis.
+            serialize (Callable[[T], bytes]):
+                A callable that converts a credential object of type ``T`` into a ``bytes`` representation suitable for storage in Redis.
 
-            deserialize:
-                A callable that converts a ``bytes`` payload retrieved
-                from Redis back into a credential object of type ``T``.
+            deserialize (Callable[[bytes], T]):
+                A callable that converts a ``bytes`` payload retrieved from Redis back into a credential object of type ``T``.
 
-            ttl_seconds:
-                Optional time-to-live (TTL) for the stored credentials,
-                expressed in seconds. When provided, Redis will
-                automatically expire the stored credentials after the
-                specified duration. If ``None``, credentials are stored
-                without an expiration.
+            ttl_seconds (Optional[int]):
+                Optional time-to-live (TTL) for the stored credentials, expressed in seconds. When provided, Redis will automatically expire the stored credentials after the specified duration. If ``None``, credentials are stored without an expiration.
         """
         self.redis = redis_client
         self.key = key
@@ -95,16 +90,16 @@ class RedisCredentialStore(CredentialStore[T]):
         """
         Load credentials from Redis.
 
-        If no value exists for the configured key, or if the stored
-        payload cannot be successfully deserialized, this method
-        returns ``None``.
-
-        The store does not attempt to validate the returned credentials
-        or determine whether they are expired or otherwise usable.
-
         Returns:
-            An instance of type ``T`` if credentials are present and
-            successfully deserialized; otherwise ``None``.
+            Optional[T]:
+                An instance of type ``T`` if credentials are present and
+                successfully deserialized; otherwise ``None``.
+
+        Notes:
+            **Guarantees:**
+
+                - If no value exists for the configured key, or if the stored payload cannot be successfully deserialized, this method returns ``None``
+                - The store does not attempt to validate the returned credentials or determine whether they are expired or otherwise usable
         """
         raw = self.redis.get(self.key)
         if not raw:
@@ -118,13 +113,15 @@ class RedisCredentialStore(CredentialStore[T]):
         """
         Persist credentials to Redis.
 
-        Any previously stored credentials under the same key are
-        overwritten. If a TTL is configured, the credentials will
-        expire automatically after the specified duration.
-
         Args:
-            credentials:
+            credentials (T):
                 The credential object to persist.
+
+        Notes:
+            **Responsibilities:**
+
+                - Any previously stored credentials under the same key are overwritten
+                - If a TTL is configured, the credentials will expire automatically after the specified duration
         """
         payload = self.serialize(credentials)
         if self.ttl_seconds:
@@ -136,7 +133,10 @@ class RedisCredentialStore(CredentialStore[T]):
         """
         Remove stored credentials from Redis.
 
-        This operation deletes the configured Redis key if it exists.
-        Implementations should treat this method as idempotent.
+        Notes:
+            **Lifecycle:**
+
+                - This operation deletes the configured Redis key if it exists
+                - Implementations should treat this method as idempotent
         """
         self.redis.delete(self.key)