standardize packaging, tooling, docs, CI, and licensing

mail_intake/adapters/base.py

@@ -12,7 +12,8 @@ types or semantics should leak beyond implementations of this interface.
 """
 
 from abc import ABC, abstractmethod
-from typing import Iterator, Dict, Any
+from collections.abc import Iterator
+from typing import Any
 
 
 class MailIntakeAdapter(ABC):
@@ -32,7 +33,7 @@ class MailIntakeAdapter(ABC):
     """
 
     @abstractmethod
-    def iter_message_refs(self, query: str) -> Iterator[Dict[str, str]]:
+    def iter_message_refs(self, query: str) -> Iterator[dict[str, str]]:
         """
         Iterate over lightweight message references matching a query.
 
@@ -63,7 +64,7 @@ class MailIntakeAdapter(ABC):
         raise NotImplementedError
 
     @abstractmethod
-    def fetch_message(self, message_id: str) -> Dict[str, Any]:
+    def fetch_message(self, message_id: str) -> dict[str, Any]:
         """
         Fetch a full raw message by message identifier.
 
@@ -78,7 +79,7 @@ class MailIntakeAdapter(ABC):
         raise NotImplementedError
 
     @abstractmethod
-    def fetch_thread(self, thread_id: str) -> Dict[str, Any]:
+    def fetch_thread(self, thread_id: str) -> dict[str, Any]:
         """
         Fetch a full raw thread by thread identifier.
 

mail_intake/adapters/base.pyi

@@ -1,10 +1,11 @@
 from abc import ABC, abstractmethod
-from typing import Iterator, Dict, Any
+from collections.abc import Iterator
+from typing import Any
 
 class MailIntakeAdapter(ABC):
     @abstractmethod
-    def iter_message_refs(self, query: str) -> Iterator[Dict[str, str]]: ...
+    def iter_message_refs(self, query: str) -> Iterator[dict[str, str]]: ...
     @abstractmethod
-    def fetch_message(self, message_id: str) -> Dict[str, Any]: ...
+    def fetch_message(self, message_id: str) -> dict[str, Any]: ...
     @abstractmethod
-    def fetch_thread(self, thread_id: str) -> Dict[str, Any]: ...
+    def fetch_thread(self, thread_id: str) -> dict[str, Any]: ...

mail_intake/adapters/gmail.py

@@ -15,14 +15,15 @@ It is the only place in the codebase where:
 All Gmail-specific behavior must be strictly contained within this module.
 """
 
-from typing import Iterator, Dict, Any
+from collections.abc import Iterator
+from typing import Any
 
 from googleapiclient.discovery import build
 from googleapiclient.errors import HttpError
 
 from mail_intake.adapters.base import MailIntakeAdapter
-from mail_intake.exceptions import MailIntakeAdapterError
 from mail_intake.auth.base import MailIntakeAuthProvider
+from mail_intake.exceptions import MailIntakeAdapterError
 
 
 class MailIntakeGmailAdapter(MailIntakeAdapter):
@@ -89,7 +90,7 @@ class MailIntakeGmailAdapter(MailIntakeAdapter):
                 ) from exc
         return self._service
 
-    def iter_message_refs(self, query: str) -> Iterator[Dict[str, str]]:
+    def iter_message_refs(self, query: str) -> Iterator[dict[str, str]]:
         """
         Iterate over message references matching the query.
 
@@ -107,9 +108,7 @@ class MailIntakeGmailAdapter(MailIntakeAdapter):
         """
         try:
             request = (
-                self.service.users()
-                .messages()
-                .list(userId=self._user_id, q=query)
+                self.service.users().messages().list(userId=self._user_id, q=query)
             )
 
             while request is not None:
@@ -121,18 +120,14 @@ class MailIntakeGmailAdapter(MailIntakeAdapter):
                         "thread_id": msg["threadId"],
                     }
 
-                request = (
-                    self.service.users()
-                    .messages()
-                    .list_next(request, response)
-                )
+                request = self.service.users().messages().list_next(request, response)
 
         except HttpError as exc:
             raise MailIntakeAdapterError(
                 "Gmail API error while listing messages"
             ) from exc
 
-    def fetch_message(self, message_id: str) -> Dict[str, Any]:
+    def fetch_message(self, message_id: str) -> dict[str, Any]:
         """
         Fetch a full Gmail message by message ID.
 
@@ -160,7 +155,7 @@ class MailIntakeGmailAdapter(MailIntakeAdapter):
                 f"Gmail API error while fetching message {message_id}"
             ) from exc
 
-    def fetch_thread(self, thread_id: str) -> Dict[str, Any]:
+    def fetch_thread(self, thread_id: str) -> dict[str, Any]:
         """
         Fetch a full Gmail thread by thread ID.
 

mail_intake/adapters/gmail.pyi

@@ -1,11 +1,15 @@
-from typing import Iterator, Dict, Any
+from collections.abc import Iterator
+from typing import Any
+
 from mail_intake.adapters.base import MailIntakeAdapter
 from mail_intake.auth.base import MailIntakeAuthProvider
 
 class MailIntakeGmailAdapter(MailIntakeAdapter):
-    def __init__(self, auth_provider: MailIntakeAuthProvider, user_id: str = ...) -> None: ...
+    def __init__(
+        self, auth_provider: MailIntakeAuthProvider[Any], user_id: str = ...
+    ) -> None: ...
     @property
     def service(self) -> Any: ...
-    def iter_message_refs(self, query: str) -> Iterator[Dict[str, str]]: ...
-    def fetch_message(self, message_id: str) -> Dict[str, Any]: ...
-    def fetch_thread(self, thread_id: str) -> Dict[str, Any]: ...
+    def iter_message_refs(self, query: str) -> Iterator[dict[str, str]]: ...
+    def fetch_message(self, message_id: str) -> dict[str, Any]: ...
+    def fetch_thread(self, thread_id: str) -> dict[str, Any]: ...