Vishesh 'ironeagle' Bangotra
f22af90e98
- docs(mail_intake/__init__.py): document module-based public API and usage patterns - docs(mail_intake/ingestion/reader.py): document high-level ingestion orchestration - docs(mail_intake/adapters/base.py): document adapter contract for mail providers - docs(mail_intake/adapters/gmail.py): document Gmail adapter implementation and constraints - docs(mail_intake/auth/base.py): document authentication provider contract - docs(mail_intake/auth/google.py): document Google OAuth authentication provider - docs(mail_intake/models/message.py): document canonical email message model - docs(mail_intake/models/thread.py): document canonical email thread model - docs(mail_intake/parsers/body.py): document message body extraction logic - docs(mail_intake/parsers/headers.py): document message header normalization utilities - docs(mail_intake/parsers/subject.py): document subject normalization utilities - docs(mail_intake/config.py): document global configuration model - docs(mail_intake/exceptions.py): document library exception hierarchy
127 lines
3.9 KiB
Python
127 lines
3.9 KiB
Python
"""
|
|
Mail Intake — provider-agnostic, read-only email ingestion framework.
|
|
|
|
Mail Intake is a **contract-first library** designed to ingest, parse, and
|
|
normalize email data from external providers (such as Gmail) into clean,
|
|
provider-agnostic domain models.
|
|
|
|
The library is intentionally structured around clear layers, each exposed
|
|
as a first-class module at the package root:
|
|
|
|
- adapters: provider-specific access (e.g. Gmail)
|
|
- auth: authentication providers and credential management
|
|
- parsers: extraction and normalization of message content
|
|
- ingestion: orchestration and high-level ingestion workflows
|
|
- models: canonical, provider-agnostic data representations
|
|
- config: explicit global configuration
|
|
- exceptions: library-defined error hierarchy
|
|
|
|
The package root acts as a **namespace**, not a facade. Consumers are
|
|
expected to import functionality explicitly from the appropriate module.
|
|
|
|
----------------------------------------------------------------------
|
|
Installation
|
|
----------------------------------------------------------------------
|
|
|
|
Install using pip:
|
|
|
|
pip install mail-intake
|
|
|
|
Or with Poetry:
|
|
|
|
poetry add mail-intake
|
|
|
|
Mail Intake is pure Python and has no runtime dependencies beyond those
|
|
required by the selected provider (for example, Google APIs for Gmail).
|
|
|
|
----------------------------------------------------------------------
|
|
Basic Usage
|
|
----------------------------------------------------------------------
|
|
|
|
Minimal Gmail ingestion example:
|
|
|
|
from mail_intake.ingestion import MailIntakeReader
|
|
from mail_intake.adapters import MailIntakeGmailAdapter
|
|
from mail_intake.auth import MailIntakeGoogleAuth
|
|
|
|
auth = MailIntakeGoogleAuth(
|
|
credentials_path="credentials.json",
|
|
token_path="token.pickle",
|
|
scopes=["https://www.googleapis.com/auth/gmail.readonly"],
|
|
)
|
|
|
|
adapter = MailIntakeGmailAdapter(auth_provider=auth)
|
|
reader = MailIntakeReader(adapter)
|
|
|
|
for message in reader.iter_messages("from:recruiter@example.com"):
|
|
print(message.subject, message.from_email)
|
|
|
|
Iterating over threads:
|
|
|
|
for thread in reader.iter_threads("subject:Interview"):
|
|
print(thread.normalized_subject, len(thread.messages))
|
|
|
|
----------------------------------------------------------------------
|
|
Extensibility Model
|
|
----------------------------------------------------------------------
|
|
|
|
Mail Intake is designed to be extensible via **public contracts** exposed
|
|
through its modules:
|
|
|
|
- Users MAY implement their own mail adapters by subclassing
|
|
`adapters.MailIntakeAdapter`
|
|
- Users MAY implement their own authentication providers by subclassing
|
|
`auth.MailIntakeAuthProvider`
|
|
|
|
Users SHOULD NOT subclass built-in adapter implementations. Built-in
|
|
adapters (such as Gmail) are reference implementations and may change
|
|
internally without notice.
|
|
|
|
----------------------------------------------------------------------
|
|
Public API Surface
|
|
----------------------------------------------------------------------
|
|
|
|
The supported public API consists of the following top-level modules:
|
|
|
|
- mail_intake.ingestion
|
|
- mail_intake.adapters
|
|
- mail_intake.auth
|
|
- mail_intake.parsers
|
|
- mail_intake.models
|
|
- mail_intake.config
|
|
- mail_intake.exceptions
|
|
|
|
Classes and functions should be imported explicitly from these modules.
|
|
No individual symbols are re-exported at the package root.
|
|
|
|
----------------------------------------------------------------------
|
|
Design Guarantees
|
|
----------------------------------------------------------------------
|
|
|
|
- Read-only access: no mutation of provider state
|
|
- Provider-agnostic domain models
|
|
- Explicit configuration and dependency injection
|
|
- No implicit global state or environment reads
|
|
- Deterministic, testable behavior
|
|
|
|
Mail Intake favors correctness, clarity, and explicitness over convenience
|
|
shortcuts.
|
|
"""
|
|
|
|
|
|
import ingestion
|
|
import adapters
|
|
import auth
|
|
import models
|
|
import config
|
|
import exceptions
|
|
|
|
__all__ = [
|
|
"ingestion",
|
|
"adapters",
|
|
"auth",
|
|
"models",
|
|
"config",
|
|
"exceptions",
|
|
]
|