Compare commits

7 Commits

109 changed files with 922 additions and 1002 deletions

View File

@@ -32,6 +32,26 @@ steps:
echo "🆕 New version detected: $PACKAGE_NAME==$VERSION"
fi
- name: quality-gate
image: python:3.13-slim
environment:
PIP_REPO_URL:
from_secret: PIP_REPO_URL
PIP_USERNAME:
from_secret: PIP_USERNAME
PIP_PASSWORD:
from_secret: PIP_PASSWORD
commands:
- pip install --upgrade pip build
- |
AUTH_URL="https://${PIP_USERNAME}:${PIP_PASSWORD}@$(echo "${PIP_REPO_URL#*://}" | sed 's:/*$::')/simple"
pip install --index-url "$AUTH_URL" --extra-index-url https://pypi.org/simple/ -U ".[dev]"
- echo "🛡️ Running quality gate..."
- python -m black --check .
- python -m ruff check .
- python -m mypy
- python -m pytest
- name: build-package
image: python:3.13-slim
commands:
@@ -126,4 +146,4 @@ steps:
trigger:
event:
- custom
- custom

8
.gitignore vendored
View File

@@ -25,10 +25,17 @@ env/
htmlcov/
coverage.xml
# Lint / type checking
.mypy_cache/
.ruff_cache/
# Environment variables
.env
.env.local
# Docs build artifacts
site
# OS
.DS_Store
Thumbs.db
@@ -38,7 +45,6 @@ Thumbs.db
*.swo
*~
*.tmp
site
# Credentials
client_secret_*.json

23
CHANGELOG.md Normal file
View File

@@ -0,0 +1,23 @@
# Changelog
All notable changes to this project will be documented in this file.
The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
## [Unreleased]
### Added
- `py.typed` marker for PEP 561 type information.
- `.drone.yml` CI with a quality-gate step (black, ruff, mypy, pytest).
- Canonical `docforge.nav.yml`, generated `mkdocs.yml` and `mcp_docs/` via doc-forge.
- MIT `LICENSE`.
### Changed
- Standardized `pyproject.toml` (canonical packaging, lint tool config, extras).
- `fetch_emails.py` debug script excluded from black/ruff scans.
### Fixed
- Regression test for immutable config models raises `AssertionError` instead of
a bare `assert False`.
- Stub fixes for typed API surfaces.

21
LICENSE Normal file
View File

@@ -0,0 +1,21 @@
MIT License
Copyright (c) 2026 Aetoskia Platform
Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.

View File

@@ -1,29 +1,32 @@
home: index.md
home: lib/index.md
groups:
Core API:
- ingestion/index.md
- ingestion/reader.md
- lib/ingestion/index.md
- lib/ingestion/reader.md
Domain Models:
- models/index.md
- models/message.md
- models/thread.md
- lib/models/index.md
- lib/models/message.md
- lib/models/thread.md
Provider Adapters:
- adapters/index.md
- adapters/base.md
- adapters/gmail.md
- lib/adapters/index.md
- lib/adapters/base.md
- lib/adapters/gmail.md
Authentication & Storage:
- auth/index.md
- auth/base.md
- auth/google.md
- credentials/index.md
- credentials/store.md
- credentials/pickle.md
- credentials/redis.md
- lib/auth/index.md
- lib/auth/base.md
- lib/auth/google.md
- lib/credentials/index.md
- lib/credentials/store.md
- lib/credentials/pickle.md
- lib/credentials/redis.md
Normalization & Parsing:
- parsers/index.md
- parsers/body.md
- parsers/headers.md
- parsers/subject.md
- lib/parsers/index.md
- lib/parsers/body.md
- lib/parsers/headers.md
- lib/parsers/subject.md
Configuration & Errors:
- config.md
- exceptions.md
- lib/config.md
- lib/exceptions.md
icon:
logo: material/inbox
repo: fontawesome/brands/github

View File

@@ -1,3 +1,4 @@
# mail_intake
::: mail_intake
- [Mail Intake](mail_intake/)

View File

@@ -0,0 +1,3 @@
# Base
::: mail_intake.adapters.base

View File

@@ -0,0 +1,3 @@
# Gmail
::: mail_intake.adapters.gmail

View File

@@ -0,0 +1,5 @@
# Adapters
::: mail_intake.adapters
- [Base](base.md)
- [Gmail](gmail.md)

View File

@@ -0,0 +1,3 @@
# Base
::: mail_intake.auth.base

View File

@@ -0,0 +1,3 @@
# Google
::: mail_intake.auth.google

View File

@@ -0,0 +1,5 @@
# Auth
::: mail_intake.auth
- [Base](base.md)
- [Google](google.md)

View File

@@ -0,0 +1,3 @@
# Config
::: mail_intake.config

View File

@@ -0,0 +1,6 @@
# Credentials
::: mail_intake.credentials
- [Pickle](pickle.md)
- [Redis](redis.md)
- [Store](store.md)

View File

@@ -0,0 +1,3 @@
# Pickle
::: mail_intake.credentials.pickle

View File

@@ -0,0 +1,3 @@
# Redis
::: mail_intake.credentials.redis

View File

@@ -0,0 +1,3 @@
# Store
::: mail_intake.credentials.store

View File

@@ -0,0 +1,3 @@
# Exceptions
::: mail_intake.exceptions

View File

@@ -0,0 +1,11 @@
# Mail Intake
::: mail_intake
- [Adapters](adapters/)
- [Auth](auth/)
- [Config](config.md)
- [Credentials](credentials/)
- [Exceptions](exceptions.md)
- [Ingestion](ingestion/)
- [Models](models/)
- [Parsers](parsers/)

View File

@@ -0,0 +1,4 @@
# Ingestion
::: mail_intake.ingestion
- [Reader](reader.md)

View File

@@ -0,0 +1,3 @@
# Reader
::: mail_intake.ingestion.reader

View File

@@ -0,0 +1,5 @@
# Models
::: mail_intake.models
- [Message](message.md)
- [Thread](thread.md)

View File

@@ -0,0 +1,6 @@
# Parsers
::: mail_intake.parsers
- [Body](body.md)
- [Headers](headers.md)
- [Subject](subject.md)

View File

@@ -0,0 +1,3 @@
# Message
::: mail_intake.models.message

View File

@@ -0,0 +1,3 @@
# Thread
::: mail_intake.models.thread

3
docs/lib/parsers/body.md Normal file
View File

@@ -0,0 +1,3 @@
# Body
::: mail_intake.parsers.body

View File

@@ -0,0 +1,3 @@
# Headers
::: mail_intake.parsers.headers

View File

@@ -0,0 +1,3 @@
# Subject
::: mail_intake.parsers.subject

View File

@@ -22,14 +22,7 @@
"name": "Iterator",
"kind": "alias",
"path": "mail_intake.adapters.base.Iterator",
"signature": "<bound method Alias.signature of Alias('Iterator', 'typing.Iterator')>",
"docstring": null
},
"Dict": {
"name": "Dict",
"kind": "alias",
"path": "mail_intake.adapters.base.Dict",
"signature": "<bound method Alias.signature of Alias('Dict', 'typing.Dict')>",
"signature": "<bound method Alias.signature of Alias('Iterator', 'collections.abc.Iterator')>",
"docstring": null
},
"Any": {
@@ -43,29 +36,29 @@
"name": "MailIntakeAdapter",
"kind": "class",
"path": "mail_intake.adapters.base.MailIntakeAdapter",
"signature": "<bound method Class.signature of Class('MailIntakeAdapter', 18, 93)>",
"signature": "<bound method Class.signature of Class('MailIntakeAdapter', 19, 98)>",
"docstring": "Base adapter interface for mail providers.\n\nNotes:\n **Guarantees:**\n\n - Discover messages matching a query.\n - Retrieve full message payloads.\n - Retrieve full thread payloads.\n\n **Lifecycle:**\n\n - Adapters are intentionally read-only and must not mutate provider state.",
"members": {
"iter_message_refs": {
"name": "iter_message_refs",
"kind": "function",
"path": "mail_intake.adapters.base.MailIntakeAdapter.iter_message_refs",
"signature": "<bound method Function.signature of Function('iter_message_refs', 34, 63)>",
"docstring": "Iterate over lightweight message references matching a query.\n\nArgs:\n query (str):\n Provider-specific query string used to filter messages.\n\nYields:\n Dict[str, str]:\n Dictionaries containing message and thread identifiers.\n\nNotes:\n **Guarantees:**\n\n - Implementations must yield dictionaries containing at least\n `message_id` and `thread_id`.\n\nExample:\n Typical yield:\n\n ```python\n {\n \"message_id\": \"...\",\n \"thread_id\": \"...\"\n }\n ```"
"signature": "<bound method Function.signature of Function('iter_message_refs', 35, 68)>",
"docstring": "Iterate over lightweight message references matching a query.\n\nArgs:\n query (str):\n Provider-specific query string used to filter messages.\n\nReturns:\n Iterator[dict[str, str]]:\n An iterator over lightweight message reference dictionaries.\n\nYields:\n dict[str, str]:\n Dictionaries containing message and thread identifiers.\n\nNotes:\n **Guarantees:**\n\n - Implementations must yield dictionaries containing at least\n `message_id` and `thread_id`.\n\nExample:\n Typical yield:\n\n ```python\n {\n \"message_id\": \"...\",\n \"thread_id\": \"...\"\n }\n ```"
},
"fetch_message": {
"name": "fetch_message",
"kind": "function",
"path": "mail_intake.adapters.base.MailIntakeAdapter.fetch_message",
"signature": "<bound method Function.signature of Function('fetch_message', 65, 78)>",
"docstring": "Fetch a full raw message by message identifier.\n\nArgs:\n message_id (str):\n Provider-specific message identifier.\n\nReturns:\n Dict[str, Any]:\n Provider-native message payload (e.g., Gmail message JSON structure)."
"signature": "<bound method Function.signature of Function('fetch_message', 70, 83)>",
"docstring": "Fetch a full raw message by message identifier.\n\nArgs:\n message_id (str):\n Provider-specific message identifier.\n\nReturns:\n dict[str, Any]:\n Provider-native message payload (e.g., Gmail message JSON structure)."
},
"fetch_thread": {
"name": "fetch_thread",
"kind": "function",
"path": "mail_intake.adapters.base.MailIntakeAdapter.fetch_thread",
"signature": "<bound method Function.signature of Function('fetch_thread', 80, 93)>",
"docstring": "Fetch a full raw thread by thread identifier.\n\nArgs:\n thread_id (str):\n Provider-specific thread identifier.\n\nReturns:\n Dict[str, Any]:\n Provider-native thread payload."
"signature": "<bound method Function.signature of Function('fetch_thread', 85, 98)>",
"docstring": "Fetch a full raw thread by thread identifier.\n\nArgs:\n thread_id (str):\n Provider-specific thread identifier.\n\nReturns:\n dict[str, Any]:\n Provider-native thread payload."
}
}
}

View File

@@ -8,14 +8,7 @@
"name": "Iterator",
"kind": "alias",
"path": "mail_intake.adapters.gmail.Iterator",
"signature": "<bound method Alias.signature of Alias('Iterator', 'typing.Iterator')>",
"docstring": null
},
"Dict": {
"name": "Dict",
"kind": "alias",
"path": "mail_intake.adapters.gmail.Dict",
"signature": "<bound method Alias.signature of Alias('Dict', 'typing.Dict')>",
"signature": "<bound method Alias.signature of Alias('Iterator', 'collections.abc.Iterator')>",
"docstring": null
},
"Any": {
@@ -51,31 +44,24 @@
"kind": "function",
"path": "mail_intake.adapters.gmail.MailIntakeAdapter.iter_message_refs",
"signature": "<bound method Alias.signature of Alias('iter_message_refs', 'mail_intake.adapters.base.MailIntakeAdapter.iter_message_refs')>",
"docstring": "Iterate over lightweight message references matching a query.\n\nArgs:\n query (str):\n Provider-specific query string used to filter messages.\n\nYields:\n Dict[str, str]:\n Dictionaries containing message and thread identifiers.\n\nNotes:\n **Guarantees:**\n\n - Implementations must yield dictionaries containing at least\n `message_id` and `thread_id`.\n\nExample:\n Typical yield:\n\n ```python\n {\n \"message_id\": \"...\",\n \"thread_id\": \"...\"\n }\n ```"
"docstring": "Iterate over lightweight message references matching a query.\n\nArgs:\n query (str):\n Provider-specific query string used to filter messages.\n\nReturns:\n Iterator[dict[str, str]]:\n An iterator over lightweight message reference dictionaries.\n\nYields:\n dict[str, str]:\n Dictionaries containing message and thread identifiers.\n\nNotes:\n **Guarantees:**\n\n - Implementations must yield dictionaries containing at least\n `message_id` and `thread_id`.\n\nExample:\n Typical yield:\n\n ```python\n {\n \"message_id\": \"...\",\n \"thread_id\": \"...\"\n }\n ```"
},
"fetch_message": {
"name": "fetch_message",
"kind": "function",
"path": "mail_intake.adapters.gmail.MailIntakeAdapter.fetch_message",
"signature": "<bound method Alias.signature of Alias('fetch_message', 'mail_intake.adapters.base.MailIntakeAdapter.fetch_message')>",
"docstring": "Fetch a full raw message by message identifier.\n\nArgs:\n message_id (str):\n Provider-specific message identifier.\n\nReturns:\n Dict[str, Any]:\n Provider-native message payload (e.g., Gmail message JSON structure)."
"docstring": "Fetch a full raw message by message identifier.\n\nArgs:\n message_id (str):\n Provider-specific message identifier.\n\nReturns:\n dict[str, Any]:\n Provider-native message payload (e.g., Gmail message JSON structure)."
},
"fetch_thread": {
"name": "fetch_thread",
"kind": "function",
"path": "mail_intake.adapters.gmail.MailIntakeAdapter.fetch_thread",
"signature": "<bound method Alias.signature of Alias('fetch_thread', 'mail_intake.adapters.base.MailIntakeAdapter.fetch_thread')>",
"docstring": "Fetch a full raw thread by thread identifier.\n\nArgs:\n thread_id (str):\n Provider-specific thread identifier.\n\nReturns:\n Dict[str, Any]:\n Provider-native thread payload."
"docstring": "Fetch a full raw thread by thread identifier.\n\nArgs:\n thread_id (str):\n Provider-specific thread identifier.\n\nReturns:\n dict[str, Any]:\n Provider-native thread payload."
}
}
},
"MailIntakeAdapterError": {
"name": "MailIntakeAdapterError",
"kind": "class",
"path": "mail_intake.adapters.gmail.MailIntakeAdapterError",
"signature": "<bound method Alias.signature of Alias('MailIntakeAdapterError', 'mail_intake.exceptions.MailIntakeAdapterError')>",
"docstring": "Errors raised by mail provider adapters.\n\nNotes:\n **Lifecycle:**\n\n - Raised when a provider adapter encounters API errors, transport\n failures, or invalid provider responses."
},
"MailIntakeAuthProvider": {
"name": "MailIntakeAuthProvider",
"kind": "class",
@@ -92,11 +78,18 @@
}
}
},
"MailIntakeAdapterError": {
"name": "MailIntakeAdapterError",
"kind": "class",
"path": "mail_intake.adapters.gmail.MailIntakeAdapterError",
"signature": "<bound method Alias.signature of Alias('MailIntakeAdapterError', 'mail_intake.exceptions.MailIntakeAdapterError')>",
"docstring": "Errors raised by mail provider adapters.\n\nNotes:\n **Lifecycle:**\n\n - Raised when a provider adapter encounters API errors, transport\n failures, or invalid provider responses."
},
"MailIntakeGmailAdapter": {
"name": "MailIntakeGmailAdapter",
"kind": "class",
"path": "mail_intake.adapters.gmail.MailIntakeGmailAdapter",
"signature": "<bound method Class.signature of Class('MailIntakeGmailAdapter', 28, 189)>",
"signature": "<bound method Class.signature of Class('MailIntakeGmailAdapter', 29, 180)>",
"docstring": "Gmail read-only adapter.\n\nThis adapter implements the `MailIntakeAdapter` interface using the\nGmail REST API. It translates the generic mail intake contract into\nGmail-specific API calls.\n\nNotes:\n **Responsibilities:**\n\n - This class is the ONLY place where `googleapiclient` is imported.\n - Gmail REST semantics are known.\n - `.execute()` is called.\n\n **Constraints:**\n\n - Must remain thin and imperative.\n - Must not perform parsing or interpretation.\n - Must not expose Gmail-specific types beyond this class.",
"members": {
"service": {
@@ -104,28 +97,28 @@
"kind": "attribute",
"path": "mail_intake.adapters.gmail.MailIntakeGmailAdapter.service",
"signature": null,
"docstring": "Lazily initialize and return the Gmail API service client.\n\nReturns:\n Any:\n Initialized Gmail API service instance.\n\nRaises:\n MailIntakeAdapterError:\n If the Gmail service cannot be initialized."
"docstring": "Lazily initialize and return the Gmail API service client.\n\nRaises:\n MailIntakeAdapterError:\n If the Gmail service cannot be initialized."
},
"iter_message_refs": {
"name": "iter_message_refs",
"kind": "function",
"path": "mail_intake.adapters.gmail.MailIntakeGmailAdapter.iter_message_refs",
"signature": "<bound method Function.signature of Function('iter_message_refs', 92, 133)>",
"docstring": "Iterate over message references matching the query.\n\nArgs:\n query (str):\n Gmail search query string.\n\nYields:\n Dict[str, str]:\n Dictionaries containing ``message_id`` and ``thread_id``.\n\nRaises:\n MailIntakeAdapterError:\n If the Gmail API returns an error."
"signature": "<bound method Function.signature of Function('iter_message_refs', 89, 124)>",
"docstring": "Iterate over message references matching the query.\n\nArgs:\n query (str):\n Gmail search query string.\n\nYields:\n dict[str, str]:\n Dictionaries containing ``message_id`` and ``thread_id``.\n\nRaises:\n MailIntakeAdapterError:\n If the Gmail API returns an error."
},
"fetch_message": {
"name": "fetch_message",
"kind": "function",
"path": "mail_intake.adapters.gmail.MailIntakeGmailAdapter.fetch_message",
"signature": "<bound method Function.signature of Function('fetch_message', 135, 161)>",
"docstring": "Fetch a full Gmail message by message ID.\n\nArgs:\n message_id (str):\n Gmail message identifier.\n\nReturns:\n Dict[str, Any]:\n Provider-native Gmail message payload.\n\nRaises:\n MailIntakeAdapterError:\n If the Gmail API returns an error."
"signature": "<bound method Function.signature of Function('fetch_message', 126, 152)>",
"docstring": "Fetch a full Gmail message by message ID.\n\nArgs:\n message_id (str):\n Gmail message identifier.\n\nReturns:\n dict[str, Any]:\n Provider-native Gmail message payload.\n\nRaises:\n MailIntakeAdapterError:\n If the Gmail API returns an error."
},
"fetch_thread": {
"name": "fetch_thread",
"kind": "function",
"path": "mail_intake.adapters.gmail.MailIntakeGmailAdapter.fetch_thread",
"signature": "<bound method Function.signature of Function('fetch_thread', 163, 189)>",
"docstring": "Fetch a full Gmail thread by thread ID.\n\nArgs:\n thread_id (str):\n Gmail thread identifier.\n\nReturns:\n Dict[str, Any]:\n Provider-native Gmail thread payload.\n\nRaises:\n MailIntakeAdapterError:\n If the Gmail API returns an error."
"signature": "<bound method Function.signature of Function('fetch_thread', 154, 180)>",
"docstring": "Fetch a full Gmail thread by thread ID.\n\nArgs:\n thread_id (str):\n Gmail thread identifier.\n\nReturns:\n dict[str, Any]:\n Provider-native Gmail thread payload.\n\nRaises:\n MailIntakeAdapterError:\n If the Gmail API returns an error."
}
}
}

View File

@@ -16,21 +16,21 @@
"kind": "function",
"path": "mail_intake.adapters.MailIntakeAdapter.iter_message_refs",
"signature": "<bound method Alias.signature of Alias('iter_message_refs', 'mail_intake.adapters.base.MailIntakeAdapter.iter_message_refs')>",
"docstring": "Iterate over lightweight message references matching a query.\n\nArgs:\n query (str):\n Provider-specific query string used to filter messages.\n\nYields:\n Dict[str, str]:\n Dictionaries containing message and thread identifiers.\n\nNotes:\n **Guarantees:**\n\n - Implementations must yield dictionaries containing at least\n `message_id` and `thread_id`.\n\nExample:\n Typical yield:\n\n ```python\n {\n \"message_id\": \"...\",\n \"thread_id\": \"...\"\n }\n ```"
"docstring": "Iterate over lightweight message references matching a query.\n\nArgs:\n query (str):\n Provider-specific query string used to filter messages.\n\nReturns:\n Iterator[dict[str, str]]:\n An iterator over lightweight message reference dictionaries.\n\nYields:\n dict[str, str]:\n Dictionaries containing message and thread identifiers.\n\nNotes:\n **Guarantees:**\n\n - Implementations must yield dictionaries containing at least\n `message_id` and `thread_id`.\n\nExample:\n Typical yield:\n\n ```python\n {\n \"message_id\": \"...\",\n \"thread_id\": \"...\"\n }\n ```"
},
"fetch_message": {
"name": "fetch_message",
"kind": "function",
"path": "mail_intake.adapters.MailIntakeAdapter.fetch_message",
"signature": "<bound method Alias.signature of Alias('fetch_message', 'mail_intake.adapters.base.MailIntakeAdapter.fetch_message')>",
"docstring": "Fetch a full raw message by message identifier.\n\nArgs:\n message_id (str):\n Provider-specific message identifier.\n\nReturns:\n Dict[str, Any]:\n Provider-native message payload (e.g., Gmail message JSON structure)."
"docstring": "Fetch a full raw message by message identifier.\n\nArgs:\n message_id (str):\n Provider-specific message identifier.\n\nReturns:\n dict[str, Any]:\n Provider-native message payload (e.g., Gmail message JSON structure)."
},
"fetch_thread": {
"name": "fetch_thread",
"kind": "function",
"path": "mail_intake.adapters.MailIntakeAdapter.fetch_thread",
"signature": "<bound method Alias.signature of Alias('fetch_thread', 'mail_intake.adapters.base.MailIntakeAdapter.fetch_thread')>",
"docstring": "Fetch a full raw thread by thread identifier.\n\nArgs:\n thread_id (str):\n Provider-specific thread identifier.\n\nReturns:\n Dict[str, Any]:\n Provider-native thread payload."
"docstring": "Fetch a full raw thread by thread identifier.\n\nArgs:\n thread_id (str):\n Provider-specific thread identifier.\n\nReturns:\n dict[str, Any]:\n Provider-native thread payload."
}
}
},
@@ -46,28 +46,28 @@
"kind": "attribute",
"path": "mail_intake.adapters.MailIntakeGmailAdapter.service",
"signature": "<bound method Alias.signature of Alias('service', 'mail_intake.adapters.gmail.MailIntakeGmailAdapter.service')>",
"docstring": "Lazily initialize and return the Gmail API service client.\n\nReturns:\n Any:\n Initialized Gmail API service instance.\n\nRaises:\n MailIntakeAdapterError:\n If the Gmail service cannot be initialized."
"docstring": "Lazily initialize and return the Gmail API service client.\n\nRaises:\n MailIntakeAdapterError:\n If the Gmail service cannot be initialized."
},
"iter_message_refs": {
"name": "iter_message_refs",
"kind": "function",
"path": "mail_intake.adapters.MailIntakeGmailAdapter.iter_message_refs",
"signature": "<bound method Alias.signature of Alias('iter_message_refs', 'mail_intake.adapters.gmail.MailIntakeGmailAdapter.iter_message_refs')>",
"docstring": "Iterate over message references matching the query.\n\nArgs:\n query (str):\n Gmail search query string.\n\nYields:\n Dict[str, str]:\n Dictionaries containing ``message_id`` and ``thread_id``.\n\nRaises:\n MailIntakeAdapterError:\n If the Gmail API returns an error."
"docstring": "Iterate over message references matching the query.\n\nArgs:\n query (str):\n Gmail search query string.\n\nYields:\n dict[str, str]:\n Dictionaries containing ``message_id`` and ``thread_id``.\n\nRaises:\n MailIntakeAdapterError:\n If the Gmail API returns an error."
},
"fetch_message": {
"name": "fetch_message",
"kind": "function",
"path": "mail_intake.adapters.MailIntakeGmailAdapter.fetch_message",
"signature": "<bound method Alias.signature of Alias('fetch_message', 'mail_intake.adapters.gmail.MailIntakeGmailAdapter.fetch_message')>",
"docstring": "Fetch a full Gmail message by message ID.\n\nArgs:\n message_id (str):\n Gmail message identifier.\n\nReturns:\n Dict[str, Any]:\n Provider-native Gmail message payload.\n\nRaises:\n MailIntakeAdapterError:\n If the Gmail API returns an error."
"docstring": "Fetch a full Gmail message by message ID.\n\nArgs:\n message_id (str):\n Gmail message identifier.\n\nReturns:\n dict[str, Any]:\n Provider-native Gmail message payload.\n\nRaises:\n MailIntakeAdapterError:\n If the Gmail API returns an error."
},
"fetch_thread": {
"name": "fetch_thread",
"kind": "function",
"path": "mail_intake.adapters.MailIntakeGmailAdapter.fetch_thread",
"signature": "<bound method Alias.signature of Alias('fetch_thread', 'mail_intake.adapters.gmail.MailIntakeGmailAdapter.fetch_thread')>",
"docstring": "Fetch a full Gmail thread by thread ID.\n\nArgs:\n thread_id (str):\n Gmail thread identifier.\n\nReturns:\n Dict[str, Any]:\n Provider-native Gmail thread payload.\n\nRaises:\n MailIntakeAdapterError:\n If the Gmail API returns an error."
"docstring": "Fetch a full Gmail thread by thread ID.\n\nArgs:\n thread_id (str):\n Gmail thread identifier.\n\nReturns:\n dict[str, Any]:\n Provider-native Gmail thread payload.\n\nRaises:\n MailIntakeAdapterError:\n If the Gmail API returns an error."
}
}
},
@@ -96,14 +96,7 @@
"name": "Iterator",
"kind": "alias",
"path": "mail_intake.adapters.base.Iterator",
"signature": "<bound method Alias.signature of Alias('Iterator', 'typing.Iterator')>",
"docstring": null
},
"Dict": {
"name": "Dict",
"kind": "alias",
"path": "mail_intake.adapters.base.Dict",
"signature": "<bound method Alias.signature of Alias('Dict', 'typing.Dict')>",
"signature": "<bound method Alias.signature of Alias('Iterator', 'collections.abc.Iterator')>",
"docstring": null
},
"Any": {
@@ -117,29 +110,29 @@
"name": "MailIntakeAdapter",
"kind": "class",
"path": "mail_intake.adapters.base.MailIntakeAdapter",
"signature": "<bound method Class.signature of Class('MailIntakeAdapter', 18, 93)>",
"signature": "<bound method Class.signature of Class('MailIntakeAdapter', 19, 98)>",
"docstring": "Base adapter interface for mail providers.\n\nNotes:\n **Guarantees:**\n\n - Discover messages matching a query.\n - Retrieve full message payloads.\n - Retrieve full thread payloads.\n\n **Lifecycle:**\n\n - Adapters are intentionally read-only and must not mutate provider state.",
"members": {
"iter_message_refs": {
"name": "iter_message_refs",
"kind": "function",
"path": "mail_intake.adapters.base.MailIntakeAdapter.iter_message_refs",
"signature": "<bound method Function.signature of Function('iter_message_refs', 34, 63)>",
"docstring": "Iterate over lightweight message references matching a query.\n\nArgs:\n query (str):\n Provider-specific query string used to filter messages.\n\nYields:\n Dict[str, str]:\n Dictionaries containing message and thread identifiers.\n\nNotes:\n **Guarantees:**\n\n - Implementations must yield dictionaries containing at least\n `message_id` and `thread_id`.\n\nExample:\n Typical yield:\n\n ```python\n {\n \"message_id\": \"...\",\n \"thread_id\": \"...\"\n }\n ```"
"signature": "<bound method Function.signature of Function('iter_message_refs', 35, 68)>",
"docstring": "Iterate over lightweight message references matching a query.\n\nArgs:\n query (str):\n Provider-specific query string used to filter messages.\n\nReturns:\n Iterator[dict[str, str]]:\n An iterator over lightweight message reference dictionaries.\n\nYields:\n dict[str, str]:\n Dictionaries containing message and thread identifiers.\n\nNotes:\n **Guarantees:**\n\n - Implementations must yield dictionaries containing at least\n `message_id` and `thread_id`.\n\nExample:\n Typical yield:\n\n ```python\n {\n \"message_id\": \"...\",\n \"thread_id\": \"...\"\n }\n ```"
},
"fetch_message": {
"name": "fetch_message",
"kind": "function",
"path": "mail_intake.adapters.base.MailIntakeAdapter.fetch_message",
"signature": "<bound method Function.signature of Function('fetch_message', 65, 78)>",
"docstring": "Fetch a full raw message by message identifier.\n\nArgs:\n message_id (str):\n Provider-specific message identifier.\n\nReturns:\n Dict[str, Any]:\n Provider-native message payload (e.g., Gmail message JSON structure)."
"signature": "<bound method Function.signature of Function('fetch_message', 70, 83)>",
"docstring": "Fetch a full raw message by message identifier.\n\nArgs:\n message_id (str):\n Provider-specific message identifier.\n\nReturns:\n dict[str, Any]:\n Provider-native message payload (e.g., Gmail message JSON structure)."
},
"fetch_thread": {
"name": "fetch_thread",
"kind": "function",
"path": "mail_intake.adapters.base.MailIntakeAdapter.fetch_thread",
"signature": "<bound method Function.signature of Function('fetch_thread', 80, 93)>",
"docstring": "Fetch a full raw thread by thread identifier.\n\nArgs:\n thread_id (str):\n Provider-specific thread identifier.\n\nReturns:\n Dict[str, Any]:\n Provider-native thread payload."
"signature": "<bound method Function.signature of Function('fetch_thread', 85, 98)>",
"docstring": "Fetch a full raw thread by thread identifier.\n\nArgs:\n thread_id (str):\n Provider-specific thread identifier.\n\nReturns:\n dict[str, Any]:\n Provider-native thread payload."
}
}
}
@@ -156,14 +149,7 @@
"name": "Iterator",
"kind": "alias",
"path": "mail_intake.adapters.gmail.Iterator",
"signature": "<bound method Alias.signature of Alias('Iterator', 'typing.Iterator')>",
"docstring": null
},
"Dict": {
"name": "Dict",
"kind": "alias",
"path": "mail_intake.adapters.gmail.Dict",
"signature": "<bound method Alias.signature of Alias('Dict', 'typing.Dict')>",
"signature": "<bound method Alias.signature of Alias('Iterator', 'collections.abc.Iterator')>",
"docstring": null
},
"Any": {
@@ -199,31 +185,24 @@
"kind": "function",
"path": "mail_intake.adapters.gmail.MailIntakeAdapter.iter_message_refs",
"signature": "<bound method Alias.signature of Alias('iter_message_refs', 'mail_intake.adapters.base.MailIntakeAdapter.iter_message_refs')>",
"docstring": "Iterate over lightweight message references matching a query.\n\nArgs:\n query (str):\n Provider-specific query string used to filter messages.\n\nYields:\n Dict[str, str]:\n Dictionaries containing message and thread identifiers.\n\nNotes:\n **Guarantees:**\n\n - Implementations must yield dictionaries containing at least\n `message_id` and `thread_id`.\n\nExample:\n Typical yield:\n\n ```python\n {\n \"message_id\": \"...\",\n \"thread_id\": \"...\"\n }\n ```"
"docstring": "Iterate over lightweight message references matching a query.\n\nArgs:\n query (str):\n Provider-specific query string used to filter messages.\n\nReturns:\n Iterator[dict[str, str]]:\n An iterator over lightweight message reference dictionaries.\n\nYields:\n dict[str, str]:\n Dictionaries containing message and thread identifiers.\n\nNotes:\n **Guarantees:**\n\n - Implementations must yield dictionaries containing at least\n `message_id` and `thread_id`.\n\nExample:\n Typical yield:\n\n ```python\n {\n \"message_id\": \"...\",\n \"thread_id\": \"...\"\n }\n ```"
},
"fetch_message": {
"name": "fetch_message",
"kind": "function",
"path": "mail_intake.adapters.gmail.MailIntakeAdapter.fetch_message",
"signature": "<bound method Alias.signature of Alias('fetch_message', 'mail_intake.adapters.base.MailIntakeAdapter.fetch_message')>",
"docstring": "Fetch a full raw message by message identifier.\n\nArgs:\n message_id (str):\n Provider-specific message identifier.\n\nReturns:\n Dict[str, Any]:\n Provider-native message payload (e.g., Gmail message JSON structure)."
"docstring": "Fetch a full raw message by message identifier.\n\nArgs:\n message_id (str):\n Provider-specific message identifier.\n\nReturns:\n dict[str, Any]:\n Provider-native message payload (e.g., Gmail message JSON structure)."
},
"fetch_thread": {
"name": "fetch_thread",
"kind": "function",
"path": "mail_intake.adapters.gmail.MailIntakeAdapter.fetch_thread",
"signature": "<bound method Alias.signature of Alias('fetch_thread', 'mail_intake.adapters.base.MailIntakeAdapter.fetch_thread')>",
"docstring": "Fetch a full raw thread by thread identifier.\n\nArgs:\n thread_id (str):\n Provider-specific thread identifier.\n\nReturns:\n Dict[str, Any]:\n Provider-native thread payload."
"docstring": "Fetch a full raw thread by thread identifier.\n\nArgs:\n thread_id (str):\n Provider-specific thread identifier.\n\nReturns:\n dict[str, Any]:\n Provider-native thread payload."
}
}
},
"MailIntakeAdapterError": {
"name": "MailIntakeAdapterError",
"kind": "class",
"path": "mail_intake.adapters.gmail.MailIntakeAdapterError",
"signature": "<bound method Alias.signature of Alias('MailIntakeAdapterError', 'mail_intake.exceptions.MailIntakeAdapterError')>",
"docstring": "Errors raised by mail provider adapters.\n\nNotes:\n **Lifecycle:**\n\n - Raised when a provider adapter encounters API errors, transport\n failures, or invalid provider responses."
},
"MailIntakeAuthProvider": {
"name": "MailIntakeAuthProvider",
"kind": "class",
@@ -240,11 +219,18 @@
}
}
},
"MailIntakeAdapterError": {
"name": "MailIntakeAdapterError",
"kind": "class",
"path": "mail_intake.adapters.gmail.MailIntakeAdapterError",
"signature": "<bound method Alias.signature of Alias('MailIntakeAdapterError', 'mail_intake.exceptions.MailIntakeAdapterError')>",
"docstring": "Errors raised by mail provider adapters.\n\nNotes:\n **Lifecycle:**\n\n - Raised when a provider adapter encounters API errors, transport\n failures, or invalid provider responses."
},
"MailIntakeGmailAdapter": {
"name": "MailIntakeGmailAdapter",
"kind": "class",
"path": "mail_intake.adapters.gmail.MailIntakeGmailAdapter",
"signature": "<bound method Class.signature of Class('MailIntakeGmailAdapter', 28, 189)>",
"signature": "<bound method Class.signature of Class('MailIntakeGmailAdapter', 29, 180)>",
"docstring": "Gmail read-only adapter.\n\nThis adapter implements the `MailIntakeAdapter` interface using the\nGmail REST API. It translates the generic mail intake contract into\nGmail-specific API calls.\n\nNotes:\n **Responsibilities:**\n\n - This class is the ONLY place where `googleapiclient` is imported.\n - Gmail REST semantics are known.\n - `.execute()` is called.\n\n **Constraints:**\n\n - Must remain thin and imperative.\n - Must not perform parsing or interpretation.\n - Must not expose Gmail-specific types beyond this class.",
"members": {
"service": {
@@ -252,28 +238,28 @@
"kind": "attribute",
"path": "mail_intake.adapters.gmail.MailIntakeGmailAdapter.service",
"signature": null,
"docstring": "Lazily initialize and return the Gmail API service client.\n\nReturns:\n Any:\n Initialized Gmail API service instance.\n\nRaises:\n MailIntakeAdapterError:\n If the Gmail service cannot be initialized."
"docstring": "Lazily initialize and return the Gmail API service client.\n\nRaises:\n MailIntakeAdapterError:\n If the Gmail service cannot be initialized."
},
"iter_message_refs": {
"name": "iter_message_refs",
"kind": "function",
"path": "mail_intake.adapters.gmail.MailIntakeGmailAdapter.iter_message_refs",
"signature": "<bound method Function.signature of Function('iter_message_refs', 92, 133)>",
"docstring": "Iterate over message references matching the query.\n\nArgs:\n query (str):\n Gmail search query string.\n\nYields:\n Dict[str, str]:\n Dictionaries containing ``message_id`` and ``thread_id``.\n\nRaises:\n MailIntakeAdapterError:\n If the Gmail API returns an error."
"signature": "<bound method Function.signature of Function('iter_message_refs', 89, 124)>",
"docstring": "Iterate over message references matching the query.\n\nArgs:\n query (str):\n Gmail search query string.\n\nYields:\n dict[str, str]:\n Dictionaries containing ``message_id`` and ``thread_id``.\n\nRaises:\n MailIntakeAdapterError:\n If the Gmail API returns an error."
},
"fetch_message": {
"name": "fetch_message",
"kind": "function",
"path": "mail_intake.adapters.gmail.MailIntakeGmailAdapter.fetch_message",
"signature": "<bound method Function.signature of Function('fetch_message', 135, 161)>",
"docstring": "Fetch a full Gmail message by message ID.\n\nArgs:\n message_id (str):\n Gmail message identifier.\n\nReturns:\n Dict[str, Any]:\n Provider-native Gmail message payload.\n\nRaises:\n MailIntakeAdapterError:\n If the Gmail API returns an error."
"signature": "<bound method Function.signature of Function('fetch_message', 126, 152)>",
"docstring": "Fetch a full Gmail message by message ID.\n\nArgs:\n message_id (str):\n Gmail message identifier.\n\nReturns:\n dict[str, Any]:\n Provider-native Gmail message payload.\n\nRaises:\n MailIntakeAdapterError:\n If the Gmail API returns an error."
},
"fetch_thread": {
"name": "fetch_thread",
"kind": "function",
"path": "mail_intake.adapters.gmail.MailIntakeGmailAdapter.fetch_thread",
"signature": "<bound method Function.signature of Function('fetch_thread', 163, 189)>",
"docstring": "Fetch a full Gmail thread by thread ID.\n\nArgs:\n thread_id (str):\n Gmail thread identifier.\n\nReturns:\n Dict[str, Any]:\n Provider-native Gmail thread payload.\n\nRaises:\n MailIntakeAdapterError:\n If the Gmail API returns an error."
"signature": "<bound method Function.signature of Function('fetch_thread', 154, 180)>",
"docstring": "Fetch a full Gmail thread by thread ID.\n\nArgs:\n thread_id (str):\n Gmail thread identifier.\n\nReturns:\n dict[str, Any]:\n Provider-native Gmail thread payload.\n\nRaises:\n MailIntakeAdapterError:\n If the Gmail API returns an error."
}
}
}

View File

@@ -15,7 +15,7 @@
"name": "Sequence",
"kind": "alias",
"path": "mail_intake.auth.google.Sequence",
"signature": "<bound method Alias.signature of Alias('Sequence', 'typing.Sequence')>",
"signature": "<bound method Alias.signature of Alias('Sequence', 'collections.abc.Sequence')>",
"docstring": null
},
"google": {
@@ -32,13 +32,6 @@
"signature": "<bound method Alias.signature of Alias('Request', 'google.auth.transport.requests.Request')>",
"docstring": null
},
"InstalledAppFlow": {
"name": "InstalledAppFlow",
"kind": "alias",
"path": "mail_intake.auth.google.InstalledAppFlow",
"signature": "<bound method Alias.signature of Alias('InstalledAppFlow', 'google_auth_oauthlib.flow.InstalledAppFlow')>",
"docstring": null
},
"Credentials": {
"name": "Credentials",
"kind": "alias",
@@ -46,6 +39,13 @@
"signature": "<bound method Alias.signature of Alias('Credentials', 'google.oauth2.credentials.Credentials')>",
"docstring": null
},
"InstalledAppFlow": {
"name": "InstalledAppFlow",
"kind": "alias",
"path": "mail_intake.auth.google.InstalledAppFlow",
"signature": "<bound method Alias.signature of Alias('InstalledAppFlow', 'google_auth_oauthlib.flow.InstalledAppFlow')>",
"docstring": null
},
"MailIntakeAuthProvider": {
"name": "MailIntakeAuthProvider",
"kind": "class",
@@ -74,7 +74,7 @@
"kind": "function",
"path": "mail_intake.auth.google.CredentialStore.load",
"signature": "<bound method Alias.signature of Alias('load', 'mail_intake.credentials.store.CredentialStore.load')>",
"docstring": "Load previously persisted credentials.\n\nReturns:\n Optional[T]:\n An instance of type `T` if credentials are available and\n loadable; otherwise `None`.\n\nNotes:\n **Guarantees:**\n\n - Implementations should return `None` when no credentials are\n present or when stored credentials cannot be successfully\n decoded or deserialized.\n - The store must not attempt to validate, refresh, or otherwise\n interpret the returned credentials."
"docstring": "Load previously persisted credentials.\n\nReturns:\n T | None:\n An instance of type `T` if credentials are available and\n loadable; otherwise `None`.\n\nNotes:\n **Guarantees:**\n\n - Implementations should return `None` when no credentials are\n present or when stored credentials cannot be successfully\n decoded or deserialized.\n - The store must not attempt to validate, refresh, or otherwise\n interpret the returned credentials."
},
"save": {
"name": "save",

View File

@@ -135,7 +135,7 @@
"name": "Sequence",
"kind": "alias",
"path": "mail_intake.auth.google.Sequence",
"signature": "<bound method Alias.signature of Alias('Sequence', 'typing.Sequence')>",
"signature": "<bound method Alias.signature of Alias('Sequence', 'collections.abc.Sequence')>",
"docstring": null
},
"google": {
@@ -152,13 +152,6 @@
"signature": "<bound method Alias.signature of Alias('Request', 'google.auth.transport.requests.Request')>",
"docstring": null
},
"InstalledAppFlow": {
"name": "InstalledAppFlow",
"kind": "alias",
"path": "mail_intake.auth.google.InstalledAppFlow",
"signature": "<bound method Alias.signature of Alias('InstalledAppFlow', 'google_auth_oauthlib.flow.InstalledAppFlow')>",
"docstring": null
},
"Credentials": {
"name": "Credentials",
"kind": "alias",
@@ -166,6 +159,13 @@
"signature": "<bound method Alias.signature of Alias('Credentials', 'google.oauth2.credentials.Credentials')>",
"docstring": null
},
"InstalledAppFlow": {
"name": "InstalledAppFlow",
"kind": "alias",
"path": "mail_intake.auth.google.InstalledAppFlow",
"signature": "<bound method Alias.signature of Alias('InstalledAppFlow', 'google_auth_oauthlib.flow.InstalledAppFlow')>",
"docstring": null
},
"MailIntakeAuthProvider": {
"name": "MailIntakeAuthProvider",
"kind": "class",
@@ -194,7 +194,7 @@
"kind": "function",
"path": "mail_intake.auth.google.CredentialStore.load",
"signature": "<bound method Alias.signature of Alias('load', 'mail_intake.credentials.store.CredentialStore.load')>",
"docstring": "Load previously persisted credentials.\n\nReturns:\n Optional[T]:\n An instance of type `T` if credentials are available and\n loadable; otherwise `None`.\n\nNotes:\n **Guarantees:**\n\n - Implementations should return `None` when no credentials are\n present or when stored credentials cannot be successfully\n decoded or deserialized.\n - The store must not attempt to validate, refresh, or otherwise\n interpret the returned credentials."
"docstring": "Load previously persisted credentials.\n\nReturns:\n T | None:\n An instance of type `T` if credentials are available and\n loadable; otherwise `None`.\n\nNotes:\n **Guarantees:**\n\n - Implementations should return `None` when no credentials are\n present or when stored credentials cannot be successfully\n decoded or deserialized.\n - The store must not attempt to validate, refresh, or otherwise\n interpret the returned credentials."
},
"save": {
"name": "save",

View File

@@ -11,18 +11,11 @@
"signature": "<bound method Alias.signature of Alias('dataclass', 'dataclasses.dataclass')>",
"docstring": null
},
"Optional": {
"name": "Optional",
"kind": "alias",
"path": "mail_intake.config.Optional",
"signature": "<bound method Alias.signature of Alias('Optional', 'typing.Optional')>",
"docstring": null
},
"MailIntakeConfig": {
"name": "MailIntakeConfig",
"kind": "class",
"path": "mail_intake.config.MailIntakeConfig",
"signature": "<bound method Class.signature of Class('MailIntakeConfig', 18, 57)>",
"signature": "<bound method Class.signature of Class('MailIntakeConfig', 17, 56)>",
"docstring": "Global configuration for `mail-intake`.\n\nNotes:\n **Guarantees:**\n\n - This configuration is intentionally explicit and immutable.\n - No implicit environment reads or global state.\n - Explicit configuration over implicit defaults.\n - No direct environment or filesystem access.\n - This model is safe to pass across layers and suitable for\n serialization.",
"members": {
"provider": {

View File

@@ -16,7 +16,7 @@
"kind": "function",
"path": "mail_intake.credentials.CredentialStore.load",
"signature": "<bound method Alias.signature of Alias('load', 'mail_intake.credentials.store.CredentialStore.load')>",
"docstring": "Load previously persisted credentials.\n\nReturns:\n Optional[T]:\n An instance of type `T` if credentials are available and\n loadable; otherwise `None`.\n\nNotes:\n **Guarantees:**\n\n - Implementations should return `None` when no credentials are\n present or when stored credentials cannot be successfully\n decoded or deserialized.\n - The store must not attempt to validate, refresh, or otherwise\n interpret the returned credentials."
"docstring": "Load previously persisted credentials.\n\nReturns:\n T | None:\n An instance of type `T` if credentials are available and\n loadable; otherwise `None`.\n\nNotes:\n **Guarantees:**\n\n - Implementations should return `None` when no credentials are\n present or when stored credentials cannot be successfully\n decoded or deserialized.\n - The store must not attempt to validate, refresh, or otherwise\n interpret the returned credentials."
},
"save": {
"name": "save",
@@ -53,7 +53,7 @@
"kind": "function",
"path": "mail_intake.credentials.PickleCredentialStore.load",
"signature": "<bound method Alias.signature of Alias('load', 'mail_intake.credentials.pickle.PickleCredentialStore.load')>",
"docstring": "Load credentials from the local filesystem.\n\nReturns:\n Optional[T]:\n An instance of type `T` if credentials are present and\n successfully deserialized; otherwise `None`.\n\nNotes:\n **Guarantees:**\n\n - If the credential file does not exist or cannot be successfully\n deserialized, this method returns `None`.\n - The store does not attempt to validate or interpret the\n returned credentials."
"docstring": "Load credentials from the local filesystem.\n\nReturns:\n T | None:\n An instance of type `T` if credentials are present and\n successfully deserialized; otherwise `None`.\n\nNotes:\n **Guarantees:**\n\n - If the credential file does not exist or cannot be successfully\n deserialized, this method returns `None`.\n - The store does not attempt to validate or interpret the\n returned credentials."
},
"save": {
"name": "save",
@@ -118,7 +118,7 @@
"kind": "function",
"path": "mail_intake.credentials.RedisCredentialStore.load",
"signature": "<bound method Alias.signature of Alias('load', 'mail_intake.credentials.redis.RedisCredentialStore.load')>",
"docstring": "Load credentials from Redis.\n\nReturns:\n Optional[T]:\n An instance of type `T` if credentials are present and\n successfully deserialized; otherwise `None`.\n\nNotes:\n **Guarantees:**\n\n - If no value exists for the configured key, or if the stored\n payload cannot be successfully deserialized, this method\n returns `None`.\n - The store does not attempt to validate the returned\n credentials or determine whether they are expired or\n otherwise usable."
"docstring": "Load credentials from Redis.\n\nReturns:\n T | None:\n An instance of type `T` if credentials are present and\n successfully deserialized; otherwise `None`.\n\nNotes:\n **Guarantees:**\n\n - If no value exists for the configured key, or if the stored\n payload cannot be successfully deserialized, this method\n returns `None`.\n - The store does not attempt to validate the returned\n credentials or determine whether they are expired or\n otherwise usable."
},
"save": {
"name": "save",
@@ -150,13 +150,6 @@
"signature": "<bound method Alias.signature of Alias('pickle', 'pickle')>",
"docstring": null
},
"Optional": {
"name": "Optional",
"kind": "alias",
"path": "mail_intake.credentials.pickle.Optional",
"signature": "<bound method Alias.signature of Alias('Optional', 'typing.Optional')>",
"docstring": null
},
"TypeVar": {
"name": "TypeVar",
"kind": "alias",
@@ -176,7 +169,7 @@
"kind": "function",
"path": "mail_intake.credentials.pickle.CredentialStore.load",
"signature": "<bound method Alias.signature of Alias('load', 'mail_intake.credentials.store.CredentialStore.load')>",
"docstring": "Load previously persisted credentials.\n\nReturns:\n Optional[T]:\n An instance of type `T` if credentials are available and\n loadable; otherwise `None`.\n\nNotes:\n **Guarantees:**\n\n - Implementations should return `None` when no credentials are\n present or when stored credentials cannot be successfully\n decoded or deserialized.\n - The store must not attempt to validate, refresh, or otherwise\n interpret the returned credentials."
"docstring": "Load previously persisted credentials.\n\nReturns:\n T | None:\n An instance of type `T` if credentials are available and\n loadable; otherwise `None`.\n\nNotes:\n **Guarantees:**\n\n - Implementations should return `None` when no credentials are\n present or when stored credentials cannot be successfully\n decoded or deserialized.\n - The store must not attempt to validate, refresh, or otherwise\n interpret the returned credentials."
},
"save": {
"name": "save",
@@ -220,7 +213,7 @@
"kind": "function",
"path": "mail_intake.credentials.pickle.PickleCredentialStore.load",
"signature": "<bound method Function.signature of Function('load', 58, 79)>",
"docstring": "Load credentials from the local filesystem.\n\nReturns:\n Optional[T]:\n An instance of type `T` if credentials are present and\n successfully deserialized; otherwise `None`.\n\nNotes:\n **Guarantees:**\n\n - If the credential file does not exist or cannot be successfully\n deserialized, this method returns `None`.\n - The store does not attempt to validate or interpret the\n returned credentials."
"docstring": "Load credentials from the local filesystem.\n\nReturns:\n T | None:\n An instance of type `T` if credentials are present and\n successfully deserialized; otherwise `None`.\n\nNotes:\n **Guarantees:**\n\n - If the credential file does not exist or cannot be successfully\n deserialized, this method returns `None`.\n - The store does not attempt to validate or interpret the\n returned credentials."
},
"save": {
"name": "save",
@@ -247,11 +240,18 @@
"signature": null,
"docstring": "# Summary\n\nRedis-backed credential persistence for Mail Intake.\n\nThis module provides a Redis-based implementation of the\n`CredentialStore` abstraction, enabling credential persistence\nacross distributed and horizontally scaled deployments.\n\nThe Redis credential store is designed for environments where\nauthentication credentials must be shared safely across multiple\nprocesses, containers, or nodes, such as container orchestration\nplatforms and microservice architectures.\n\nKey characteristics:\n\n- Distributed-safe, shared storage using Redis.\n- Explicit, caller-defined serialization and deserialization.\n- No reliance on unsafe mechanisms such as `pickle`.\n- Optional time-to-live (TTL) support for automatic credential expiry.\n\nThis module is responsible solely for persistence concerns.\nCredential validation, refresh, rotation, and acquisition remain the\nresponsibility of authentication provider implementations.",
"members": {
"Optional": {
"name": "Optional",
"Callable": {
"name": "Callable",
"kind": "alias",
"path": "mail_intake.credentials.redis.Optional",
"signature": "<bound method Alias.signature of Alias('Optional', 'typing.Optional')>",
"path": "mail_intake.credentials.redis.Callable",
"signature": "<bound method Alias.signature of Alias('Callable', 'collections.abc.Callable')>",
"docstring": null
},
"Any": {
"name": "Any",
"kind": "alias",
"path": "mail_intake.credentials.redis.Any",
"signature": "<bound method Alias.signature of Alias('Any', 'typing.Any')>",
"docstring": null
},
"TypeVar": {
@@ -261,13 +261,6 @@
"signature": "<bound method Alias.signature of Alias('TypeVar', 'typing.TypeVar')>",
"docstring": null
},
"Callable": {
"name": "Callable",
"kind": "alias",
"path": "mail_intake.credentials.redis.Callable",
"signature": "<bound method Alias.signature of Alias('Callable', 'typing.Callable')>",
"docstring": null
},
"CredentialStore": {
"name": "CredentialStore",
"kind": "class",
@@ -280,7 +273,7 @@
"kind": "function",
"path": "mail_intake.credentials.redis.CredentialStore.load",
"signature": "<bound method Alias.signature of Alias('load', 'mail_intake.credentials.store.CredentialStore.load')>",
"docstring": "Load previously persisted credentials.\n\nReturns:\n Optional[T]:\n An instance of type `T` if credentials are available and\n loadable; otherwise `None`.\n\nNotes:\n **Guarantees:**\n\n - Implementations should return `None` when no credentials are\n present or when stored credentials cannot be successfully\n decoded or deserialized.\n - The store must not attempt to validate, refresh, or otherwise\n interpret the returned credentials."
"docstring": "Load previously persisted credentials.\n\nReturns:\n T | None:\n An instance of type `T` if credentials are available and\n loadable; otherwise `None`.\n\nNotes:\n **Guarantees:**\n\n - Implementations should return `None` when no credentials are\n present or when stored credentials cannot be successfully\n decoded or deserialized.\n - The store must not attempt to validate, refresh, or otherwise\n interpret the returned credentials."
},
"save": {
"name": "save",
@@ -309,7 +302,7 @@
"name": "RedisCredentialStore",
"kind": "class",
"path": "mail_intake.credentials.redis.RedisCredentialStore",
"signature": "<bound method Class.signature of Class('RedisCredentialStore', 35, 148)>",
"signature": "<bound method Class.signature of Class('RedisCredentialStore', 35, 145)>",
"docstring": "Redis-backed implementation of `CredentialStore`.\n\nThis store persists credentials in Redis and is suitable for\ndistributed and horizontally scaled deployments where credentials\nmust be shared across multiple processes or nodes.\n\nNotes:\n **Responsibilities:**\n\n - This class is responsible only for persistence and retrieval.\n - It does not interpret, validate, refresh, or otherwise manage the\n lifecycle of the credentials being stored.\n\n **Guarantees:**\n\n - The store is intentionally generic and delegates all serialization\n concerns to caller-provided functions.\n - This avoids unsafe mechanisms such as `pickle` and allows\n credential formats to be explicitly controlled and audited.",
"members": {
"redis": {
@@ -351,31 +344,24 @@
"name": "load",
"kind": "function",
"path": "mail_intake.credentials.redis.RedisCredentialStore.load",
"signature": "<bound method Function.signature of Function('load', 91, 116)>",
"docstring": "Load credentials from Redis.\n\nReturns:\n Optional[T]:\n An instance of type `T` if credentials are present and\n successfully deserialized; otherwise `None`.\n\nNotes:\n **Guarantees:**\n\n - If no value exists for the configured key, or if the stored\n payload cannot be successfully deserialized, this method\n returns `None`.\n - The store does not attempt to validate the returned\n credentials or determine whether they are expired or\n otherwise usable."
"signature": "<bound method Function.signature of Function('load', 88, 113)>",
"docstring": "Load credentials from Redis.\n\nReturns:\n T | None:\n An instance of type `T` if credentials are present and\n successfully deserialized; otherwise `None`.\n\nNotes:\n **Guarantees:**\n\n - If no value exists for the configured key, or if the stored\n payload cannot be successfully deserialized, this method\n returns `None`.\n - The store does not attempt to validate the returned\n credentials or determine whether they are expired or\n otherwise usable."
},
"save": {
"name": "save",
"kind": "function",
"path": "mail_intake.credentials.redis.RedisCredentialStore.save",
"signature": "<bound method Function.signature of Function('save', 118, 136)>",
"signature": "<bound method Function.signature of Function('save', 115, 133)>",
"docstring": "Persist credentials to Redis.\n\nArgs:\n credentials (T):\n The credential object to persist.\n\nNotes:\n **Responsibilities:**\n\n - Any previously stored credentials under the same key are overwritten\n - If a TTL is configured, the credentials will expire automatically after the specified duration"
},
"clear": {
"name": "clear",
"kind": "function",
"path": "mail_intake.credentials.redis.RedisCredentialStore.clear",
"signature": "<bound method Function.signature of Function('clear', 138, 148)>",
"signature": "<bound method Function.signature of Function('clear', 135, 145)>",
"docstring": "Remove stored credentials from Redis.\n\nNotes:\n **Lifecycle:**\n\n - This operation deletes the configured Redis key if it exists\n - Implementations should treat this method as idempotent"
}
}
},
"Any": {
"name": "Any",
"kind": "alias",
"path": "mail_intake.credentials.redis.Any",
"signature": "<bound method Alias.signature of Alias('Any', 'typing.Any')>",
"docstring": null
}
}
},
@@ -407,13 +393,6 @@
"signature": "<bound method Alias.signature of Alias('Generic', 'typing.Generic')>",
"docstring": null
},
"Optional": {
"name": "Optional",
"kind": "alias",
"path": "mail_intake.credentials.store.Optional",
"signature": "<bound method Alias.signature of Alias('Optional', 'typing.Optional')>",
"docstring": null
},
"TypeVar": {
"name": "TypeVar",
"kind": "alias",
@@ -432,28 +411,28 @@
"name": "CredentialStore",
"kind": "class",
"path": "mail_intake.credentials.store.CredentialStore",
"signature": "<bound method Class.signature of Class('CredentialStore', 29, 105)>",
"signature": "<bound method Class.signature of Class('CredentialStore', 28, 104)>",
"docstring": "Abstract base class defining a generic persistence interface.\n\nUsed for authentication credentials across different backends.\n\nNotes:\n **Responsibilities:**\n\n - Provide persistent storage separating life-cycle management from\n storage mechanics.\n - Keep implementation focused only on persistence.\n\n **Constraints:**\n\n - The store is intentionally agnostic to:\n - The concrete credential type being stored.\n - The serialization format used to persist credentials.\n - The underlying storage backend or durability guarantees.",
"members": {
"load": {
"name": "load",
"kind": "function",
"path": "mail_intake.credentials.store.CredentialStore.load",
"signature": "<bound method Function.signature of Function('load', 50, 68)>",
"docstring": "Load previously persisted credentials.\n\nReturns:\n Optional[T]:\n An instance of type `T` if credentials are available and\n loadable; otherwise `None`.\n\nNotes:\n **Guarantees:**\n\n - Implementations should return `None` when no credentials are\n present or when stored credentials cannot be successfully\n decoded or deserialized.\n - The store must not attempt to validate, refresh, or otherwise\n interpret the returned credentials."
"signature": "<bound method Function.signature of Function('load', 49, 67)>",
"docstring": "Load previously persisted credentials.\n\nReturns:\n T | None:\n An instance of type `T` if credentials are available and\n loadable; otherwise `None`.\n\nNotes:\n **Guarantees:**\n\n - Implementations should return `None` when no credentials are\n present or when stored credentials cannot be successfully\n decoded or deserialized.\n - The store must not attempt to validate, refresh, or otherwise\n interpret the returned credentials."
},
"save": {
"name": "save",
"kind": "function",
"path": "mail_intake.credentials.store.CredentialStore.save",
"signature": "<bound method Function.signature of Function('save', 70, 89)>",
"signature": "<bound method Function.signature of Function('save', 69, 88)>",
"docstring": "Persist credentials to the underlying storage backend.\n\nArgs:\n credentials (T):\n The credential object to persist.\n\nNotes:\n **Lifecycle:**\n\n - This method is invoked when credentials are newly obtained or have been refreshed and are known to be valid at the time of persistence\n\n **Responsibilities:**\n\n - Ensuring durability appropriate to the deployment context\n - Applying encryption or access controls where required\n - Overwriting any previously stored credentials"
},
"clear": {
"name": "clear",
"kind": "function",
"path": "mail_intake.credentials.store.CredentialStore.clear",
"signature": "<bound method Function.signature of Function('clear', 91, 105)>",
"signature": "<bound method Function.signature of Function('clear', 90, 104)>",
"docstring": "Remove any persisted credentials from the store.\n\nNotes:\n **Lifecycle:**\n\n - This method is called when credentials are known to be invalid, revoked, corrupted, or otherwise unusable\n - Must ensure that no stale authentication material remains accessible\n\n **Guarantees:**\n\n - Implementations should treat this operation as idempotent"
}
}

View File

@@ -11,13 +11,6 @@
"signature": "<bound method Alias.signature of Alias('pickle', 'pickle')>",
"docstring": null
},
"Optional": {
"name": "Optional",
"kind": "alias",
"path": "mail_intake.credentials.pickle.Optional",
"signature": "<bound method Alias.signature of Alias('Optional', 'typing.Optional')>",
"docstring": null
},
"TypeVar": {
"name": "TypeVar",
"kind": "alias",
@@ -37,7 +30,7 @@
"kind": "function",
"path": "mail_intake.credentials.pickle.CredentialStore.load",
"signature": "<bound method Alias.signature of Alias('load', 'mail_intake.credentials.store.CredentialStore.load')>",
"docstring": "Load previously persisted credentials.\n\nReturns:\n Optional[T]:\n An instance of type `T` if credentials are available and\n loadable; otherwise `None`.\n\nNotes:\n **Guarantees:**\n\n - Implementations should return `None` when no credentials are\n present or when stored credentials cannot be successfully\n decoded or deserialized.\n - The store must not attempt to validate, refresh, or otherwise\n interpret the returned credentials."
"docstring": "Load previously persisted credentials.\n\nReturns:\n T | None:\n An instance of type `T` if credentials are available and\n loadable; otherwise `None`.\n\nNotes:\n **Guarantees:**\n\n - Implementations should return `None` when no credentials are\n present or when stored credentials cannot be successfully\n decoded or deserialized.\n - The store must not attempt to validate, refresh, or otherwise\n interpret the returned credentials."
},
"save": {
"name": "save",
@@ -81,7 +74,7 @@
"kind": "function",
"path": "mail_intake.credentials.pickle.PickleCredentialStore.load",
"signature": "<bound method Function.signature of Function('load', 58, 79)>",
"docstring": "Load credentials from the local filesystem.\n\nReturns:\n Optional[T]:\n An instance of type `T` if credentials are present and\n successfully deserialized; otherwise `None`.\n\nNotes:\n **Guarantees:**\n\n - If the credential file does not exist or cannot be successfully\n deserialized, this method returns `None`.\n - The store does not attempt to validate or interpret the\n returned credentials."
"docstring": "Load credentials from the local filesystem.\n\nReturns:\n T | None:\n An instance of type `T` if credentials are present and\n successfully deserialized; otherwise `None`.\n\nNotes:\n **Guarantees:**\n\n - If the credential file does not exist or cannot be successfully\n deserialized, this method returns `None`.\n - The store does not attempt to validate or interpret the\n returned credentials."
},
"save": {
"name": "save",

View File

@@ -4,11 +4,18 @@
"path": "mail_intake.credentials.redis",
"docstring": "# Summary\n\nRedis-backed credential persistence for Mail Intake.\n\nThis module provides a Redis-based implementation of the\n`CredentialStore` abstraction, enabling credential persistence\nacross distributed and horizontally scaled deployments.\n\nThe Redis credential store is designed for environments where\nauthentication credentials must be shared safely across multiple\nprocesses, containers, or nodes, such as container orchestration\nplatforms and microservice architectures.\n\nKey characteristics:\n\n- Distributed-safe, shared storage using Redis.\n- Explicit, caller-defined serialization and deserialization.\n- No reliance on unsafe mechanisms such as `pickle`.\n- Optional time-to-live (TTL) support for automatic credential expiry.\n\nThis module is responsible solely for persistence concerns.\nCredential validation, refresh, rotation, and acquisition remain the\nresponsibility of authentication provider implementations.",
"objects": {
"Optional": {
"name": "Optional",
"Callable": {
"name": "Callable",
"kind": "alias",
"path": "mail_intake.credentials.redis.Optional",
"signature": "<bound method Alias.signature of Alias('Optional', 'typing.Optional')>",
"path": "mail_intake.credentials.redis.Callable",
"signature": "<bound method Alias.signature of Alias('Callable', 'collections.abc.Callable')>",
"docstring": null
},
"Any": {
"name": "Any",
"kind": "alias",
"path": "mail_intake.credentials.redis.Any",
"signature": "<bound method Alias.signature of Alias('Any', 'typing.Any')>",
"docstring": null
},
"TypeVar": {
@@ -18,13 +25,6 @@
"signature": "<bound method Alias.signature of Alias('TypeVar', 'typing.TypeVar')>",
"docstring": null
},
"Callable": {
"name": "Callable",
"kind": "alias",
"path": "mail_intake.credentials.redis.Callable",
"signature": "<bound method Alias.signature of Alias('Callable', 'typing.Callable')>",
"docstring": null
},
"CredentialStore": {
"name": "CredentialStore",
"kind": "class",
@@ -37,7 +37,7 @@
"kind": "function",
"path": "mail_intake.credentials.redis.CredentialStore.load",
"signature": "<bound method Alias.signature of Alias('load', 'mail_intake.credentials.store.CredentialStore.load')>",
"docstring": "Load previously persisted credentials.\n\nReturns:\n Optional[T]:\n An instance of type `T` if credentials are available and\n loadable; otherwise `None`.\n\nNotes:\n **Guarantees:**\n\n - Implementations should return `None` when no credentials are\n present or when stored credentials cannot be successfully\n decoded or deserialized.\n - The store must not attempt to validate, refresh, or otherwise\n interpret the returned credentials."
"docstring": "Load previously persisted credentials.\n\nReturns:\n T | None:\n An instance of type `T` if credentials are available and\n loadable; otherwise `None`.\n\nNotes:\n **Guarantees:**\n\n - Implementations should return `None` when no credentials are\n present or when stored credentials cannot be successfully\n decoded or deserialized.\n - The store must not attempt to validate, refresh, or otherwise\n interpret the returned credentials."
},
"save": {
"name": "save",
@@ -66,7 +66,7 @@
"name": "RedisCredentialStore",
"kind": "class",
"path": "mail_intake.credentials.redis.RedisCredentialStore",
"signature": "<bound method Class.signature of Class('RedisCredentialStore', 35, 148)>",
"signature": "<bound method Class.signature of Class('RedisCredentialStore', 35, 145)>",
"docstring": "Redis-backed implementation of `CredentialStore`.\n\nThis store persists credentials in Redis and is suitable for\ndistributed and horizontally scaled deployments where credentials\nmust be shared across multiple processes or nodes.\n\nNotes:\n **Responsibilities:**\n\n - This class is responsible only for persistence and retrieval.\n - It does not interpret, validate, refresh, or otherwise manage the\n lifecycle of the credentials being stored.\n\n **Guarantees:**\n\n - The store is intentionally generic and delegates all serialization\n concerns to caller-provided functions.\n - This avoids unsafe mechanisms such as `pickle` and allows\n credential formats to be explicitly controlled and audited.",
"members": {
"redis": {
@@ -108,31 +108,24 @@
"name": "load",
"kind": "function",
"path": "mail_intake.credentials.redis.RedisCredentialStore.load",
"signature": "<bound method Function.signature of Function('load', 91, 116)>",
"docstring": "Load credentials from Redis.\n\nReturns:\n Optional[T]:\n An instance of type `T` if credentials are present and\n successfully deserialized; otherwise `None`.\n\nNotes:\n **Guarantees:**\n\n - If no value exists for the configured key, or if the stored\n payload cannot be successfully deserialized, this method\n returns `None`.\n - The store does not attempt to validate the returned\n credentials or determine whether they are expired or\n otherwise usable."
"signature": "<bound method Function.signature of Function('load', 88, 113)>",
"docstring": "Load credentials from Redis.\n\nReturns:\n T | None:\n An instance of type `T` if credentials are present and\n successfully deserialized; otherwise `None`.\n\nNotes:\n **Guarantees:**\n\n - If no value exists for the configured key, or if the stored\n payload cannot be successfully deserialized, this method\n returns `None`.\n - The store does not attempt to validate the returned\n credentials or determine whether they are expired or\n otherwise usable."
},
"save": {
"name": "save",
"kind": "function",
"path": "mail_intake.credentials.redis.RedisCredentialStore.save",
"signature": "<bound method Function.signature of Function('save', 118, 136)>",
"signature": "<bound method Function.signature of Function('save', 115, 133)>",
"docstring": "Persist credentials to Redis.\n\nArgs:\n credentials (T):\n The credential object to persist.\n\nNotes:\n **Responsibilities:**\n\n - Any previously stored credentials under the same key are overwritten\n - If a TTL is configured, the credentials will expire automatically after the specified duration"
},
"clear": {
"name": "clear",
"kind": "function",
"path": "mail_intake.credentials.redis.RedisCredentialStore.clear",
"signature": "<bound method Function.signature of Function('clear', 138, 148)>",
"signature": "<bound method Function.signature of Function('clear', 135, 145)>",
"docstring": "Remove stored credentials from Redis.\n\nNotes:\n **Lifecycle:**\n\n - This operation deletes the configured Redis key if it exists\n - Implementations should treat this method as idempotent"
}
}
},
"Any": {
"name": "Any",
"kind": "alias",
"path": "mail_intake.credentials.redis.Any",
"signature": "<bound method Alias.signature of Alias('Any', 'typing.Any')>",
"docstring": null
}
}
}

View File

@@ -25,13 +25,6 @@
"signature": "<bound method Alias.signature of Alias('Generic', 'typing.Generic')>",
"docstring": null
},
"Optional": {
"name": "Optional",
"kind": "alias",
"path": "mail_intake.credentials.store.Optional",
"signature": "<bound method Alias.signature of Alias('Optional', 'typing.Optional')>",
"docstring": null
},
"TypeVar": {
"name": "TypeVar",
"kind": "alias",
@@ -50,28 +43,28 @@
"name": "CredentialStore",
"kind": "class",
"path": "mail_intake.credentials.store.CredentialStore",
"signature": "<bound method Class.signature of Class('CredentialStore', 29, 105)>",
"signature": "<bound method Class.signature of Class('CredentialStore', 28, 104)>",
"docstring": "Abstract base class defining a generic persistence interface.\n\nUsed for authentication credentials across different backends.\n\nNotes:\n **Responsibilities:**\n\n - Provide persistent storage separating life-cycle management from\n storage mechanics.\n - Keep implementation focused only on persistence.\n\n **Constraints:**\n\n - The store is intentionally agnostic to:\n - The concrete credential type being stored.\n - The serialization format used to persist credentials.\n - The underlying storage backend or durability guarantees.",
"members": {
"load": {
"name": "load",
"kind": "function",
"path": "mail_intake.credentials.store.CredentialStore.load",
"signature": "<bound method Function.signature of Function('load', 50, 68)>",
"docstring": "Load previously persisted credentials.\n\nReturns:\n Optional[T]:\n An instance of type `T` if credentials are available and\n loadable; otherwise `None`.\n\nNotes:\n **Guarantees:**\n\n - Implementations should return `None` when no credentials are\n present or when stored credentials cannot be successfully\n decoded or deserialized.\n - The store must not attempt to validate, refresh, or otherwise\n interpret the returned credentials."
"signature": "<bound method Function.signature of Function('load', 49, 67)>",
"docstring": "Load previously persisted credentials.\n\nReturns:\n T | None:\n An instance of type `T` if credentials are available and\n loadable; otherwise `None`.\n\nNotes:\n **Guarantees:**\n\n - Implementations should return `None` when no credentials are\n present or when stored credentials cannot be successfully\n decoded or deserialized.\n - The store must not attempt to validate, refresh, or otherwise\n interpret the returned credentials."
},
"save": {
"name": "save",
"kind": "function",
"path": "mail_intake.credentials.store.CredentialStore.save",
"signature": "<bound method Function.signature of Function('save', 70, 89)>",
"signature": "<bound method Function.signature of Function('save', 69, 88)>",
"docstring": "Persist credentials to the underlying storage backend.\n\nArgs:\n credentials (T):\n The credential object to persist.\n\nNotes:\n **Lifecycle:**\n\n - This method is invoked when credentials are newly obtained or have been refreshed and are known to be valid at the time of persistence\n\n **Responsibilities:**\n\n - Ensuring durability appropriate to the deployment context\n - Applying encryption or access controls where required\n - Overwriting any previously stored credentials"
},
"clear": {
"name": "clear",
"kind": "function",
"path": "mail_intake.credentials.store.CredentialStore.clear",
"signature": "<bound method Function.signature of Function('clear', 91, 105)>",
"signature": "<bound method Function.signature of Function('clear', 90, 104)>",
"docstring": "Remove any persisted credentials from the store.\n\nNotes:\n **Lifecycle:**\n\n - This method is called when credentials are known to be invalid, revoked, corrupted, or otherwise unusable\n - Must ensure that no stale authentication material remains accessible\n\n **Guarantees:**\n\n - Implementations should treat this operation as idempotent"
}
}

View File

@@ -2,34 +2,34 @@
"module": "mail_intake.exceptions",
"content": {
"path": "mail_intake.exceptions",
"docstring": "Exception hierarchy for Mail Intake.\n\n---\n\n## Summary\n\nThis module defines the **canonical exception types** used throughout the\nMail Intake library.\n\nAll library-raised errors derive from `MailIntakeError`. Consumers are\nencouraged to catch this base type (or specific subclasses) rather than\nprovider-specific or third-party exceptions.",
"docstring": "# Summary\n\nException hierarchy for Mail Intake.\n\nThis module defines the **canonical exception types** used throughout the\nMail Intake library.\n\nAll library-raised errors derive from `MailIntakeError`. Consumers are\nencouraged to catch this base type (or specific subclasses) rather than\nprovider-specific or third-party exceptions.",
"objects": {
"MailIntakeError": {
"name": "MailIntakeError",
"kind": "class",
"path": "mail_intake.exceptions.MailIntakeError",
"signature": "<bound method Class.signature of Class('MailIntakeError', 17, 27)>",
"signature": "<bound method Class.signature of Class('MailIntakeError', 15, 25)>",
"docstring": "Base exception for all Mail Intake errors.\n\nNotes:\n **Guarantees:**\n\n - This is the root of the Mail Intake exception hierarchy\n - All errors raised by the library must derive from this class\n - Consumers should generally catch this type when handling library-level failures"
},
"MailIntakeAuthError": {
"name": "MailIntakeAuthError",
"kind": "class",
"path": "mail_intake.exceptions.MailIntakeAuthError",
"signature": "<bound method Class.signature of Class('MailIntakeAuthError', 30, 39)>",
"signature": "<bound method Class.signature of Class('MailIntakeAuthError', 28, 37)>",
"docstring": "Authentication and credential-related failures.\n\nNotes:\n **Lifecycle:**\n\n - Raised when authentication providers are unable to acquire,\n refresh, or persist valid credentials."
},
"MailIntakeAdapterError": {
"name": "MailIntakeAdapterError",
"kind": "class",
"path": "mail_intake.exceptions.MailIntakeAdapterError",
"signature": "<bound method Class.signature of Class('MailIntakeAdapterError', 42, 51)>",
"signature": "<bound method Class.signature of Class('MailIntakeAdapterError', 40, 49)>",
"docstring": "Errors raised by mail provider adapters.\n\nNotes:\n **Lifecycle:**\n\n - Raised when a provider adapter encounters API errors, transport\n failures, or invalid provider responses."
},
"MailIntakeParsingError": {
"name": "MailIntakeParsingError",
"kind": "class",
"path": "mail_intake.exceptions.MailIntakeParsingError",
"signature": "<bound method Class.signature of Class('MailIntakeParsingError', 54, 63)>",
"signature": "<bound method Class.signature of Class('MailIntakeParsingError', 52, 61)>",
"docstring": "Errors encountered while parsing message content.\n\nNotes:\n **Lifecycle:**\n\n - Raised when raw provider payloads cannot be interpreted or\n normalized into internal domain models."
}
}

View File

@@ -23,7 +23,7 @@
"kind": "function",
"path": "mail_intake.ingestion.MailIntakeReader.iter_threads",
"signature": "<bound method Alias.signature of Alias('iter_threads', 'mail_intake.ingestion.reader.MailIntakeReader.iter_threads')>",
"docstring": "Iterate over threads constructed from messages matching a query.\n\nArgs:\n query (str):\n Provider-specific query string used to filter messages.\n\nYields:\n MailIntakeThread:\n An iterator of `MailIntakeThread` instances.\n\nRaises:\n `MailIntakeParsingError`:\n If a message cannot be parsed.\n\nNotes:\n **Guarantees:**\n\n - Messages are grouped by `thread_id` and yielded as complete\n thread objects containing all associated messages."
"docstring": "Iterate over threads constructed from messages matching a query.\n\nArgs:\n query (str):\n Provider-specific query string used to filter messages.\n\nReturns:\n Iterator[MailIntakeThread]:\n An iterator over `MailIntakeThread` instances.\n\nRaises:\n `MailIntakeParsingError`:\n If a message cannot be parsed.\n\nNotes:\n **Guarantees:**\n\n - Messages are grouped by `thread_id` and yielded as complete\n thread objects containing all associated messages."
}
}
},
@@ -34,6 +34,13 @@
"signature": null,
"docstring": "# Summary\n\nHigh-level mail ingestion orchestration for Mail Intake.\n\nThis module provides the primary, provider-agnostic entry point for\nreading and processing mail data.\n\nIt coordinates:\n\n- Mail adapter access.\n- Message and thread iteration.\n- Header and body parsing.\n- Normalization and model construction.\n\nNo provider-specific logic or API semantics are permitted in this layer.",
"members": {
"Iterator": {
"name": "Iterator",
"kind": "alias",
"path": "mail_intake.ingestion.reader.Iterator",
"signature": "<bound method Alias.signature of Alias('Iterator', 'collections.abc.Iterator')>",
"docstring": null
},
"datetime": {
"name": "datetime",
"kind": "alias",
@@ -41,20 +48,6 @@
"signature": "<bound method Alias.signature of Alias('datetime', 'datetime.datetime')>",
"docstring": null
},
"Iterator": {
"name": "Iterator",
"kind": "alias",
"path": "mail_intake.ingestion.reader.Iterator",
"signature": "<bound method Alias.signature of Alias('Iterator', 'typing.Iterator')>",
"docstring": null
},
"Dict": {
"name": "Dict",
"kind": "alias",
"path": "mail_intake.ingestion.reader.Dict",
"signature": "<bound method Alias.signature of Alias('Dict', 'typing.Dict')>",
"docstring": null
},
"Any": {
"name": "Any",
"kind": "alias",
@@ -74,24 +67,31 @@
"kind": "function",
"path": "mail_intake.ingestion.reader.MailIntakeAdapter.iter_message_refs",
"signature": "<bound method Alias.signature of Alias('iter_message_refs', 'mail_intake.adapters.base.MailIntakeAdapter.iter_message_refs')>",
"docstring": "Iterate over lightweight message references matching a query.\n\nArgs:\n query (str):\n Provider-specific query string used to filter messages.\n\nYields:\n Dict[str, str]:\n Dictionaries containing message and thread identifiers.\n\nNotes:\n **Guarantees:**\n\n - Implementations must yield dictionaries containing at least\n `message_id` and `thread_id`.\n\nExample:\n Typical yield:\n\n ```python\n {\n \"message_id\": \"...\",\n \"thread_id\": \"...\"\n }\n ```"
"docstring": "Iterate over lightweight message references matching a query.\n\nArgs:\n query (str):\n Provider-specific query string used to filter messages.\n\nReturns:\n Iterator[dict[str, str]]:\n An iterator over lightweight message reference dictionaries.\n\nYields:\n dict[str, str]:\n Dictionaries containing message and thread identifiers.\n\nNotes:\n **Guarantees:**\n\n - Implementations must yield dictionaries containing at least\n `message_id` and `thread_id`.\n\nExample:\n Typical yield:\n\n ```python\n {\n \"message_id\": \"...\",\n \"thread_id\": \"...\"\n }\n ```"
},
"fetch_message": {
"name": "fetch_message",
"kind": "function",
"path": "mail_intake.ingestion.reader.MailIntakeAdapter.fetch_message",
"signature": "<bound method Alias.signature of Alias('fetch_message', 'mail_intake.adapters.base.MailIntakeAdapter.fetch_message')>",
"docstring": "Fetch a full raw message by message identifier.\n\nArgs:\n message_id (str):\n Provider-specific message identifier.\n\nReturns:\n Dict[str, Any]:\n Provider-native message payload (e.g., Gmail message JSON structure)."
"docstring": "Fetch a full raw message by message identifier.\n\nArgs:\n message_id (str):\n Provider-specific message identifier.\n\nReturns:\n dict[str, Any]:\n Provider-native message payload (e.g., Gmail message JSON structure)."
},
"fetch_thread": {
"name": "fetch_thread",
"kind": "function",
"path": "mail_intake.ingestion.reader.MailIntakeAdapter.fetch_thread",
"signature": "<bound method Alias.signature of Alias('fetch_thread', 'mail_intake.adapters.base.MailIntakeAdapter.fetch_thread')>",
"docstring": "Fetch a full raw thread by thread identifier.\n\nArgs:\n thread_id (str):\n Provider-specific thread identifier.\n\nReturns:\n Dict[str, Any]:\n Provider-native thread payload."
"docstring": "Fetch a full raw thread by thread identifier.\n\nArgs:\n thread_id (str):\n Provider-specific thread identifier.\n\nReturns:\n dict[str, Any]:\n Provider-native thread payload."
}
}
},
"MailIntakeParsingError": {
"name": "MailIntakeParsingError",
"kind": "class",
"path": "mail_intake.ingestion.reader.MailIntakeParsingError",
"signature": "<bound method Alias.signature of Alias('MailIntakeParsingError', 'mail_intake.exceptions.MailIntakeParsingError')>",
"docstring": "Errors encountered while parsing message content.\n\nNotes:\n **Lifecycle:**\n\n - Raised when raw provider payloads cannot be interpreted or\n normalized into internal domain models."
},
"MailIntakeMessage": {
"name": "MailIntakeMessage",
"kind": "class",
@@ -215,26 +215,26 @@
}
}
},
"parse_headers": {
"name": "parse_headers",
"extract_body": {
"name": "extract_body",
"kind": "function",
"path": "mail_intake.ingestion.reader.parse_headers",
"signature": "<bound method Alias.signature of Alias('parse_headers', 'mail_intake.parsers.headers.parse_headers')>",
"docstring": "Convert a list of Gmail-style headers into a normalized dict.\n\nArgs:\n raw_headers (List[Dict[str, str]]):\n List of header dictionaries, each containing `name` and `value` keys.\n\nReturns:\n Dict[str, str]:\n Dictionary mapping lowercase header names to stripped values.\n\nNotes:\n **Guarantees:**\n\n - Provider payloads (such as Gmail) typically represent headers as a\n list of name/value mappings.\n - This function normalizes them into a case-insensitive dictionary\n keyed by lowercase header names.\n\nExample:\n Typical usage:\n\n ```python\n Input:\n [\n {\"name\": \"From\", \"value\": \"John Doe <john@example.com>\"},\n {\"name\": \"Subject\", \"value\": \"Re: Interview Update\"},\n ]\n\n Output:\n {\n \"from\": \"John Doe <john@example.com>\",\n \"subject\": \"Re: Interview Update\",\n }\n ```"
"path": "mail_intake.ingestion.reader.extract_body",
"signature": "<bound method Alias.signature of Alias('extract_body', 'mail_intake.parsers.body.extract_body')>",
"docstring": "Extract the best-effort message body from a Gmail payload.\n\nPriority:\n\n1. `text/plain`\n2. `text/html` (stripped to text)\n3. Single-part body\n4. Empty string (if nothing usable found)\n\nArgs:\n payload (dict[str, Any]):\n Provider-native message payload dictionary.\n\nReturns:\n str:\n Extracted plain-text message body."
},
"extract_sender": {
"name": "extract_sender",
"kind": "function",
"path": "mail_intake.ingestion.reader.extract_sender",
"signature": "<bound method Alias.signature of Alias('extract_sender', 'mail_intake.parsers.headers.extract_sender')>",
"docstring": "Extract sender email and optional display name from headers.\n\nArgs:\n headers (Dict[str, str]):\n Normalized header dictionary as returned by `parse_headers()`.\n\nReturns:\n Tuple[str, Optional[str]]:\n A tuple `(email, name)` where `email` is the sender email address\n and `name` is the display name, or `None` if unavailable.\n\nNotes:\n **Responsibilities:**\n\n - This function parses the `From` header and attempts to extract\n sender email address and optional human-readable display name.\n\nExample:\n Typical values:\n\n - `\"John Doe <john@example.com>\"` -> `(\"john@example.com\", \"John Doe\")`\n - `\"john@example.com\"` -> `(\"john@example.com\", None)`"
"docstring": "Extract sender email and optional display name from headers.\n\nArgs:\n headers (dict[str, str]):\n Normalized header dictionary as returned by `parse_headers()`.\n\nReturns:\n tuple[str, str | None]:\n A tuple `(email, name)` where `email` is the sender email address\n and `name` is the display name, or `None` if unavailable.\n\nNotes:\n **Responsibilities:**\n\n - This function parses the `From` header and attempts to extract\n sender email address and optional human-readable display name.\n\nExample:\n Typical values:\n\n - `\"John Doe <john@example.com>\"` -> `(\"john@example.com\", \"John Doe\")`\n - `\"john@example.com\"` -> `(\"john@example.com\", None)`"
},
"extract_body": {
"name": "extract_body",
"parse_headers": {
"name": "parse_headers",
"kind": "function",
"path": "mail_intake.ingestion.reader.extract_body",
"signature": "<bound method Alias.signature of Alias('extract_body', 'mail_intake.parsers.body.extract_body')>",
"docstring": "Extract the best-effort message body from a Gmail payload.\n\nPriority:\n\n1. `text/plain`\n2. `text/html` (stripped to text)\n3. Single-part body\n4. Empty string (if nothing usable found)\n\nArgs:\n payload (Dict[str, Any]):\n Provider-native message payload dictionary.\n\nReturns:\n str:\n Extracted plain-text message body."
"path": "mail_intake.ingestion.reader.parse_headers",
"signature": "<bound method Alias.signature of Alias('parse_headers', 'mail_intake.parsers.headers.parse_headers')>",
"docstring": "Convert a list of Gmail-style headers into a normalized dict.\n\nArgs:\n raw_headers (list[dict[str, str]]):\n List of header dictionaries, each containing `name` and `value` keys.\n\nReturns:\n dict[str, str]:\n Dictionary mapping lowercase header names to stripped values.\n\nNotes:\n **Guarantees:**\n\n - Provider payloads (such as Gmail) typically represent headers as a\n list of name/value mappings.\n - This function normalizes them into a case-insensitive dictionary\n keyed by lowercase header names.\n\nExample:\n Typical usage:\n\n ```python\n Input:\n [\n {\"name\": \"From\", \"value\": \"John Doe <john@example.com>\"},\n {\"name\": \"Subject\", \"value\": \"Re: Interview Update\"},\n ]\n\n Output:\n {\n \"from\": \"John Doe <john@example.com>\",\n \"subject\": \"Re: Interview Update\",\n }\n ```"
},
"normalize_subject": {
"name": "normalize_subject",
@@ -243,33 +243,26 @@
"signature": "<bound method Alias.signature of Alias('normalize_subject', 'mail_intake.parsers.subject.normalize_subject')>",
"docstring": "Normalize an email subject for thread-level comparison.\n\nArgs:\n subject (str):\n Raw subject line from a message header.\n\nReturns:\n str:\n Normalized subject string suitable for thread grouping.\n\nNotes:\n **Responsibilities:**\n\n - Strips common prefixes such as `Re:`, `Fwd:`, and `FW:`.\n - Repeats prefix stripping to handle stacked prefixes.\n - Collapses excessive whitespace.\n - Preserves original casing (no lowercasing).\n\n **Guarantees:**\n\n - This function is intentionally conservative and avoids aggressive\n transformations that could alter the semantic meaning of the subject."
},
"MailIntakeParsingError": {
"name": "MailIntakeParsingError",
"kind": "class",
"path": "mail_intake.ingestion.reader.MailIntakeParsingError",
"signature": "<bound method Alias.signature of Alias('MailIntakeParsingError', 'mail_intake.exceptions.MailIntakeParsingError')>",
"docstring": "Errors encountered while parsing message content.\n\nNotes:\n **Lifecycle:**\n\n - Raised when raw provider payloads cannot be interpreted or\n normalized into internal domain models."
},
"MailIntakeReader": {
"name": "MailIntakeReader",
"kind": "class",
"path": "mail_intake.ingestion.reader.MailIntakeReader",
"signature": "<bound method Class.signature of Class('MailIntakeReader', 31, 171)>",
"signature": "<bound method Class.signature of Class('MailIntakeReader', 32, 172)>",
"docstring": "High-level read-only ingestion interface.\n\nNotes:\n **Responsibilities:**\n\n - This class is the primary entry point for consumers of the\n Mail Intake library.\n - It orchestrates the full ingestion pipeline:\n - Querying the adapter for message references.\n - Fetching raw provider messages.\n - Parsing and normalizing message data.\n - Constructing domain models.\n\n **Constraints:**\n\n - This class is intentionally: Provider-agnostic, stateless beyond\n iteration scope, read-only.",
"members": {
"iter_messages": {
"name": "iter_messages",
"kind": "function",
"path": "mail_intake.ingestion.reader.MailIntakeReader.iter_messages",
"signature": "<bound method Function.signature of Function('iter_messages', 62, 80)>",
"signature": "<bound method Function.signature of Function('iter_messages', 63, 81)>",
"docstring": "Iterate over parsed messages matching a provider query.\n\nArgs:\n query (str):\n Provider-specific query string used to filter messages.\n\nYields:\n MailIntakeMessage:\n Fully parsed and normalized `MailIntakeMessage` instances.\n\nRaises:\n MailIntakeParsingError:\n If a message cannot be parsed."
},
"iter_threads": {
"name": "iter_threads",
"kind": "function",
"path": "mail_intake.ingestion.reader.MailIntakeReader.iter_threads",
"signature": "<bound method Function.signature of Function('iter_threads', 82, 120)>",
"docstring": "Iterate over threads constructed from messages matching a query.\n\nArgs:\n query (str):\n Provider-specific query string used to filter messages.\n\nYields:\n MailIntakeThread:\n An iterator of `MailIntakeThread` instances.\n\nRaises:\n `MailIntakeParsingError`:\n If a message cannot be parsed.\n\nNotes:\n **Guarantees:**\n\n - Messages are grouped by `thread_id` and yielded as complete\n thread objects containing all associated messages."
"signature": "<bound method Function.signature of Function('iter_threads', 83, 121)>",
"docstring": "Iterate over threads constructed from messages matching a query.\n\nArgs:\n query (str):\n Provider-specific query string used to filter messages.\n\nReturns:\n Iterator[MailIntakeThread]:\n An iterator over `MailIntakeThread` instances.\n\nRaises:\n `MailIntakeParsingError`:\n If a message cannot be parsed.\n\nNotes:\n **Guarantees:**\n\n - Messages are grouped by `thread_id` and yielded as complete\n thread objects containing all associated messages."
}
}
}

View File

@@ -4,6 +4,13 @@
"path": "mail_intake.ingestion.reader",
"docstring": "# Summary\n\nHigh-level mail ingestion orchestration for Mail Intake.\n\nThis module provides the primary, provider-agnostic entry point for\nreading and processing mail data.\n\nIt coordinates:\n\n- Mail adapter access.\n- Message and thread iteration.\n- Header and body parsing.\n- Normalization and model construction.\n\nNo provider-specific logic or API semantics are permitted in this layer.",
"objects": {
"Iterator": {
"name": "Iterator",
"kind": "alias",
"path": "mail_intake.ingestion.reader.Iterator",
"signature": "<bound method Alias.signature of Alias('Iterator', 'collections.abc.Iterator')>",
"docstring": null
},
"datetime": {
"name": "datetime",
"kind": "alias",
@@ -11,20 +18,6 @@
"signature": "<bound method Alias.signature of Alias('datetime', 'datetime.datetime')>",
"docstring": null
},
"Iterator": {
"name": "Iterator",
"kind": "alias",
"path": "mail_intake.ingestion.reader.Iterator",
"signature": "<bound method Alias.signature of Alias('Iterator', 'typing.Iterator')>",
"docstring": null
},
"Dict": {
"name": "Dict",
"kind": "alias",
"path": "mail_intake.ingestion.reader.Dict",
"signature": "<bound method Alias.signature of Alias('Dict', 'typing.Dict')>",
"docstring": null
},
"Any": {
"name": "Any",
"kind": "alias",
@@ -44,24 +37,31 @@
"kind": "function",
"path": "mail_intake.ingestion.reader.MailIntakeAdapter.iter_message_refs",
"signature": "<bound method Alias.signature of Alias('iter_message_refs', 'mail_intake.adapters.base.MailIntakeAdapter.iter_message_refs')>",
"docstring": "Iterate over lightweight message references matching a query.\n\nArgs:\n query (str):\n Provider-specific query string used to filter messages.\n\nYields:\n Dict[str, str]:\n Dictionaries containing message and thread identifiers.\n\nNotes:\n **Guarantees:**\n\n - Implementations must yield dictionaries containing at least\n `message_id` and `thread_id`.\n\nExample:\n Typical yield:\n\n ```python\n {\n \"message_id\": \"...\",\n \"thread_id\": \"...\"\n }\n ```"
"docstring": "Iterate over lightweight message references matching a query.\n\nArgs:\n query (str):\n Provider-specific query string used to filter messages.\n\nReturns:\n Iterator[dict[str, str]]:\n An iterator over lightweight message reference dictionaries.\n\nYields:\n dict[str, str]:\n Dictionaries containing message and thread identifiers.\n\nNotes:\n **Guarantees:**\n\n - Implementations must yield dictionaries containing at least\n `message_id` and `thread_id`.\n\nExample:\n Typical yield:\n\n ```python\n {\n \"message_id\": \"...\",\n \"thread_id\": \"...\"\n }\n ```"
},
"fetch_message": {
"name": "fetch_message",
"kind": "function",
"path": "mail_intake.ingestion.reader.MailIntakeAdapter.fetch_message",
"signature": "<bound method Alias.signature of Alias('fetch_message', 'mail_intake.adapters.base.MailIntakeAdapter.fetch_message')>",
"docstring": "Fetch a full raw message by message identifier.\n\nArgs:\n message_id (str):\n Provider-specific message identifier.\n\nReturns:\n Dict[str, Any]:\n Provider-native message payload (e.g., Gmail message JSON structure)."
"docstring": "Fetch a full raw message by message identifier.\n\nArgs:\n message_id (str):\n Provider-specific message identifier.\n\nReturns:\n dict[str, Any]:\n Provider-native message payload (e.g., Gmail message JSON structure)."
},
"fetch_thread": {
"name": "fetch_thread",
"kind": "function",
"path": "mail_intake.ingestion.reader.MailIntakeAdapter.fetch_thread",
"signature": "<bound method Alias.signature of Alias('fetch_thread', 'mail_intake.adapters.base.MailIntakeAdapter.fetch_thread')>",
"docstring": "Fetch a full raw thread by thread identifier.\n\nArgs:\n thread_id (str):\n Provider-specific thread identifier.\n\nReturns:\n Dict[str, Any]:\n Provider-native thread payload."
"docstring": "Fetch a full raw thread by thread identifier.\n\nArgs:\n thread_id (str):\n Provider-specific thread identifier.\n\nReturns:\n dict[str, Any]:\n Provider-native thread payload."
}
}
},
"MailIntakeParsingError": {
"name": "MailIntakeParsingError",
"kind": "class",
"path": "mail_intake.ingestion.reader.MailIntakeParsingError",
"signature": "<bound method Alias.signature of Alias('MailIntakeParsingError', 'mail_intake.exceptions.MailIntakeParsingError')>",
"docstring": "Errors encountered while parsing message content.\n\nNotes:\n **Lifecycle:**\n\n - Raised when raw provider payloads cannot be interpreted or\n normalized into internal domain models."
},
"MailIntakeMessage": {
"name": "MailIntakeMessage",
"kind": "class",
@@ -185,26 +185,26 @@
}
}
},
"parse_headers": {
"name": "parse_headers",
"extract_body": {
"name": "extract_body",
"kind": "function",
"path": "mail_intake.ingestion.reader.parse_headers",
"signature": "<bound method Alias.signature of Alias('parse_headers', 'mail_intake.parsers.headers.parse_headers')>",
"docstring": "Convert a list of Gmail-style headers into a normalized dict.\n\nArgs:\n raw_headers (List[Dict[str, str]]):\n List of header dictionaries, each containing `name` and `value` keys.\n\nReturns:\n Dict[str, str]:\n Dictionary mapping lowercase header names to stripped values.\n\nNotes:\n **Guarantees:**\n\n - Provider payloads (such as Gmail) typically represent headers as a\n list of name/value mappings.\n - This function normalizes them into a case-insensitive dictionary\n keyed by lowercase header names.\n\nExample:\n Typical usage:\n\n ```python\n Input:\n [\n {\"name\": \"From\", \"value\": \"John Doe <john@example.com>\"},\n {\"name\": \"Subject\", \"value\": \"Re: Interview Update\"},\n ]\n\n Output:\n {\n \"from\": \"John Doe <john@example.com>\",\n \"subject\": \"Re: Interview Update\",\n }\n ```"
"path": "mail_intake.ingestion.reader.extract_body",
"signature": "<bound method Alias.signature of Alias('extract_body', 'mail_intake.parsers.body.extract_body')>",
"docstring": "Extract the best-effort message body from a Gmail payload.\n\nPriority:\n\n1. `text/plain`\n2. `text/html` (stripped to text)\n3. Single-part body\n4. Empty string (if nothing usable found)\n\nArgs:\n payload (dict[str, Any]):\n Provider-native message payload dictionary.\n\nReturns:\n str:\n Extracted plain-text message body."
},
"extract_sender": {
"name": "extract_sender",
"kind": "function",
"path": "mail_intake.ingestion.reader.extract_sender",
"signature": "<bound method Alias.signature of Alias('extract_sender', 'mail_intake.parsers.headers.extract_sender')>",
"docstring": "Extract sender email and optional display name from headers.\n\nArgs:\n headers (Dict[str, str]):\n Normalized header dictionary as returned by `parse_headers()`.\n\nReturns:\n Tuple[str, Optional[str]]:\n A tuple `(email, name)` where `email` is the sender email address\n and `name` is the display name, or `None` if unavailable.\n\nNotes:\n **Responsibilities:**\n\n - This function parses the `From` header and attempts to extract\n sender email address and optional human-readable display name.\n\nExample:\n Typical values:\n\n - `\"John Doe <john@example.com>\"` -> `(\"john@example.com\", \"John Doe\")`\n - `\"john@example.com\"` -> `(\"john@example.com\", None)`"
"docstring": "Extract sender email and optional display name from headers.\n\nArgs:\n headers (dict[str, str]):\n Normalized header dictionary as returned by `parse_headers()`.\n\nReturns:\n tuple[str, str | None]:\n A tuple `(email, name)` where `email` is the sender email address\n and `name` is the display name, or `None` if unavailable.\n\nNotes:\n **Responsibilities:**\n\n - This function parses the `From` header and attempts to extract\n sender email address and optional human-readable display name.\n\nExample:\n Typical values:\n\n - `\"John Doe <john@example.com>\"` -> `(\"john@example.com\", \"John Doe\")`\n - `\"john@example.com\"` -> `(\"john@example.com\", None)`"
},
"extract_body": {
"name": "extract_body",
"parse_headers": {
"name": "parse_headers",
"kind": "function",
"path": "mail_intake.ingestion.reader.extract_body",
"signature": "<bound method Alias.signature of Alias('extract_body', 'mail_intake.parsers.body.extract_body')>",
"docstring": "Extract the best-effort message body from a Gmail payload.\n\nPriority:\n\n1. `text/plain`\n2. `text/html` (stripped to text)\n3. Single-part body\n4. Empty string (if nothing usable found)\n\nArgs:\n payload (Dict[str, Any]):\n Provider-native message payload dictionary.\n\nReturns:\n str:\n Extracted plain-text message body."
"path": "mail_intake.ingestion.reader.parse_headers",
"signature": "<bound method Alias.signature of Alias('parse_headers', 'mail_intake.parsers.headers.parse_headers')>",
"docstring": "Convert a list of Gmail-style headers into a normalized dict.\n\nArgs:\n raw_headers (list[dict[str, str]]):\n List of header dictionaries, each containing `name` and `value` keys.\n\nReturns:\n dict[str, str]:\n Dictionary mapping lowercase header names to stripped values.\n\nNotes:\n **Guarantees:**\n\n - Provider payloads (such as Gmail) typically represent headers as a\n list of name/value mappings.\n - This function normalizes them into a case-insensitive dictionary\n keyed by lowercase header names.\n\nExample:\n Typical usage:\n\n ```python\n Input:\n [\n {\"name\": \"From\", \"value\": \"John Doe <john@example.com>\"},\n {\"name\": \"Subject\", \"value\": \"Re: Interview Update\"},\n ]\n\n Output:\n {\n \"from\": \"John Doe <john@example.com>\",\n \"subject\": \"Re: Interview Update\",\n }\n ```"
},
"normalize_subject": {
"name": "normalize_subject",
@@ -213,33 +213,26 @@
"signature": "<bound method Alias.signature of Alias('normalize_subject', 'mail_intake.parsers.subject.normalize_subject')>",
"docstring": "Normalize an email subject for thread-level comparison.\n\nArgs:\n subject (str):\n Raw subject line from a message header.\n\nReturns:\n str:\n Normalized subject string suitable for thread grouping.\n\nNotes:\n **Responsibilities:**\n\n - Strips common prefixes such as `Re:`, `Fwd:`, and `FW:`.\n - Repeats prefix stripping to handle stacked prefixes.\n - Collapses excessive whitespace.\n - Preserves original casing (no lowercasing).\n\n **Guarantees:**\n\n - This function is intentionally conservative and avoids aggressive\n transformations that could alter the semantic meaning of the subject."
},
"MailIntakeParsingError": {
"name": "MailIntakeParsingError",
"kind": "class",
"path": "mail_intake.ingestion.reader.MailIntakeParsingError",
"signature": "<bound method Alias.signature of Alias('MailIntakeParsingError', 'mail_intake.exceptions.MailIntakeParsingError')>",
"docstring": "Errors encountered while parsing message content.\n\nNotes:\n **Lifecycle:**\n\n - Raised when raw provider payloads cannot be interpreted or\n normalized into internal domain models."
},
"MailIntakeReader": {
"name": "MailIntakeReader",
"kind": "class",
"path": "mail_intake.ingestion.reader.MailIntakeReader",
"signature": "<bound method Class.signature of Class('MailIntakeReader', 31, 171)>",
"signature": "<bound method Class.signature of Class('MailIntakeReader', 32, 172)>",
"docstring": "High-level read-only ingestion interface.\n\nNotes:\n **Responsibilities:**\n\n - This class is the primary entry point for consumers of the\n Mail Intake library.\n - It orchestrates the full ingestion pipeline:\n - Querying the adapter for message references.\n - Fetching raw provider messages.\n - Parsing and normalizing message data.\n - Constructing domain models.\n\n **Constraints:**\n\n - This class is intentionally: Provider-agnostic, stateless beyond\n iteration scope, read-only.",
"members": {
"iter_messages": {
"name": "iter_messages",
"kind": "function",
"path": "mail_intake.ingestion.reader.MailIntakeReader.iter_messages",
"signature": "<bound method Function.signature of Function('iter_messages', 62, 80)>",
"signature": "<bound method Function.signature of Function('iter_messages', 63, 81)>",
"docstring": "Iterate over parsed messages matching a provider query.\n\nArgs:\n query (str):\n Provider-specific query string used to filter messages.\n\nYields:\n MailIntakeMessage:\n Fully parsed and normalized `MailIntakeMessage` instances.\n\nRaises:\n MailIntakeParsingError:\n If a message cannot be parsed."
},
"iter_threads": {
"name": "iter_threads",
"kind": "function",
"path": "mail_intake.ingestion.reader.MailIntakeReader.iter_threads",
"signature": "<bound method Function.signature of Function('iter_threads', 82, 120)>",
"docstring": "Iterate over threads constructed from messages matching a query.\n\nArgs:\n query (str):\n Provider-specific query string used to filter messages.\n\nYields:\n MailIntakeThread:\n An iterator of `MailIntakeThread` instances.\n\nRaises:\n `MailIntakeParsingError`:\n If a message cannot be parsed.\n\nNotes:\n **Guarantees:**\n\n - Messages are grouped by `thread_id` and yielded as complete\n thread objects containing all associated messages."
"signature": "<bound method Function.signature of Function('iter_threads', 83, 121)>",
"docstring": "Iterate over threads constructed from messages matching a query.\n\nArgs:\n query (str):\n Provider-specific query string used to filter messages.\n\nReturns:\n Iterator[MailIntakeThread]:\n An iterator over `MailIntakeThread` instances.\n\nRaises:\n `MailIntakeParsingError`:\n If a message cannot be parsed.\n\nNotes:\n **Guarantees:**\n\n - Messages are grouped by `thread_id` and yielded as complete\n thread objects containing all associated messages."
}
}
}

View File

@@ -18,18 +18,11 @@
"signature": "<bound method Alias.signature of Alias('dataclass', 'dataclasses.dataclass')>",
"docstring": null
},
"Optional": {
"name": "Optional",
"kind": "alias",
"path": "mail_intake.config.Optional",
"signature": "<bound method Alias.signature of Alias('Optional', 'typing.Optional')>",
"docstring": null
},
"MailIntakeConfig": {
"name": "MailIntakeConfig",
"kind": "class",
"path": "mail_intake.config.MailIntakeConfig",
"signature": "<bound method Class.signature of Class('MailIntakeConfig', 18, 57)>",
"signature": "<bound method Class.signature of Class('MailIntakeConfig', 17, 56)>",
"docstring": "Global configuration for `mail-intake`.\n\nNotes:\n **Guarantees:**\n\n - This configuration is intentionally explicit and immutable.\n - No implicit environment reads or global state.\n - Explicit configuration over implicit defaults.\n - No direct environment or filesystem access.\n - This model is safe to pass across layers and suitable for\n serialization.",
"members": {
"provider": {
@@ -76,34 +69,34 @@
"kind": "module",
"path": "mail_intake.exceptions",
"signature": null,
"docstring": "Exception hierarchy for Mail Intake.\n\n---\n\n## Summary\n\nThis module defines the **canonical exception types** used throughout the\nMail Intake library.\n\nAll library-raised errors derive from `MailIntakeError`. Consumers are\nencouraged to catch this base type (or specific subclasses) rather than\nprovider-specific or third-party exceptions.",
"docstring": "# Summary\n\nException hierarchy for Mail Intake.\n\nThis module defines the **canonical exception types** used throughout the\nMail Intake library.\n\nAll library-raised errors derive from `MailIntakeError`. Consumers are\nencouraged to catch this base type (or specific subclasses) rather than\nprovider-specific or third-party exceptions.",
"members": {
"MailIntakeError": {
"name": "MailIntakeError",
"kind": "class",
"path": "mail_intake.exceptions.MailIntakeError",
"signature": "<bound method Class.signature of Class('MailIntakeError', 17, 27)>",
"signature": "<bound method Class.signature of Class('MailIntakeError', 15, 25)>",
"docstring": "Base exception for all Mail Intake errors.\n\nNotes:\n **Guarantees:**\n\n - This is the root of the Mail Intake exception hierarchy\n - All errors raised by the library must derive from this class\n - Consumers should generally catch this type when handling library-level failures"
},
"MailIntakeAuthError": {
"name": "MailIntakeAuthError",
"kind": "class",
"path": "mail_intake.exceptions.MailIntakeAuthError",
"signature": "<bound method Class.signature of Class('MailIntakeAuthError', 30, 39)>",
"signature": "<bound method Class.signature of Class('MailIntakeAuthError', 28, 37)>",
"docstring": "Authentication and credential-related failures.\n\nNotes:\n **Lifecycle:**\n\n - Raised when authentication providers are unable to acquire,\n refresh, or persist valid credentials."
},
"MailIntakeAdapterError": {
"name": "MailIntakeAdapterError",
"kind": "class",
"path": "mail_intake.exceptions.MailIntakeAdapterError",
"signature": "<bound method Class.signature of Class('MailIntakeAdapterError', 42, 51)>",
"signature": "<bound method Class.signature of Class('MailIntakeAdapterError', 40, 49)>",
"docstring": "Errors raised by mail provider adapters.\n\nNotes:\n **Lifecycle:**\n\n - Raised when a provider adapter encounters API errors, transport\n failures, or invalid provider responses."
},
"MailIntakeParsingError": {
"name": "MailIntakeParsingError",
"kind": "class",
"path": "mail_intake.exceptions.MailIntakeParsingError",
"signature": "<bound method Class.signature of Class('MailIntakeParsingError', 54, 63)>",
"signature": "<bound method Class.signature of Class('MailIntakeParsingError', 52, 61)>",
"docstring": "Errors encountered while parsing message content.\n\nNotes:\n **Lifecycle:**\n\n - Raised when raw provider payloads cannot be interpreted or\n normalized into internal domain models."
}
}
@@ -127,21 +120,21 @@
"kind": "function",
"path": "mail_intake.adapters.MailIntakeAdapter.iter_message_refs",
"signature": "<bound method Alias.signature of Alias('iter_message_refs', 'mail_intake.adapters.base.MailIntakeAdapter.iter_message_refs')>",
"docstring": "Iterate over lightweight message references matching a query.\n\nArgs:\n query (str):\n Provider-specific query string used to filter messages.\n\nYields:\n Dict[str, str]:\n Dictionaries containing message and thread identifiers.\n\nNotes:\n **Guarantees:**\n\n - Implementations must yield dictionaries containing at least\n `message_id` and `thread_id`.\n\nExample:\n Typical yield:\n\n ```python\n {\n \"message_id\": \"...\",\n \"thread_id\": \"...\"\n }\n ```"
"docstring": "Iterate over lightweight message references matching a query.\n\nArgs:\n query (str):\n Provider-specific query string used to filter messages.\n\nReturns:\n Iterator[dict[str, str]]:\n An iterator over lightweight message reference dictionaries.\n\nYields:\n dict[str, str]:\n Dictionaries containing message and thread identifiers.\n\nNotes:\n **Guarantees:**\n\n - Implementations must yield dictionaries containing at least\n `message_id` and `thread_id`.\n\nExample:\n Typical yield:\n\n ```python\n {\n \"message_id\": \"...\",\n \"thread_id\": \"...\"\n }\n ```"
},
"fetch_message": {
"name": "fetch_message",
"kind": "function",
"path": "mail_intake.adapters.MailIntakeAdapter.fetch_message",
"signature": "<bound method Alias.signature of Alias('fetch_message', 'mail_intake.adapters.base.MailIntakeAdapter.fetch_message')>",
"docstring": "Fetch a full raw message by message identifier.\n\nArgs:\n message_id (str):\n Provider-specific message identifier.\n\nReturns:\n Dict[str, Any]:\n Provider-native message payload (e.g., Gmail message JSON structure)."
"docstring": "Fetch a full raw message by message identifier.\n\nArgs:\n message_id (str):\n Provider-specific message identifier.\n\nReturns:\n dict[str, Any]:\n Provider-native message payload (e.g., Gmail message JSON structure)."
},
"fetch_thread": {
"name": "fetch_thread",
"kind": "function",
"path": "mail_intake.adapters.MailIntakeAdapter.fetch_thread",
"signature": "<bound method Alias.signature of Alias('fetch_thread', 'mail_intake.adapters.base.MailIntakeAdapter.fetch_thread')>",
"docstring": "Fetch a full raw thread by thread identifier.\n\nArgs:\n thread_id (str):\n Provider-specific thread identifier.\n\nReturns:\n Dict[str, Any]:\n Provider-native thread payload."
"docstring": "Fetch a full raw thread by thread identifier.\n\nArgs:\n thread_id (str):\n Provider-specific thread identifier.\n\nReturns:\n dict[str, Any]:\n Provider-native thread payload."
}
}
},
@@ -157,28 +150,28 @@
"kind": "attribute",
"path": "mail_intake.adapters.MailIntakeGmailAdapter.service",
"signature": "<bound method Alias.signature of Alias('service', 'mail_intake.adapters.gmail.MailIntakeGmailAdapter.service')>",
"docstring": "Lazily initialize and return the Gmail API service client.\n\nReturns:\n Any:\n Initialized Gmail API service instance.\n\nRaises:\n MailIntakeAdapterError:\n If the Gmail service cannot be initialized."
"docstring": "Lazily initialize and return the Gmail API service client.\n\nRaises:\n MailIntakeAdapterError:\n If the Gmail service cannot be initialized."
},
"iter_message_refs": {
"name": "iter_message_refs",
"kind": "function",
"path": "mail_intake.adapters.MailIntakeGmailAdapter.iter_message_refs",
"signature": "<bound method Alias.signature of Alias('iter_message_refs', 'mail_intake.adapters.gmail.MailIntakeGmailAdapter.iter_message_refs')>",
"docstring": "Iterate over message references matching the query.\n\nArgs:\n query (str):\n Gmail search query string.\n\nYields:\n Dict[str, str]:\n Dictionaries containing ``message_id`` and ``thread_id``.\n\nRaises:\n MailIntakeAdapterError:\n If the Gmail API returns an error."
"docstring": "Iterate over message references matching the query.\n\nArgs:\n query (str):\n Gmail search query string.\n\nYields:\n dict[str, str]:\n Dictionaries containing ``message_id`` and ``thread_id``.\n\nRaises:\n MailIntakeAdapterError:\n If the Gmail API returns an error."
},
"fetch_message": {
"name": "fetch_message",
"kind": "function",
"path": "mail_intake.adapters.MailIntakeGmailAdapter.fetch_message",
"signature": "<bound method Alias.signature of Alias('fetch_message', 'mail_intake.adapters.gmail.MailIntakeGmailAdapter.fetch_message')>",
"docstring": "Fetch a full Gmail message by message ID.\n\nArgs:\n message_id (str):\n Gmail message identifier.\n\nReturns:\n Dict[str, Any]:\n Provider-native Gmail message payload.\n\nRaises:\n MailIntakeAdapterError:\n If the Gmail API returns an error."
"docstring": "Fetch a full Gmail message by message ID.\n\nArgs:\n message_id (str):\n Gmail message identifier.\n\nReturns:\n dict[str, Any]:\n Provider-native Gmail message payload.\n\nRaises:\n MailIntakeAdapterError:\n If the Gmail API returns an error."
},
"fetch_thread": {
"name": "fetch_thread",
"kind": "function",
"path": "mail_intake.adapters.MailIntakeGmailAdapter.fetch_thread",
"signature": "<bound method Alias.signature of Alias('fetch_thread', 'mail_intake.adapters.gmail.MailIntakeGmailAdapter.fetch_thread')>",
"docstring": "Fetch a full Gmail thread by thread ID.\n\nArgs:\n thread_id (str):\n Gmail thread identifier.\n\nReturns:\n Dict[str, Any]:\n Provider-native Gmail thread payload.\n\nRaises:\n MailIntakeAdapterError:\n If the Gmail API returns an error."
"docstring": "Fetch a full Gmail thread by thread ID.\n\nArgs:\n thread_id (str):\n Gmail thread identifier.\n\nReturns:\n dict[str, Any]:\n Provider-native Gmail thread payload.\n\nRaises:\n MailIntakeAdapterError:\n If the Gmail API returns an error."
}
}
},
@@ -207,14 +200,7 @@
"name": "Iterator",
"kind": "alias",
"path": "mail_intake.adapters.base.Iterator",
"signature": "<bound method Alias.signature of Alias('Iterator', 'typing.Iterator')>",
"docstring": null
},
"Dict": {
"name": "Dict",
"kind": "alias",
"path": "mail_intake.adapters.base.Dict",
"signature": "<bound method Alias.signature of Alias('Dict', 'typing.Dict')>",
"signature": "<bound method Alias.signature of Alias('Iterator', 'collections.abc.Iterator')>",
"docstring": null
},
"Any": {
@@ -228,29 +214,29 @@
"name": "MailIntakeAdapter",
"kind": "class",
"path": "mail_intake.adapters.base.MailIntakeAdapter",
"signature": "<bound method Class.signature of Class('MailIntakeAdapter', 18, 93)>",
"signature": "<bound method Class.signature of Class('MailIntakeAdapter', 19, 98)>",
"docstring": "Base adapter interface for mail providers.\n\nNotes:\n **Guarantees:**\n\n - Discover messages matching a query.\n - Retrieve full message payloads.\n - Retrieve full thread payloads.\n\n **Lifecycle:**\n\n - Adapters are intentionally read-only and must not mutate provider state.",
"members": {
"iter_message_refs": {
"name": "iter_message_refs",
"kind": "function",
"path": "mail_intake.adapters.base.MailIntakeAdapter.iter_message_refs",
"signature": "<bound method Function.signature of Function('iter_message_refs', 34, 63)>",
"docstring": "Iterate over lightweight message references matching a query.\n\nArgs:\n query (str):\n Provider-specific query string used to filter messages.\n\nYields:\n Dict[str, str]:\n Dictionaries containing message and thread identifiers.\n\nNotes:\n **Guarantees:**\n\n - Implementations must yield dictionaries containing at least\n `message_id` and `thread_id`.\n\nExample:\n Typical yield:\n\n ```python\n {\n \"message_id\": \"...\",\n \"thread_id\": \"...\"\n }\n ```"
"signature": "<bound method Function.signature of Function('iter_message_refs', 35, 68)>",
"docstring": "Iterate over lightweight message references matching a query.\n\nArgs:\n query (str):\n Provider-specific query string used to filter messages.\n\nReturns:\n Iterator[dict[str, str]]:\n An iterator over lightweight message reference dictionaries.\n\nYields:\n dict[str, str]:\n Dictionaries containing message and thread identifiers.\n\nNotes:\n **Guarantees:**\n\n - Implementations must yield dictionaries containing at least\n `message_id` and `thread_id`.\n\nExample:\n Typical yield:\n\n ```python\n {\n \"message_id\": \"...\",\n \"thread_id\": \"...\"\n }\n ```"
},
"fetch_message": {
"name": "fetch_message",
"kind": "function",
"path": "mail_intake.adapters.base.MailIntakeAdapter.fetch_message",
"signature": "<bound method Function.signature of Function('fetch_message', 65, 78)>",
"docstring": "Fetch a full raw message by message identifier.\n\nArgs:\n message_id (str):\n Provider-specific message identifier.\n\nReturns:\n Dict[str, Any]:\n Provider-native message payload (e.g., Gmail message JSON structure)."
"signature": "<bound method Function.signature of Function('fetch_message', 70, 83)>",
"docstring": "Fetch a full raw message by message identifier.\n\nArgs:\n message_id (str):\n Provider-specific message identifier.\n\nReturns:\n dict[str, Any]:\n Provider-native message payload (e.g., Gmail message JSON structure)."
},
"fetch_thread": {
"name": "fetch_thread",
"kind": "function",
"path": "mail_intake.adapters.base.MailIntakeAdapter.fetch_thread",
"signature": "<bound method Function.signature of Function('fetch_thread', 80, 93)>",
"docstring": "Fetch a full raw thread by thread identifier.\n\nArgs:\n thread_id (str):\n Provider-specific thread identifier.\n\nReturns:\n Dict[str, Any]:\n Provider-native thread payload."
"signature": "<bound method Function.signature of Function('fetch_thread', 85, 98)>",
"docstring": "Fetch a full raw thread by thread identifier.\n\nArgs:\n thread_id (str):\n Provider-specific thread identifier.\n\nReturns:\n dict[str, Any]:\n Provider-native thread payload."
}
}
}
@@ -267,14 +253,7 @@
"name": "Iterator",
"kind": "alias",
"path": "mail_intake.adapters.gmail.Iterator",
"signature": "<bound method Alias.signature of Alias('Iterator', 'typing.Iterator')>",
"docstring": null
},
"Dict": {
"name": "Dict",
"kind": "alias",
"path": "mail_intake.adapters.gmail.Dict",
"signature": "<bound method Alias.signature of Alias('Dict', 'typing.Dict')>",
"signature": "<bound method Alias.signature of Alias('Iterator', 'collections.abc.Iterator')>",
"docstring": null
},
"Any": {
@@ -310,31 +289,24 @@
"kind": "function",
"path": "mail_intake.adapters.gmail.MailIntakeAdapter.iter_message_refs",
"signature": "<bound method Alias.signature of Alias('iter_message_refs', 'mail_intake.adapters.base.MailIntakeAdapter.iter_message_refs')>",
"docstring": "Iterate over lightweight message references matching a query.\n\nArgs:\n query (str):\n Provider-specific query string used to filter messages.\n\nYields:\n Dict[str, str]:\n Dictionaries containing message and thread identifiers.\n\nNotes:\n **Guarantees:**\n\n - Implementations must yield dictionaries containing at least\n `message_id` and `thread_id`.\n\nExample:\n Typical yield:\n\n ```python\n {\n \"message_id\": \"...\",\n \"thread_id\": \"...\"\n }\n ```"
"docstring": "Iterate over lightweight message references matching a query.\n\nArgs:\n query (str):\n Provider-specific query string used to filter messages.\n\nReturns:\n Iterator[dict[str, str]]:\n An iterator over lightweight message reference dictionaries.\n\nYields:\n dict[str, str]:\n Dictionaries containing message and thread identifiers.\n\nNotes:\n **Guarantees:**\n\n - Implementations must yield dictionaries containing at least\n `message_id` and `thread_id`.\n\nExample:\n Typical yield:\n\n ```python\n {\n \"message_id\": \"...\",\n \"thread_id\": \"...\"\n }\n ```"
},
"fetch_message": {
"name": "fetch_message",
"kind": "function",
"path": "mail_intake.adapters.gmail.MailIntakeAdapter.fetch_message",
"signature": "<bound method Alias.signature of Alias('fetch_message', 'mail_intake.adapters.base.MailIntakeAdapter.fetch_message')>",
"docstring": "Fetch a full raw message by message identifier.\n\nArgs:\n message_id (str):\n Provider-specific message identifier.\n\nReturns:\n Dict[str, Any]:\n Provider-native message payload (e.g., Gmail message JSON structure)."
"docstring": "Fetch a full raw message by message identifier.\n\nArgs:\n message_id (str):\n Provider-specific message identifier.\n\nReturns:\n dict[str, Any]:\n Provider-native message payload (e.g., Gmail message JSON structure)."
},
"fetch_thread": {
"name": "fetch_thread",
"kind": "function",
"path": "mail_intake.adapters.gmail.MailIntakeAdapter.fetch_thread",
"signature": "<bound method Alias.signature of Alias('fetch_thread', 'mail_intake.adapters.base.MailIntakeAdapter.fetch_thread')>",
"docstring": "Fetch a full raw thread by thread identifier.\n\nArgs:\n thread_id (str):\n Provider-specific thread identifier.\n\nReturns:\n Dict[str, Any]:\n Provider-native thread payload."
"docstring": "Fetch a full raw thread by thread identifier.\n\nArgs:\n thread_id (str):\n Provider-specific thread identifier.\n\nReturns:\n dict[str, Any]:\n Provider-native thread payload."
}
}
},
"MailIntakeAdapterError": {
"name": "MailIntakeAdapterError",
"kind": "class",
"path": "mail_intake.adapters.gmail.MailIntakeAdapterError",
"signature": "<bound method Alias.signature of Alias('MailIntakeAdapterError', 'mail_intake.exceptions.MailIntakeAdapterError')>",
"docstring": "Errors raised by mail provider adapters.\n\nNotes:\n **Lifecycle:**\n\n - Raised when a provider adapter encounters API errors, transport\n failures, or invalid provider responses."
},
"MailIntakeAuthProvider": {
"name": "MailIntakeAuthProvider",
"kind": "class",
@@ -351,11 +323,18 @@
}
}
},
"MailIntakeAdapterError": {
"name": "MailIntakeAdapterError",
"kind": "class",
"path": "mail_intake.adapters.gmail.MailIntakeAdapterError",
"signature": "<bound method Alias.signature of Alias('MailIntakeAdapterError', 'mail_intake.exceptions.MailIntakeAdapterError')>",
"docstring": "Errors raised by mail provider adapters.\n\nNotes:\n **Lifecycle:**\n\n - Raised when a provider adapter encounters API errors, transport\n failures, or invalid provider responses."
},
"MailIntakeGmailAdapter": {
"name": "MailIntakeGmailAdapter",
"kind": "class",
"path": "mail_intake.adapters.gmail.MailIntakeGmailAdapter",
"signature": "<bound method Class.signature of Class('MailIntakeGmailAdapter', 28, 189)>",
"signature": "<bound method Class.signature of Class('MailIntakeGmailAdapter', 29, 180)>",
"docstring": "Gmail read-only adapter.\n\nThis adapter implements the `MailIntakeAdapter` interface using the\nGmail REST API. It translates the generic mail intake contract into\nGmail-specific API calls.\n\nNotes:\n **Responsibilities:**\n\n - This class is the ONLY place where `googleapiclient` is imported.\n - Gmail REST semantics are known.\n - `.execute()` is called.\n\n **Constraints:**\n\n - Must remain thin and imperative.\n - Must not perform parsing or interpretation.\n - Must not expose Gmail-specific types beyond this class.",
"members": {
"service": {
@@ -363,28 +342,28 @@
"kind": "attribute",
"path": "mail_intake.adapters.gmail.MailIntakeGmailAdapter.service",
"signature": null,
"docstring": "Lazily initialize and return the Gmail API service client.\n\nReturns:\n Any:\n Initialized Gmail API service instance.\n\nRaises:\n MailIntakeAdapterError:\n If the Gmail service cannot be initialized."
"docstring": "Lazily initialize and return the Gmail API service client.\n\nRaises:\n MailIntakeAdapterError:\n If the Gmail service cannot be initialized."
},
"iter_message_refs": {
"name": "iter_message_refs",
"kind": "function",
"path": "mail_intake.adapters.gmail.MailIntakeGmailAdapter.iter_message_refs",
"signature": "<bound method Function.signature of Function('iter_message_refs', 92, 133)>",
"docstring": "Iterate over message references matching the query.\n\nArgs:\n query (str):\n Gmail search query string.\n\nYields:\n Dict[str, str]:\n Dictionaries containing ``message_id`` and ``thread_id``.\n\nRaises:\n MailIntakeAdapterError:\n If the Gmail API returns an error."
"signature": "<bound method Function.signature of Function('iter_message_refs', 89, 124)>",
"docstring": "Iterate over message references matching the query.\n\nArgs:\n query (str):\n Gmail search query string.\n\nYields:\n dict[str, str]:\n Dictionaries containing ``message_id`` and ``thread_id``.\n\nRaises:\n MailIntakeAdapterError:\n If the Gmail API returns an error."
},
"fetch_message": {
"name": "fetch_message",
"kind": "function",
"path": "mail_intake.adapters.gmail.MailIntakeGmailAdapter.fetch_message",
"signature": "<bound method Function.signature of Function('fetch_message', 135, 161)>",
"docstring": "Fetch a full Gmail message by message ID.\n\nArgs:\n message_id (str):\n Gmail message identifier.\n\nReturns:\n Dict[str, Any]:\n Provider-native Gmail message payload.\n\nRaises:\n MailIntakeAdapterError:\n If the Gmail API returns an error."
"signature": "<bound method Function.signature of Function('fetch_message', 126, 152)>",
"docstring": "Fetch a full Gmail message by message ID.\n\nArgs:\n message_id (str):\n Gmail message identifier.\n\nReturns:\n dict[str, Any]:\n Provider-native Gmail message payload.\n\nRaises:\n MailIntakeAdapterError:\n If the Gmail API returns an error."
},
"fetch_thread": {
"name": "fetch_thread",
"kind": "function",
"path": "mail_intake.adapters.gmail.MailIntakeGmailAdapter.fetch_thread",
"signature": "<bound method Function.signature of Function('fetch_thread', 163, 189)>",
"docstring": "Fetch a full Gmail thread by thread ID.\n\nArgs:\n thread_id (str):\n Gmail thread identifier.\n\nReturns:\n Dict[str, Any]:\n Provider-native Gmail thread payload.\n\nRaises:\n MailIntakeAdapterError:\n If the Gmail API returns an error."
"signature": "<bound method Function.signature of Function('fetch_thread', 154, 180)>",
"docstring": "Fetch a full Gmail thread by thread ID.\n\nArgs:\n thread_id (str):\n Gmail thread identifier.\n\nReturns:\n dict[str, Any]:\n Provider-native Gmail thread payload.\n\nRaises:\n MailIntakeAdapterError:\n If the Gmail API returns an error."
}
}
}
@@ -530,7 +509,7 @@
"name": "Sequence",
"kind": "alias",
"path": "mail_intake.auth.google.Sequence",
"signature": "<bound method Alias.signature of Alias('Sequence', 'typing.Sequence')>",
"signature": "<bound method Alias.signature of Alias('Sequence', 'collections.abc.Sequence')>",
"docstring": null
},
"google": {
@@ -547,13 +526,6 @@
"signature": "<bound method Alias.signature of Alias('Request', 'google.auth.transport.requests.Request')>",
"docstring": null
},
"InstalledAppFlow": {
"name": "InstalledAppFlow",
"kind": "alias",
"path": "mail_intake.auth.google.InstalledAppFlow",
"signature": "<bound method Alias.signature of Alias('InstalledAppFlow', 'google_auth_oauthlib.flow.InstalledAppFlow')>",
"docstring": null
},
"Credentials": {
"name": "Credentials",
"kind": "alias",
@@ -561,6 +533,13 @@
"signature": "<bound method Alias.signature of Alias('Credentials', 'google.oauth2.credentials.Credentials')>",
"docstring": null
},
"InstalledAppFlow": {
"name": "InstalledAppFlow",
"kind": "alias",
"path": "mail_intake.auth.google.InstalledAppFlow",
"signature": "<bound method Alias.signature of Alias('InstalledAppFlow', 'google_auth_oauthlib.flow.InstalledAppFlow')>",
"docstring": null
},
"MailIntakeAuthProvider": {
"name": "MailIntakeAuthProvider",
"kind": "class",
@@ -589,7 +568,7 @@
"kind": "function",
"path": "mail_intake.auth.google.CredentialStore.load",
"signature": "<bound method Alias.signature of Alias('load', 'mail_intake.credentials.store.CredentialStore.load')>",
"docstring": "Load previously persisted credentials.\n\nReturns:\n Optional[T]:\n An instance of type `T` if credentials are available and\n loadable; otherwise `None`.\n\nNotes:\n **Guarantees:**\n\n - Implementations should return `None` when no credentials are\n present or when stored credentials cannot be successfully\n decoded or deserialized.\n - The store must not attempt to validate, refresh, or otherwise\n interpret the returned credentials."
"docstring": "Load previously persisted credentials.\n\nReturns:\n T | None:\n An instance of type `T` if credentials are available and\n loadable; otherwise `None`.\n\nNotes:\n **Guarantees:**\n\n - Implementations should return `None` when no credentials are\n present or when stored credentials cannot be successfully\n decoded or deserialized.\n - The store must not attempt to validate, refresh, or otherwise\n interpret the returned credentials."
},
"save": {
"name": "save",
@@ -681,7 +660,7 @@
"kind": "function",
"path": "mail_intake.credentials.CredentialStore.load",
"signature": "<bound method Alias.signature of Alias('load', 'mail_intake.credentials.store.CredentialStore.load')>",
"docstring": "Load previously persisted credentials.\n\nReturns:\n Optional[T]:\n An instance of type `T` if credentials are available and\n loadable; otherwise `None`.\n\nNotes:\n **Guarantees:**\n\n - Implementations should return `None` when no credentials are\n present or when stored credentials cannot be successfully\n decoded or deserialized.\n - The store must not attempt to validate, refresh, or otherwise\n interpret the returned credentials."
"docstring": "Load previously persisted credentials.\n\nReturns:\n T | None:\n An instance of type `T` if credentials are available and\n loadable; otherwise `None`.\n\nNotes:\n **Guarantees:**\n\n - Implementations should return `None` when no credentials are\n present or when stored credentials cannot be successfully\n decoded or deserialized.\n - The store must not attempt to validate, refresh, or otherwise\n interpret the returned credentials."
},
"save": {
"name": "save",
@@ -718,7 +697,7 @@
"kind": "function",
"path": "mail_intake.credentials.PickleCredentialStore.load",
"signature": "<bound method Alias.signature of Alias('load', 'mail_intake.credentials.pickle.PickleCredentialStore.load')>",
"docstring": "Load credentials from the local filesystem.\n\nReturns:\n Optional[T]:\n An instance of type `T` if credentials are present and\n successfully deserialized; otherwise `None`.\n\nNotes:\n **Guarantees:**\n\n - If the credential file does not exist or cannot be successfully\n deserialized, this method returns `None`.\n - The store does not attempt to validate or interpret the\n returned credentials."
"docstring": "Load credentials from the local filesystem.\n\nReturns:\n T | None:\n An instance of type `T` if credentials are present and\n successfully deserialized; otherwise `None`.\n\nNotes:\n **Guarantees:**\n\n - If the credential file does not exist or cannot be successfully\n deserialized, this method returns `None`.\n - The store does not attempt to validate or interpret the\n returned credentials."
},
"save": {
"name": "save",
@@ -783,7 +762,7 @@
"kind": "function",
"path": "mail_intake.credentials.RedisCredentialStore.load",
"signature": "<bound method Alias.signature of Alias('load', 'mail_intake.credentials.redis.RedisCredentialStore.load')>",
"docstring": "Load credentials from Redis.\n\nReturns:\n Optional[T]:\n An instance of type `T` if credentials are present and\n successfully deserialized; otherwise `None`.\n\nNotes:\n **Guarantees:**\n\n - If no value exists for the configured key, or if the stored\n payload cannot be successfully deserialized, this method\n returns `None`.\n - The store does not attempt to validate the returned\n credentials or determine whether they are expired or\n otherwise usable."
"docstring": "Load credentials from Redis.\n\nReturns:\n T | None:\n An instance of type `T` if credentials are present and\n successfully deserialized; otherwise `None`.\n\nNotes:\n **Guarantees:**\n\n - If no value exists for the configured key, or if the stored\n payload cannot be successfully deserialized, this method\n returns `None`.\n - The store does not attempt to validate the returned\n credentials or determine whether they are expired or\n otherwise usable."
},
"save": {
"name": "save",
@@ -815,13 +794,6 @@
"signature": "<bound method Alias.signature of Alias('pickle', 'pickle')>",
"docstring": null
},
"Optional": {
"name": "Optional",
"kind": "alias",
"path": "mail_intake.credentials.pickle.Optional",
"signature": "<bound method Alias.signature of Alias('Optional', 'typing.Optional')>",
"docstring": null
},
"TypeVar": {
"name": "TypeVar",
"kind": "alias",
@@ -841,7 +813,7 @@
"kind": "function",
"path": "mail_intake.credentials.pickle.CredentialStore.load",
"signature": "<bound method Alias.signature of Alias('load', 'mail_intake.credentials.store.CredentialStore.load')>",
"docstring": "Load previously persisted credentials.\n\nReturns:\n Optional[T]:\n An instance of type `T` if credentials are available and\n loadable; otherwise `None`.\n\nNotes:\n **Guarantees:**\n\n - Implementations should return `None` when no credentials are\n present or when stored credentials cannot be successfully\n decoded or deserialized.\n - The store must not attempt to validate, refresh, or otherwise\n interpret the returned credentials."
"docstring": "Load previously persisted credentials.\n\nReturns:\n T | None:\n An instance of type `T` if credentials are available and\n loadable; otherwise `None`.\n\nNotes:\n **Guarantees:**\n\n - Implementations should return `None` when no credentials are\n present or when stored credentials cannot be successfully\n decoded or deserialized.\n - The store must not attempt to validate, refresh, or otherwise\n interpret the returned credentials."
},
"save": {
"name": "save",
@@ -885,7 +857,7 @@
"kind": "function",
"path": "mail_intake.credentials.pickle.PickleCredentialStore.load",
"signature": "<bound method Function.signature of Function('load', 58, 79)>",
"docstring": "Load credentials from the local filesystem.\n\nReturns:\n Optional[T]:\n An instance of type `T` if credentials are present and\n successfully deserialized; otherwise `None`.\n\nNotes:\n **Guarantees:**\n\n - If the credential file does not exist or cannot be successfully\n deserialized, this method returns `None`.\n - The store does not attempt to validate or interpret the\n returned credentials."
"docstring": "Load credentials from the local filesystem.\n\nReturns:\n T | None:\n An instance of type `T` if credentials are present and\n successfully deserialized; otherwise `None`.\n\nNotes:\n **Guarantees:**\n\n - If the credential file does not exist or cannot be successfully\n deserialized, this method returns `None`.\n - The store does not attempt to validate or interpret the\n returned credentials."
},
"save": {
"name": "save",
@@ -912,11 +884,18 @@
"signature": null,
"docstring": "# Summary\n\nRedis-backed credential persistence for Mail Intake.\n\nThis module provides a Redis-based implementation of the\n`CredentialStore` abstraction, enabling credential persistence\nacross distributed and horizontally scaled deployments.\n\nThe Redis credential store is designed for environments where\nauthentication credentials must be shared safely across multiple\nprocesses, containers, or nodes, such as container orchestration\nplatforms and microservice architectures.\n\nKey characteristics:\n\n- Distributed-safe, shared storage using Redis.\n- Explicit, caller-defined serialization and deserialization.\n- No reliance on unsafe mechanisms such as `pickle`.\n- Optional time-to-live (TTL) support for automatic credential expiry.\n\nThis module is responsible solely for persistence concerns.\nCredential validation, refresh, rotation, and acquisition remain the\nresponsibility of authentication provider implementations.",
"members": {
"Optional": {
"name": "Optional",
"Callable": {
"name": "Callable",
"kind": "alias",
"path": "mail_intake.credentials.redis.Optional",
"signature": "<bound method Alias.signature of Alias('Optional', 'typing.Optional')>",
"path": "mail_intake.credentials.redis.Callable",
"signature": "<bound method Alias.signature of Alias('Callable', 'collections.abc.Callable')>",
"docstring": null
},
"Any": {
"name": "Any",
"kind": "alias",
"path": "mail_intake.credentials.redis.Any",
"signature": "<bound method Alias.signature of Alias('Any', 'typing.Any')>",
"docstring": null
},
"TypeVar": {
@@ -926,13 +905,6 @@
"signature": "<bound method Alias.signature of Alias('TypeVar', 'typing.TypeVar')>",
"docstring": null
},
"Callable": {
"name": "Callable",
"kind": "alias",
"path": "mail_intake.credentials.redis.Callable",
"signature": "<bound method Alias.signature of Alias('Callable', 'typing.Callable')>",
"docstring": null
},
"CredentialStore": {
"name": "CredentialStore",
"kind": "class",
@@ -945,7 +917,7 @@
"kind": "function",
"path": "mail_intake.credentials.redis.CredentialStore.load",
"signature": "<bound method Alias.signature of Alias('load', 'mail_intake.credentials.store.CredentialStore.load')>",
"docstring": "Load previously persisted credentials.\n\nReturns:\n Optional[T]:\n An instance of type `T` if credentials are available and\n loadable; otherwise `None`.\n\nNotes:\n **Guarantees:**\n\n - Implementations should return `None` when no credentials are\n present or when stored credentials cannot be successfully\n decoded or deserialized.\n - The store must not attempt to validate, refresh, or otherwise\n interpret the returned credentials."
"docstring": "Load previously persisted credentials.\n\nReturns:\n T | None:\n An instance of type `T` if credentials are available and\n loadable; otherwise `None`.\n\nNotes:\n **Guarantees:**\n\n - Implementations should return `None` when no credentials are\n present or when stored credentials cannot be successfully\n decoded or deserialized.\n - The store must not attempt to validate, refresh, or otherwise\n interpret the returned credentials."
},
"save": {
"name": "save",
@@ -974,7 +946,7 @@
"name": "RedisCredentialStore",
"kind": "class",
"path": "mail_intake.credentials.redis.RedisCredentialStore",
"signature": "<bound method Class.signature of Class('RedisCredentialStore', 35, 148)>",
"signature": "<bound method Class.signature of Class('RedisCredentialStore', 35, 145)>",
"docstring": "Redis-backed implementation of `CredentialStore`.\n\nThis store persists credentials in Redis and is suitable for\ndistributed and horizontally scaled deployments where credentials\nmust be shared across multiple processes or nodes.\n\nNotes:\n **Responsibilities:**\n\n - This class is responsible only for persistence and retrieval.\n - It does not interpret, validate, refresh, or otherwise manage the\n lifecycle of the credentials being stored.\n\n **Guarantees:**\n\n - The store is intentionally generic and delegates all serialization\n concerns to caller-provided functions.\n - This avoids unsafe mechanisms such as `pickle` and allows\n credential formats to be explicitly controlled and audited.",
"members": {
"redis": {
@@ -1016,31 +988,24 @@
"name": "load",
"kind": "function",
"path": "mail_intake.credentials.redis.RedisCredentialStore.load",
"signature": "<bound method Function.signature of Function('load', 91, 116)>",
"docstring": "Load credentials from Redis.\n\nReturns:\n Optional[T]:\n An instance of type `T` if credentials are present and\n successfully deserialized; otherwise `None`.\n\nNotes:\n **Guarantees:**\n\n - If no value exists for the configured key, or if the stored\n payload cannot be successfully deserialized, this method\n returns `None`.\n - The store does not attempt to validate the returned\n credentials or determine whether they are expired or\n otherwise usable."
"signature": "<bound method Function.signature of Function('load', 88, 113)>",
"docstring": "Load credentials from Redis.\n\nReturns:\n T | None:\n An instance of type `T` if credentials are present and\n successfully deserialized; otherwise `None`.\n\nNotes:\n **Guarantees:**\n\n - If no value exists for the configured key, or if the stored\n payload cannot be successfully deserialized, this method\n returns `None`.\n - The store does not attempt to validate the returned\n credentials or determine whether they are expired or\n otherwise usable."
},
"save": {
"name": "save",
"kind": "function",
"path": "mail_intake.credentials.redis.RedisCredentialStore.save",
"signature": "<bound method Function.signature of Function('save', 118, 136)>",
"signature": "<bound method Function.signature of Function('save', 115, 133)>",
"docstring": "Persist credentials to Redis.\n\nArgs:\n credentials (T):\n The credential object to persist.\n\nNotes:\n **Responsibilities:**\n\n - Any previously stored credentials under the same key are overwritten\n - If a TTL is configured, the credentials will expire automatically after the specified duration"
},
"clear": {
"name": "clear",
"kind": "function",
"path": "mail_intake.credentials.redis.RedisCredentialStore.clear",
"signature": "<bound method Function.signature of Function('clear', 138, 148)>",
"signature": "<bound method Function.signature of Function('clear', 135, 145)>",
"docstring": "Remove stored credentials from Redis.\n\nNotes:\n **Lifecycle:**\n\n - This operation deletes the configured Redis key if it exists\n - Implementations should treat this method as idempotent"
}
}
},
"Any": {
"name": "Any",
"kind": "alias",
"path": "mail_intake.credentials.redis.Any",
"signature": "<bound method Alias.signature of Alias('Any', 'typing.Any')>",
"docstring": null
}
}
},
@@ -1072,13 +1037,6 @@
"signature": "<bound method Alias.signature of Alias('Generic', 'typing.Generic')>",
"docstring": null
},
"Optional": {
"name": "Optional",
"kind": "alias",
"path": "mail_intake.credentials.store.Optional",
"signature": "<bound method Alias.signature of Alias('Optional', 'typing.Optional')>",
"docstring": null
},
"TypeVar": {
"name": "TypeVar",
"kind": "alias",
@@ -1097,28 +1055,28 @@
"name": "CredentialStore",
"kind": "class",
"path": "mail_intake.credentials.store.CredentialStore",
"signature": "<bound method Class.signature of Class('CredentialStore', 29, 105)>",
"signature": "<bound method Class.signature of Class('CredentialStore', 28, 104)>",
"docstring": "Abstract base class defining a generic persistence interface.\n\nUsed for authentication credentials across different backends.\n\nNotes:\n **Responsibilities:**\n\n - Provide persistent storage separating life-cycle management from\n storage mechanics.\n - Keep implementation focused only on persistence.\n\n **Constraints:**\n\n - The store is intentionally agnostic to:\n - The concrete credential type being stored.\n - The serialization format used to persist credentials.\n - The underlying storage backend or durability guarantees.",
"members": {
"load": {
"name": "load",
"kind": "function",
"path": "mail_intake.credentials.store.CredentialStore.load",
"signature": "<bound method Function.signature of Function('load', 50, 68)>",
"docstring": "Load previously persisted credentials.\n\nReturns:\n Optional[T]:\n An instance of type `T` if credentials are available and\n loadable; otherwise `None`.\n\nNotes:\n **Guarantees:**\n\n - Implementations should return `None` when no credentials are\n present or when stored credentials cannot be successfully\n decoded or deserialized.\n - The store must not attempt to validate, refresh, or otherwise\n interpret the returned credentials."
"signature": "<bound method Function.signature of Function('load', 49, 67)>",
"docstring": "Load previously persisted credentials.\n\nReturns:\n T | None:\n An instance of type `T` if credentials are available and\n loadable; otherwise `None`.\n\nNotes:\n **Guarantees:**\n\n - Implementations should return `None` when no credentials are\n present or when stored credentials cannot be successfully\n decoded or deserialized.\n - The store must not attempt to validate, refresh, or otherwise\n interpret the returned credentials."
},
"save": {
"name": "save",
"kind": "function",
"path": "mail_intake.credentials.store.CredentialStore.save",
"signature": "<bound method Function.signature of Function('save', 70, 89)>",
"signature": "<bound method Function.signature of Function('save', 69, 88)>",
"docstring": "Persist credentials to the underlying storage backend.\n\nArgs:\n credentials (T):\n The credential object to persist.\n\nNotes:\n **Lifecycle:**\n\n - This method is invoked when credentials are newly obtained or have been refreshed and are known to be valid at the time of persistence\n\n **Responsibilities:**\n\n - Ensuring durability appropriate to the deployment context\n - Applying encryption or access controls where required\n - Overwriting any previously stored credentials"
},
"clear": {
"name": "clear",
"kind": "function",
"path": "mail_intake.credentials.store.CredentialStore.clear",
"signature": "<bound method Function.signature of Function('clear', 91, 105)>",
"signature": "<bound method Function.signature of Function('clear', 90, 104)>",
"docstring": "Remove any persisted credentials from the store.\n\nNotes:\n **Lifecycle:**\n\n - This method is called when credentials are known to be invalid, revoked, corrupted, or otherwise unusable\n - Must ensure that no stale authentication material remains accessible\n\n **Guarantees:**\n\n - Implementations should treat this operation as idempotent"
}
}
@@ -1153,7 +1111,7 @@
"kind": "function",
"path": "mail_intake.ingestion.MailIntakeReader.iter_threads",
"signature": "<bound method Alias.signature of Alias('iter_threads', 'mail_intake.ingestion.reader.MailIntakeReader.iter_threads')>",
"docstring": "Iterate over threads constructed from messages matching a query.\n\nArgs:\n query (str):\n Provider-specific query string used to filter messages.\n\nYields:\n MailIntakeThread:\n An iterator of `MailIntakeThread` instances.\n\nRaises:\n `MailIntakeParsingError`:\n If a message cannot be parsed.\n\nNotes:\n **Guarantees:**\n\n - Messages are grouped by `thread_id` and yielded as complete\n thread objects containing all associated messages."
"docstring": "Iterate over threads constructed from messages matching a query.\n\nArgs:\n query (str):\n Provider-specific query string used to filter messages.\n\nReturns:\n Iterator[MailIntakeThread]:\n An iterator over `MailIntakeThread` instances.\n\nRaises:\n `MailIntakeParsingError`:\n If a message cannot be parsed.\n\nNotes:\n **Guarantees:**\n\n - Messages are grouped by `thread_id` and yielded as complete\n thread objects containing all associated messages."
}
}
},
@@ -1164,6 +1122,13 @@
"signature": null,
"docstring": "# Summary\n\nHigh-level mail ingestion orchestration for Mail Intake.\n\nThis module provides the primary, provider-agnostic entry point for\nreading and processing mail data.\n\nIt coordinates:\n\n- Mail adapter access.\n- Message and thread iteration.\n- Header and body parsing.\n- Normalization and model construction.\n\nNo provider-specific logic or API semantics are permitted in this layer.",
"members": {
"Iterator": {
"name": "Iterator",
"kind": "alias",
"path": "mail_intake.ingestion.reader.Iterator",
"signature": "<bound method Alias.signature of Alias('Iterator', 'collections.abc.Iterator')>",
"docstring": null
},
"datetime": {
"name": "datetime",
"kind": "alias",
@@ -1171,20 +1136,6 @@
"signature": "<bound method Alias.signature of Alias('datetime', 'datetime.datetime')>",
"docstring": null
},
"Iterator": {
"name": "Iterator",
"kind": "alias",
"path": "mail_intake.ingestion.reader.Iterator",
"signature": "<bound method Alias.signature of Alias('Iterator', 'typing.Iterator')>",
"docstring": null
},
"Dict": {
"name": "Dict",
"kind": "alias",
"path": "mail_intake.ingestion.reader.Dict",
"signature": "<bound method Alias.signature of Alias('Dict', 'typing.Dict')>",
"docstring": null
},
"Any": {
"name": "Any",
"kind": "alias",
@@ -1204,24 +1155,31 @@
"kind": "function",
"path": "mail_intake.ingestion.reader.MailIntakeAdapter.iter_message_refs",
"signature": "<bound method Alias.signature of Alias('iter_message_refs', 'mail_intake.adapters.base.MailIntakeAdapter.iter_message_refs')>",
"docstring": "Iterate over lightweight message references matching a query.\n\nArgs:\n query (str):\n Provider-specific query string used to filter messages.\n\nYields:\n Dict[str, str]:\n Dictionaries containing message and thread identifiers.\n\nNotes:\n **Guarantees:**\n\n - Implementations must yield dictionaries containing at least\n `message_id` and `thread_id`.\n\nExample:\n Typical yield:\n\n ```python\n {\n \"message_id\": \"...\",\n \"thread_id\": \"...\"\n }\n ```"
"docstring": "Iterate over lightweight message references matching a query.\n\nArgs:\n query (str):\n Provider-specific query string used to filter messages.\n\nReturns:\n Iterator[dict[str, str]]:\n An iterator over lightweight message reference dictionaries.\n\nYields:\n dict[str, str]:\n Dictionaries containing message and thread identifiers.\n\nNotes:\n **Guarantees:**\n\n - Implementations must yield dictionaries containing at least\n `message_id` and `thread_id`.\n\nExample:\n Typical yield:\n\n ```python\n {\n \"message_id\": \"...\",\n \"thread_id\": \"...\"\n }\n ```"
},
"fetch_message": {
"name": "fetch_message",
"kind": "function",
"path": "mail_intake.ingestion.reader.MailIntakeAdapter.fetch_message",
"signature": "<bound method Alias.signature of Alias('fetch_message', 'mail_intake.adapters.base.MailIntakeAdapter.fetch_message')>",
"docstring": "Fetch a full raw message by message identifier.\n\nArgs:\n message_id (str):\n Provider-specific message identifier.\n\nReturns:\n Dict[str, Any]:\n Provider-native message payload (e.g., Gmail message JSON structure)."
"docstring": "Fetch a full raw message by message identifier.\n\nArgs:\n message_id (str):\n Provider-specific message identifier.\n\nReturns:\n dict[str, Any]:\n Provider-native message payload (e.g., Gmail message JSON structure)."
},
"fetch_thread": {
"name": "fetch_thread",
"kind": "function",
"path": "mail_intake.ingestion.reader.MailIntakeAdapter.fetch_thread",
"signature": "<bound method Alias.signature of Alias('fetch_thread', 'mail_intake.adapters.base.MailIntakeAdapter.fetch_thread')>",
"docstring": "Fetch a full raw thread by thread identifier.\n\nArgs:\n thread_id (str):\n Provider-specific thread identifier.\n\nReturns:\n Dict[str, Any]:\n Provider-native thread payload."
"docstring": "Fetch a full raw thread by thread identifier.\n\nArgs:\n thread_id (str):\n Provider-specific thread identifier.\n\nReturns:\n dict[str, Any]:\n Provider-native thread payload."
}
}
},
"MailIntakeParsingError": {
"name": "MailIntakeParsingError",
"kind": "class",
"path": "mail_intake.ingestion.reader.MailIntakeParsingError",
"signature": "<bound method Alias.signature of Alias('MailIntakeParsingError', 'mail_intake.exceptions.MailIntakeParsingError')>",
"docstring": "Errors encountered while parsing message content.\n\nNotes:\n **Lifecycle:**\n\n - Raised when raw provider payloads cannot be interpreted or\n normalized into internal domain models."
},
"MailIntakeMessage": {
"name": "MailIntakeMessage",
"kind": "class",
@@ -1345,26 +1303,26 @@
}
}
},
"parse_headers": {
"name": "parse_headers",
"extract_body": {
"name": "extract_body",
"kind": "function",
"path": "mail_intake.ingestion.reader.parse_headers",
"signature": "<bound method Alias.signature of Alias('parse_headers', 'mail_intake.parsers.headers.parse_headers')>",
"docstring": "Convert a list of Gmail-style headers into a normalized dict.\n\nArgs:\n raw_headers (List[Dict[str, str]]):\n List of header dictionaries, each containing `name` and `value` keys.\n\nReturns:\n Dict[str, str]:\n Dictionary mapping lowercase header names to stripped values.\n\nNotes:\n **Guarantees:**\n\n - Provider payloads (such as Gmail) typically represent headers as a\n list of name/value mappings.\n - This function normalizes them into a case-insensitive dictionary\n keyed by lowercase header names.\n\nExample:\n Typical usage:\n\n ```python\n Input:\n [\n {\"name\": \"From\", \"value\": \"John Doe <john@example.com>\"},\n {\"name\": \"Subject\", \"value\": \"Re: Interview Update\"},\n ]\n\n Output:\n {\n \"from\": \"John Doe <john@example.com>\",\n \"subject\": \"Re: Interview Update\",\n }\n ```"
"path": "mail_intake.ingestion.reader.extract_body",
"signature": "<bound method Alias.signature of Alias('extract_body', 'mail_intake.parsers.body.extract_body')>",
"docstring": "Extract the best-effort message body from a Gmail payload.\n\nPriority:\n\n1. `text/plain`\n2. `text/html` (stripped to text)\n3. Single-part body\n4. Empty string (if nothing usable found)\n\nArgs:\n payload (dict[str, Any]):\n Provider-native message payload dictionary.\n\nReturns:\n str:\n Extracted plain-text message body."
},
"extract_sender": {
"name": "extract_sender",
"kind": "function",
"path": "mail_intake.ingestion.reader.extract_sender",
"signature": "<bound method Alias.signature of Alias('extract_sender', 'mail_intake.parsers.headers.extract_sender')>",
"docstring": "Extract sender email and optional display name from headers.\n\nArgs:\n headers (Dict[str, str]):\n Normalized header dictionary as returned by `parse_headers()`.\n\nReturns:\n Tuple[str, Optional[str]]:\n A tuple `(email, name)` where `email` is the sender email address\n and `name` is the display name, or `None` if unavailable.\n\nNotes:\n **Responsibilities:**\n\n - This function parses the `From` header and attempts to extract\n sender email address and optional human-readable display name.\n\nExample:\n Typical values:\n\n - `\"John Doe <john@example.com>\"` -> `(\"john@example.com\", \"John Doe\")`\n - `\"john@example.com\"` -> `(\"john@example.com\", None)`"
"docstring": "Extract sender email and optional display name from headers.\n\nArgs:\n headers (dict[str, str]):\n Normalized header dictionary as returned by `parse_headers()`.\n\nReturns:\n tuple[str, str | None]:\n A tuple `(email, name)` where `email` is the sender email address\n and `name` is the display name, or `None` if unavailable.\n\nNotes:\n **Responsibilities:**\n\n - This function parses the `From` header and attempts to extract\n sender email address and optional human-readable display name.\n\nExample:\n Typical values:\n\n - `\"John Doe <john@example.com>\"` -> `(\"john@example.com\", \"John Doe\")`\n - `\"john@example.com\"` -> `(\"john@example.com\", None)`"
},
"extract_body": {
"name": "extract_body",
"parse_headers": {
"name": "parse_headers",
"kind": "function",
"path": "mail_intake.ingestion.reader.extract_body",
"signature": "<bound method Alias.signature of Alias('extract_body', 'mail_intake.parsers.body.extract_body')>",
"docstring": "Extract the best-effort message body from a Gmail payload.\n\nPriority:\n\n1. `text/plain`\n2. `text/html` (stripped to text)\n3. Single-part body\n4. Empty string (if nothing usable found)\n\nArgs:\n payload (Dict[str, Any]):\n Provider-native message payload dictionary.\n\nReturns:\n str:\n Extracted plain-text message body."
"path": "mail_intake.ingestion.reader.parse_headers",
"signature": "<bound method Alias.signature of Alias('parse_headers', 'mail_intake.parsers.headers.parse_headers')>",
"docstring": "Convert a list of Gmail-style headers into a normalized dict.\n\nArgs:\n raw_headers (list[dict[str, str]]):\n List of header dictionaries, each containing `name` and `value` keys.\n\nReturns:\n dict[str, str]:\n Dictionary mapping lowercase header names to stripped values.\n\nNotes:\n **Guarantees:**\n\n - Provider payloads (such as Gmail) typically represent headers as a\n list of name/value mappings.\n - This function normalizes them into a case-insensitive dictionary\n keyed by lowercase header names.\n\nExample:\n Typical usage:\n\n ```python\n Input:\n [\n {\"name\": \"From\", \"value\": \"John Doe <john@example.com>\"},\n {\"name\": \"Subject\", \"value\": \"Re: Interview Update\"},\n ]\n\n Output:\n {\n \"from\": \"John Doe <john@example.com>\",\n \"subject\": \"Re: Interview Update\",\n }\n ```"
},
"normalize_subject": {
"name": "normalize_subject",
@@ -1373,33 +1331,26 @@
"signature": "<bound method Alias.signature of Alias('normalize_subject', 'mail_intake.parsers.subject.normalize_subject')>",
"docstring": "Normalize an email subject for thread-level comparison.\n\nArgs:\n subject (str):\n Raw subject line from a message header.\n\nReturns:\n str:\n Normalized subject string suitable for thread grouping.\n\nNotes:\n **Responsibilities:**\n\n - Strips common prefixes such as `Re:`, `Fwd:`, and `FW:`.\n - Repeats prefix stripping to handle stacked prefixes.\n - Collapses excessive whitespace.\n - Preserves original casing (no lowercasing).\n\n **Guarantees:**\n\n - This function is intentionally conservative and avoids aggressive\n transformations that could alter the semantic meaning of the subject."
},
"MailIntakeParsingError": {
"name": "MailIntakeParsingError",
"kind": "class",
"path": "mail_intake.ingestion.reader.MailIntakeParsingError",
"signature": "<bound method Alias.signature of Alias('MailIntakeParsingError', 'mail_intake.exceptions.MailIntakeParsingError')>",
"docstring": "Errors encountered while parsing message content.\n\nNotes:\n **Lifecycle:**\n\n - Raised when raw provider payloads cannot be interpreted or\n normalized into internal domain models."
},
"MailIntakeReader": {
"name": "MailIntakeReader",
"kind": "class",
"path": "mail_intake.ingestion.reader.MailIntakeReader",
"signature": "<bound method Class.signature of Class('MailIntakeReader', 31, 171)>",
"signature": "<bound method Class.signature of Class('MailIntakeReader', 32, 172)>",
"docstring": "High-level read-only ingestion interface.\n\nNotes:\n **Responsibilities:**\n\n - This class is the primary entry point for consumers of the\n Mail Intake library.\n - It orchestrates the full ingestion pipeline:\n - Querying the adapter for message references.\n - Fetching raw provider messages.\n - Parsing and normalizing message data.\n - Constructing domain models.\n\n **Constraints:**\n\n - This class is intentionally: Provider-agnostic, stateless beyond\n iteration scope, read-only.",
"members": {
"iter_messages": {
"name": "iter_messages",
"kind": "function",
"path": "mail_intake.ingestion.reader.MailIntakeReader.iter_messages",
"signature": "<bound method Function.signature of Function('iter_messages', 62, 80)>",
"signature": "<bound method Function.signature of Function('iter_messages', 63, 81)>",
"docstring": "Iterate over parsed messages matching a provider query.\n\nArgs:\n query (str):\n Provider-specific query string used to filter messages.\n\nYields:\n MailIntakeMessage:\n Fully parsed and normalized `MailIntakeMessage` instances.\n\nRaises:\n MailIntakeParsingError:\n If a message cannot be parsed."
},
"iter_threads": {
"name": "iter_threads",
"kind": "function",
"path": "mail_intake.ingestion.reader.MailIntakeReader.iter_threads",
"signature": "<bound method Function.signature of Function('iter_threads', 82, 120)>",
"docstring": "Iterate over threads constructed from messages matching a query.\n\nArgs:\n query (str):\n Provider-specific query string used to filter messages.\n\nYields:\n MailIntakeThread:\n An iterator of `MailIntakeThread` instances.\n\nRaises:\n `MailIntakeParsingError`:\n If a message cannot be parsed.\n\nNotes:\n **Guarantees:**\n\n - Messages are grouped by `thread_id` and yielded as complete\n thread objects containing all associated messages."
"signature": "<bound method Function.signature of Function('iter_threads', 83, 121)>",
"docstring": "Iterate over threads constructed from messages matching a query.\n\nArgs:\n query (str):\n Provider-specific query string used to filter messages.\n\nReturns:\n Iterator[MailIntakeThread]:\n An iterator over `MailIntakeThread` instances.\n\nRaises:\n `MailIntakeParsingError`:\n If a message cannot be parsed.\n\nNotes:\n **Guarantees:**\n\n - Messages are grouped by `thread_id` and yielded as complete\n thread objects containing all associated messages."
}
}
}
@@ -1558,25 +1509,11 @@
"signature": "<bound method Alias.signature of Alias('datetime', 'datetime.datetime')>",
"docstring": null
},
"Optional": {
"name": "Optional",
"kind": "alias",
"path": "mail_intake.models.message.Optional",
"signature": "<bound method Alias.signature of Alias('Optional', 'typing.Optional')>",
"docstring": null
},
"Dict": {
"name": "Dict",
"kind": "alias",
"path": "mail_intake.models.message.Dict",
"signature": "<bound method Alias.signature of Alias('Dict', 'typing.Dict')>",
"docstring": null
},
"MailIntakeMessage": {
"name": "MailIntakeMessage",
"kind": "class",
"path": "mail_intake.models.message.MailIntakeMessage",
"signature": "<bound method Class.signature of Class('MailIntakeMessage', 19, 80)>",
"signature": "<bound method Class.signature of Class('MailIntakeMessage', 18, 79)>",
"docstring": "Canonical internal representation of a single email message.\n\nNotes:\n **Guarantees:**\n\n - This model represents a fully parsed and normalized email message.\n - It is intentionally provider-agnostic and suitable for\n persistence, indexing, and downstream processing.\n\n **Constraints:**\n\n - No provider-specific identifiers, payloads, or API semantics\n should appear in this model.",
"members": {
"message_id": {
@@ -1674,20 +1611,6 @@
"signature": "<bound method Alias.signature of Alias('datetime', 'datetime.datetime')>",
"docstring": null
},
"List": {
"name": "List",
"kind": "alias",
"path": "mail_intake.models.thread.List",
"signature": "<bound method Alias.signature of Alias('List', 'typing.List')>",
"docstring": null
},
"Set": {
"name": "Set",
"kind": "alias",
"path": "mail_intake.models.thread.Set",
"signature": "<bound method Alias.signature of Alias('Set', 'typing.Set')>",
"docstring": null
},
"MailIntakeMessage": {
"name": "MailIntakeMessage",
"kind": "class",
@@ -1764,7 +1687,7 @@
"name": "MailIntakeThread",
"kind": "class",
"path": "mail_intake.models.thread.MailIntakeThread",
"signature": "<bound method Class.signature of Class('MailIntakeThread', 20, 81)>",
"signature": "<bound method Class.signature of Class('MailIntakeThread', 19, 80)>",
"docstring": "Canonical internal representation of an email thread.\n\nNotes:\n **Guarantees:**\n\n - A thread groups multiple related messages under a single subject\n and participant set.\n - It is designed to support reasoning over conversational context\n such as job applications, interviews, follow-ups, and ongoing discussions.\n - This model is provider-agnostic and safe to persist.",
"members": {
"thread_id": {
@@ -1806,17 +1729,10 @@
"name": "add_message",
"kind": "function",
"path": "mail_intake.models.thread.MailIntakeThread.add_message",
"signature": "<bound method Function.signature of Function('add_message', 60, 81)>",
"signature": "<bound method Function.signature of Function('add_message', 59, 80)>",
"docstring": "Add a message to the thread and update derived fields.\n\nArgs:\n message (MailIntakeMessage):\n Parsed mail message to add to the thread.\n\nNotes:\n **Responsibilities:**\n\n - Appends the message to the thread.\n - Tracks unique participants.\n - Updates the last activity timestamp."
}
}
},
"Optional": {
"name": "Optional",
"kind": "alias",
"path": "mail_intake.models.thread.Optional",
"signature": "<bound method Alias.signature of Alias('Optional', 'typing.Optional')>",
"docstring": null
}
}
}
@@ -1834,21 +1750,21 @@
"kind": "function",
"path": "mail_intake.parsers.extract_body",
"signature": "<bound method Alias.signature of Alias('extract_body', 'mail_intake.parsers.body.extract_body')>",
"docstring": "Extract the best-effort message body from a Gmail payload.\n\nPriority:\n\n1. `text/plain`\n2. `text/html` (stripped to text)\n3. Single-part body\n4. Empty string (if nothing usable found)\n\nArgs:\n payload (Dict[str, Any]):\n Provider-native message payload dictionary.\n\nReturns:\n str:\n Extracted plain-text message body."
"docstring": "Extract the best-effort message body from a Gmail payload.\n\nPriority:\n\n1. `text/plain`\n2. `text/html` (stripped to text)\n3. Single-part body\n4. Empty string (if nothing usable found)\n\nArgs:\n payload (dict[str, Any]):\n Provider-native message payload dictionary.\n\nReturns:\n str:\n Extracted plain-text message body."
},
"parse_headers": {
"name": "parse_headers",
"kind": "function",
"path": "mail_intake.parsers.parse_headers",
"signature": "<bound method Alias.signature of Alias('parse_headers', 'mail_intake.parsers.headers.parse_headers')>",
"docstring": "Convert a list of Gmail-style headers into a normalized dict.\n\nArgs:\n raw_headers (List[Dict[str, str]]):\n List of header dictionaries, each containing `name` and `value` keys.\n\nReturns:\n Dict[str, str]:\n Dictionary mapping lowercase header names to stripped values.\n\nNotes:\n **Guarantees:**\n\n - Provider payloads (such as Gmail) typically represent headers as a\n list of name/value mappings.\n - This function normalizes them into a case-insensitive dictionary\n keyed by lowercase header names.\n\nExample:\n Typical usage:\n\n ```python\n Input:\n [\n {\"name\": \"From\", \"value\": \"John Doe <john@example.com>\"},\n {\"name\": \"Subject\", \"value\": \"Re: Interview Update\"},\n ]\n\n Output:\n {\n \"from\": \"John Doe <john@example.com>\",\n \"subject\": \"Re: Interview Update\",\n }\n ```"
"docstring": "Convert a list of Gmail-style headers into a normalized dict.\n\nArgs:\n raw_headers (list[dict[str, str]]):\n List of header dictionaries, each containing `name` and `value` keys.\n\nReturns:\n dict[str, str]:\n Dictionary mapping lowercase header names to stripped values.\n\nNotes:\n **Guarantees:**\n\n - Provider payloads (such as Gmail) typically represent headers as a\n list of name/value mappings.\n - This function normalizes them into a case-insensitive dictionary\n keyed by lowercase header names.\n\nExample:\n Typical usage:\n\n ```python\n Input:\n [\n {\"name\": \"From\", \"value\": \"John Doe <john@example.com>\"},\n {\"name\": \"Subject\", \"value\": \"Re: Interview Update\"},\n ]\n\n Output:\n {\n \"from\": \"John Doe <john@example.com>\",\n \"subject\": \"Re: Interview Update\",\n }\n ```"
},
"extract_sender": {
"name": "extract_sender",
"kind": "function",
"path": "mail_intake.parsers.extract_sender",
"signature": "<bound method Alias.signature of Alias('extract_sender', 'mail_intake.parsers.headers.extract_sender')>",
"docstring": "Extract sender email and optional display name from headers.\n\nArgs:\n headers (Dict[str, str]):\n Normalized header dictionary as returned by `parse_headers()`.\n\nReturns:\n Tuple[str, Optional[str]]:\n A tuple `(email, name)` where `email` is the sender email address\n and `name` is the display name, or `None` if unavailable.\n\nNotes:\n **Responsibilities:**\n\n - This function parses the `From` header and attempts to extract\n sender email address and optional human-readable display name.\n\nExample:\n Typical values:\n\n - `\"John Doe <john@example.com>\"` -> `(\"john@example.com\", \"John Doe\")`\n - `\"john@example.com\"` -> `(\"john@example.com\", None)`"
"docstring": "Extract sender email and optional display name from headers.\n\nArgs:\n headers (dict[str, str]):\n Normalized header dictionary as returned by `parse_headers()`.\n\nReturns:\n tuple[str, str | None]:\n A tuple `(email, name)` where `email` is the sender email address\n and `name` is the display name, or `None` if unavailable.\n\nNotes:\n **Responsibilities:**\n\n - This function parses the `From` header and attempts to extract\n sender email address and optional human-readable display name.\n\nExample:\n Typical values:\n\n - `\"John Doe <john@example.com>\"` -> `(\"john@example.com\", \"John Doe\")`\n - `\"john@example.com\"` -> `(\"john@example.com\", None)`"
},
"normalize_subject": {
"name": "normalize_subject",
@@ -1871,13 +1787,6 @@
"signature": "<bound method Alias.signature of Alias('base64', 'base64')>",
"docstring": null
},
"Dict": {
"name": "Dict",
"kind": "alias",
"path": "mail_intake.parsers.body.Dict",
"signature": "<bound method Alias.signature of Alias('Dict', 'typing.Dict')>",
"docstring": null
},
"Any": {
"name": "Any",
"kind": "alias",
@@ -1885,13 +1794,6 @@
"signature": "<bound method Alias.signature of Alias('Any', 'typing.Any')>",
"docstring": null
},
"Optional": {
"name": "Optional",
"kind": "alias",
"path": "mail_intake.parsers.body.Optional",
"signature": "<bound method Alias.signature of Alias('Optional', 'typing.Optional')>",
"docstring": null
},
"BeautifulSoup": {
"name": "BeautifulSoup",
"kind": "alias",
@@ -1911,7 +1813,7 @@
"kind": "function",
"path": "mail_intake.parsers.body.extract_body",
"signature": "<bound method Function.signature of Function('extract_body', 85, 133)>",
"docstring": "Extract the best-effort message body from a Gmail payload.\n\nPriority:\n\n1. `text/plain`\n2. `text/html` (stripped to text)\n3. Single-part body\n4. Empty string (if nothing usable found)\n\nArgs:\n payload (Dict[str, Any]):\n Provider-native message payload dictionary.\n\nReturns:\n str:\n Extracted plain-text message body."
"docstring": "Extract the best-effort message body from a Gmail payload.\n\nPriority:\n\n1. `text/plain`\n2. `text/html` (stripped to text)\n3. Single-part body\n4. Empty string (if nothing usable found)\n\nArgs:\n payload (dict[str, Any]):\n Provider-native message payload dictionary.\n\nReturns:\n str:\n Extracted plain-text message body."
}
}
},
@@ -1922,47 +1824,19 @@
"signature": null,
"docstring": "# Summary\n\nMessage header parsing utilities for Mail Intake.\n\nThis module provides helper functions for normalizing and extracting\nuseful information from provider-native message headers.\n\nThe functions here are intentionally simple and tolerant of malformed\nor incomplete header data.",
"members": {
"Dict": {
"name": "Dict",
"kind": "alias",
"path": "mail_intake.parsers.headers.Dict",
"signature": "<bound method Alias.signature of Alias('Dict', 'typing.Dict')>",
"docstring": null
},
"List": {
"name": "List",
"kind": "alias",
"path": "mail_intake.parsers.headers.List",
"signature": "<bound method Alias.signature of Alias('List', 'typing.List')>",
"docstring": null
},
"Tuple": {
"name": "Tuple",
"kind": "alias",
"path": "mail_intake.parsers.headers.Tuple",
"signature": "<bound method Alias.signature of Alias('Tuple', 'typing.Tuple')>",
"docstring": null
},
"Optional": {
"name": "Optional",
"kind": "alias",
"path": "mail_intake.parsers.headers.Optional",
"signature": "<bound method Alias.signature of Alias('Optional', 'typing.Optional')>",
"docstring": null
},
"parse_headers": {
"name": "parse_headers",
"kind": "function",
"path": "mail_intake.parsers.headers.parse_headers",
"signature": "<bound method Function.signature of Function('parse_headers', 16, 64)>",
"docstring": "Convert a list of Gmail-style headers into a normalized dict.\n\nArgs:\n raw_headers (List[Dict[str, str]]):\n List of header dictionaries, each containing `name` and `value` keys.\n\nReturns:\n Dict[str, str]:\n Dictionary mapping lowercase header names to stripped values.\n\nNotes:\n **Guarantees:**\n\n - Provider payloads (such as Gmail) typically represent headers as a\n list of name/value mappings.\n - This function normalizes them into a case-insensitive dictionary\n keyed by lowercase header names.\n\nExample:\n Typical usage:\n\n ```python\n Input:\n [\n {\"name\": \"From\", \"value\": \"John Doe <john@example.com>\"},\n {\"name\": \"Subject\", \"value\": \"Re: Interview Update\"},\n ]\n\n Output:\n {\n \"from\": \"John Doe <john@example.com>\",\n \"subject\": \"Re: Interview Update\",\n }\n ```"
"signature": "<bound method Function.signature of Function('parse_headers', 14, 62)>",
"docstring": "Convert a list of Gmail-style headers into a normalized dict.\n\nArgs:\n raw_headers (list[dict[str, str]]):\n List of header dictionaries, each containing `name` and `value` keys.\n\nReturns:\n dict[str, str]:\n Dictionary mapping lowercase header names to stripped values.\n\nNotes:\n **Guarantees:**\n\n - Provider payloads (such as Gmail) typically represent headers as a\n list of name/value mappings.\n - This function normalizes them into a case-insensitive dictionary\n keyed by lowercase header names.\n\nExample:\n Typical usage:\n\n ```python\n Input:\n [\n {\"name\": \"From\", \"value\": \"John Doe <john@example.com>\"},\n {\"name\": \"Subject\", \"value\": \"Re: Interview Update\"},\n ]\n\n Output:\n {\n \"from\": \"John Doe <john@example.com>\",\n \"subject\": \"Re: Interview Update\",\n }\n ```"
},
"extract_sender": {
"name": "extract_sender",
"kind": "function",
"path": "mail_intake.parsers.headers.extract_sender",
"signature": "<bound method Function.signature of Function('extract_sender', 67, 102)>",
"docstring": "Extract sender email and optional display name from headers.\n\nArgs:\n headers (Dict[str, str]):\n Normalized header dictionary as returned by `parse_headers()`.\n\nReturns:\n Tuple[str, Optional[str]]:\n A tuple `(email, name)` where `email` is the sender email address\n and `name` is the display name, or `None` if unavailable.\n\nNotes:\n **Responsibilities:**\n\n - This function parses the `From` header and attempts to extract\n sender email address and optional human-readable display name.\n\nExample:\n Typical values:\n\n - `\"John Doe <john@example.com>\"` -> `(\"john@example.com\", \"John Doe\")`\n - `\"john@example.com\"` -> `(\"john@example.com\", None)`"
"signature": "<bound method Function.signature of Function('extract_sender', 65, 100)>",
"docstring": "Extract sender email and optional display name from headers.\n\nArgs:\n headers (dict[str, str]):\n Normalized header dictionary as returned by `parse_headers()`.\n\nReturns:\n tuple[str, str | None]:\n A tuple `(email, name)` where `email` is the sender email address\n and `name` is the display name, or `None` if unavailable.\n\nNotes:\n **Responsibilities:**\n\n - This function parses the `From` header and attempts to extract\n sender email address and optional human-readable display name.\n\nExample:\n Typical values:\n\n - `\"John Doe <john@example.com>\"` -> `(\"john@example.com\", \"John Doe\")`\n - `\"john@example.com\"` -> `(\"john@example.com\", None)`"
}
}
},
@@ -1984,7 +1858,7 @@
"name": "normalize_subject",
"kind": "function",
"path": "mail_intake.parsers.subject.normalize_subject",
"signature": "<bound method Function.signature of Function('normalize_subject', 22, 62)>",
"signature": "<bound method Function.signature of Function('normalize_subject', 21, 61)>",
"docstring": "Normalize an email subject for thread-level comparison.\n\nArgs:\n subject (str):\n Raw subject line from a message header.\n\nReturns:\n str:\n Normalized subject string suitable for thread grouping.\n\nNotes:\n **Responsibilities:**\n\n - Strips common prefixes such as `Re:`, `Fwd:`, and `FW:`.\n - Repeats prefix stripping to handle stacked prefixes.\n - Collapses excessive whitespace.\n - Preserves original casing (no lowercasing).\n\n **Guarantees:**\n\n - This function is intentionally conservative and avoids aggressive\n transformations that could alter the semantic meaning of the subject."
}
}

