aetos/mail-intake
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

chore(release): 0.0.3

Browse Source 
Squash-merge lib-standardisation: adopt repo standards across packaging,
tooling, docs, and CI.

- standardize pyproject.toml (canonical packaging, lint config, extras, GSDFC pydoclint)
- add py.typed marker, modernize type hints and Google-style docstrings
- nest generated docs under docs/lib and docs/mcp; add hand-written wiki
- adopt standard Type A PyPI CI pipeline (tag==version guard + quality gate)
- promote generated CHANGELOG.md; bump version to 0.0.3
This commit is contained in:
Vishesh 'ironeagle' Bangotra
2026-10-17 02:16:46 +05:30
parent c541577788
commit 371b74806f
96 changed files with 1756 additions and 2200 deletions
Download Patch File Download Diff File Expand all files Collapse all files

19
mail_intake/adapters/base.py
View File

@@ -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.
@@ -40,8 +41,12 @@ class MailIntakeAdapter(ABC):
query (str):
Provider-specific query string used to filter messages.
Returns:
Iterator[dict[str, str]]:
An iterator over lightweight message reference dictionaries.
Yields:
Dict[str, str]:
dict[str, str]:
Dictionaries containing message and thread identifiers.
Notes:
@@ -63,7 +68,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.
@@ -72,13 +77,13 @@ class MailIntakeAdapter(ABC):
Provider-specific message identifier.
Returns:
Dict[str, Any]:
dict[str, Any]:
Provider-native message payload (e.g., Gmail message JSON structure).
"""
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.
@@ -87,7 +92,7 @@ class MailIntakeAdapter(ABC):
Provider-specific thread identifier.
Returns:
Dict[str, Any]:
dict[str, Any]:
Provider-native thread payload.
"""
raise NotImplementedError

9
mail_intake/adapters/base.pyi
View File

@@ -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]: ...

31
mail_intake/adapters/gmail.py
View File

@@ -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):
@@ -71,10 +72,6 @@ class MailIntakeGmailAdapter(MailIntakeAdapter):
"""
Lazily initialize and return the Gmail API service client.
Returns:
Any:
Initialized Gmail API service instance.
Raises:
MailIntakeAdapterError:
If the Gmail service cannot be initialized.
@@ -89,7 +86,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.
@@ -98,7 +95,7 @@ class MailIntakeGmailAdapter(MailIntakeAdapter):
Gmail search query string.
Yields:
Dict[str, str]:
dict[str, str]:
Dictionaries containing ``message_id`` and ``thread_id``.
Raises:
@@ -107,9 +104,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 +116,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.
@@ -141,7 +132,7 @@ class MailIntakeGmailAdapter(MailIntakeAdapter):
Gmail message identifier.
Returns:
Dict[str, Any]:
dict[str, Any]:
Provider-native Gmail message payload.
Raises:
@@ -160,7 +151,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.
@@ -169,7 +160,7 @@ class MailIntakeGmailAdapter(MailIntakeAdapter):
Gmail thread identifier.
Returns:
Dict[str, Any]:
dict[str, Any]:
Provider-native Gmail thread payload.
Raises:

14
mail_intake/adapters/gmail.pyi
View File

@@ -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]: ...