updated docs strings and added README.md

mail_intake/credentials/pickle.py

@@ -1,18 +1,16 @@
 """
+# Summary
+
 Local filesystem–based credential persistence for Mail Intake.
 
----
-
-## Summary
-
 This module provides a file-backed implementation of the
-``CredentialStore`` abstraction using Python's ``pickle`` module.
+`CredentialStore` abstraction using Python's `pickle` module.
 
-The pickle-based credential store is intended for local development,
+The `pickle`-based credential store is intended for local development,
 single-node deployments, and controlled environments where credentials
 do not need to be shared across processes or machines.
 
-Due to the security and portability risks associated with pickle-based
+Due to the security and portability risks associated with `pickle`-based
 serialization, this implementation is not suitable for distributed or
 untrusted environments.
 """
@@ -36,13 +34,14 @@ class PickleCredentialStore(CredentialStore[T]):
     Notes:
         **Guarantees:**
 
-            - Stores credentials on the local filesystem
-            - Uses pickle for serialization and deserialization
-            - Does not provide encryption, locking, or concurrency guarantees
+            - Stores credentials on the local filesystem.
+            - Uses `pickle` for serialization and deserialization.
+            - Does not provide encryption, locking, or concurrency guarantees.
 
         **Constraints:**
-        
-            - Credential lifecycle management, validation, and refresh logic are explicitly out of scope for this class
+
+            - Credential lifecycle management, validation, and refresh logic are
+              explicitly out of scope for this class.
     """
 
     def __init__(self, path: str):
@@ -62,14 +61,16 @@ class PickleCredentialStore(CredentialStore[T]):
 
         Returns:
             Optional[T]:
-                An instance of type ``T`` if credentials are present and
-                successfully deserialized; otherwise ``None``.
+                An instance of type `T` if credentials are present and
+                successfully deserialized; otherwise `None`.
 
         Notes:
             **Guarantees:**
 
-                - If the credential file does not exist or cannot be successfully deserialized, this method returns ``None``
-                - The store does not attempt to validate or interpret the returned credentials
+                - If the credential file does not exist or cannot be successfully
+                  deserialized, this method returns `None`.
+                - The store does not attempt to validate or interpret the
+                  returned credentials.
         """
         try:
             with open(self.path, "rb") as fh: