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

updated docs strings and added README.md

Browse Source
This commit is contained in:
Vishesh 'ironeagle' Bangotra
2026-03-08 17:59:53 +05:30
parent 0453fdd88a
commit c541577788
46 changed files with 863 additions and 681 deletions
Download Patch File Download Diff File Expand all files Collapse all files

24
mail_intake/auth/__init__.py
View File

@@ -1,31 +1,31 @@
"""
# Summary
Authentication provider implementations for Mail Intake.
---
## Summary
This package defines the **authentication layer** used by mail adapters
to obtain provider-specific credentials.
It exposes:
- A stable, provider-agnostic authentication contract
- Concrete authentication providers for supported platforms
- A stable, provider-agnostic authentication contract.
- Concrete authentication providers for supported platforms.
Authentication providers:
- Are responsible for credential acquisition and lifecycle management
- Are intentionally decoupled from adapter logic
- May be extended by users to support additional providers
- Are responsible for credential acquisition and lifecycle management.
- Are intentionally decoupled from adapter logic.
- May be extended by users to support additional providers.
Consumers should depend on the abstract interface and use concrete
implementations only where explicitly required.
---
## Public API
# Public API
MailIntakeAuthProvider
MailIntakeGoogleAuth
- `MailIntakeAuthProvider`
- `MailIntakeGoogleAuth`
---
"""

32
mail_intake/auth/base.py
View File

@@ -1,10 +1,8 @@
"""
# Summary
Authentication provider contracts for Mail Intake.
---
## Summary
This module defines the **authentication abstraction layer** used by mail
adapters to obtain provider-specific credentials.
@@ -30,15 +28,17 @@ class MailIntakeAuthProvider(ABC, Generic[T]):
Notes:
**Responsibilities:**
- Acquire credentials from an external provider
- Refresh or revalidate credentials as needed
- Handle authentication-specific failure modes
- Coordinate with credential persistence layers where applicable
- 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
- 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
@@ -48,7 +48,7 @@ class MailIntakeAuthProvider(ABC, Generic[T]):
Returns:
T:
Credentials of type ``T`` suitable for immediate use by the
Credentials of type `T` suitable for immediate use by the
corresponding mail adapter.
Raises:
@@ -59,8 +59,10 @@ class MailIntakeAuthProvider(ABC, Generic[T]):
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
- 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

36
mail_intake/auth/google.py
View File

@@ -1,18 +1,17 @@
"""
# Summary
Google authentication provider implementation for Mail Intake.
---
## Summary
This module provides a **Google OAuth–based authentication provider**
used primarily for Gmail access.
It encapsulates all Google-specific authentication concerns, including:
- Credential loading and persistence
- Token refresh handling
- Interactive OAuth flow initiation
- Coordination with a credential persistence layer
- Credential loading and persistence.
- Token refresh handling.
- Interactive OAuth flow initiation.
- Coordination with a credential persistence layer.
No Google authentication details should leak outside this module.
"""
@@ -40,14 +39,15 @@ class MailIntakeGoogleAuth(MailIntakeAuthProvider):
Notes:
**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
- 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
- This class is synchronous by design and maintains a minimal
internal state.
"""
def __init__(
@@ -79,7 +79,7 @@ class MailIntakeGoogleAuth(MailIntakeAuthProvider):
Returns:
Credentials:
A ``google.oauth2.credentials.Credentials`` instance suitable
A `google.oauth2.credentials.Credentials` instance suitable
for use with Google API clients.
Raises:
@@ -90,10 +90,10 @@ class MailIntakeGoogleAuth(MailIntakeAuthProvider):
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
- 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()