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

fix: GSDFC docstring conformance, modernize legacy typing to match signatures; regenerate lib/MCP docs (pydoclint zero)

Browse Source
This commit is contained in:
Vishesh 'ironeagle' Bangotra
2026-09-13 16:21:12 +05:30
parent af8bb5add8
commit b530276df2
49 changed files with 292 additions and 217 deletions
Download Patch File Download Diff File Expand all files Collapse all files

10
mail_intake/adapters/base.py
View File

@@ -41,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:
@@ -73,7 +77,7 @@ 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
@@ -88,7 +92,7 @@ class MailIntakeAdapter(ABC):
Provider-specific thread identifier.
Returns:
Dict[str, Any]:
dict[str, Any]:
Provider-native thread payload.
"""
raise NotImplementedError

10
mail_intake/adapters/gmail.py
View File

@@ -72,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.
@@ -99,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:
@@ -136,7 +132,7 @@ class MailIntakeGmailAdapter(MailIntakeAdapter):
Gmail message identifier.
Returns:
Dict[str, Any]:
dict[str, Any]:
Provider-native Gmail message payload.
Raises:
@@ -164,7 +160,7 @@ class MailIntakeGmailAdapter(MailIntakeAdapter):
Gmail thread identifier.
Returns:
Dict[str, Any]:
dict[str, Any]:
Provider-native Gmail thread payload.
Raises:

2
mail_intake/credentials/pickle.py
View File

@@ -60,7 +60,7 @@ class PickleCredentialStore(CredentialStore[T]):
Load credentials from the local filesystem.
Returns:
Optional[T]:
T | None:
An instance of type `T` if credentials are present and
successfully deserialized; otherwise `None`.

21
mail_intake/credentials/redis.py
View File

@@ -66,21 +66,10 @@ class RedisCredentialStore(CredentialStore[T]):
"""
Initialize a Redis-backed credential store.
Args:
redis_client (Any):
An initialized Redis client instance (for example, ``redis.Redis`` or a compatible interface) used to communicate with the Redis server.
key (str):
The Redis key under which credentials are stored. Callers are responsible for applying appropriate namespacing to avoid collisions.
serialize (Callable[[T], bytes]):
A callable that converts a credential object of type ``T`` into a ``bytes`` representation suitable for storage in Redis.
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[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.
Callers supply all runtime dependencies: ``redis_client`` is an
initialized Redis client instance, ``key`` names the storage key,
``serialize``/``deserialize`` are the encoding and decoding callables,
and ``ttl_seconds`` optionally limits credential lifetime.
"""
self.redis = redis_client
self.key = key
@@ -93,7 +82,7 @@ class RedisCredentialStore(CredentialStore[T]):
Load credentials from Redis.
Returns:
Optional[T]:
T | None:
An instance of type `T` if credentials are present and
successfully deserialized; otherwise `None`.

2
mail_intake/credentials/store.py
View File

@@ -52,7 +52,7 @@ class CredentialStore(ABC, Generic[T]):
Load previously persisted credentials.
Returns:
Optional[T]:
T | None:
An instance of type `T` if credentials are available and
loadable; otherwise `None`.

6
mail_intake/exceptions.py
View File

@@ -1,10 +1,8 @@
"""
# Summary
Exception hierarchy for Mail Intake.
---
## Summary
This module defines the **canonical exception types** used throughout the
Mail Intake library.

8
mail_intake/ingestion/reader.py
View File

@@ -88,9 +88,9 @@ class MailIntakeReader:
query (str):
Provider-specific query string used to filter messages.
Yields:
MailIntakeThread:
An iterator of `MailIntakeThread` instances.
Returns:
Iterator[MailIntakeThread]:
An iterator over `MailIntakeThread` instances.
Raises:
`MailIntakeParsingError`:
@@ -125,7 +125,7 @@ class MailIntakeReader:
Parse a raw provider message into a `MailIntakeMessage`.
Args:
raw_message (Dict[str, Any]):
raw_message (dict[str, Any]):
Provider-native message payload.
Returns:

6
mail_intake/parsers/body.py
View File

@@ -55,11 +55,11 @@ def _extract_from_part(part: dict[str, Any]) -> str | None:
- `text/html` (converted to plain text)
Args:
part (Dict[str, Any]):
part (dict[str, Any]):
MIME part dictionary from a provider payload.
Returns:
Optional[str]:
str | None:
Extracted plain-text content, or `None` if unsupported or empty.
"""
mime_type = part.get("mimeType")
@@ -94,7 +94,7 @@ def extract_body(payload: dict[str, Any]) -> str:
4. Empty string (if nothing usable found)
Args:
payload (Dict[str, Any]):
payload (dict[str, Any]):
Provider-native message payload dictionary.
Returns:

8
mail_intake/parsers/headers.py
View File

@@ -16,11 +16,11 @@ def parse_headers(raw_headers: list[dict[str, str]]) -> dict[str, str]:
Convert a list of Gmail-style headers into a normalized dict.
Args:
raw_headers (List[Dict[str, str]]):
raw_headers (list[dict[str, str]]):
List of header dictionaries, each containing `name` and `value` keys.
Returns:
Dict[str, str]:
dict[str, str]:
Dictionary mapping lowercase header names to stripped values.
Notes:
@@ -67,11 +67,11 @@ def extract_sender(headers: dict[str, str]) -> tuple[str, str | None]:
Extract sender email and optional display name from headers.
Args:
headers (Dict[str, str]):
headers (dict[str, str]):
Normalized header dictionary as returned by `parse_headers()`.
Returns:
Tuple[str, Optional[str]]:
tuple[str, str | None]:
A tuple `(email, name)` where `email` is the sender email address
and `name` is the display name, or `None` if unavailable.