View File

@@ -148,25 +148,11 @@
"signature": "<bound method Alias.signature of Alias('datetime', 'datetime.datetime')>",
"docstring": null
},
"Optional": {
"name": "Optional",
"kind": "alias",
"path": "mail_intake.models.message.Optional",
"signature": "<bound method Alias.signature of Alias('Optional', 'typing.Optional')>",
"docstring": null
},
"Dict": {
"name": "Dict",
"kind": "alias",
"path": "mail_intake.models.message.Dict",
"signature": "<bound method Alias.signature of Alias('Dict', 'typing.Dict')>",
"docstring": null
},
"MailIntakeMessage": {
"name": "MailIntakeMessage",
"kind": "class",
"path": "mail_intake.models.message.MailIntakeMessage",
"signature": "<bound method Class.signature of Class('MailIntakeMessage', 19, 80)>",
"signature": "<bound method Class.signature of Class('MailIntakeMessage', 18, 79)>",
"docstring": "Canonical internal representation of a single email message.\n\nNotes:\n **Guarantees:**\n\n - This model represents a fully parsed and normalized email message.\n - It is intentionally provider-agnostic and suitable for\n persistence, indexing, and downstream processing.\n\n **Constraints:**\n\n - No provider-specific identifiers, payloads, or API semantics\n should appear in this model.",
"members": {
"message_id": {
@@ -264,20 +250,6 @@
"signature": "<bound method Alias.signature of Alias('datetime', 'datetime.datetime')>",
"docstring": null
},
"List": {
"name": "List",
"kind": "alias",
"path": "mail_intake.models.thread.List",
"signature": "<bound method Alias.signature of Alias('List', 'typing.List')>",
"docstring": null
},
"Set": {
"name": "Set",
"kind": "alias",
"path": "mail_intake.models.thread.Set",
"signature": "<bound method Alias.signature of Alias('Set', 'typing.Set')>",
"docstring": null
},
"MailIntakeMessage": {
"name": "MailIntakeMessage",
"kind": "class",
@@ -354,7 +326,7 @@
"name": "MailIntakeThread",
"kind": "class",
"path": "mail_intake.models.thread.MailIntakeThread",
"signature": "<bound method Class.signature of Class('MailIntakeThread', 20, 81)>",
"signature": "<bound method Class.signature of Class('MailIntakeThread', 19, 80)>",
"docstring": "Canonical internal representation of an email thread.\n\nNotes:\n **Guarantees:**\n\n - A thread groups multiple related messages under a single subject\n and participant set.\n - It is designed to support reasoning over conversational context\n such as job applications, interviews, follow-ups, and ongoing discussions.\n - This model is provider-agnostic and safe to persist.",
"members": {
"thread_id": {
@@ -396,17 +368,10 @@
"name": "add_message",
"kind": "function",
"path": "mail_intake.models.thread.MailIntakeThread.add_message",
"signature": "<bound method Function.signature of Function('add_message', 60, 81)>",
"signature": "<bound method Function.signature of Function('add_message', 59, 80)>",
"docstring": "Add a message to the thread and update derived fields.\n\nArgs:\n message (MailIntakeMessage):\n Parsed mail message to add to the thread.\n\nNotes:\n **Responsibilities:**\n\n - Appends the message to the thread.\n - Tracks unique participants.\n - Updates the last activity timestamp."
}
}
},
"Optional": {
"name": "Optional",
"kind": "alias",
"path": "mail_intake.models.thread.Optional",
"signature": "<bound method Alias.signature of Alias('Optional', 'typing.Optional')>",
"docstring": null
}
}
}

View File

@@ -18,25 +18,11 @@
"signature": "<bound method Alias.signature of Alias('datetime', 'datetime.datetime')>",
"docstring": null
},
"Optional": {
"name": "Optional",
"kind": "alias",
"path": "mail_intake.models.message.Optional",
"signature": "<bound method Alias.signature of Alias('Optional', 'typing.Optional')>",
"docstring": null
},
"Dict": {
"name": "Dict",
"kind": "alias",
"path": "mail_intake.models.message.Dict",
"signature": "<bound method Alias.signature of Alias('Dict', 'typing.Dict')>",
"docstring": null
},
"MailIntakeMessage": {
"name": "MailIntakeMessage",
"kind": "class",
"path": "mail_intake.models.message.MailIntakeMessage",
"signature": "<bound method Class.signature of Class('MailIntakeMessage', 19, 80)>",
"signature": "<bound method Class.signature of Class('MailIntakeMessage', 18, 79)>",
"docstring": "Canonical internal representation of a single email message.\n\nNotes:\n **Guarantees:**\n\n - This model represents a fully parsed and normalized email message.\n - It is intentionally provider-agnostic and suitable for\n persistence, indexing, and downstream processing.\n\n **Constraints:**\n\n - No provider-specific identifiers, payloads, or API semantics\n should appear in this model.",
"members": {
"message_id": {

View File

@@ -25,20 +25,6 @@
"signature": "<bound method Alias.signature of Alias('datetime', 'datetime.datetime')>",
"docstring": null
},
"List": {
"name": "List",
"kind": "alias",
"path": "mail_intake.models.thread.List",
"signature": "<bound method Alias.signature of Alias('List', 'typing.List')>",
"docstring": null
},
"Set": {
"name": "Set",
"kind": "alias",
"path": "mail_intake.models.thread.Set",
"signature": "<bound method Alias.signature of Alias('Set', 'typing.Set')>",
"docstring": null
},
"MailIntakeMessage": {
"name": "MailIntakeMessage",
"kind": "class",
@@ -115,7 +101,7 @@
"name": "MailIntakeThread",
"kind": "class",
"path": "mail_intake.models.thread.MailIntakeThread",
"signature": "<bound method Class.signature of Class('MailIntakeThread', 20, 81)>",
"signature": "<bound method Class.signature of Class('MailIntakeThread', 19, 80)>",
"docstring": "Canonical internal representation of an email thread.\n\nNotes:\n **Guarantees:**\n\n - A thread groups multiple related messages under a single subject\n and participant set.\n - It is designed to support reasoning over conversational context\n such as job applications, interviews, follow-ups, and ongoing discussions.\n - This model is provider-agnostic and safe to persist.",
"members": {
"thread_id": {
@@ -157,17 +143,10 @@
"name": "add_message",
"kind": "function",
"path": "mail_intake.models.thread.MailIntakeThread.add_message",
"signature": "<bound method Function.signature of Function('add_message', 60, 81)>",
"signature": "<bound method Function.signature of Function('add_message', 59, 80)>",
"docstring": "Add a message to the thread and update derived fields.\n\nArgs:\n message (MailIntakeMessage):\n Parsed mail message to add to the thread.\n\nNotes:\n **Responsibilities:**\n\n - Appends the message to the thread.\n - Tracks unique participants.\n - Updates the last activity timestamp."
}
}
},
"Optional": {
"name": "Optional",
"kind": "alias",
"path": "mail_intake.models.thread.Optional",
"signature": "<bound method Alias.signature of Alias('Optional', 'typing.Optional')>",
"docstring": null
}
}
}

