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" echo "🆕 New version detected: $PACKAGE_NAME==$VERSION"
fi 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 - name: build-package
image: python:3.13-slim image: python:3.13-slim
commands: commands:
@@ -126,4 +146,4 @@ steps:
trigger: trigger:
event: event:
- custom - custom

8
.gitignore vendored
View File

@@ -25,10 +25,17 @@ env/
htmlcov/ htmlcov/
coverage.xml coverage.xml
# Lint / type checking
.mypy_cache/
.ruff_cache/
# Environment variables # Environment variables
.env .env
.env.local .env.local
# Docs build artifacts
site
# OS # OS
.DS_Store .DS_Store
Thumbs.db Thumbs.db
@@ -38,7 +45,6 @@ Thumbs.db
*.swo *.swo
*~ *~
*.tmp *.tmp
site
# Credentials # Credentials
client_secret_*.json 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: groups:
Core API: Core API:
- ingestion/index.md - lib/ingestion/index.md
- ingestion/reader.md - lib/ingestion/reader.md
Domain Models: Domain Models:
- models/index.md - lib/models/index.md
- models/message.md - lib/models/message.md
- models/thread.md - lib/models/thread.md
Provider Adapters: Provider Adapters:
- adapters/index.md - lib/adapters/index.md
- adapters/base.md - lib/adapters/base.md
- adapters/gmail.md - lib/adapters/gmail.md
Authentication & Storage: Authentication & Storage:
- auth/index.md - lib/auth/index.md
- auth/base.md - lib/auth/base.md
- auth/google.md - lib/auth/google.md
- credentials/index.md - lib/credentials/index.md
- credentials/store.md - lib/credentials/store.md
- credentials/pickle.md - lib/credentials/pickle.md
- credentials/redis.md - lib/credentials/redis.md
Normalization & Parsing: Normalization & Parsing:
- parsers/index.md - lib/parsers/index.md
- parsers/body.md - lib/parsers/body.md
- parsers/headers.md - lib/parsers/headers.md
- parsers/subject.md - lib/parsers/subject.md
Configuration & Errors: Configuration & Errors:
- config.md - lib/config.md
- exceptions.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
- [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", "name": "Iterator",
"kind": "alias", "kind": "alias",
"path": "mail_intake.adapters.base.Iterator", "path": "mail_intake.adapters.base.Iterator",
"signature": "<bound method Alias.signature of Alias('Iterator', 'typing.Iterator')>", "signature": "<bound method Alias.signature of Alias('Iterator', 'collections.abc.Iterator')>",
"docstring": null
},
"Dict": {
"name": "Dict",
"kind": "alias",
"path": "mail_intake.adapters.base.Dict",
"signature": "<bound method Alias.signature of Alias('Dict', 'typing.Dict')>",
"docstring": null "docstring": null
}, },
"Any": { "Any": {
@@ -43,29 +36,29 @@
"name": "MailIntakeAdapter", "name": "MailIntakeAdapter",
"kind": "class", "kind": "class",
"path": "mail_intake.adapters.base.MailIntakeAdapter", "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.", "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": { "members": {
"iter_message_refs": { "iter_message_refs": {
"name": "iter_message_refs", "name": "iter_message_refs",
"kind": "function", "kind": "function",
"path": "mail_intake.adapters.base.MailIntakeAdapter.iter_message_refs", "path": "mail_intake.adapters.base.MailIntakeAdapter.iter_message_refs",
"signature": "<bound method Function.signature of Function('iter_message_refs', 34, 63)>", "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\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": { "fetch_message": {
"name": "fetch_message", "name": "fetch_message",
"kind": "function", "kind": "function",
"path": "mail_intake.adapters.base.MailIntakeAdapter.fetch_message", "path": "mail_intake.adapters.base.MailIntakeAdapter.fetch_message",
"signature": "<bound method Function.signature of Function('fetch_message', 65, 78)>", "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)." "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": { "fetch_thread": {
"name": "fetch_thread", "name": "fetch_thread",
"kind": "function", "kind": "function",
"path": "mail_intake.adapters.base.MailIntakeAdapter.fetch_thread", "path": "mail_intake.adapters.base.MailIntakeAdapter.fetch_thread",
"signature": "<bound method Function.signature of Function('fetch_thread', 80, 93)>", "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." "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", "name": "Iterator",
"kind": "alias", "kind": "alias",
"path": "mail_intake.adapters.gmail.Iterator", "path": "mail_intake.adapters.gmail.Iterator",
"signature": "<bound method Alias.signature of Alias('Iterator', 'typing.Iterator')>", "signature": "<bound method Alias.signature of Alias('Iterator', 'collections.abc.Iterator')>",
"docstring": null
},
"Dict": {
"name": "Dict",
"kind": "alias",
"path": "mail_intake.adapters.gmail.Dict",
"signature": "<bound method Alias.signature of Alias('Dict', 'typing.Dict')>",
"docstring": null "docstring": null
}, },
"Any": { "Any": {
@@ -51,31 +44,24 @@
"kind": "function", "kind": "function",
"path": "mail_intake.adapters.gmail.MailIntakeAdapter.iter_message_refs", "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')>", "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": { "fetch_message": {
"name": "fetch_message", "name": "fetch_message",
"kind": "function", "kind": "function",
"path": "mail_intake.adapters.gmail.MailIntakeAdapter.fetch_message", "path": "mail_intake.adapters.gmail.MailIntakeAdapter.fetch_message",
"signature": "<bound method Alias.signature of Alias('fetch_message', 'mail_intake.adapters.base.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": { "fetch_thread": {
"name": "fetch_thread", "name": "fetch_thread",
"kind": "function", "kind": "function",
"path": "mail_intake.adapters.gmail.MailIntakeAdapter.fetch_thread", "path": "mail_intake.adapters.gmail.MailIntakeAdapter.fetch_thread",
"signature": "<bound method Alias.signature of Alias('fetch_thread', 'mail_intake.adapters.base.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": { "MailIntakeAuthProvider": {
"name": "MailIntakeAuthProvider", "name": "MailIntakeAuthProvider",
"kind": "class", "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": { "MailIntakeGmailAdapter": {
"name": "MailIntakeGmailAdapter", "name": "MailIntakeGmailAdapter",
"kind": "class", "kind": "class",
"path": "mail_intake.adapters.gmail.MailIntakeGmailAdapter", "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.", "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": { "members": {
"service": { "service": {
@@ -104,28 +97,28 @@
"kind": "attribute", "kind": "attribute",
"path": "mail_intake.adapters.gmail.MailIntakeGmailAdapter.service", "path": "mail_intake.adapters.gmail.MailIntakeGmailAdapter.service",
"signature": null, "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": { "iter_message_refs": {
"name": "iter_message_refs", "name": "iter_message_refs",
"kind": "function", "kind": "function",
"path": "mail_intake.adapters.gmail.MailIntakeGmailAdapter.iter_message_refs", "path": "mail_intake.adapters.gmail.MailIntakeGmailAdapter.iter_message_refs",
"signature": "<bound method Function.signature of Function('iter_message_refs', 92, 133)>", "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." "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": { "fetch_message": {
"name": "fetch_message", "name": "fetch_message",
"kind": "function", "kind": "function",
"path": "mail_intake.adapters.gmail.MailIntakeGmailAdapter.fetch_message", "path": "mail_intake.adapters.gmail.MailIntakeGmailAdapter.fetch_message",
"signature": "<bound method Function.signature of Function('fetch_message', 135, 161)>", "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." "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": { "fetch_thread": {
"name": "fetch_thread", "name": "fetch_thread",
"kind": "function", "kind": "function",
"path": "mail_intake.adapters.gmail.MailIntakeGmailAdapter.fetch_thread", "path": "mail_intake.adapters.gmail.MailIntakeGmailAdapter.fetch_thread",
"signature": "<bound method Function.signature of Function('fetch_thread', 163, 189)>", "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." "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", "kind": "function",
"path": "mail_intake.adapters.MailIntakeAdapter.iter_message_refs", "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')>", "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": { "fetch_message": {
"name": "fetch_message", "name": "fetch_message",
"kind": "function", "kind": "function",
"path": "mail_intake.adapters.MailIntakeAdapter.fetch_message", "path": "mail_intake.adapters.MailIntakeAdapter.fetch_message",
"signature": "<bound method Alias.signature of Alias('fetch_message', 'mail_intake.adapters.base.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": { "fetch_thread": {
"name": "fetch_thread", "name": "fetch_thread",
"kind": "function", "kind": "function",
"path": "mail_intake.adapters.MailIntakeAdapter.fetch_thread", "path": "mail_intake.adapters.MailIntakeAdapter.fetch_thread",
"signature": "<bound method Alias.signature of Alias('fetch_thread', 'mail_intake.adapters.base.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", "kind": "attribute",
"path": "mail_intake.adapters.MailIntakeGmailAdapter.service", "path": "mail_intake.adapters.MailIntakeGmailAdapter.service",
"signature": "<bound method Alias.signature of Alias('service', 'mail_intake.adapters.gmail.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": { "iter_message_refs": {
"name": "iter_message_refs", "name": "iter_message_refs",
"kind": "function", "kind": "function",
"path": "mail_intake.adapters.MailIntakeGmailAdapter.iter_message_refs", "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')>", "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": { "fetch_message": {
"name": "fetch_message", "name": "fetch_message",
"kind": "function", "kind": "function",
"path": "mail_intake.adapters.MailIntakeGmailAdapter.fetch_message", "path": "mail_intake.adapters.MailIntakeGmailAdapter.fetch_message",
"signature": "<bound method Alias.signature of Alias('fetch_message', 'mail_intake.adapters.gmail.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": { "fetch_thread": {
"name": "fetch_thread", "name": "fetch_thread",
"kind": "function", "kind": "function",
"path": "mail_intake.adapters.MailIntakeGmailAdapter.fetch_thread", "path": "mail_intake.adapters.MailIntakeGmailAdapter.fetch_thread",
"signature": "<bound method Alias.signature of Alias('fetch_thread', 'mail_intake.adapters.gmail.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", "name": "Iterator",
"kind": "alias", "kind": "alias",
"path": "mail_intake.adapters.base.Iterator", "path": "mail_intake.adapters.base.Iterator",
"signature": "<bound method Alias.signature of Alias('Iterator', 'typing.Iterator')>", "signature": "<bound method Alias.signature of Alias('Iterator', 'collections.abc.Iterator')>",
"docstring": null
},
"Dict": {
"name": "Dict",
"kind": "alias",
"path": "mail_intake.adapters.base.Dict",
"signature": "<bound method Alias.signature of Alias('Dict', 'typing.Dict')>",
"docstring": null "docstring": null
}, },
"Any": { "Any": {
@@ -117,29 +110,29 @@
"name": "MailIntakeAdapter", "name": "MailIntakeAdapter",
"kind": "class", "kind": "class",
"path": "mail_intake.adapters.base.MailIntakeAdapter", "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.", "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": { "members": {
"iter_message_refs": { "iter_message_refs": {
"name": "iter_message_refs", "name": "iter_message_refs",
"kind": "function", "kind": "function",
"path": "mail_intake.adapters.base.MailIntakeAdapter.iter_message_refs", "path": "mail_intake.adapters.base.MailIntakeAdapter.iter_message_refs",
"signature": "<bound method Function.signature of Function('iter_message_refs', 34, 63)>", "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\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": { "fetch_message": {
"name": "fetch_message", "name": "fetch_message",
"kind": "function", "kind": "function",
"path": "mail_intake.adapters.base.MailIntakeAdapter.fetch_message", "path": "mail_intake.adapters.base.MailIntakeAdapter.fetch_message",
"signature": "<bound method Function.signature of Function('fetch_message', 65, 78)>", "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)." "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": { "fetch_thread": {
"name": "fetch_thread", "name": "fetch_thread",
"kind": "function", "kind": "function",
"path": "mail_intake.adapters.base.MailIntakeAdapter.fetch_thread", "path": "mail_intake.adapters.base.MailIntakeAdapter.fetch_thread",
"signature": "<bound method Function.signature of Function('fetch_thread', 80, 93)>", "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." "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", "name": "Iterator",
"kind": "alias", "kind": "alias",
"path": "mail_intake.adapters.gmail.Iterator", "path": "mail_intake.adapters.gmail.Iterator",
"signature": "<bound method Alias.signature of Alias('Iterator', 'typing.Iterator')>", "signature": "<bound method Alias.signature of Alias('Iterator', 'collections.abc.Iterator')>",
"docstring": null
},
"Dict": {
"name": "Dict",
"kind": "alias",
"path": "mail_intake.adapters.gmail.Dict",
"signature": "<bound method Alias.signature of Alias('Dict', 'typing.Dict')>",
"docstring": null "docstring": null
}, },
"Any": { "Any": {
@@ -199,31 +185,24 @@
"kind": "function", "kind": "function",
"path": "mail_intake.adapters.gmail.MailIntakeAdapter.iter_message_refs", "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')>", "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": { "fetch_message": {
"name": "fetch_message", "name": "fetch_message",
"kind": "function", "kind": "function",
"path": "mail_intake.adapters.gmail.MailIntakeAdapter.fetch_message", "path": "mail_intake.adapters.gmail.MailIntakeAdapter.fetch_message",
"signature": "<bound method Alias.signature of Alias('fetch_message', 'mail_intake.adapters.base.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": { "fetch_thread": {
"name": "fetch_thread", "name": "fetch_thread",
"kind": "function", "kind": "function",
"path": "mail_intake.adapters.gmail.MailIntakeAdapter.fetch_thread", "path": "mail_intake.adapters.gmail.MailIntakeAdapter.fetch_thread",
"signature": "<bound method Alias.signature of Alias('fetch_thread', 'mail_intake.adapters.base.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": { "MailIntakeAuthProvider": {
"name": "MailIntakeAuthProvider", "name": "MailIntakeAuthProvider",
"kind": "class", "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": { "MailIntakeGmailAdapter": {
"name": "MailIntakeGmailAdapter", "name": "MailIntakeGmailAdapter",
"kind": "class", "kind": "class",
"path": "mail_intake.adapters.gmail.MailIntakeGmailAdapter", "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.", "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": { "members": {
"service": { "service": {
@@ -252,28 +238,28 @@
"kind": "attribute", "kind": "attribute",
"path": "mail_intake.adapters.gmail.MailIntakeGmailAdapter.service", "path": "mail_intake.adapters.gmail.MailIntakeGmailAdapter.service",
"signature": null, "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": { "iter_message_refs": {
"name": "iter_message_refs", "name": "iter_message_refs",
"kind": "function", "kind": "function",
"path": "mail_intake.adapters.gmail.MailIntakeGmailAdapter.iter_message_refs", "path": "mail_intake.adapters.gmail.MailIntakeGmailAdapter.iter_message_refs",
"signature": "<bound method Function.signature of Function('iter_message_refs', 92, 133)>", "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." "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": { "fetch_message": {
"name": "fetch_message", "name": "fetch_message",
"kind": "function", "kind": "function",
"path": "mail_intake.adapters.gmail.MailIntakeGmailAdapter.fetch_message", "path": "mail_intake.adapters.gmail.MailIntakeGmailAdapter.fetch_message",
"signature": "<bound method Function.signature of Function('fetch_message', 135, 161)>", "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." "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": { "fetch_thread": {
"name": "fetch_thread", "name": "fetch_thread",
"kind": "function", "kind": "function",
"path": "mail_intake.adapters.gmail.MailIntakeGmailAdapter.fetch_thread", "path": "mail_intake.adapters.gmail.MailIntakeGmailAdapter.fetch_thread",
"signature": "<bound method Function.signature of Function('fetch_thread', 163, 189)>", "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." "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", "name": "Sequence",
"kind": "alias", "kind": "alias",
"path": "mail_intake.auth.google.Sequence", "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 "docstring": null
}, },
"google": { "google": {
@@ -32,13 +32,6 @@
"signature": "<bound method Alias.signature of Alias('Request', 'google.auth.transport.requests.Request')>", "signature": "<bound method Alias.signature of Alias('Request', 'google.auth.transport.requests.Request')>",
"docstring": null "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": { "Credentials": {
"name": "Credentials", "name": "Credentials",
"kind": "alias", "kind": "alias",
@@ -46,6 +39,13 @@
"signature": "<bound method Alias.signature of Alias('Credentials', 'google.oauth2.credentials.Credentials')>", "signature": "<bound method Alias.signature of Alias('Credentials', 'google.oauth2.credentials.Credentials')>",
"docstring": null "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": { "MailIntakeAuthProvider": {
"name": "MailIntakeAuthProvider", "name": "MailIntakeAuthProvider",
"kind": "class", "kind": "class",
@@ -74,7 +74,7 @@
"kind": "function", "kind": "function",
"path": "mail_intake.auth.google.CredentialStore.load", "path": "mail_intake.auth.google.CredentialStore.load",
"signature": "<bound method Alias.signature of Alias('load', 'mail_intake.credentials.store.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": { "save": {
"name": "save", "name": "save",

View File

@@ -135,7 +135,7 @@
"name": "Sequence", "name": "Sequence",
"kind": "alias", "kind": "alias",
"path": "mail_intake.auth.google.Sequence", "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 "docstring": null
}, },
"google": { "google": {
@@ -152,13 +152,6 @@
"signature": "<bound method Alias.signature of Alias('Request', 'google.auth.transport.requests.Request')>", "signature": "<bound method Alias.signature of Alias('Request', 'google.auth.transport.requests.Request')>",
"docstring": null "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": { "Credentials": {
"name": "Credentials", "name": "Credentials",
"kind": "alias", "kind": "alias",
@@ -166,6 +159,13 @@
"signature": "<bound method Alias.signature of Alias('Credentials', 'google.oauth2.credentials.Credentials')>", "signature": "<bound method Alias.signature of Alias('Credentials', 'google.oauth2.credentials.Credentials')>",
"docstring": null "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": { "MailIntakeAuthProvider": {
"name": "MailIntakeAuthProvider", "name": "MailIntakeAuthProvider",
"kind": "class", "kind": "class",
@@ -194,7 +194,7 @@
"kind": "function", "kind": "function",
"path": "mail_intake.auth.google.CredentialStore.load", "path": "mail_intake.auth.google.CredentialStore.load",
"signature": "<bound method Alias.signature of Alias('load', 'mail_intake.credentials.store.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": { "save": {
"name": "save", "name": "save",

View File

@@ -11,18 +11,11 @@
"signature": "<bound method Alias.signature of Alias('dataclass', 'dataclasses.dataclass')>", "signature": "<bound method Alias.signature of Alias('dataclass', 'dataclasses.dataclass')>",
"docstring": null "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": { "MailIntakeConfig": {
"name": "MailIntakeConfig", "name": "MailIntakeConfig",
"kind": "class", "kind": "class",
"path": "mail_intake.config.MailIntakeConfig", "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.", "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": { "members": {
"provider": { "provider": {

View File

@@ -16,7 +16,7 @@
"kind": "function", "kind": "function",
"path": "mail_intake.credentials.CredentialStore.load", "path": "mail_intake.credentials.CredentialStore.load",
"signature": "<bound method Alias.signature of Alias('load', 'mail_intake.credentials.store.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": { "save": {
"name": "save", "name": "save",
@@ -53,7 +53,7 @@
"kind": "function", "kind": "function",
"path": "mail_intake.credentials.PickleCredentialStore.load", "path": "mail_intake.credentials.PickleCredentialStore.load",
"signature": "<bound method Alias.signature of Alias('load', 'mail_intake.credentials.pickle.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": { "save": {
"name": "save", "name": "save",
@@ -118,7 +118,7 @@
"kind": "function", "kind": "function",
"path": "mail_intake.credentials.RedisCredentialStore.load", "path": "mail_intake.credentials.RedisCredentialStore.load",
"signature": "<bound method Alias.signature of Alias('load', 'mail_intake.credentials.redis.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": { "save": {
"name": "save", "name": "save",
@@ -150,13 +150,6 @@
"signature": "<bound method Alias.signature of Alias('pickle', 'pickle')>", "signature": "<bound method Alias.signature of Alias('pickle', 'pickle')>",
"docstring": null "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": { "TypeVar": {
"name": "TypeVar", "name": "TypeVar",
"kind": "alias", "kind": "alias",
@@ -176,7 +169,7 @@
"kind": "function", "kind": "function",
"path": "mail_intake.credentials.pickle.CredentialStore.load", "path": "mail_intake.credentials.pickle.CredentialStore.load",
"signature": "<bound method Alias.signature of Alias('load', 'mail_intake.credentials.store.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": { "save": {
"name": "save", "name": "save",
@@ -220,7 +213,7 @@
"kind": "function", "kind": "function",
"path": "mail_intake.credentials.pickle.PickleCredentialStore.load", "path": "mail_intake.credentials.pickle.PickleCredentialStore.load",
"signature": "<bound method Function.signature of Function('load', 58, 79)>", "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": { "save": {
"name": "save", "name": "save",
@@ -247,11 +240,18 @@
"signature": null, "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.", "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": { "members": {
"Optional": { "Callable": {
"name": "Optional", "name": "Callable",
"kind": "alias", "kind": "alias",
"path": "mail_intake.credentials.redis.Optional", "path": "mail_intake.credentials.redis.Callable",
"signature": "<bound method Alias.signature of Alias('Optional', 'typing.Optional')>", "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 "docstring": null
}, },
"TypeVar": { "TypeVar": {
@@ -261,13 +261,6 @@
"signature": "<bound method Alias.signature of Alias('TypeVar', 'typing.TypeVar')>", "signature": "<bound method Alias.signature of Alias('TypeVar', 'typing.TypeVar')>",
"docstring": null "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": { "CredentialStore": {
"name": "CredentialStore", "name": "CredentialStore",
"kind": "class", "kind": "class",
@@ -280,7 +273,7 @@
"kind": "function", "kind": "function",
"path": "mail_intake.credentials.redis.CredentialStore.load", "path": "mail_intake.credentials.redis.CredentialStore.load",
"signature": "<bound method Alias.signature of Alias('load', 'mail_intake.credentials.store.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": { "save": {
"name": "save", "name": "save",
@@ -309,7 +302,7 @@
"name": "RedisCredentialStore", "name": "RedisCredentialStore",
"kind": "class", "kind": "class",
"path": "mail_intake.credentials.redis.RedisCredentialStore", "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.", "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": { "members": {
"redis": { "redis": {
@@ -351,31 +344,24 @@
"name": "load", "name": "load",
"kind": "function", "kind": "function",
"path": "mail_intake.credentials.redis.RedisCredentialStore.load", "path": "mail_intake.credentials.redis.RedisCredentialStore.load",
"signature": "<bound method Function.signature of Function('load', 91, 116)>", "signature": "<bound method Function.signature of Function('load', 88, 113)>",
"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": { "save": {
"name": "save", "name": "save",
"kind": "function", "kind": "function",
"path": "mail_intake.credentials.redis.RedisCredentialStore.save", "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" "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": { "clear": {
"name": "clear", "name": "clear",
"kind": "function", "kind": "function",
"path": "mail_intake.credentials.redis.RedisCredentialStore.clear", "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" "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')>", "signature": "<bound method Alias.signature of Alias('Generic', 'typing.Generic')>",
"docstring": null "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": { "TypeVar": {
"name": "TypeVar", "name": "TypeVar",
"kind": "alias", "kind": "alias",
@@ -432,28 +411,28 @@
"name": "CredentialStore", "name": "CredentialStore",
"kind": "class", "kind": "class",
"path": "mail_intake.credentials.store.CredentialStore", "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.", "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": { "members": {
"load": { "load": {
"name": "load", "name": "load",
"kind": "function", "kind": "function",
"path": "mail_intake.credentials.store.CredentialStore.load", "path": "mail_intake.credentials.store.CredentialStore.load",
"signature": "<bound method Function.signature of Function('load', 50, 68)>", "signature": "<bound method Function.signature of Function('load', 49, 67)>",
"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": { "save": {
"name": "save", "name": "save",
"kind": "function", "kind": "function",
"path": "mail_intake.credentials.store.CredentialStore.save", "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" "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": { "clear": {
"name": "clear", "name": "clear",
"kind": "function", "kind": "function",
"path": "mail_intake.credentials.store.CredentialStore.clear", "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" "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')>", "signature": "<bound method Alias.signature of Alias('pickle', 'pickle')>",
"docstring": null "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": { "TypeVar": {
"name": "TypeVar", "name": "TypeVar",
"kind": "alias", "kind": "alias",
@@ -37,7 +30,7 @@
"kind": "function", "kind": "function",
"path": "mail_intake.credentials.pickle.CredentialStore.load", "path": "mail_intake.credentials.pickle.CredentialStore.load",
"signature": "<bound method Alias.signature of Alias('load', 'mail_intake.credentials.store.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": { "save": {
"name": "save", "name": "save",
@@ -81,7 +74,7 @@
"kind": "function", "kind": "function",
"path": "mail_intake.credentials.pickle.PickleCredentialStore.load", "path": "mail_intake.credentials.pickle.PickleCredentialStore.load",
"signature": "<bound method Function.signature of Function('load', 58, 79)>", "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": { "save": {
"name": "save", "name": "save",

View File

@@ -4,11 +4,18 @@
"path": "mail_intake.credentials.redis", "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.", "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": { "objects": {
"Optional": { "Callable": {
"name": "Optional", "name": "Callable",
"kind": "alias", "kind": "alias",
"path": "mail_intake.credentials.redis.Optional", "path": "mail_intake.credentials.redis.Callable",
"signature": "<bound method Alias.signature of Alias('Optional', 'typing.Optional')>", "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 "docstring": null
}, },
"TypeVar": { "TypeVar": {
@@ -18,13 +25,6 @@
"signature": "<bound method Alias.signature of Alias('TypeVar', 'typing.TypeVar')>", "signature": "<bound method Alias.signature of Alias('TypeVar', 'typing.TypeVar')>",
"docstring": null "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": { "CredentialStore": {
"name": "CredentialStore", "name": "CredentialStore",
"kind": "class", "kind": "class",
@@ -37,7 +37,7 @@
"kind": "function", "kind": "function",
"path": "mail_intake.credentials.redis.CredentialStore.load", "path": "mail_intake.credentials.redis.CredentialStore.load",
"signature": "<bound method Alias.signature of Alias('load', 'mail_intake.credentials.store.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": { "save": {
"name": "save", "name": "save",
@@ -66,7 +66,7 @@
"name": "RedisCredentialStore", "name": "RedisCredentialStore",
"kind": "class", "kind": "class",
"path": "mail_intake.credentials.redis.RedisCredentialStore", "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.", "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": { "members": {
"redis": { "redis": {
@@ -108,31 +108,24 @@
"name": "load", "name": "load",
"kind": "function", "kind": "function",
"path": "mail_intake.credentials.redis.RedisCredentialStore.load", "path": "mail_intake.credentials.redis.RedisCredentialStore.load",
"signature": "<bound method Function.signature of Function('load', 91, 116)>", "signature": "<bound method Function.signature of Function('load', 88, 113)>",
"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": { "save": {
"name": "save", "name": "save",
"kind": "function", "kind": "function",
"path": "mail_intake.credentials.redis.RedisCredentialStore.save", "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" "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": { "clear": {
"name": "clear", "name": "clear",
"kind": "function", "kind": "function",
"path": "mail_intake.credentials.redis.RedisCredentialStore.clear", "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" "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')>", "signature": "<bound method Alias.signature of Alias('Generic', 'typing.Generic')>",
"docstring": null "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": { "TypeVar": {
"name": "TypeVar", "name": "TypeVar",
"kind": "alias", "kind": "alias",
@@ -50,28 +43,28 @@
"name": "CredentialStore", "name": "CredentialStore",
"kind": "class", "kind": "class",
"path": "mail_intake.credentials.store.CredentialStore", "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.", "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": { "members": {
"load": { "load": {
"name": "load", "name": "load",
"kind": "function", "kind": "function",
"path": "mail_intake.credentials.store.CredentialStore.load", "path": "mail_intake.credentials.store.CredentialStore.load",
"signature": "<bound method Function.signature of Function('load', 50, 68)>", "signature": "<bound method Function.signature of Function('load', 49, 67)>",
"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": { "save": {
"name": "save", "name": "save",
"kind": "function", "kind": "function",
"path": "mail_intake.credentials.store.CredentialStore.save", "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" "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": { "clear": {
"name": "clear", "name": "clear",
"kind": "function", "kind": "function",
"path": "mail_intake.credentials.store.CredentialStore.clear", "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" "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", "module": "mail_intake.exceptions",
"content": { "content": {
"path": "mail_intake.exceptions", "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": { "objects": {
"MailIntakeError": { "MailIntakeError": {
"name": "MailIntakeError", "name": "MailIntakeError",
"kind": "class", "kind": "class",
"path": "mail_intake.exceptions.MailIntakeError", "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" "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": { "MailIntakeAuthError": {
"name": "MailIntakeAuthError", "name": "MailIntakeAuthError",
"kind": "class", "kind": "class",
"path": "mail_intake.exceptions.MailIntakeAuthError", "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." "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": { "MailIntakeAdapterError": {
"name": "MailIntakeAdapterError", "name": "MailIntakeAdapterError",
"kind": "class", "kind": "class",
"path": "mail_intake.exceptions.MailIntakeAdapterError", "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." "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": { "MailIntakeParsingError": {
"name": "MailIntakeParsingError", "name": "MailIntakeParsingError",
"kind": "class", "kind": "class",
"path": "mail_intake.exceptions.MailIntakeParsingError", "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." "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", "kind": "function",
"path": "mail_intake.ingestion.MailIntakeReader.iter_threads", "path": "mail_intake.ingestion.MailIntakeReader.iter_threads",
"signature": "<bound method Alias.signature of Alias('iter_threads', 'mail_intake.ingestion.reader.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, "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.", "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": { "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": { "datetime": {
"name": "datetime", "name": "datetime",
"kind": "alias", "kind": "alias",
@@ -41,20 +48,6 @@
"signature": "<bound method Alias.signature of Alias('datetime', 'datetime.datetime')>", "signature": "<bound method Alias.signature of Alias('datetime', 'datetime.datetime')>",
"docstring": null "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": { "Any": {
"name": "Any", "name": "Any",
"kind": "alias", "kind": "alias",
@@ -74,24 +67,31 @@
"kind": "function", "kind": "function",
"path": "mail_intake.ingestion.reader.MailIntakeAdapter.iter_message_refs", "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')>", "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": { "fetch_message": {
"name": "fetch_message", "name": "fetch_message",
"kind": "function", "kind": "function",
"path": "mail_intake.ingestion.reader.MailIntakeAdapter.fetch_message", "path": "mail_intake.ingestion.reader.MailIntakeAdapter.fetch_message",
"signature": "<bound method Alias.signature of Alias('fetch_message', 'mail_intake.adapters.base.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": { "fetch_thread": {
"name": "fetch_thread", "name": "fetch_thread",
"kind": "function", "kind": "function",
"path": "mail_intake.ingestion.reader.MailIntakeAdapter.fetch_thread", "path": "mail_intake.ingestion.reader.MailIntakeAdapter.fetch_thread",
"signature": "<bound method Alias.signature of Alias('fetch_thread', 'mail_intake.adapters.base.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": { "MailIntakeMessage": {
"name": "MailIntakeMessage", "name": "MailIntakeMessage",
"kind": "class", "kind": "class",
@@ -215,26 +215,26 @@
} }
} }
}, },
"parse_headers": { "extract_body": {
"name": "parse_headers", "name": "extract_body",
"kind": "function", "kind": "function",
"path": "mail_intake.ingestion.reader.parse_headers", "path": "mail_intake.ingestion.reader.extract_body",
"signature": "<bound method Alias.signature of Alias('parse_headers', 'mail_intake.parsers.headers.parse_headers')>", "signature": "<bound method Alias.signature of Alias('extract_body', 'mail_intake.parsers.body.extract_body')>",
"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": "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": { "extract_sender": {
"name": "extract_sender", "name": "extract_sender",
"kind": "function", "kind": "function",
"path": "mail_intake.ingestion.reader.extract_sender", "path": "mail_intake.ingestion.reader.extract_sender",
"signature": "<bound method Alias.signature of Alias('extract_sender', 'mail_intake.parsers.headers.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": { "parse_headers": {
"name": "extract_body", "name": "parse_headers",
"kind": "function", "kind": "function",
"path": "mail_intake.ingestion.reader.extract_body", "path": "mail_intake.ingestion.reader.parse_headers",
"signature": "<bound method Alias.signature of Alias('extract_body', 'mail_intake.parsers.body.extract_body')>", "signature": "<bound method Alias.signature of Alias('parse_headers', 'mail_intake.parsers.headers.parse_headers')>",
"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": "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": { "normalize_subject": {
"name": "normalize_subject", "name": "normalize_subject",
@@ -243,33 +243,26 @@
"signature": "<bound method Alias.signature of Alias('normalize_subject', 'mail_intake.parsers.subject.normalize_subject')>", "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." "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": { "MailIntakeReader": {
"name": "MailIntakeReader", "name": "MailIntakeReader",
"kind": "class", "kind": "class",
"path": "mail_intake.ingestion.reader.MailIntakeReader", "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.", "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": { "members": {
"iter_messages": { "iter_messages": {
"name": "iter_messages", "name": "iter_messages",
"kind": "function", "kind": "function",
"path": "mail_intake.ingestion.reader.MailIntakeReader.iter_messages", "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." "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": { "iter_threads": {
"name": "iter_threads", "name": "iter_threads",
"kind": "function", "kind": "function",
"path": "mail_intake.ingestion.reader.MailIntakeReader.iter_threads", "path": "mail_intake.ingestion.reader.MailIntakeReader.iter_threads",
"signature": "<bound method Function.signature of Function('iter_threads', 82, 120)>", "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\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."
} }
} }
} }

View File

@@ -4,6 +4,13 @@
"path": "mail_intake.ingestion.reader", "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.", "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": { "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": { "datetime": {
"name": "datetime", "name": "datetime",
"kind": "alias", "kind": "alias",
@@ -11,20 +18,6 @@
"signature": "<bound method Alias.signature of Alias('datetime', 'datetime.datetime')>", "signature": "<bound method Alias.signature of Alias('datetime', 'datetime.datetime')>",
"docstring": null "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": { "Any": {
"name": "Any", "name": "Any",
"kind": "alias", "kind": "alias",
@@ -44,24 +37,31 @@
"kind": "function", "kind": "function",
"path": "mail_intake.ingestion.reader.MailIntakeAdapter.iter_message_refs", "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')>", "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": { "fetch_message": {
"name": "fetch_message", "name": "fetch_message",
"kind": "function", "kind": "function",
"path": "mail_intake.ingestion.reader.MailIntakeAdapter.fetch_message", "path": "mail_intake.ingestion.reader.MailIntakeAdapter.fetch_message",
"signature": "<bound method Alias.signature of Alias('fetch_message', 'mail_intake.adapters.base.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": { "fetch_thread": {
"name": "fetch_thread", "name": "fetch_thread",
"kind": "function", "kind": "function",
"path": "mail_intake.ingestion.reader.MailIntakeAdapter.fetch_thread", "path": "mail_intake.ingestion.reader.MailIntakeAdapter.fetch_thread",
"signature": "<bound method Alias.signature of Alias('fetch_thread', 'mail_intake.adapters.base.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": { "MailIntakeMessage": {
"name": "MailIntakeMessage", "name": "MailIntakeMessage",
"kind": "class", "kind": "class",
@@ -185,26 +185,26 @@
} }
} }
}, },
"parse_headers": { "extract_body": {
"name": "parse_headers", "name": "extract_body",
"kind": "function", "kind": "function",
"path": "mail_intake.ingestion.reader.parse_headers", "path": "mail_intake.ingestion.reader.extract_body",
"signature": "<bound method Alias.signature of Alias('parse_headers', 'mail_intake.parsers.headers.parse_headers')>", "signature": "<bound method Alias.signature of Alias('extract_body', 'mail_intake.parsers.body.extract_body')>",
"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": "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": { "extract_sender": {
"name": "extract_sender", "name": "extract_sender",
"kind": "function", "kind": "function",
"path": "mail_intake.ingestion.reader.extract_sender", "path": "mail_intake.ingestion.reader.extract_sender",
"signature": "<bound method Alias.signature of Alias('extract_sender', 'mail_intake.parsers.headers.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": { "parse_headers": {
"name": "extract_body", "name": "parse_headers",
"kind": "function", "kind": "function",
"path": "mail_intake.ingestion.reader.extract_body", "path": "mail_intake.ingestion.reader.parse_headers",
"signature": "<bound method Alias.signature of Alias('extract_body', 'mail_intake.parsers.body.extract_body')>", "signature": "<bound method Alias.signature of Alias('parse_headers', 'mail_intake.parsers.headers.parse_headers')>",
"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": "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": { "normalize_subject": {
"name": "normalize_subject", "name": "normalize_subject",
@@ -213,33 +213,26 @@
"signature": "<bound method Alias.signature of Alias('normalize_subject', 'mail_intake.parsers.subject.normalize_subject')>", "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." "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": { "MailIntakeReader": {
"name": "MailIntakeReader", "name": "MailIntakeReader",
"kind": "class", "kind": "class",
"path": "mail_intake.ingestion.reader.MailIntakeReader", "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.", "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": { "members": {
"iter_messages": { "iter_messages": {
"name": "iter_messages", "name": "iter_messages",
"kind": "function", "kind": "function",
"path": "mail_intake.ingestion.reader.MailIntakeReader.iter_messages", "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." "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": { "iter_threads": {
"name": "iter_threads", "name": "iter_threads",
"kind": "function", "kind": "function",
"path": "mail_intake.ingestion.reader.MailIntakeReader.iter_threads", "path": "mail_intake.ingestion.reader.MailIntakeReader.iter_threads",
"signature": "<bound method Function.signature of Function('iter_threads', 82, 120)>", "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\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."
} }
} }
} }

View File

@@ -18,18 +18,11 @@
"signature": "<bound method Alias.signature of Alias('dataclass', 'dataclasses.dataclass')>", "signature": "<bound method Alias.signature of Alias('dataclass', 'dataclasses.dataclass')>",
"docstring": null "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": { "MailIntakeConfig": {
"name": "MailIntakeConfig", "name": "MailIntakeConfig",
"kind": "class", "kind": "class",
"path": "mail_intake.config.MailIntakeConfig", "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.", "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": { "members": {
"provider": { "provider": {
@@ -76,34 +69,34 @@
"kind": "module", "kind": "module",
"path": "mail_intake.exceptions", "path": "mail_intake.exceptions",
"signature": null, "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": { "members": {
"MailIntakeError": { "MailIntakeError": {
"name": "MailIntakeError", "name": "MailIntakeError",
"kind": "class", "kind": "class",
"path": "mail_intake.exceptions.MailIntakeError", "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" "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": { "MailIntakeAuthError": {
"name": "MailIntakeAuthError", "name": "MailIntakeAuthError",
"kind": "class", "kind": "class",
"path": "mail_intake.exceptions.MailIntakeAuthError", "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." "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": { "MailIntakeAdapterError": {
"name": "MailIntakeAdapterError", "name": "MailIntakeAdapterError",
"kind": "class", "kind": "class",
"path": "mail_intake.exceptions.MailIntakeAdapterError", "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." "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": { "MailIntakeParsingError": {
"name": "MailIntakeParsingError", "name": "MailIntakeParsingError",
"kind": "class", "kind": "class",
"path": "mail_intake.exceptions.MailIntakeParsingError", "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." "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", "kind": "function",
"path": "mail_intake.adapters.MailIntakeAdapter.iter_message_refs", "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')>", "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": { "fetch_message": {
"name": "fetch_message", "name": "fetch_message",
"kind": "function", "kind": "function",
"path": "mail_intake.adapters.MailIntakeAdapter.fetch_message", "path": "mail_intake.adapters.MailIntakeAdapter.fetch_message",
"signature": "<bound method Alias.signature of Alias('fetch_message', 'mail_intake.adapters.base.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": { "fetch_thread": {
"name": "fetch_thread", "name": "fetch_thread",
"kind": "function", "kind": "function",
"path": "mail_intake.adapters.MailIntakeAdapter.fetch_thread", "path": "mail_intake.adapters.MailIntakeAdapter.fetch_thread",
"signature": "<bound method Alias.signature of Alias('fetch_thread', 'mail_intake.adapters.base.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", "kind": "attribute",
"path": "mail_intake.adapters.MailIntakeGmailAdapter.service", "path": "mail_intake.adapters.MailIntakeGmailAdapter.service",
"signature": "<bound method Alias.signature of Alias('service', 'mail_intake.adapters.gmail.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": { "iter_message_refs": {
"name": "iter_message_refs", "name": "iter_message_refs",
"kind": "function", "kind": "function",
"path": "mail_intake.adapters.MailIntakeGmailAdapter.iter_message_refs", "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')>", "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": { "fetch_message": {
"name": "fetch_message", "name": "fetch_message",
"kind": "function", "kind": "function",
"path": "mail_intake.adapters.MailIntakeGmailAdapter.fetch_message", "path": "mail_intake.adapters.MailIntakeGmailAdapter.fetch_message",
"signature": "<bound method Alias.signature of Alias('fetch_message', 'mail_intake.adapters.gmail.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": { "fetch_thread": {
"name": "fetch_thread", "name": "fetch_thread",
"kind": "function", "kind": "function",
"path": "mail_intake.adapters.MailIntakeGmailAdapter.fetch_thread", "path": "mail_intake.adapters.MailIntakeGmailAdapter.fetch_thread",
"signature": "<bound method Alias.signature of Alias('fetch_thread', 'mail_intake.adapters.gmail.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", "name": "Iterator",
"kind": "alias", "kind": "alias",
"path": "mail_intake.adapters.base.Iterator", "path": "mail_intake.adapters.base.Iterator",
"signature": "<bound method Alias.signature of Alias('Iterator', 'typing.Iterator')>", "signature": "<bound method Alias.signature of Alias('Iterator', 'collections.abc.Iterator')>",
"docstring": null
},
"Dict": {
"name": "Dict",
"kind": "alias",
"path": "mail_intake.adapters.base.Dict",
"signature": "<bound method Alias.signature of Alias('Dict', 'typing.Dict')>",
"docstring": null "docstring": null
}, },
"Any": { "Any": {
@@ -228,29 +214,29 @@
"name": "MailIntakeAdapter", "name": "MailIntakeAdapter",
"kind": "class", "kind": "class",
"path": "mail_intake.adapters.base.MailIntakeAdapter", "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.", "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": { "members": {
"iter_message_refs": { "iter_message_refs": {
"name": "iter_message_refs", "name": "iter_message_refs",
"kind": "function", "kind": "function",
"path": "mail_intake.adapters.base.MailIntakeAdapter.iter_message_refs", "path": "mail_intake.adapters.base.MailIntakeAdapter.iter_message_refs",
"signature": "<bound method Function.signature of Function('iter_message_refs', 34, 63)>", "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\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": { "fetch_message": {
"name": "fetch_message", "name": "fetch_message",
"kind": "function", "kind": "function",
"path": "mail_intake.adapters.base.MailIntakeAdapter.fetch_message", "path": "mail_intake.adapters.base.MailIntakeAdapter.fetch_message",
"signature": "<bound method Function.signature of Function('fetch_message', 65, 78)>", "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)." "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": { "fetch_thread": {
"name": "fetch_thread", "name": "fetch_thread",
"kind": "function", "kind": "function",
"path": "mail_intake.adapters.base.MailIntakeAdapter.fetch_thread", "path": "mail_intake.adapters.base.MailIntakeAdapter.fetch_thread",
"signature": "<bound method Function.signature of Function('fetch_thread', 80, 93)>", "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." "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", "name": "Iterator",
"kind": "alias", "kind": "alias",
"path": "mail_intake.adapters.gmail.Iterator", "path": "mail_intake.adapters.gmail.Iterator",
"signature": "<bound method Alias.signature of Alias('Iterator', 'typing.Iterator')>", "signature": "<bound method Alias.signature of Alias('Iterator', 'collections.abc.Iterator')>",
"docstring": null
},
"Dict": {
"name": "Dict",
"kind": "alias",
"path": "mail_intake.adapters.gmail.Dict",
"signature": "<bound method Alias.signature of Alias('Dict', 'typing.Dict')>",
"docstring": null "docstring": null
}, },
"Any": { "Any": {
@@ -310,31 +289,24 @@
"kind": "function", "kind": "function",
"path": "mail_intake.adapters.gmail.MailIntakeAdapter.iter_message_refs", "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')>", "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": { "fetch_message": {
"name": "fetch_message", "name": "fetch_message",
"kind": "function", "kind": "function",
"path": "mail_intake.adapters.gmail.MailIntakeAdapter.fetch_message", "path": "mail_intake.adapters.gmail.MailIntakeAdapter.fetch_message",
"signature": "<bound method Alias.signature of Alias('fetch_message', 'mail_intake.adapters.base.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": { "fetch_thread": {
"name": "fetch_thread", "name": "fetch_thread",
"kind": "function", "kind": "function",
"path": "mail_intake.adapters.gmail.MailIntakeAdapter.fetch_thread", "path": "mail_intake.adapters.gmail.MailIntakeAdapter.fetch_thread",
"signature": "<bound method Alias.signature of Alias('fetch_thread', 'mail_intake.adapters.base.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": { "MailIntakeAuthProvider": {
"name": "MailIntakeAuthProvider", "name": "MailIntakeAuthProvider",
"kind": "class", "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": { "MailIntakeGmailAdapter": {
"name": "MailIntakeGmailAdapter", "name": "MailIntakeGmailAdapter",
"kind": "class", "kind": "class",
"path": "mail_intake.adapters.gmail.MailIntakeGmailAdapter", "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.", "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": { "members": {
"service": { "service": {
@@ -363,28 +342,28 @@
"kind": "attribute", "kind": "attribute",
"path": "mail_intake.adapters.gmail.MailIntakeGmailAdapter.service", "path": "mail_intake.adapters.gmail.MailIntakeGmailAdapter.service",
"signature": null, "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": { "iter_message_refs": {
"name": "iter_message_refs", "name": "iter_message_refs",
"kind": "function", "kind": "function",
"path": "mail_intake.adapters.gmail.MailIntakeGmailAdapter.iter_message_refs", "path": "mail_intake.adapters.gmail.MailIntakeGmailAdapter.iter_message_refs",
"signature": "<bound method Function.signature of Function('iter_message_refs', 92, 133)>", "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." "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": { "fetch_message": {
"name": "fetch_message", "name": "fetch_message",
"kind": "function", "kind": "function",
"path": "mail_intake.adapters.gmail.MailIntakeGmailAdapter.fetch_message", "path": "mail_intake.adapters.gmail.MailIntakeGmailAdapter.fetch_message",
"signature": "<bound method Function.signature of Function('fetch_message', 135, 161)>", "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." "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": { "fetch_thread": {
"name": "fetch_thread", "name": "fetch_thread",
"kind": "function", "kind": "function",
"path": "mail_intake.adapters.gmail.MailIntakeGmailAdapter.fetch_thread", "path": "mail_intake.adapters.gmail.MailIntakeGmailAdapter.fetch_thread",
"signature": "<bound method Function.signature of Function('fetch_thread', 163, 189)>", "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." "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", "name": "Sequence",
"kind": "alias", "kind": "alias",
"path": "mail_intake.auth.google.Sequence", "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 "docstring": null
}, },
"google": { "google": {
@@ -547,13 +526,6 @@
"signature": "<bound method Alias.signature of Alias('Request', 'google.auth.transport.requests.Request')>", "signature": "<bound method Alias.signature of Alias('Request', 'google.auth.transport.requests.Request')>",
"docstring": null "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": { "Credentials": {
"name": "Credentials", "name": "Credentials",
"kind": "alias", "kind": "alias",
@@ -561,6 +533,13 @@
"signature": "<bound method Alias.signature of Alias('Credentials', 'google.oauth2.credentials.Credentials')>", "signature": "<bound method Alias.signature of Alias('Credentials', 'google.oauth2.credentials.Credentials')>",
"docstring": null "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": { "MailIntakeAuthProvider": {
"name": "MailIntakeAuthProvider", "name": "MailIntakeAuthProvider",
"kind": "class", "kind": "class",
@@ -589,7 +568,7 @@
"kind": "function", "kind": "function",
"path": "mail_intake.auth.google.CredentialStore.load", "path": "mail_intake.auth.google.CredentialStore.load",
"signature": "<bound method Alias.signature of Alias('load', 'mail_intake.credentials.store.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": { "save": {
"name": "save", "name": "save",
@@ -681,7 +660,7 @@
"kind": "function", "kind": "function",
"path": "mail_intake.credentials.CredentialStore.load", "path": "mail_intake.credentials.CredentialStore.load",
"signature": "<bound method Alias.signature of Alias('load', 'mail_intake.credentials.store.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": { "save": {
"name": "save", "name": "save",
@@ -718,7 +697,7 @@
"kind": "function", "kind": "function",
"path": "mail_intake.credentials.PickleCredentialStore.load", "path": "mail_intake.credentials.PickleCredentialStore.load",
"signature": "<bound method Alias.signature of Alias('load', 'mail_intake.credentials.pickle.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": { "save": {
"name": "save", "name": "save",
@@ -783,7 +762,7 @@
"kind": "function", "kind": "function",
"path": "mail_intake.credentials.RedisCredentialStore.load", "path": "mail_intake.credentials.RedisCredentialStore.load",
"signature": "<bound method Alias.signature of Alias('load', 'mail_intake.credentials.redis.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": { "save": {
"name": "save", "name": "save",
@@ -815,13 +794,6 @@
"signature": "<bound method Alias.signature of Alias('pickle', 'pickle')>", "signature": "<bound method Alias.signature of Alias('pickle', 'pickle')>",
"docstring": null "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": { "TypeVar": {
"name": "TypeVar", "name": "TypeVar",
"kind": "alias", "kind": "alias",
@@ -841,7 +813,7 @@
"kind": "function", "kind": "function",
"path": "mail_intake.credentials.pickle.CredentialStore.load", "path": "mail_intake.credentials.pickle.CredentialStore.load",
"signature": "<bound method Alias.signature of Alias('load', 'mail_intake.credentials.store.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": { "save": {
"name": "save", "name": "save",
@@ -885,7 +857,7 @@
"kind": "function", "kind": "function",
"path": "mail_intake.credentials.pickle.PickleCredentialStore.load", "path": "mail_intake.credentials.pickle.PickleCredentialStore.load",
"signature": "<bound method Function.signature of Function('load', 58, 79)>", "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": { "save": {
"name": "save", "name": "save",
@@ -912,11 +884,18 @@
"signature": null, "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.", "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": { "members": {
"Optional": { "Callable": {
"name": "Optional", "name": "Callable",
"kind": "alias", "kind": "alias",
"path": "mail_intake.credentials.redis.Optional", "path": "mail_intake.credentials.redis.Callable",
"signature": "<bound method Alias.signature of Alias('Optional', 'typing.Optional')>", "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 "docstring": null
}, },
"TypeVar": { "TypeVar": {
@@ -926,13 +905,6 @@
"signature": "<bound method Alias.signature of Alias('TypeVar', 'typing.TypeVar')>", "signature": "<bound method Alias.signature of Alias('TypeVar', 'typing.TypeVar')>",
"docstring": null "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": { "CredentialStore": {
"name": "CredentialStore", "name": "CredentialStore",
"kind": "class", "kind": "class",
@@ -945,7 +917,7 @@
"kind": "function", "kind": "function",
"path": "mail_intake.credentials.redis.CredentialStore.load", "path": "mail_intake.credentials.redis.CredentialStore.load",
"signature": "<bound method Alias.signature of Alias('load', 'mail_intake.credentials.store.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": { "save": {
"name": "save", "name": "save",
@@ -974,7 +946,7 @@
"name": "RedisCredentialStore", "name": "RedisCredentialStore",
"kind": "class", "kind": "class",
"path": "mail_intake.credentials.redis.RedisCredentialStore", "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.", "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": { "members": {
"redis": { "redis": {
@@ -1016,31 +988,24 @@
"name": "load", "name": "load",
"kind": "function", "kind": "function",
"path": "mail_intake.credentials.redis.RedisCredentialStore.load", "path": "mail_intake.credentials.redis.RedisCredentialStore.load",
"signature": "<bound method Function.signature of Function('load', 91, 116)>", "signature": "<bound method Function.signature of Function('load', 88, 113)>",
"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": { "save": {
"name": "save", "name": "save",
"kind": "function", "kind": "function",
"path": "mail_intake.credentials.redis.RedisCredentialStore.save", "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" "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": { "clear": {
"name": "clear", "name": "clear",
"kind": "function", "kind": "function",
"path": "mail_intake.credentials.redis.RedisCredentialStore.clear", "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" "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')>", "signature": "<bound method Alias.signature of Alias('Generic', 'typing.Generic')>",
"docstring": null "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": { "TypeVar": {
"name": "TypeVar", "name": "TypeVar",
"kind": "alias", "kind": "alias",
@@ -1097,28 +1055,28 @@
"name": "CredentialStore", "name": "CredentialStore",
"kind": "class", "kind": "class",
"path": "mail_intake.credentials.store.CredentialStore", "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.", "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": { "members": {
"load": { "load": {
"name": "load", "name": "load",
"kind": "function", "kind": "function",
"path": "mail_intake.credentials.store.CredentialStore.load", "path": "mail_intake.credentials.store.CredentialStore.load",
"signature": "<bound method Function.signature of Function('load', 50, 68)>", "signature": "<bound method Function.signature of Function('load', 49, 67)>",
"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": { "save": {
"name": "save", "name": "save",
"kind": "function", "kind": "function",
"path": "mail_intake.credentials.store.CredentialStore.save", "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" "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": { "clear": {
"name": "clear", "name": "clear",
"kind": "function", "kind": "function",
"path": "mail_intake.credentials.store.CredentialStore.clear", "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" "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", "kind": "function",
"path": "mail_intake.ingestion.MailIntakeReader.iter_threads", "path": "mail_intake.ingestion.MailIntakeReader.iter_threads",
"signature": "<bound method Alias.signature of Alias('iter_threads', 'mail_intake.ingestion.reader.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, "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.", "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": { "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": { "datetime": {
"name": "datetime", "name": "datetime",
"kind": "alias", "kind": "alias",
@@ -1171,20 +1136,6 @@
"signature": "<bound method Alias.signature of Alias('datetime', 'datetime.datetime')>", "signature": "<bound method Alias.signature of Alias('datetime', 'datetime.datetime')>",
"docstring": null "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": { "Any": {
"name": "Any", "name": "Any",
"kind": "alias", "kind": "alias",
@@ -1204,24 +1155,31 @@
"kind": "function", "kind": "function",
"path": "mail_intake.ingestion.reader.MailIntakeAdapter.iter_message_refs", "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')>", "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": { "fetch_message": {
"name": "fetch_message", "name": "fetch_message",
"kind": "function", "kind": "function",
"path": "mail_intake.ingestion.reader.MailIntakeAdapter.fetch_message", "path": "mail_intake.ingestion.reader.MailIntakeAdapter.fetch_message",
"signature": "<bound method Alias.signature of Alias('fetch_message', 'mail_intake.adapters.base.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": { "fetch_thread": {
"name": "fetch_thread", "name": "fetch_thread",
"kind": "function", "kind": "function",
"path": "mail_intake.ingestion.reader.MailIntakeAdapter.fetch_thread", "path": "mail_intake.ingestion.reader.MailIntakeAdapter.fetch_thread",
"signature": "<bound method Alias.signature of Alias('fetch_thread', 'mail_intake.adapters.base.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": { "MailIntakeMessage": {
"name": "MailIntakeMessage", "name": "MailIntakeMessage",
"kind": "class", "kind": "class",
@@ -1345,26 +1303,26 @@
} }
} }
}, },
"parse_headers": { "extract_body": {
"name": "parse_headers", "name": "extract_body",
"kind": "function", "kind": "function",
"path": "mail_intake.ingestion.reader.parse_headers", "path": "mail_intake.ingestion.reader.extract_body",
"signature": "<bound method Alias.signature of Alias('parse_headers', 'mail_intake.parsers.headers.parse_headers')>", "signature": "<bound method Alias.signature of Alias('extract_body', 'mail_intake.parsers.body.extract_body')>",
"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": "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": { "extract_sender": {
"name": "extract_sender", "name": "extract_sender",
"kind": "function", "kind": "function",
"path": "mail_intake.ingestion.reader.extract_sender", "path": "mail_intake.ingestion.reader.extract_sender",
"signature": "<bound method Alias.signature of Alias('extract_sender', 'mail_intake.parsers.headers.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": { "parse_headers": {
"name": "extract_body", "name": "parse_headers",
"kind": "function", "kind": "function",
"path": "mail_intake.ingestion.reader.extract_body", "path": "mail_intake.ingestion.reader.parse_headers",
"signature": "<bound method Alias.signature of Alias('extract_body', 'mail_intake.parsers.body.extract_body')>", "signature": "<bound method Alias.signature of Alias('parse_headers', 'mail_intake.parsers.headers.parse_headers')>",
"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": "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": { "normalize_subject": {
"name": "normalize_subject", "name": "normalize_subject",
@@ -1373,33 +1331,26 @@
"signature": "<bound method Alias.signature of Alias('normalize_subject', 'mail_intake.parsers.subject.normalize_subject')>", "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." "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": { "MailIntakeReader": {
"name": "MailIntakeReader", "name": "MailIntakeReader",
"kind": "class", "kind": "class",
"path": "mail_intake.ingestion.reader.MailIntakeReader", "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.", "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": { "members": {
"iter_messages": { "iter_messages": {
"name": "iter_messages", "name": "iter_messages",
"kind": "function", "kind": "function",
"path": "mail_intake.ingestion.reader.MailIntakeReader.iter_messages", "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." "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": { "iter_threads": {
"name": "iter_threads", "name": "iter_threads",
"kind": "function", "kind": "function",
"path": "mail_intake.ingestion.reader.MailIntakeReader.iter_threads", "path": "mail_intake.ingestion.reader.MailIntakeReader.iter_threads",
"signature": "<bound method Function.signature of Function('iter_threads', 82, 120)>", "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\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."
} }
} }
} }
@@ -1558,25 +1509,11 @@
"signature": "<bound method Alias.signature of Alias('datetime', 'datetime.datetime')>", "signature": "<bound method Alias.signature of Alias('datetime', 'datetime.datetime')>",
"docstring": null "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": { "MailIntakeMessage": {
"name": "MailIntakeMessage", "name": "MailIntakeMessage",
"kind": "class", "kind": "class",
"path": "mail_intake.models.message.MailIntakeMessage", "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.", "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": { "members": {
"message_id": { "message_id": {
@@ -1674,20 +1611,6 @@
"signature": "<bound method Alias.signature of Alias('datetime', 'datetime.datetime')>", "signature": "<bound method Alias.signature of Alias('datetime', 'datetime.datetime')>",
"docstring": null "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": { "MailIntakeMessage": {
"name": "MailIntakeMessage", "name": "MailIntakeMessage",
"kind": "class", "kind": "class",
@@ -1764,7 +1687,7 @@
"name": "MailIntakeThread", "name": "MailIntakeThread",
"kind": "class", "kind": "class",
"path": "mail_intake.models.thread.MailIntakeThread", "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.", "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": { "members": {
"thread_id": { "thread_id": {
@@ -1806,17 +1729,10 @@
"name": "add_message", "name": "add_message",
"kind": "function", "kind": "function",
"path": "mail_intake.models.thread.MailIntakeThread.add_message", "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." "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", "kind": "function",
"path": "mail_intake.parsers.extract_body", "path": "mail_intake.parsers.extract_body",
"signature": "<bound method Alias.signature of Alias('extract_body', 'mail_intake.parsers.body.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": { "parse_headers": {
"name": "parse_headers", "name": "parse_headers",
"kind": "function", "kind": "function",
"path": "mail_intake.parsers.parse_headers", "path": "mail_intake.parsers.parse_headers",
"signature": "<bound method Alias.signature of Alias('parse_headers', 'mail_intake.parsers.headers.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": { "extract_sender": {
"name": "extract_sender", "name": "extract_sender",
"kind": "function", "kind": "function",
"path": "mail_intake.parsers.extract_sender", "path": "mail_intake.parsers.extract_sender",
"signature": "<bound method Alias.signature of Alias('extract_sender', 'mail_intake.parsers.headers.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": { "normalize_subject": {
"name": "normalize_subject", "name": "normalize_subject",
@@ -1871,13 +1787,6 @@
"signature": "<bound method Alias.signature of Alias('base64', 'base64')>", "signature": "<bound method Alias.signature of Alias('base64', 'base64')>",
"docstring": null "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": { "Any": {
"name": "Any", "name": "Any",
"kind": "alias", "kind": "alias",
@@ -1885,13 +1794,6 @@
"signature": "<bound method Alias.signature of Alias('Any', 'typing.Any')>", "signature": "<bound method Alias.signature of Alias('Any', 'typing.Any')>",
"docstring": null "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": { "BeautifulSoup": {
"name": "BeautifulSoup", "name": "BeautifulSoup",
"kind": "alias", "kind": "alias",
@@ -1911,7 +1813,7 @@
"kind": "function", "kind": "function",
"path": "mail_intake.parsers.body.extract_body", "path": "mail_intake.parsers.body.extract_body",
"signature": "<bound method Function.signature of Function('extract_body', 85, 133)>", "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, "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.", "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": { "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": { "parse_headers": {
"name": "parse_headers", "name": "parse_headers",
"kind": "function", "kind": "function",
"path": "mail_intake.parsers.headers.parse_headers", "path": "mail_intake.parsers.headers.parse_headers",
"signature": "<bound method Function.signature of Function('parse_headers', 16, 64)>", "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 ```" "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": { "extract_sender": {
"name": "extract_sender", "name": "extract_sender",
"kind": "function", "kind": "function",
"path": "mail_intake.parsers.headers.extract_sender", "path": "mail_intake.parsers.headers.extract_sender",
"signature": "<bound method Function.signature of Function('extract_sender', 67, 102)>", "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, 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)`"
} }
} }
}, },
@@ -1984,7 +1858,7 @@
"name": "normalize_subject", "name": "normalize_subject",
"kind": "function", "kind": "function",
"path": "mail_intake.parsers.subject.normalize_subject", "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." "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')>", "signature": "<bound method Alias.signature of Alias('datetime', 'datetime.datetime')>",
"docstring": null "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": { "MailIntakeMessage": {
"name": "MailIntakeMessage", "name": "MailIntakeMessage",
"kind": "class", "kind": "class",
"path": "mail_intake.models.message.MailIntakeMessage", "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.", "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": { "members": {
"message_id": { "message_id": {
@@ -264,20 +250,6 @@
"signature": "<bound method Alias.signature of Alias('datetime', 'datetime.datetime')>", "signature": "<bound method Alias.signature of Alias('datetime', 'datetime.datetime')>",
"docstring": null "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": { "MailIntakeMessage": {
"name": "MailIntakeMessage", "name": "MailIntakeMessage",
"kind": "class", "kind": "class",
@@ -354,7 +326,7 @@
"name": "MailIntakeThread", "name": "MailIntakeThread",
"kind": "class", "kind": "class",
"path": "mail_intake.models.thread.MailIntakeThread", "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.", "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": { "members": {
"thread_id": { "thread_id": {
@@ -396,17 +368,10 @@
"name": "add_message", "name": "add_message",
"kind": "function", "kind": "function",
"path": "mail_intake.models.thread.MailIntakeThread.add_message", "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." "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')>", "signature": "<bound method Alias.signature of Alias('datetime', 'datetime.datetime')>",
"docstring": null "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": { "MailIntakeMessage": {
"name": "MailIntakeMessage", "name": "MailIntakeMessage",
"kind": "class", "kind": "class",
"path": "mail_intake.models.message.MailIntakeMessage", "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.", "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": { "members": {
"message_id": { "message_id": {

View File

@@ -25,20 +25,6 @@
"signature": "<bound method Alias.signature of Alias('datetime', 'datetime.datetime')>", "signature": "<bound method Alias.signature of Alias('datetime', 'datetime.datetime')>",
"docstring": null "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": { "MailIntakeMessage": {
"name": "MailIntakeMessage", "name": "MailIntakeMessage",
"kind": "class", "kind": "class",
@@ -115,7 +101,7 @@
"name": "MailIntakeThread", "name": "MailIntakeThread",
"kind": "class", "kind": "class",
"path": "mail_intake.models.thread.MailIntakeThread", "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.", "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": { "members": {
"thread_id": { "thread_id": {
@@ -157,17 +143,10 @@
"name": "add_message", "name": "add_message",
"kind": "function", "kind": "function",
"path": "mail_intake.models.thread.MailIntakeThread.add_message", "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." "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')>", "signature": "<bound method Alias.signature of Alias('base64', 'base64')>",
"docstring": null "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": { "Any": {
"name": "Any", "name": "Any",
"kind": "alias", "kind": "alias",
@@ -25,13 +18,6 @@
"signature": "<bound method Alias.signature of Alias('Any', 'typing.Any')>", "signature": "<bound method Alias.signature of Alias('Any', 'typing.Any')>",
"docstring": null "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": { "BeautifulSoup": {
"name": "BeautifulSoup", "name": "BeautifulSoup",
"kind": "alias", "kind": "alias",
@@ -51,7 +37,7 @@
"kind": "function", "kind": "function",
"path": "mail_intake.parsers.body.extract_body", "path": "mail_intake.parsers.body.extract_body",
"signature": "<bound method Function.signature of Function('extract_body', 85, 133)>", "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", "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.", "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": { "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": { "parse_headers": {
"name": "parse_headers", "name": "parse_headers",
"kind": "function", "kind": "function",
"path": "mail_intake.parsers.headers.parse_headers", "path": "mail_intake.parsers.headers.parse_headers",
"signature": "<bound method Function.signature of Function('parse_headers', 16, 64)>", "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 ```" "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": { "extract_sender": {
"name": "extract_sender", "name": "extract_sender",
"kind": "function", "kind": "function",
"path": "mail_intake.parsers.headers.extract_sender", "path": "mail_intake.parsers.headers.extract_sender",
"signature": "<bound method Function.signature of Function('extract_sender', 67, 102)>", "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, 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)`"
} }
} }
} }

View File

@@ -9,21 +9,21 @@
"kind": "function", "kind": "function",
"path": "mail_intake.parsers.extract_body", "path": "mail_intake.parsers.extract_body",
"signature": "<bound method Alias.signature of Alias('extract_body', 'mail_intake.parsers.body.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": { "parse_headers": {
"name": "parse_headers", "name": "parse_headers",
"kind": "function", "kind": "function",
"path": "mail_intake.parsers.parse_headers", "path": "mail_intake.parsers.parse_headers",
"signature": "<bound method Alias.signature of Alias('parse_headers', 'mail_intake.parsers.headers.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": { "extract_sender": {
"name": "extract_sender", "name": "extract_sender",
"kind": "function", "kind": "function",
"path": "mail_intake.parsers.extract_sender", "path": "mail_intake.parsers.extract_sender",
"signature": "<bound method Alias.signature of Alias('extract_sender', 'mail_intake.parsers.headers.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": { "normalize_subject": {
"name": "normalize_subject", "name": "normalize_subject",
@@ -46,13 +46,6 @@
"signature": "<bound method Alias.signature of Alias('base64', 'base64')>", "signature": "<bound method Alias.signature of Alias('base64', 'base64')>",
"docstring": null "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": { "Any": {
"name": "Any", "name": "Any",
"kind": "alias", "kind": "alias",
@@ -60,13 +53,6 @@
"signature": "<bound method Alias.signature of Alias('Any', 'typing.Any')>", "signature": "<bound method Alias.signature of Alias('Any', 'typing.Any')>",
"docstring": null "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": { "BeautifulSoup": {
"name": "BeautifulSoup", "name": "BeautifulSoup",
"kind": "alias", "kind": "alias",
@@ -86,7 +72,7 @@
"kind": "function", "kind": "function",
"path": "mail_intake.parsers.body.extract_body", "path": "mail_intake.parsers.body.extract_body",
"signature": "<bound method Function.signature of Function('extract_body', 85, 133)>", "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, "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.", "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": { "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": { "parse_headers": {
"name": "parse_headers", "name": "parse_headers",
"kind": "function", "kind": "function",
"path": "mail_intake.parsers.headers.parse_headers", "path": "mail_intake.parsers.headers.parse_headers",
"signature": "<bound method Function.signature of Function('parse_headers', 16, 64)>", "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 ```" "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": { "extract_sender": {
"name": "extract_sender", "name": "extract_sender",
"kind": "function", "kind": "function",
"path": "mail_intake.parsers.headers.extract_sender", "path": "mail_intake.parsers.headers.extract_sender",
"signature": "<bound method Function.signature of Function('extract_sender', 67, 102)>", "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, 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)`"
} }
} }
}, },
@@ -159,7 +117,7 @@
"name": "normalize_subject", "name": "normalize_subject",
"kind": "function", "kind": "function",
"path": "mail_intake.parsers.subject.normalize_subject", "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." "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", "name": "normalize_subject",
"kind": "function", "kind": "function",
"path": "mail_intake.parsers.subject.normalize_subject", "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." "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.highlight
- search.share - search.share
- search.suggest - search.suggest
plugins: icon:
- search logo: material/inbox
- mkdocstrings: repo: fontawesome/brands/github
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
markdown_extensions: markdown_extensions:
- pymdownx.superfences - pymdownx.superfences
- pymdownx.inlinehilite - pymdownx.inlinehilite
- pymdownx.snippets - pymdownx.snippets
- admonition - admonition
- pymdownx.details - pymdownx.details
- pymdownx.superfences
- pymdownx.highlight: - pymdownx.highlight:
linenums: true linenums: true
anchor_linenums: true anchor_linenums: true
@@ -62,7 +44,31 @@ markdown_extensions:
- pymdownx.caret - pymdownx.caret
- pymdownx.tilde - pymdownx.tilde
- pymdownx.mark - 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 site_name: mail_intake
docs_dir: lib
site_dir: ../site/lib
nav: nav:
- Home: index.md - Home: index.md
- Core API: - Core API:

View File

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

View File

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

View File

@@ -12,7 +12,8 @@ types or semantics should leak beyond implementations of this interface.
""" """
from abc import ABC, abstractmethod from abc import ABC, abstractmethod
from typing import Iterator, Dict, Any from collections.abc import Iterator
from typing import Any
class MailIntakeAdapter(ABC): class MailIntakeAdapter(ABC):
@@ -32,7 +33,7 @@ class MailIntakeAdapter(ABC):
""" """
@abstractmethod @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. Iterate over lightweight message references matching a query.
@@ -40,8 +41,12 @@ class MailIntakeAdapter(ABC):
query (str): query (str):
Provider-specific query string used to filter messages. Provider-specific query string used to filter messages.
Returns:
Iterator[dict[str, str]]:
An iterator over lightweight message reference dictionaries.
Yields: Yields:
Dict[str, str]: dict[str, str]:
Dictionaries containing message and thread identifiers. Dictionaries containing message and thread identifiers.
Notes: Notes:
@@ -63,7 +68,7 @@ class MailIntakeAdapter(ABC):
raise NotImplementedError raise NotImplementedError
@abstractmethod @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. Fetch a full raw message by message identifier.
@@ -72,13 +77,13 @@ class MailIntakeAdapter(ABC):
Provider-specific message identifier. Provider-specific message identifier.
Returns: Returns:
Dict[str, Any]: dict[str, Any]:
Provider-native message payload (e.g., Gmail message JSON structure). Provider-native message payload (e.g., Gmail message JSON structure).
""" """
raise NotImplementedError raise NotImplementedError
@abstractmethod @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. Fetch a full raw thread by thread identifier.
@@ -87,7 +92,7 @@ class MailIntakeAdapter(ABC):
Provider-specific thread identifier. Provider-specific thread identifier.
Returns: Returns:
Dict[str, Any]: dict[str, Any]:
Provider-native thread payload. Provider-native thread payload.
""" """
raise NotImplementedError raise NotImplementedError

View File

@@ -1,10 +1,11 @@
from abc import ABC, abstractmethod from abc import ABC, abstractmethod
from typing import Iterator, Dict, Any from collections.abc import Iterator
from typing import Any
class MailIntakeAdapter(ABC): class MailIntakeAdapter(ABC):
@abstractmethod @abstractmethod
def iter_message_refs(self, query: str) -> Iterator[Dict[str, str]]: ... def iter_message_refs(self, query: str) -> Iterator[dict[str, str]]: ...
@abstractmethod @abstractmethod
def fetch_message(self, message_id: str) -> Dict[str, Any]: ... def fetch_message(self, message_id: str) -> dict[str, Any]: ...
@abstractmethod @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. 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.discovery import build
from googleapiclient.errors import HttpError from googleapiclient.errors import HttpError
from mail_intake.adapters.base import MailIntakeAdapter from mail_intake.adapters.base import MailIntakeAdapter
from mail_intake.exceptions import MailIntakeAdapterError
from mail_intake.auth.base import MailIntakeAuthProvider from mail_intake.auth.base import MailIntakeAuthProvider
from mail_intake.exceptions import MailIntakeAdapterError
class MailIntakeGmailAdapter(MailIntakeAdapter): class MailIntakeGmailAdapter(MailIntakeAdapter):
@@ -71,10 +72,6 @@ class MailIntakeGmailAdapter(MailIntakeAdapter):
""" """
Lazily initialize and return the Gmail API service client. Lazily initialize and return the Gmail API service client.
Returns:
Any:
Initialized Gmail API service instance.
Raises: Raises:
MailIntakeAdapterError: MailIntakeAdapterError:
If the Gmail service cannot be initialized. If the Gmail service cannot be initialized.
@@ -89,7 +86,7 @@ class MailIntakeGmailAdapter(MailIntakeAdapter):
) from exc ) from exc
return self._service 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. Iterate over message references matching the query.
@@ -98,7 +95,7 @@ class MailIntakeGmailAdapter(MailIntakeAdapter):
Gmail search query string. Gmail search query string.
Yields: Yields:
Dict[str, str]: dict[str, str]:
Dictionaries containing ``message_id`` and ``thread_id``. Dictionaries containing ``message_id`` and ``thread_id``.
Raises: Raises:
@@ -107,9 +104,7 @@ class MailIntakeGmailAdapter(MailIntakeAdapter):
""" """
try: try:
request = ( request = (
self.service.users() self.service.users().messages().list(userId=self._user_id, q=query)
.messages()
.list(userId=self._user_id, q=query)
) )
while request is not None: while request is not None:
@@ -121,18 +116,14 @@ class MailIntakeGmailAdapter(MailIntakeAdapter):
"thread_id": msg["threadId"], "thread_id": msg["threadId"],
} }
request = ( request = self.service.users().messages().list_next(request, response)
self.service.users()
.messages()
.list_next(request, response)
)
except HttpError as exc: except HttpError as exc:
raise MailIntakeAdapterError( raise MailIntakeAdapterError(
"Gmail API error while listing messages" "Gmail API error while listing messages"
) from exc ) 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. Fetch a full Gmail message by message ID.
@@ -141,7 +132,7 @@ class MailIntakeGmailAdapter(MailIntakeAdapter):
Gmail message identifier. Gmail message identifier.
Returns: Returns:
Dict[str, Any]: dict[str, Any]:
Provider-native Gmail message payload. Provider-native Gmail message payload.
Raises: Raises:
@@ -160,7 +151,7 @@ class MailIntakeGmailAdapter(MailIntakeAdapter):
f"Gmail API error while fetching message {message_id}" f"Gmail API error while fetching message {message_id}"
) from exc ) 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. Fetch a full Gmail thread by thread ID.
@@ -169,7 +160,7 @@ class MailIntakeGmailAdapter(MailIntakeAdapter):
Gmail thread identifier. Gmail thread identifier.
Returns: Returns:
Dict[str, Any]: dict[str, Any]:
Provider-native Gmail thread payload. Provider-native Gmail thread payload.
Raises: 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.adapters.base import MailIntakeAdapter
from mail_intake.auth.base import MailIntakeAuthProvider from mail_intake.auth.base import MailIntakeAuthProvider
class MailIntakeGmailAdapter(MailIntakeAdapter): 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 @property
def service(self) -> Any: ... def service(self) -> Any: ...
def iter_message_refs(self, query: str) -> Iterator[Dict[str, str]]: ... def iter_message_refs(self, query: str) -> Iterator[dict[str, str]]: ...
def fetch_message(self, message_id: str) -> Dict[str, Any]: ... def fetch_message(self, message_id: str) -> dict[str, Any]: ...
def fetch_thread(self, thread_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 import os
from typing import Sequence from collections.abc import Sequence
import google.auth.exceptions import google.auth.exceptions
from google.auth.transport.requests import Request from google.auth.transport.requests import Request
from google_auth_oauthlib.flow import InstalledAppFlow
from google.oauth2.credentials import Credentials from google.oauth2.credentials import Credentials
from google_auth_oauthlib.flow import InstalledAppFlow
from mail_intake.auth.base import MailIntakeAuthProvider from mail_intake.auth.base import MailIntakeAuthProvider
from mail_intake.credentials.store import CredentialStore 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.auth.base import MailIntakeAuthProvider
from mail_intake.credentials.store import CredentialStore from mail_intake.credentials.store import CredentialStore
class MailIntakeGoogleAuth(MailIntakeAuthProvider[Any]): 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: ... def get_credentials(self) -> Any: ...

View File

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

View File

@@ -1,9 +1,14 @@
from typing import Optional
class MailIntakeConfig: class MailIntakeConfig:
provider: str provider: str
user_id: str user_id: str
readonly: bool readonly: bool
credentials_path: Optional[str] credentials_path: str | None
token_path: Optional[str] token_path: str | None
def __init__(self, provider: str = ..., user_id: str = ..., readonly: bool = ..., credentials_path: Optional[str] = ..., token_path: Optional[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 .pickle import PickleCredentialStore
from .redis import RedisCredentialStore from .redis import RedisCredentialStore
from .store import CredentialStore
__all__ = ["CredentialStore", "PickleCredentialStore", "RedisCredentialStore"] __all__ = ["CredentialStore", "PickleCredentialStore", "RedisCredentialStore"]

View File

@@ -16,7 +16,7 @@ untrusted environments.
""" """
import pickle import pickle
from typing import Optional, TypeVar from typing import TypeVar
from mail_intake.credentials.store import CredentialStore from mail_intake.credentials.store import CredentialStore
@@ -55,12 +55,12 @@ class PickleCredentialStore(CredentialStore[T]):
""" """
self.path = path self.path = path
def load(self) -> Optional[T]: def load(self) -> T | None:
""" """
Load credentials from the local filesystem. Load credentials from the local filesystem.
Returns: Returns:
Optional[T]: T | None:
An instance of type `T` if credentials are present and An instance of type `T` if credentials are present and
successfully deserialized; otherwise `None`. successfully deserialized; otherwise `None`.

View File

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

View File

@@ -24,8 +24,8 @@ Credential validation, refresh, rotation, and acquisition remain the
responsibility of authentication provider implementations. responsibility of authentication provider implementations.
""" """
from collections.abc import Callable
from typing import Optional, TypeVar, Callable from typing import Any, TypeVar
from mail_intake.credentials.store import CredentialStore from mail_intake.credentials.store import CredentialStore
@@ -57,30 +57,27 @@ class RedisCredentialStore(CredentialStore[T]):
def __init__( def __init__(
self, self,
redis_client, redis_client: Any,
key: str, key: str,
serialize: Callable[[T], bytes], serialize: Callable[[T], bytes],
deserialize: Callable[[bytes], T], deserialize: Callable[[bytes], T],
ttl_seconds: Optional[int] = None, ttl_seconds: int | None = None,
): ):
""" """
Initialize a Redis-backed credential store. Initialize a Redis-backed credential store.
Args: Args:
redis_client (Any): 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): 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]): 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]): deserialize (Callable[[bytes], T]):
A callable that converts a ``bytes`` payload retrieved from Redis back into a credential object of type ``T``. Callable that decodes stored bytes back into credentials.
ttl_seconds (int | None):
ttl_seconds (Optional[int]): Optional time-to-live in seconds after which stored
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. credentials expire automatically. ``None`` disables expiry.
""" """
self.redis = redis_client self.redis = redis_client
self.key = key self.key = key
@@ -88,12 +85,12 @@ class RedisCredentialStore(CredentialStore[T]):
self.deserialize = deserialize self.deserialize = deserialize
self.ttl_seconds = ttl_seconds self.ttl_seconds = ttl_seconds
def load(self) -> Optional[T]: def load(self) -> T | None:
""" """
Load credentials from Redis. Load credentials from Redis.
Returns: Returns:
Optional[T]: T | None:
An instance of type `T` if credentials are present and An instance of type `T` if credentials are present and
successfully deserialized; otherwise `None`. 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 from .store import CredentialStore
T = TypeVar("T") T = TypeVar("T")
@@ -8,8 +10,15 @@ class RedisCredentialStore(CredentialStore[T]):
key: str key: str
serialize: Callable[[T], bytes] serialize: Callable[[T], bytes]
deserialize: Callable[[bytes], T] deserialize: Callable[[bytes], T]
ttl_seconds: Optional[int] ttl_seconds: int | None
def __init__(self, redis_client: Any, key: str, serialize: Callable[[T], bytes], deserialize: Callable[[bytes], T], ttl_seconds: Optional[int] = ...) -> None: ... def __init__(
def load(self) -> Optional[T]: ... 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 save(self, credentials: T) -> None: ...
def clear(self) -> None: ... def clear(self) -> None: ...

View File

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

View File

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

View File

@@ -1,10 +1,8 @@
""" """
# Summary
Exception hierarchy for Mail Intake. Exception hierarchy for Mail Intake.
---
## Summary
This module defines the **canonical exception types** used throughout the This module defines the **canonical exception types** used throughout the
Mail Intake library. Mail Intake library.

View File

@@ -16,16 +16,17 @@ It coordinates:
No provider-specific logic or API semantics are permitted in this layer. No provider-specific logic or API semantics are permitted in this layer.
""" """
from collections.abc import Iterator
from datetime import datetime from datetime import datetime
from typing import Iterator, Dict, Any from typing import Any
from mail_intake.adapters.base import MailIntakeAdapter from mail_intake.adapters.base import MailIntakeAdapter
from mail_intake.exceptions import MailIntakeParsingError
from mail_intake.models.message import MailIntakeMessage from mail_intake.models.message import MailIntakeMessage
from mail_intake.models.thread import MailIntakeThread 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.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.parsers.subject import normalize_subject
from mail_intake.exceptions import MailIntakeParsingError
class MailIntakeReader: class MailIntakeReader:
@@ -87,9 +88,9 @@ class MailIntakeReader:
query (str): query (str):
Provider-specific query string used to filter messages. Provider-specific query string used to filter messages.
Yields: Returns:
MailIntakeThread: Iterator[MailIntakeThread]:
An iterator of `MailIntakeThread` instances. An iterator over `MailIntakeThread` instances.
Raises: Raises:
`MailIntakeParsingError`: `MailIntakeParsingError`:
@@ -101,7 +102,7 @@ class MailIntakeReader:
- Messages are grouped by `thread_id` and yielded as complete - Messages are grouped by `thread_id` and yielded as complete
thread objects containing all associated messages. thread objects containing all associated messages.
""" """
threads: Dict[str, MailIntakeThread] = {} threads: dict[str, MailIntakeThread] = {}
for ref in self._adapter.iter_message_refs(query): for ref in self._adapter.iter_message_refs(query):
raw = self._adapter.fetch_message(ref["message_id"]) raw = self._adapter.fetch_message(ref["message_id"])
@@ -119,12 +120,12 @@ class MailIntakeReader:
return iter(threads.values()) 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`. Parse a raw provider message into a `MailIntakeMessage`.
Args: Args:
raw_message (Dict[str, Any]): raw_message (dict[str, Any]):
Provider-native message payload. Provider-native message payload.
Returns: 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.adapters.base import MailIntakeAdapter
from mail_intake.models.message import MailIntakeMessage from mail_intake.models.message import MailIntakeMessage
from mail_intake.models.thread import MailIntakeThread from mail_intake.models.thread import MailIntakeThread
@@ -7,4 +9,4 @@ class MailIntakeReader:
def __init__(self, adapter: MailIntakeAdapter) -> None: ... def __init__(self, adapter: MailIntakeAdapter) -> None: ...
def iter_messages(self, query: str) -> Iterator[MailIntakeMessage]: ... def iter_messages(self, query: str) -> Iterator[MailIntakeMessage]: ...
def iter_threads(self, query: str) -> Iterator[MailIntakeThread]: ... 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 dataclasses import dataclass
from datetime import datetime from datetime import datetime
from typing import Optional, Dict
@dataclass(frozen=True) @dataclass(frozen=True)
@@ -54,7 +53,7 @@ class MailIntakeMessage:
Sender email address. Sender email address.
""" """
from_name: Optional[str] from_name: str | None
""" """
Optional human-readable sender name. Optional human-readable sender name.
""" """
@@ -74,7 +73,7 @@ class MailIntakeMessage:
Short provider-supplied preview snippet of the message. 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). Normalized mapping of message headers (header name → value).
""" """

View File

@@ -1,14 +1,24 @@
from datetime import datetime from datetime import datetime
from typing import Optional, Dict
class MailIntakeMessage: class MailIntakeMessage:
message_id: str message_id: str
thread_id: str thread_id: str
timestamp: datetime timestamp: datetime
from_email: str from_email: str
from_name: Optional[str] from_name: str | None
subject: str subject: str
body_text: str body_text: str
snippet: str snippet: str
raw_headers: Dict[str, 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: ... 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 dataclasses import dataclass, field
from datetime import datetime from datetime import datetime
from typing import List, Set
from mail_intake.models.message import MailIntakeMessage from mail_intake.models.message import MailIntakeMessage
@@ -42,12 +41,12 @@ class MailIntakeThread:
Normalized subject line used to group related messages. 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. 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. Ordered list of messages belonging to this thread.
""" """

View File

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

View File

@@ -1,5 +1,5 @@
from .body import extract_body from .body import extract_body
from .headers import parse_headers, extract_sender from .headers import extract_sender, parse_headers
from .subject import normalize_subject from .subject import normalize_subject
__all__ = ["extract_body", "parse_headers", "extract_sender", "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 import base64
from typing import Dict, Any, Optional from typing import Any
from bs4 import BeautifulSoup from bs4 import BeautifulSoup
@@ -45,7 +45,7 @@ def _decode_base64(data: str) -> str:
raise MailIntakeParsingError("Failed to decode message body") from exc 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. 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) - `text/html` (converted to plain text)
Args: Args:
part (Dict[str, Any]): part (dict[str, Any]):
MIME part dictionary from a provider payload. MIME part dictionary from a provider payload.
Returns: Returns:
Optional[str]: str | None:
Extracted plain-text content, or `None` if unsupported or empty. Extracted plain-text content, or `None` if unsupported or empty.
""" """
mime_type = part.get("mimeType") mime_type = part.get("mimeType")
@@ -82,7 +82,7 @@ def _extract_from_part(part: Dict[str, Any]) -> Optional[str]:
return None 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. 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) 4. Empty string (if nothing usable found)
Args: Args:
payload (Dict[str, Any]): payload (dict[str, Any]):
Provider-native message payload dictionary. Provider-native message payload dictionary.
Returns: Returns:

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