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

google styled doc

Browse Source
This commit is contained in:
Vishesh 'ironeagle' Bangotra
2026-03-08 00:29:24 +05:30
parent 9f37af5761
commit 9f9e472ada
21 changed files with 593 additions and 358 deletions
Download Patch File Download Diff File Expand all files Collapse all files

13
mail_intake/auth/__init__.py
View File

@@ -1,6 +1,10 @@
"""
Authentication provider implementations for Mail Intake.
---
## Summary
This package defines the **authentication layer** used by mail adapters
to obtain provider-specific credentials.
@@ -15,6 +19,15 @@ Authentication providers:
Consumers should depend on the abstract interface and use concrete
implementations only where explicitly required.
---
## Public API
MailIntakeAuthProvider
MailIntakeGoogleAuth
---
"""
from .base import MailIntakeAuthProvider

43
mail_intake/auth/base.py
View File

@@ -1,6 +1,10 @@
"""
Authentication provider contracts for Mail Intake.
---
## Summary
This module defines the **authentication abstraction layer** used by mail
adapters to obtain provider-specific credentials.
@@ -23,15 +27,18 @@ class MailIntakeAuthProvider(ABC, Generic[T]):
providers and mail adapters by requiring providers to explicitly
declare the type of credentials they return.
Authentication providers encapsulate all logic required to:
- Acquire credentials from an external provider
- Refresh or revalidate credentials as needed
- Handle authentication-specific failure modes
- Coordinate with credential persistence layers where applicable
Notes:
**Responsibilities:**
Mail adapters must treat returned credentials as opaque and
provider-specific, relying only on the declared credential type
expected by the adapter.
- Acquire credentials from an external provider
- Refresh or revalidate credentials as needed
- Handle authentication-specific failure modes
- Coordinate with credential persistence layers where applicable
**Constraints:**
- Mail adapters must treat returned credentials as opaque and provider-specific
- Mail adapters rely only on the declared credential type expected by the adapter
"""
@abstractmethod
@@ -39,21 +46,21 @@ class MailIntakeAuthProvider(ABC, Generic[T]):
"""
Retrieve valid, provider-specific credentials.
This method is synchronous by design and represents the sole
entry point through which adapters obtain authentication
material.
Implementations must either return credentials of the declared
type ``T`` that are valid at the time of return or raise an
authentication-specific exception.
Returns:
Credentials of type ``T`` suitable for immediate use by the
corresponding mail adapter.
T:
Credentials of type ``T`` suitable for immediate use by the
corresponding mail adapter.
Raises:
Exception:
An authentication-specific exception indicating that
credentials could not be obtained or validated.
Notes:
**Guarantees:**
- This method is synchronous by design
- Represents the sole entry point through which adapters obtain authentication material
- Implementations must either return credentials of the declared type ``T`` that are valid at the time of return or raise an exception
"""
raise NotImplementedError

54
mail_intake/auth/google.py
View File

@@ -1,6 +1,10 @@
"""
Google authentication provider implementation for Mail Intake.
---
## Summary
This module provides a **Google OAuth–based authentication provider**
used primarily for Gmail access.
@@ -33,13 +37,17 @@ class MailIntakeGoogleAuth(MailIntakeAuthProvider):
This provider implements the `MailIntakeAuthProvider` interface using
Google's OAuth 2.0 flow and credential management libraries.
Responsibilities:
- Load cached credentials from a credential store when available
- Refresh expired credentials when possible
- Initiate an interactive OAuth flow only when required
- Persist refreshed or newly obtained credentials via the store
Notes:
**Responsibilities:**
This class is synchronous by design and maintains a minimal internal state.
- Load cached credentials from a credential store when available
- Refresh expired credentials when possible
- Initiate an interactive OAuth flow only when required
- Persist refreshed or newly obtained credentials via the store
**Guarantees:**
- This class is synchronous by design and maintains a minimal internal state
"""
def __init__(
@@ -52,15 +60,13 @@ class MailIntakeGoogleAuth(MailIntakeAuthProvider):
Initialize the Google authentication provider.
Args:
credentials_path:
Path to the Google OAuth client secrets file used to
initiate the OAuth 2.0 flow.
credentials_path (str):
Path to the Google OAuth client secrets file used to initiate the OAuth 2.0 flow.
store:
Credential store responsible for persisting and
retrieving Google OAuth credentials.
store (CredentialStore[Credentials]):
Credential store responsible for persisting and retrieving Google OAuth credentials.
scopes:
scopes (Sequence[str]):
OAuth scopes required for Gmail access.
"""
self.credentials_path = credentials_path
@@ -71,19 +77,23 @@ class MailIntakeGoogleAuth(MailIntakeAuthProvider):
"""
Retrieve valid Google OAuth credentials.
This method attempts to:
1. Load cached credentials from the configured credential store
2. Refresh expired credentials when possible
3. Perform an interactive OAuth login as a fallback
4. Persist valid credentials for future use
Returns:
A ``google.oauth2.credentials.Credentials`` instance suitable
for use with Google API clients.
Credentials:
A ``google.oauth2.credentials.Credentials`` instance suitable
for use with Google API clients.
Raises:
MailIntakeAuthError: If credentials cannot be loaded, refreshed,
MailIntakeAuthError:
If credentials cannot be loaded, refreshed,
or obtained via interactive authentication.
Notes:
**Lifecycle:**
- Load cached credentials from the configured credential store
- Refresh expired credentials when possible
- Perform an interactive OAuth login as a fallback
- Persist valid credentials for future use
"""
creds = self.store.load()