View File

@@ -11,13 +11,6 @@
"signature": "<bound method Alias.signature of Alias('base64', 'base64')>",
"docstring": null
},
"Dict": {
"name": "Dict",
"kind": "alias",
"path": "mail_intake.parsers.body.Dict",
"signature": "<bound method Alias.signature of Alias('Dict', 'typing.Dict')>",
"docstring": null
},
"Any": {
"name": "Any",
"kind": "alias",
@@ -25,13 +18,6 @@
"signature": "<bound method Alias.signature of Alias('Any', 'typing.Any')>",
"docstring": null
},
"Optional": {
"name": "Optional",
"kind": "alias",
"path": "mail_intake.parsers.body.Optional",
"signature": "<bound method Alias.signature of Alias('Optional', 'typing.Optional')>",
"docstring": null
},
"BeautifulSoup": {
"name": "BeautifulSoup",
"kind": "alias",
@@ -51,7 +37,7 @@
"kind": "function",
"path": "mail_intake.parsers.body.extract_body",
"signature": "<bound method Function.signature of Function('extract_body', 85, 133)>",
"docstring": "Extract the best-effort message body from a Gmail payload.\n\nPriority:\n\n1. `text/plain`\n2. `text/html` (stripped to text)\n3. Single-part body\n4. Empty string (if nothing usable found)\n\nArgs:\n payload (Dict[str, Any]):\n Provider-native message payload dictionary.\n\nReturns:\n str:\n Extracted plain-text message body."
"docstring": "Extract the best-effort message body from a Gmail payload.\n\nPriority:\n\n1. `text/plain`\n2. `text/html` (stripped to text)\n3. Single-part body\n4. Empty string (if nothing usable found)\n\nArgs:\n payload (dict[str, Any]):\n Provider-native message payload dictionary.\n\nReturns:\n str:\n Extracted plain-text message body."
}
}
}

View File

@@ -4,47 +4,19 @@
"path": "mail_intake.parsers.headers",
"docstring": "# Summary\n\nMessage header parsing utilities for Mail Intake.\n\nThis module provides helper functions for normalizing and extracting\nuseful information from provider-native message headers.\n\nThe functions here are intentionally simple and tolerant of malformed\nor incomplete header data.",
"objects": {
"Dict": {
"name": "Dict",
"kind": "alias",
"path": "mail_intake.parsers.headers.Dict",
"signature": "<bound method Alias.signature of Alias('Dict', 'typing.Dict')>",
"docstring": null
},
"List": {
"name": "List",
"kind": "alias",
"path": "mail_intake.parsers.headers.List",
"signature": "<bound method Alias.signature of Alias('List', 'typing.List')>",
"docstring": null
},
"Tuple": {
"name": "Tuple",
"kind": "alias",
"path": "mail_intake.parsers.headers.Tuple",
"signature": "<bound method Alias.signature of Alias('Tuple', 'typing.Tuple')>",
"docstring": null
},
"Optional": {
"name": "Optional",
"kind": "alias",
"path": "mail_intake.parsers.headers.Optional",
"signature": "<bound method Alias.signature of Alias('Optional', 'typing.Optional')>",
"docstring": null
},
"parse_headers": {
"name": "parse_headers",
"kind": "function",
"path": "mail_intake.parsers.headers.parse_headers",
"signature": "<bound method Function.signature of Function('parse_headers', 16, 64)>",
"docstring": "Convert a list of Gmail-style headers into a normalized dict.\n\nArgs:\n raw_headers (List[Dict[str, str]]):\n List of header dictionaries, each containing `name` and `value` keys.\n\nReturns:\n Dict[str, str]:\n Dictionary mapping lowercase header names to stripped values.\n\nNotes:\n **Guarantees:**\n\n - Provider payloads (such as Gmail) typically represent headers as a\n list of name/value mappings.\n - This function normalizes them into a case-insensitive dictionary\n keyed by lowercase header names.\n\nExample:\n Typical usage:\n\n ```python\n Input:\n [\n {\"name\": \"From\", \"value\": \"John Doe <john@example.com>\"},\n {\"name\": \"Subject\", \"value\": \"Re: Interview Update\"},\n ]\n\n Output:\n {\n \"from\": \"John Doe <john@example.com>\",\n \"subject\": \"Re: Interview Update\",\n }\n ```"
"signature": "<bound method Function.signature of Function('parse_headers', 14, 62)>",
"docstring": "Convert a list of Gmail-style headers into a normalized dict.\n\nArgs:\n raw_headers (list[dict[str, str]]):\n List of header dictionaries, each containing `name` and `value` keys.\n\nReturns:\n dict[str, str]:\n Dictionary mapping lowercase header names to stripped values.\n\nNotes:\n **Guarantees:**\n\n - Provider payloads (such as Gmail) typically represent headers as a\n list of name/value mappings.\n - This function normalizes them into a case-insensitive dictionary\n keyed by lowercase header names.\n\nExample:\n Typical usage:\n\n ```python\n Input:\n [\n {\"name\": \"From\", \"value\": \"John Doe <john@example.com>\"},\n {\"name\": \"Subject\", \"value\": \"Re: Interview Update\"},\n ]\n\n Output:\n {\n \"from\": \"John Doe <john@example.com>\",\n \"subject\": \"Re: Interview Update\",\n }\n ```"
},
"extract_sender": {
"name": "extract_sender",
"kind": "function",
"path": "mail_intake.parsers.headers.extract_sender",
"signature": "<bound method Function.signature of Function('extract_sender', 67, 102)>",
"docstring": "Extract sender email and optional display name from headers.\n\nArgs:\n headers (Dict[str, str]):\n Normalized header dictionary as returned by `parse_headers()`.\n\nReturns:\n Tuple[str, Optional[str]]:\n A tuple `(email, name)` where `email` is the sender email address\n and `name` is the display name, or `None` if unavailable.\n\nNotes:\n **Responsibilities:**\n\n - This function parses the `From` header and attempts to extract\n sender email address and optional human-readable display name.\n\nExample:\n Typical values:\n\n - `\"John Doe <john@example.com>\"` -> `(\"john@example.com\", \"John Doe\")`\n - `\"john@example.com\"` -> `(\"john@example.com\", None)`"
"signature": "<bound method Function.signature of Function('extract_sender', 65, 100)>",
"docstring": "Extract sender email and optional display name from headers.\n\nArgs:\n headers (dict[str, str]):\n Normalized header dictionary as returned by `parse_headers()`.\n\nReturns:\n tuple[str, str | None]:\n A tuple `(email, name)` where `email` is the sender email address\n and `name` is the display name, or `None` if unavailable.\n\nNotes:\n **Responsibilities:**\n\n - This function parses the `From` header and attempts to extract\n sender email address and optional human-readable display name.\n\nExample:\n Typical values:\n\n - `\"John Doe <john@example.com>\"` -> `(\"john@example.com\", \"John Doe\")`\n - `\"john@example.com\"` -> `(\"john@example.com\", None)`"
}
}
}

View File

@@ -9,21 +9,21 @@
"kind": "function",
"path": "mail_intake.parsers.extract_body",
"signature": "<bound method Alias.signature of Alias('extract_body', 'mail_intake.parsers.body.extract_body')>",
"docstring": "Extract the best-effort message body from a Gmail payload.\n\nPriority:\n\n1. `text/plain`\n2. `text/html` (stripped to text)\n3. Single-part body\n4. Empty string (if nothing usable found)\n\nArgs:\n payload (Dict[str, Any]):\n Provider-native message payload dictionary.\n\nReturns:\n str:\n Extracted plain-text message body."
"docstring": "Extract the best-effort message body from a Gmail payload.\n\nPriority:\n\n1. `text/plain`\n2. `text/html` (stripped to text)\n3. Single-part body\n4. Empty string (if nothing usable found)\n\nArgs:\n payload (dict[str, Any]):\n Provider-native message payload dictionary.\n\nReturns:\n str:\n Extracted plain-text message body."
},
"parse_headers": {
"name": "parse_headers",
"kind": "function",
"path": "mail_intake.parsers.parse_headers",
"signature": "<bound method Alias.signature of Alias('parse_headers', 'mail_intake.parsers.headers.parse_headers')>",
"docstring": "Convert a list of Gmail-style headers into a normalized dict.\n\nArgs:\n raw_headers (List[Dict[str, str]]):\n List of header dictionaries, each containing `name` and `value` keys.\n\nReturns:\n Dict[str, str]:\n Dictionary mapping lowercase header names to stripped values.\n\nNotes:\n **Guarantees:**\n\n - Provider payloads (such as Gmail) typically represent headers as a\n list of name/value mappings.\n - This function normalizes them into a case-insensitive dictionary\n keyed by lowercase header names.\n\nExample:\n Typical usage:\n\n ```python\n Input:\n [\n {\"name\": \"From\", \"value\": \"John Doe <john@example.com>\"},\n {\"name\": \"Subject\", \"value\": \"Re: Interview Update\"},\n ]\n\n Output:\n {\n \"from\": \"John Doe <john@example.com>\",\n \"subject\": \"Re: Interview Update\",\n }\n ```"
"docstring": "Convert a list of Gmail-style headers into a normalized dict.\n\nArgs:\n raw_headers (list[dict[str, str]]):\n List of header dictionaries, each containing `name` and `value` keys.\n\nReturns:\n dict[str, str]:\n Dictionary mapping lowercase header names to stripped values.\n\nNotes:\n **Guarantees:**\n\n - Provider payloads (such as Gmail) typically represent headers as a\n list of name/value mappings.\n - This function normalizes them into a case-insensitive dictionary\n keyed by lowercase header names.\n\nExample:\n Typical usage:\n\n ```python\n Input:\n [\n {\"name\": \"From\", \"value\": \"John Doe <john@example.com>\"},\n {\"name\": \"Subject\", \"value\": \"Re: Interview Update\"},\n ]\n\n Output:\n {\n \"from\": \"John Doe <john@example.com>\",\n \"subject\": \"Re: Interview Update\",\n }\n ```"
},
"extract_sender": {
"name": "extract_sender",
"kind": "function",
"path": "mail_intake.parsers.extract_sender",
"signature": "<bound method Alias.signature of Alias('extract_sender', 'mail_intake.parsers.headers.extract_sender')>",
"docstring": "Extract sender email and optional display name from headers.\n\nArgs:\n headers (Dict[str, str]):\n Normalized header dictionary as returned by `parse_headers()`.\n\nReturns:\n Tuple[str, Optional[str]]:\n A tuple `(email, name)` where `email` is the sender email address\n and `name` is the display name, or `None` if unavailable.\n\nNotes:\n **Responsibilities:**\n\n - This function parses the `From` header and attempts to extract\n sender email address and optional human-readable display name.\n\nExample:\n Typical values:\n\n - `\"John Doe <john@example.com>\"` -> `(\"john@example.com\", \"John Doe\")`\n - `\"john@example.com\"` -> `(\"john@example.com\", None)`"
"docstring": "Extract sender email and optional display name from headers.\n\nArgs:\n headers (dict[str, str]):\n Normalized header dictionary as returned by `parse_headers()`.\n\nReturns:\n tuple[str, str | None]:\n A tuple `(email, name)` where `email` is the sender email address\n and `name` is the display name, or `None` if unavailable.\n\nNotes:\n **Responsibilities:**\n\n - This function parses the `From` header and attempts to extract\n sender email address and optional human-readable display name.\n\nExample:\n Typical values:\n\n - `\"John Doe <john@example.com>\"` -> `(\"john@example.com\", \"John Doe\")`\n - `\"john@example.com\"` -> `(\"john@example.com\", None)`"
},
"normalize_subject": {
"name": "normalize_subject",
@@ -46,13 +46,6 @@
"signature": "<bound method Alias.signature of Alias('base64', 'base64')>",
"docstring": null
},
"Dict": {
"name": "Dict",
"kind": "alias",
"path": "mail_intake.parsers.body.Dict",
"signature": "<bound method Alias.signature of Alias('Dict', 'typing.Dict')>",
"docstring": null
},
"Any": {
"name": "Any",
"kind": "alias",
@@ -60,13 +53,6 @@
"signature": "<bound method Alias.signature of Alias('Any', 'typing.Any')>",
"docstring": null
},
"Optional": {
"name": "Optional",
"kind": "alias",
"path": "mail_intake.parsers.body.Optional",
"signature": "<bound method Alias.signature of Alias('Optional', 'typing.Optional')>",
"docstring": null
},
"BeautifulSoup": {
"name": "BeautifulSoup",
"kind": "alias",
@@ -86,7 +72,7 @@
"kind": "function",
"path": "mail_intake.parsers.body.extract_body",
"signature": "<bound method Function.signature of Function('extract_body', 85, 133)>",
"docstring": "Extract the best-effort message body from a Gmail payload.\n\nPriority:\n\n1. `text/plain`\n2. `text/html` (stripped to text)\n3. Single-part body\n4. Empty string (if nothing usable found)\n\nArgs:\n payload (Dict[str, Any]):\n Provider-native message payload dictionary.\n\nReturns:\n str:\n Extracted plain-text message body."
"docstring": "Extract the best-effort message body from a Gmail payload.\n\nPriority:\n\n1. `text/plain`\n2. `text/html` (stripped to text)\n3. Single-part body\n4. Empty string (if nothing usable found)\n\nArgs:\n payload (dict[str, Any]):\n Provider-native message payload dictionary.\n\nReturns:\n str:\n Extracted plain-text message body."
}
}
},
@@ -97,47 +83,19 @@
"signature": null,
"docstring": "# Summary\n\nMessage header parsing utilities for Mail Intake.\n\nThis module provides helper functions for normalizing and extracting\nuseful information from provider-native message headers.\n\nThe functions here are intentionally simple and tolerant of malformed\nor incomplete header data.",
"members": {
"Dict": {
"name": "Dict",
"kind": "alias",
"path": "mail_intake.parsers.headers.Dict",
"signature": "<bound method Alias.signature of Alias('Dict', 'typing.Dict')>",
"docstring": null
},
"List": {
"name": "List",
"kind": "alias",
"path": "mail_intake.parsers.headers.List",
"signature": "<bound method Alias.signature of Alias('List', 'typing.List')>",
"docstring": null
},
"Tuple": {
"name": "Tuple",
"kind": "alias",
"path": "mail_intake.parsers.headers.Tuple",
"signature": "<bound method Alias.signature of Alias('Tuple', 'typing.Tuple')>",
"docstring": null
},
"Optional": {
"name": "Optional",
"kind": "alias",
"path": "mail_intake.parsers.headers.Optional",
"signature": "<bound method Alias.signature of Alias('Optional', 'typing.Optional')>",
"docstring": null
},
"parse_headers": {
"name": "parse_headers",
"kind": "function",
"path": "mail_intake.parsers.headers.parse_headers",
"signature": "<bound method Function.signature of Function('parse_headers', 16, 64)>",
"docstring": "Convert a list of Gmail-style headers into a normalized dict.\n\nArgs:\n raw_headers (List[Dict[str, str]]):\n List of header dictionaries, each containing `name` and `value` keys.\n\nReturns:\n Dict[str, str]:\n Dictionary mapping lowercase header names to stripped values.\n\nNotes:\n **Guarantees:**\n\n - Provider payloads (such as Gmail) typically represent headers as a\n list of name/value mappings.\n - This function normalizes them into a case-insensitive dictionary\n keyed by lowercase header names.\n\nExample:\n Typical usage:\n\n ```python\n Input:\n [\n {\"name\": \"From\", \"value\": \"John Doe <john@example.com>\"},\n {\"name\": \"Subject\", \"value\": \"Re: Interview Update\"},\n ]\n\n Output:\n {\n \"from\": \"John Doe <john@example.com>\",\n \"subject\": \"Re: Interview Update\",\n }\n ```"
"signature": "<bound method Function.signature of Function('parse_headers', 14, 62)>",
"docstring": "Convert a list of Gmail-style headers into a normalized dict.\n\nArgs:\n raw_headers (list[dict[str, str]]):\n List of header dictionaries, each containing `name` and `value` keys.\n\nReturns:\n dict[str, str]:\n Dictionary mapping lowercase header names to stripped values.\n\nNotes:\n **Guarantees:**\n\n - Provider payloads (such as Gmail) typically represent headers as a\n list of name/value mappings.\n - This function normalizes them into a case-insensitive dictionary\n keyed by lowercase header names.\n\nExample:\n Typical usage:\n\n ```python\n Input:\n [\n {\"name\": \"From\", \"value\": \"John Doe <john@example.com>\"},\n {\"name\": \"Subject\", \"value\": \"Re: Interview Update\"},\n ]\n\n Output:\n {\n \"from\": \"John Doe <john@example.com>\",\n \"subject\": \"Re: Interview Update\",\n }\n ```"
},
"extract_sender": {
"name": "extract_sender",
"kind": "function",
"path": "mail_intake.parsers.headers.extract_sender",
"signature": "<bound method Function.signature of Function('extract_sender', 67, 102)>",
"docstring": "Extract sender email and optional display name from headers.\n\nArgs:\n headers (Dict[str, str]):\n Normalized header dictionary as returned by `parse_headers()`.\n\nReturns:\n Tuple[str, Optional[str]]:\n A tuple `(email, name)` where `email` is the sender email address\n and `name` is the display name, or `None` if unavailable.\n\nNotes:\n **Responsibilities:**\n\n - This function parses the `From` header and attempts to extract\n sender email address and optional human-readable display name.\n\nExample:\n Typical values:\n\n - `\"John Doe <john@example.com>\"` -> `(\"john@example.com\", \"John Doe\")`\n - `\"john@example.com\"` -> `(\"john@example.com\", None)`"
"signature": "<bound method Function.signature of Function('extract_sender', 65, 100)>",
"docstring": "Extract sender email and optional display name from headers.\n\nArgs:\n headers (dict[str, str]):\n Normalized header dictionary as returned by `parse_headers()`.\n\nReturns:\n tuple[str, str | None]:\n A tuple `(email, name)` where `email` is the sender email address\n and `name` is the display name, or `None` if unavailable.\n\nNotes:\n **Responsibilities:**\n\n - This function parses the `From` header and attempts to extract\n sender email address and optional human-readable display name.\n\nExample:\n Typical values:\n\n - `\"John Doe <john@example.com>\"` -> `(\"john@example.com\", \"John Doe\")`\n - `\"john@example.com\"` -> `(\"john@example.com\", None)`"
}
}
},
@@ -159,7 +117,7 @@
"name": "normalize_subject",
"kind": "function",
"path": "mail_intake.parsers.subject.normalize_subject",
"signature": "<bound method Function.signature of Function('normalize_subject', 22, 62)>",
"signature": "<bound method Function.signature of Function('normalize_subject', 21, 61)>",
"docstring": "Normalize an email subject for thread-level comparison.\n\nArgs:\n subject (str):\n Raw subject line from a message header.\n\nReturns:\n str:\n Normalized subject string suitable for thread grouping.\n\nNotes:\n **Responsibilities:**\n\n - Strips common prefixes such as `Re:`, `Fwd:`, and `FW:`.\n - Repeats prefix stripping to handle stacked prefixes.\n - Collapses excessive whitespace.\n - Preserves original casing (no lowercasing).\n\n **Guarantees:**\n\n - This function is intentionally conservative and avoids aggressive\n transformations that could alter the semantic meaning of the subject."
}
}

View File

@@ -15,7 +15,7 @@
"name": "normalize_subject",
"kind": "function",
"path": "mail_intake.parsers.subject.normalize_subject",
"signature": "<bound method Function.signature of Function('normalize_subject', 22, 62)>",
"signature": "<bound method Function.signature of Function('normalize_subject', 21, 61)>",
"docstring": "Normalize an email subject for thread-level comparison.\n\nArgs:\n subject (str):\n Raw subject line from a message header.\n\nReturns:\n str:\n Normalized subject string suitable for thread grouping.\n\nNotes:\n **Responsibilities:**\n\n - Strips common prefixes such as `Re:`, `Fwd:`, and `FW:`.\n - Repeats prefix stripping to handle stacked prefixes.\n - Collapses excessive whitespace.\n - Preserves original casing (no lowercasing).\n\n **Guarantees:**\n\n - This function is intentionally conservative and avoids aggressive\n transformations that could alter the semantic meaning of the subject."
}
}

90
docs/mcp/nav.json Normal file
View File

@@ -0,0 +1,90 @@
[
{
"module": "mail_intake",
"resource": "docs://modules/mail_intake"
},
{
"module": "mail_intake.adapters",
"resource": "docs://modules/mail_intake.adapters"
},
{
"module": "mail_intake.adapters.base",
"resource": "docs://modules/mail_intake.adapters.base"
},
{
"module": "mail_intake.adapters.gmail",
"resource": "docs://modules/mail_intake.adapters.gmail"
},
{
"module": "mail_intake.auth",
"resource": "docs://modules/mail_intake.auth"
},
{
"module": "mail_intake.auth.base",
"resource": "docs://modules/mail_intake.auth.base"
},
{
"module": "mail_intake.auth.google",
"resource": "docs://modules/mail_intake.auth.google"
},
{
"module": "mail_intake.config",
"resource": "docs://modules/mail_intake.config"
},
{
"module": "mail_intake.credentials",
"resource": "docs://modules/mail_intake.credentials"
},
{
"module": "mail_intake.credentials.pickle",
"resource": "docs://modules/mail_intake.credentials.pickle"
},
{
"module": "mail_intake.credentials.redis",
"resource": "docs://modules/mail_intake.credentials.redis"
},
{
"module": "mail_intake.credentials.store",
"resource": "docs://modules/mail_intake.credentials.store"
},
{
"module": "mail_intake.exceptions",
"resource": "docs://modules/mail_intake.exceptions"
},
{
"module": "mail_intake.ingestion",
"resource": "docs://modules/mail_intake.ingestion"
},
{
"module": "mail_intake.ingestion.reader",
"resource": "docs://modules/mail_intake.ingestion.reader"
},
{
"module": "mail_intake.models",
"resource": "docs://modules/mail_intake.models"
},
{
"module": "mail_intake.models.message",
"resource": "docs://modules/mail_intake.models.message"
},
{
"module": "mail_intake.models.thread",
"resource": "docs://modules/mail_intake.models.thread"
},
{
"module": "mail_intake.parsers",
"resource": "docs://modules/mail_intake.parsers"
},
{
"module": "mail_intake.parsers.body",
"resource": "docs://modules/mail_intake.parsers.body"
},
{
"module": "mail_intake.parsers.headers",
"resource": "docs://modules/mail_intake.parsers.headers"
},
{
"module": "mail_intake.parsers.subject",
"resource": "docs://modules/mail_intake.parsers.subject"
}
]

View File

@@ -21,33 +21,15 @@ theme:
- search.highlight
- search.share
- search.suggest
plugins:
- search
- mkdocstrings:
handlers:
python:
paths:
- .
options:
docstring_style: google
show_source: false
show_signature_annotations: true
separate_signature: true
merge_init_into_class: true
inherited_members: true
annotations_path: brief
show_root_heading: true
group_by_category: true
show_category_heading: true
show_object_full_path: false
show_symbol_type_heading: true
icon:
logo: material/inbox
repo: fontawesome/brands/github
markdown_extensions:
- pymdownx.superfences
- pymdownx.inlinehilite
- pymdownx.snippets
- admonition
- pymdownx.details
- pymdownx.superfences
- pymdownx.highlight:
linenums: true
anchor_linenums: true
@@ -62,7 +44,31 @@ markdown_extensions:
- pymdownx.caret
- pymdownx.tilde
- pymdownx.mark
extra_css:
- https://unpkg.com/dracula-prism/dist/css/dracula-prism.css
plugins:
- search
- mkdocstrings:
handlers:
python:
paths:
- ..
options:
docstring_style: google
show_source: false
show_signature_annotations: true
separate_signature: true
merge_init_into_class: true
inherited_members: true
annotations_path: brief
show_root_heading: true
group_by_category: true
show_category_heading: true
show_object_full_path: false
show_symbol_type_heading: true
site_name: mail_intake
docs_dir: lib
site_dir: ../site/lib
nav:
- Home: index.md
- Core API:

View File

@@ -137,7 +137,6 @@ No individual symbols are re-exported at the package root.
---
"""
from . import ingestion
from . import adapters
from . import auth

View File

@@ -1,10 +1,4 @@
from . import ingestion
from . import adapters
from . import auth
from . import credentials
from . import models
from . import config
from . import exceptions
from . import adapters, auth, config, credentials, exceptions, ingestion, models
__all__ = [
"ingestion",

View File

@@ -12,7 +12,8 @@ types or semantics should leak beyond implementations of this interface.
"""
from abc import ABC, abstractmethod
from typing import Iterator, Dict, Any
from collections.abc import Iterator
from typing import Any
class MailIntakeAdapter(ABC):
@@ -32,7 +33,7 @@ class MailIntakeAdapter(ABC):
"""
@abstractmethod
def iter_message_refs(self, query: str) -> Iterator[Dict[str, str]]:
def iter_message_refs(self, query: str) -> Iterator[dict[str, str]]:
"""
Iterate over lightweight message references matching a query.
@@ -40,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:
@@ -63,7 +68,7 @@ class MailIntakeAdapter(ABC):
raise NotImplementedError
@abstractmethod
def fetch_message(self, message_id: str) -> Dict[str, Any]:
def fetch_message(self, message_id: str) -> dict[str, Any]:
"""
Fetch a full raw message by message identifier.
@@ -72,13 +77,13 @@ 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
@abstractmethod
def fetch_thread(self, thread_id: str) -> Dict[str, Any]:
def fetch_thread(self, thread_id: str) -> dict[str, Any]:
"""
Fetch a full raw thread by thread identifier.
@@ -87,7 +92,7 @@ class MailIntakeAdapter(ABC):
Provider-specific thread identifier.
Returns:
Dict[str, Any]:
dict[str, Any]:
Provider-native thread payload.
"""
raise NotImplementedError

View File

@@ -1,10 +1,11 @@
from abc import ABC, abstractmethod
from typing import Iterator, Dict, Any
from collections.abc import Iterator
from typing import Any
class MailIntakeAdapter(ABC):
@abstractmethod
def iter_message_refs(self, query: str) -> Iterator[Dict[str, str]]: ...
def iter_message_refs(self, query: str) -> Iterator[dict[str, str]]: ...
@abstractmethod
def fetch_message(self, message_id: str) -> Dict[str, Any]: ...
def fetch_message(self, message_id: str) -> dict[str, Any]: ...
@abstractmethod
def fetch_thread(self, thread_id: str) -> Dict[str, Any]: ...
def fetch_thread(self, thread_id: str) -> dict[str, Any]: ...

View File

@@ -15,14 +15,15 @@ It is the only place in the codebase where:
All Gmail-specific behavior must be strictly contained within this module.
"""
from typing import Iterator, Dict, Any
from collections.abc import Iterator
from typing import Any
from googleapiclient.discovery import build
from googleapiclient.errors import HttpError
from mail_intake.adapters.base import MailIntakeAdapter
from mail_intake.exceptions import MailIntakeAdapterError
from mail_intake.auth.base import MailIntakeAuthProvider
from mail_intake.exceptions import MailIntakeAdapterError
class MailIntakeGmailAdapter(MailIntakeAdapter):
@@ -71,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.
@@ -89,7 +86,7 @@ class MailIntakeGmailAdapter(MailIntakeAdapter):
) from exc
return self._service
def iter_message_refs(self, query: str) -> Iterator[Dict[str, str]]:
def iter_message_refs(self, query: str) -> Iterator[dict[str, str]]:
"""
Iterate over message references matching the query.
@@ -98,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:
@@ -107,9 +104,7 @@ class MailIntakeGmailAdapter(MailIntakeAdapter):
"""
try:
request = (
self.service.users()
.messages()
.list(userId=self._user_id, q=query)
self.service.users().messages().list(userId=self._user_id, q=query)
)
while request is not None:
@@ -121,18 +116,14 @@ class MailIntakeGmailAdapter(MailIntakeAdapter):
"thread_id": msg["threadId"],
}
request = (
self.service.users()
.messages()
.list_next(request, response)
)
request = self.service.users().messages().list_next(request, response)
except HttpError as exc:
raise MailIntakeAdapterError(
"Gmail API error while listing messages"
) from exc
def fetch_message(self, message_id: str) -> Dict[str, Any]:
def fetch_message(self, message_id: str) -> dict[str, Any]:
"""
Fetch a full Gmail message by message ID.
@@ -141,7 +132,7 @@ class MailIntakeGmailAdapter(MailIntakeAdapter):
Gmail message identifier.
Returns:
Dict[str, Any]:
dict[str, Any]:
Provider-native Gmail message payload.
Raises:
@@ -160,7 +151,7 @@ class MailIntakeGmailAdapter(MailIntakeAdapter):
f"Gmail API error while fetching message {message_id}"
) from exc
def fetch_thread(self, thread_id: str) -> Dict[str, Any]:
def fetch_thread(self, thread_id: str) -> dict[str, Any]:
"""
Fetch a full Gmail thread by thread ID.
@@ -169,7 +160,7 @@ class MailIntakeGmailAdapter(MailIntakeAdapter):
Gmail thread identifier.
Returns:
Dict[str, Any]:
dict[str, Any]:
Provider-native Gmail thread payload.
Raises:

View File

@@ -1,11 +1,15 @@
from typing import Iterator, Dict, Any
from collections.abc import Iterator
from typing import Any
from mail_intake.adapters.base import MailIntakeAdapter
from mail_intake.auth.base import MailIntakeAuthProvider
class MailIntakeGmailAdapter(MailIntakeAdapter):
def __init__(self, auth_provider: MailIntakeAuthProvider, user_id: str = ...) -> None: ...
def __init__(
self, auth_provider: MailIntakeAuthProvider[Any], user_id: str = ...
) -> None: ...
@property
def service(self) -> Any: ...
def iter_message_refs(self, query: str) -> Iterator[Dict[str, str]]: ...
def fetch_message(self, message_id: str) -> Dict[str, Any]: ...
def fetch_thread(self, thread_id: str) -> Dict[str, Any]: ...
def iter_message_refs(self, query: str) -> Iterator[dict[str, str]]: ...
def fetch_message(self, message_id: str) -> dict[str, Any]: ...
def fetch_thread(self, thread_id: str) -> dict[str, Any]: ...

View File

@@ -17,12 +17,12 @@ No Google authentication details should leak outside this module.
"""
import os
from typing import Sequence
from collections.abc import Sequence
import google.auth.exceptions
from google.auth.transport.requests import Request
from google_auth_oauthlib.flow import InstalledAppFlow
from google.oauth2.credentials import Credentials
from google_auth_oauthlib.flow import InstalledAppFlow
from mail_intake.auth.base import MailIntakeAuthProvider
from mail_intake.credentials.store import CredentialStore

View File

@@ -1,7 +1,11 @@
from typing import Sequence, Any
from collections.abc import Sequence
from typing import Any
from mail_intake.auth.base import MailIntakeAuthProvider
from mail_intake.credentials.store import CredentialStore
class MailIntakeGoogleAuth(MailIntakeAuthProvider[Any]):
def __init__(self, credentials_path: str, store: CredentialStore[Any], scopes: Sequence[str]) -> None: ...
def __init__(
self, credentials_path: str, store: CredentialStore[Any], scopes: Sequence[str]
) -> None: ...
def get_credentials(self) -> Any: ...

View File

@@ -12,7 +12,6 @@ environment reads to ensure predictability and testability.
"""
from dataclasses import dataclass
from typing import Optional
@dataclass(frozen=True)
@@ -46,12 +45,12 @@ class MailIntakeConfig:
Whether ingestion should operate in read-only mode.
"""
credentials_path: Optional[str] = None
credentials_path: str | None = None
"""
Optional path to provider credentials configuration.
"""
token_path: Optional[str] = None
token_path: str | None = None
"""
Optional path to persisted authentication tokens.
"""

View File

@@ -1,9 +1,14 @@
from typing import Optional
class MailIntakeConfig:
provider: str
user_id: str
readonly: bool
credentials_path: Optional[str]
token_path: Optional[str]
def __init__(self, provider: str = ..., user_id: str = ..., readonly: bool = ..., credentials_path: Optional[str] = ..., token_path: Optional[str] = ...) -> None: ...
credentials_path: str | None
token_path: str | None
def __init__(
self,
provider: str = ...,
user_id: str = ...,
readonly: bool = ...,
credentials_path: str | None = ...,
token_path: str | None = ...,
) -> None: ...

View File

@@ -1,5 +1,5 @@
from .store import CredentialStore
from .pickle import PickleCredentialStore
from .redis import RedisCredentialStore
from .store import CredentialStore
__all__ = ["CredentialStore", "PickleCredentialStore", "RedisCredentialStore"]

View File

@@ -16,7 +16,7 @@ untrusted environments.
"""
import pickle
from typing import Optional, TypeVar
from typing import TypeVar
from mail_intake.credentials.store import CredentialStore
@@ -55,12 +55,12 @@ class PickleCredentialStore(CredentialStore[T]):
"""
self.path = path
def load(self) -> Optional[T]:
def load(self) -> T | None:
"""
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`.

View File

@@ -1,4 +1,5 @@
from typing import Optional, TypeVar
from typing import TypeVar
from .store import CredentialStore
T = TypeVar("T")
@@ -6,6 +7,6 @@ T = TypeVar("T")
class PickleCredentialStore(CredentialStore[T]):
path: str
def __init__(self, path: str) -> None: ...
def load(self) -> Optional[T]: ...
def load(self) -> T | None: ...
def save(self, credentials: T) -> None: ...
def clear(self) -> None: ...

View File

@@ -24,8 +24,8 @@ Credential validation, refresh, rotation, and acquisition remain the
responsibility of authentication provider implementations.
"""
from typing import Optional, TypeVar, Callable
from collections.abc import Callable
from typing import Any, TypeVar
from mail_intake.credentials.store import CredentialStore
@@ -57,30 +57,27 @@ class RedisCredentialStore(CredentialStore[T]):
def __init__(
self,
redis_client,
redis_client: Any,
key: str,
serialize: Callable[[T], bytes],
deserialize: Callable[[bytes], T],
ttl_seconds: Optional[int] = None,
ttl_seconds: int | None = None,
):
"""
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.
Initialized Redis client instance used for persistence.
key (str):
The Redis key under which credentials are stored. Callers are responsible for applying appropriate namespacing to avoid collisions.
Storage key under which credentials are persisted.
serialize (Callable[[T], bytes]):
A callable that converts a credential object of type ``T`` into a ``bytes`` representation suitable for storage in Redis.
Callable that encodes credentials to bytes for storage.
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.
Callable that decodes stored bytes back into credentials.
ttl_seconds (int | None):
Optional time-to-live in seconds after which stored
credentials expire automatically. ``None`` disables expiry.
"""
self.redis = redis_client
self.key = key
@@ -88,12 +85,12 @@ class RedisCredentialStore(CredentialStore[T]):
self.deserialize = deserialize
self.ttl_seconds = ttl_seconds
def load(self) -> Optional[T]:
def load(self) -> T | None:
"""
Load credentials from Redis.
Returns:
Optional[T]:
T | None:
An instance of type `T` if credentials are present and
successfully deserialized; otherwise `None`.

View File

@@ -1,4 +1,6 @@
from typing import Optional, TypeVar, Callable, Any
from collections.abc import Callable
from typing import Any, TypeVar
from .store import CredentialStore
T = TypeVar("T")
@@ -8,8 +10,15 @@ class RedisCredentialStore(CredentialStore[T]):
key: str
serialize: Callable[[T], bytes]
deserialize: Callable[[bytes], T]
ttl_seconds: Optional[int]
def __init__(self, redis_client: Any, key: str, serialize: Callable[[T], bytes], deserialize: Callable[[bytes], T], ttl_seconds: Optional[int] = ...) -> None: ...
def load(self) -> Optional[T]: ...
ttl_seconds: int | None
def __init__(
self,
redis_client: Any,
key: str,
serialize: Callable[[T], bytes],
deserialize: Callable[[bytes], T],
ttl_seconds: int | None = ...,
) -> None: ...
def load(self) -> T | None: ...
def save(self, credentials: T) -> None: ...
def clear(self) -> None: ...

View File

@@ -19,9 +19,8 @@ or secrets managers—without coupling authentication logic to any
specific storage mechanism.
"""
from abc import ABC, abstractmethod
from typing import Generic, Optional, TypeVar
from typing import Generic, TypeVar
T = TypeVar("T")
@@ -48,12 +47,12 @@ class CredentialStore(ABC, Generic[T]):
"""
@abstractmethod
def load(self) -> Optional[T]:
def load(self) -> T | None:
"""
Load previously persisted credentials.
Returns:
Optional[T]:
T | None:
An instance of type `T` if credentials are available and
loadable; otherwise `None`.

View File

@@ -1,11 +1,11 @@
from abc import ABC, abstractmethod
from typing import Generic, Optional, TypeVar
from typing import Generic, TypeVar
T = TypeVar("T")
class CredentialStore(ABC, Generic[T]):
@abstractmethod
def load(self) -> Optional[T]: ...
def load(self) -> T | None: ...
@abstractmethod
def save(self, credentials: T) -> None: ...
@abstractmethod

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.

View File

@@ -16,16 +16,17 @@ It coordinates:
No provider-specific logic or API semantics are permitted in this layer.
"""
from collections.abc import Iterator
from datetime import datetime
from typing import Iterator, Dict, Any
from typing import Any
from mail_intake.adapters.base import MailIntakeAdapter
from mail_intake.exceptions import MailIntakeParsingError
from mail_intake.models.message import MailIntakeMessage
from mail_intake.models.thread import MailIntakeThread
from mail_intake.parsers.headers import parse_headers, extract_sender
from mail_intake.parsers.body import extract_body
from mail_intake.parsers.headers import extract_sender, parse_headers
from mail_intake.parsers.subject import normalize_subject
from mail_intake.exceptions import MailIntakeParsingError
class MailIntakeReader:
@@ -87,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`:
@@ -101,7 +102,7 @@ class MailIntakeReader:
- Messages are grouped by `thread_id` and yielded as complete
thread objects containing all associated messages.
"""
threads: Dict[str, MailIntakeThread] = {}
threads: dict[str, MailIntakeThread] = {}
for ref in self._adapter.iter_message_refs(query):
raw = self._adapter.fetch_message(ref["message_id"])
@@ -119,12 +120,12 @@ class MailIntakeReader:
return iter(threads.values())
def _parse_message(self, raw_message: Dict[str, Any]) -> MailIntakeMessage:
def _parse_message(self, raw_message: dict[str, Any]) -> MailIntakeMessage:
"""
Parse a raw provider message into a `MailIntakeMessage`.
Args:
raw_message (Dict[str, Any]):
raw_message (dict[str, Any]):
Provider-native message payload.
Returns:

View File

@@ -1,4 +1,6 @@
from typing import Iterator, Dict, Any
from collections.abc import Iterator
from typing import Any
from mail_intake.adapters.base import MailIntakeAdapter
from mail_intake.models.message import MailIntakeMessage
from mail_intake.models.thread import MailIntakeThread
@@ -7,4 +9,4 @@ class MailIntakeReader:
def __init__(self, adapter: MailIntakeAdapter) -> None: ...
def iter_messages(self, query: str) -> Iterator[MailIntakeMessage]: ...
def iter_threads(self, query: str) -> Iterator[MailIntakeThread]: ...
def _parse_message(self, raw_message: Dict[str, Any]) -> MailIntakeMessage: ...
def _parse_message(self, raw_message: dict[str, Any]) -> MailIntakeMessage: ...

View File

@@ -13,7 +13,6 @@ provider-specific fields or semantics.
from dataclasses import dataclass
from datetime import datetime
from typing import Optional, Dict
@dataclass(frozen=True)
@@ -54,7 +53,7 @@ class MailIntakeMessage:
Sender email address.
"""
from_name: Optional[str]
from_name: str | None
"""
Optional human-readable sender name.
"""
@@ -74,7 +73,7 @@ class MailIntakeMessage:
Short provider-supplied preview snippet of the message.
"""
raw_headers: Dict[str, str]
raw_headers: dict[str, str]
"""
Normalized mapping of message headers (header name → value).
"""

View File

@@ -1,14 +1,24 @@
from datetime import datetime
from typing import Optional, Dict
class MailIntakeMessage:
message_id: str
thread_id: str
timestamp: datetime
from_email: str
from_name: Optional[str]
from_name: str | None
subject: str
body_text: str
snippet: str
raw_headers: Dict[str, str]
def __init__(self, message_id: str, thread_id: str, timestamp: datetime, from_email: str, from_name: Optional[str], subject: str, body_text: str, snippet: str, raw_headers: Dict[str, str]) -> None: ...
raw_headers: dict[str, str]
def __init__(
self,
message_id: str,
thread_id: str,
timestamp: datetime,
from_email: str,
from_name: str | None,
subject: str,
body_text: str,
snippet: str,
raw_headers: dict[str, str],
) -> None: ...

View File

@@ -12,7 +12,6 @@ for higher-level correspondence workflows.
from dataclasses import dataclass, field
from datetime import datetime
from typing import List, Set
from mail_intake.models.message import MailIntakeMessage
@@ -42,12 +41,12 @@ class MailIntakeThread:
Normalized subject line used to group related messages.
"""
participants: Set[str] = field(default_factory=set)
participants: set[str] = field(default_factory=set)
"""
Set of unique participant email addresses observed in the thread.
"""
messages: List[MailIntakeMessage] = field(default_factory=list)
messages: list[MailIntakeMessage] = field(default_factory=list)
"""
Ordered list of messages belonging to this thread.
"""

View File

@@ -1,12 +1,19 @@
from datetime import datetime
from typing import List, Set, Optional
from .message import MailIntakeMessage
class MailIntakeThread:
thread_id: str
normalized_subject: str
participants: Set[str]
messages: List[MailIntakeMessage]
last_activity_at: Optional[datetime]
def __init__(self, thread_id: str, normalized_subject: str, participants: Set[str] = ..., messages: List[MailIntakeMessage] = ..., last_activity_at: Optional[datetime] = ...) -> None: ...
participants: set[str]
messages: list[MailIntakeMessage]
last_activity_at: datetime | None
def __init__(
self,
thread_id: str,
normalized_subject: str,
participants: set[str] = ...,
messages: list[MailIntakeMessage] = ...,
last_activity_at: datetime | None = ...,
) -> None: ...
def add_message(self, message: MailIntakeMessage) -> None: ...

View File

@@ -1,5 +1,5 @@
from .body import extract_body
from .headers import parse_headers, extract_sender
from .headers import extract_sender, parse_headers
from .subject import normalize_subject
__all__ = ["extract_body", "parse_headers", "extract_sender", "normalize_subject"]

View File

@@ -11,7 +11,7 @@ prefers human-readable text over fidelity to original formatting.
"""
import base64
from typing import Dict, Any, Optional
from typing import Any
from bs4 import BeautifulSoup
@@ -45,7 +45,7 @@ def _decode_base64(data: str) -> str:
raise MailIntakeParsingError("Failed to decode message body") from exc
def _extract_from_part(part: Dict[str, Any]) -> Optional[str]:
def _extract_from_part(part: dict[str, Any]) -> str | None:
"""
Extract text content from a single MIME part.
@@ -55,11 +55,11 @@ def _extract_from_part(part: Dict[str, Any]) -> Optional[str]:
- `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")
@@ -82,7 +82,7 @@ def _extract_from_part(part: Dict[str, Any]) -> Optional[str]:
return None
def extract_body(payload: Dict[str, Any]) -> str:
def extract_body(payload: dict[str, Any]) -> str:
"""
Extract the best-effort message body from a Gmail payload.
@@ -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:

Some files were not shown because too many files have changed in this diff Show More