updated docs strings and added README.md

mail_intake/parsers/headers.py

@@ -1,10 +1,8 @@
 """
+# Summary
+
 Message header parsing utilities for Mail Intake.
 
----
-
-## Summary
-
 This module provides helper functions for normalizing and extracting
 useful information from provider-native message headers.
 
@@ -21,7 +19,7 @@ def parse_headers(raw_headers: List[Dict[str, str]]) -> Dict[str, str]:
 
     Args:
         raw_headers (List[Dict[str, str]]):
-            List of header dictionaries, each containing ``name`` and ``value`` keys.
+            List of header dictionaries, each containing `name` and `value` keys.
 
     Returns:
         Dict[str, str]:
@@ -30,23 +28,27 @@ def parse_headers(raw_headers: List[Dict[str, str]]) -> Dict[str, str]:
     Notes:
         **Guarantees:**
 
-            - Provider payloads (such as Gmail) typically represent headers as a list of name/value mappings
-            - This function normalizes them into a case-insensitive dictionary keyed by lowercase header names
+            - Provider payloads (such as Gmail) typically represent headers as a
+              list of name/value mappings.
+            - This function normalizes them into a case-insensitive dictionary
+              keyed by lowercase header names.
 
     Example:
         Typical usage:
-        
-            Input:
-                [
-                    {"name": "From", "value": "John Doe <john@example.com>"},
-                    {"name": "Subject", "value": "Re: Interview Update"},
-                ]
-    
-            Output:
-                {
-                    "from": "John Doe <john@example.com>",
-                    "subject": "Re: Interview Update",
-                }
+
+        ```python
+        Input:
+            [
+                {"name": "From", "value": "John Doe <john@example.com>"},
+                {"name": "Subject", "value": "Re: Interview Update"},
+            ]
+
+        Output:
+            {
+                "from": "John Doe <john@example.com>",
+                "subject": "Re: Interview Update",
+            }
+        ```
     """
     headers: Dict[str, str] = {}
 
@@ -68,22 +70,24 @@ def extract_sender(headers: Dict[str, str]) -> Tuple[str, Optional[str]]:
 
     Args:
         headers (Dict[str, str]):
-            Normalized header dictionary as returned by :func:`parse_headers`.
+            Normalized header dictionary as returned by `parse_headers()`.
 
     Returns:
         Tuple[str, Optional[str]]:
-            A tuple ``(email, name)`` where ``email`` is the sender email address and ``name`` is the display name, or ``None`` if unavailable.
+            A tuple `(email, name)` where `email` is the sender email address
+            and `name` is the display name, or `None` if unavailable.
 
     Notes:
         **Responsibilities:**
 
-            - This function parses the ``From`` header and attempts to extract sender email address and optional human-readable display name
+            - This function parses the `From` header and attempts to extract
+              sender email address and optional human-readable display name.
 
     Example:
         Typical values:
 
-            ``"John Doe <john@example.com>"`` -> ``("john@example.com", "John Doe")``
-            ``"john@example.com"`` -> ``("john@example.com", None)``
+        - `"John Doe <john@example.com>"` -> `("john@example.com", "John Doe")`
+        - `"john@example.com"` -> `("john@example.com", None)`
     """
     from_header = headers.get("from")
     if not from_header: