updated docs strings and added README.md
This commit is contained in:
@@ -1,10 +1,8 @@
|
||||
"""
|
||||
# Summary
|
||||
|
||||
Mail Intake — provider-agnostic, read-only email ingestion framework.
|
||||
|
||||
---
|
||||
|
||||
## Summary
|
||||
|
||||
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.
|
||||
@@ -12,109 +10,126 @@ 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 lifecycle management
|
||||
- credentials: credential persistence abstractions and implementations
|
||||
- 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
|
||||
- `adapters`: Provider-specific access (e.g., Gmail).
|
||||
- `auth`: Authentication providers and credential lifecycle management.
|
||||
- `credentials`: Credential persistence abstractions and implementations.
|
||||
- `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
|
||||
# Installation
|
||||
|
||||
Install using pip:
|
||||
|
||||
pip install mail-intake
|
||||
```bash
|
||||
pip install mail-intake
|
||||
```
|
||||
|
||||
Or with Poetry:
|
||||
|
||||
poetry add mail-intake
|
||||
```bash
|
||||
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).
|
||||
|
||||
---
|
||||
|
||||
## Quick start
|
||||
# Quick Start
|
||||
|
||||
Minimal Gmail ingestion example (local development):
|
||||
|
||||
from mail_intake.ingestion import MailIntakeReader
|
||||
from mail_intake.adapters import MailIntakeGmailAdapter
|
||||
from mail_intake.auth import MailIntakeGoogleAuth
|
||||
from mail_intake.credentials import PickleCredentialStore
|
||||
```python
|
||||
from mail_intake.ingestion import MailIntakeReader
|
||||
from mail_intake.adapters import MailIntakeGmailAdapter
|
||||
from mail_intake.auth import MailIntakeGoogleAuth
|
||||
from mail_intake.credentials import PickleCredentialStore
|
||||
|
||||
store = PickleCredentialStore(path="token.pickle")
|
||||
store = PickleCredentialStore(path="token.pickle")
|
||||
|
||||
auth = MailIntakeGoogleAuth(
|
||||
credentials_path="credentials.json",
|
||||
store=store,
|
||||
scopes=["https://www.googleapis.com/auth/gmail.readonly"],
|
||||
)
|
||||
auth = MailIntakeGoogleAuth(
|
||||
credentials_path="credentials.json",
|
||||
store=store,
|
||||
scopes=["https://www.googleapis.com/auth/gmail.readonly"],
|
||||
)
|
||||
|
||||
adapter = MailIntakeGmailAdapter(auth_provider=auth)
|
||||
reader = MailIntakeReader(adapter)
|
||||
adapter = MailIntakeGmailAdapter(auth_provider=auth)
|
||||
reader = MailIntakeReader(adapter)
|
||||
|
||||
for message in reader.iter_messages("from:recruiter@example.com"):
|
||||
print(message.subject, message.from_email)
|
||||
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))
|
||||
```python
|
||||
for thread in reader.iter_threads("subject:Interview"):
|
||||
print(thread.normalized_subject, len(thread.messages))
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Architecture
|
||||
# Architecture
|
||||
|
||||
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[T]``
|
||||
- Users MAY implement their own credential persistence layers by implementing ``credentials.CredentialStore[T]``
|
||||
- Users MAY implement their own mail adapters by subclassing
|
||||
`adapters.MailIntakeAdapter`.
|
||||
- Users MAY implement their own authentication providers by subclassing
|
||||
`auth.MailIntakeAuthProvider[T]`.
|
||||
- Users MAY implement their own credential persistence layers by implementing
|
||||
`credentials.CredentialStore[T]`.
|
||||
|
||||
Users SHOULD NOT subclass built-in adapter implementations. Built-in
|
||||
adapters (such as Gmail) are reference implementations and may change
|
||||
internally without notice.
|
||||
|
||||
**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
|
||||
- Distributed-safe authentication design
|
||||
|
||||
- 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.
|
||||
- Distributed-safe authentication design.
|
||||
|
||||
Mail Intake favors correctness, clarity, and explicitness over convenience
|
||||
shortcuts.
|
||||
|
||||
**Core Philosophy:**
|
||||
|
||||
`Mail Intake` is built as a **contract-first ingestion pipeline**:
|
||||
1. **Layered Decoupling**: Adapters handle transport, Parsers handle format normalization, and Ingestion orchestrates.
|
||||
2. **Provider Agnosticism**: Domain models and core logic never depend on provider-specific (e.g., Gmail) API internals.
|
||||
3. **Stateless Workflows**: The library functions as a read-only pipe, ensuring side-effect-free ingestion.
|
||||
|
||||
1. **Layered Decoupling**: Adapters handle transport, Parsers handle format
|
||||
normalization, and Ingestion orchestrates.
|
||||
2. **Provider Agnosticism**: Domain models and core logic never depend on
|
||||
provider-specific (e.g., Gmail) API internals.
|
||||
3. **Stateless Workflows**: The library functions as a read-only pipe, ensuring
|
||||
side-effect-free ingestion.
|
||||
|
||||
---
|
||||
|
||||
## Public API
|
||||
# Public API
|
||||
|
||||
The supported public API consists of the following top-level modules:
|
||||
|
||||
- mail_intake.ingestion
|
||||
- mail_intake.adapters
|
||||
- mail_intake.auth
|
||||
- mail_intake.credentials
|
||||
- mail_intake.parsers
|
||||
- mail_intake.models
|
||||
- mail_intake.config
|
||||
- mail_intake.exceptions
|
||||
- `mail_intake.ingestion`
|
||||
- `mail_intake.adapters`
|
||||
- `mail_intake.auth`
|
||||
- `mail_intake.credentials`
|
||||
- `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.
|
||||
|
||||
Reference in New Issue
Block a user