resume_fromint
+ int | None
on_stepStepHook
+ StepHook | None
run_steps_async for async nodes.
resume_fromint
+ int | None
run_steps_async for async nodes.
on_stepAsyncStepHook
+ AsyncStepHook | None
statesTuple[State, ...]
+ tuple[State, ...]
Initialise StepResult.
+ + +Parameters:
+| Name | +Type | +Description | +Default | +
|---|---|---|---|
index |
+
+ int
+ |
+
+
+
+ Ordinal index of the step. + |
+ + required + | +
node_id |
+
+ str
+ |
+
+
+
+ Identifier of the node associated with this step. + |
+ + required + | +
states |
+
+ tuple[State, ...]
+ |
+
+
+
+ States produced by running this step. + |
+ + required + | +
completed |
+
+ bool
+ |
+
+
+
+ Whether this step succeeded (vs. paused/interrupted). + |
+ + required + | +
Tuple[Node, ...]: +
tuple[Node, ...]: Outgoing neighbors.
Tuple[Node, ...]: +
tuple[Node, ...]: All registered nodes.
Tuple[Node, ...]: +
tuple[Node, ...]: Incoming neighbors.
Tuple[Node, ...]: +
tuple[Node, ...]: Entry point nodes.
payload_updateMapping[str, Any]
+ Any
metadata_updateMapping[str, Any]
+ Any
resume_fromint
+ int | None
on_stepStepHook
+ StepHook | None
run_steps_async for async nodes.
resume_fromint
+ int | None
run_steps_async for async nodes.
on_stepAsyncStepHook
+ AsyncStepHook | None
run_steps_async for async nodes.
Tuple[Node, ...]: +
tuple[Node, ...]: Outgoing neighbors.
Tuple[Node, ...]: +
tuple[Node, ...]: All registered nodes.
Tuple[Node, ...]: +
tuple[Node, ...]: Incoming neighbors.
Tuple[Node, ...]: +
tuple[Node, ...]: Entry point nodes.
payload_updateMapping[str, Any]
+ Any
metadata_updateMapping[str, Any]
+ Any
Yields:
+Returns:
| Name | Type | +Type | Description |
|---|---|---|---|
State | + |
Iterable[State]
|
-
Derived execution state(s). +Iterable[State]: +Derived execution state(s). |
Returns:
+Yields:
| Type | +Name | Type | Description | ||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| + | str |
Iterable[str]
|
-
Iterable[str]: -Generator yielding dot-paths. +Dot-path for each leaf node. |
||||||||||||
payload_override |
- Mapping[str, Any]
+ Mapping[str, Any] | None
|
@@ -5224,7 +5239,7 @@ callers can surface counts/lines/errors without coupling the engine to pydantic.
payload_update
- |
Mapping[str, Any]
+ Mapping[str, Any] | None
|
@@ -5252,7 +5267,7 @@ callers can surface counts/lines/errors without coupling the engine to pydantic.
node_id
- |
str
+ str | None
|
@@ -5266,7 +5281,7 @@ callers can surface counts/lines/errors without coupling the engine to pydantic.
metadata_update
- |
Mapping[str, Any]
+ Mapping[str, Any] | None
|
@@ -5505,7 +5520,7 @@ callers can surface counts/lines/errors without coupling the engine to pydantic.
|
@@ -5588,7 +5603,7 @@ Ordered execution lineage (root first).
-
Tuple[State, ...]: + tuple[State, ...]: Ordered execution lineage (root first). states
- |
Tuple[State, ...]
+ tuple[State, ...]
|
@@ -5610,6 +5625,79 @@ Ordered execution lineage (root first).
|
Initialise StepResult.
+ + +Parameters:
+| Name | +Type | +Description | +Default | +
|---|---|---|---|
index |
+
+ int
+ |
+
+
+
+ Ordinal index of the step. + |
+ + required + | +
node_id |
+
+ str
+ |
+
+
+
+ Identifier of the node associated with this step. + |
+ + required + | +
states |
+
+ tuple[State, ...]
+ |
+
+
+
+ States produced by running this step. + |
+ + required + | +
completed |
+
+ bool
+ |
+
+
+
+ Whether this step succeeded (vs. paused/interrupted). + |
+ + required + | +
payload_updateMapping[str, Any]
+ Any
metadata_updateMapping[str, Any]
+ Any
payload_updateMapping[str, Any]
+ Any
metadata_updateMapping[str, Any]
+ Any
Yields:
+Returns:
| Name | Type | +Type | Description |
|---|---|---|---|
State | + |
Iterable[State]
|
-
Derived execution state(s). +Iterable[State]: +Derived execution state(s). |
Returns:
+Yields:
| Type | +Name | Type | Description | |||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| + | str |
Iterable[str]
|
-
Iterable[str]: -Generator yielding dot-paths. +Dot-path for each leaf node. |
|||||||||||||||||||||
payload_update |
- Mapping[str, Any]
+ Mapping[str, Any] | None
|
@@ -1978,7 +1977,7 @@ Iterator over top-level keys.
node_id
- |
str
+ str | None
|
@@ -1992,7 +1991,7 @@ Iterator over top-level keys.
metadata_update
- |
Mapping[str, Any]
+ Mapping[str, Any] | None
|
@@ -2231,7 +2230,7 @@ Iterator over top-level keys.
|
diff --git a/dagpipe/lib/dagpipe/yaml_loader/index.html b/dagpipe/lib/dagpipe/yaml_loader/index.html
index 85eb374..a5f1eb8 100644
--- a/dagpipe/lib/dagpipe/yaml_loader/index.html
+++ b/dagpipe/lib/dagpipe/yaml_loader/index.html
@@ -943,7 +943,7 @@ and initial payloads.
-
Tuple[State, ...]: + tuple[State, ...]: Ordered execution lineage (root first). payload_override
- |
Mapping[str, Any]
+ Mapping[str, Any] | None
|
diff --git a/dagpipe/lib/engine/index.html b/dagpipe/lib/engine/index.html
index 2fe9d55..ad01711 100644
--- a/dagpipe/lib/engine/index.html
+++ b/dagpipe/lib/engine/index.html
@@ -737,6 +737,21 @@
+
+
@@ -1023,6 +1038,21 @@
+
+
@@ -1497,7 +1527,7 @@ are both supported.
resume_from
- |
int
+ int | None
|
@@ -1512,7 +1542,7 @@ Steps are 0-indexed.
on_step
- |
StepHook
+ StepHook | None
|
@@ -1619,7 +1649,7 @@ orchestrator. Use run_steps_async for async nodes.
resume_from
- |
int
+ int | None
|
@@ -1633,7 +1663,7 @@ orchestrator. Use run_steps_async for async nodes.
on_step
- |
AsyncStepHook
+ AsyncStepHook | None
| |
Initialise StepResult.
+ + +Parameters:
+| Name | +Type | +Description | +Default | +
|---|---|---|---|
index |
+
+ int
+ |
+
+
+
+ Ordinal index of the step. + |
+ + required + | +
node_id |
+
+ str
+ |
+
+
+
+ Identifier of the node associated with this step. + |
+ + required + | +
states |
+
+ tuple[State, ...]
+ |
+
+
+
+ States produced by running this step. + |
+ + required + | +
completed |
+
+ bool
+ |
+
+
+
+ Whether this step succeeded (vs. paused/interrupted). + |
+ + required + | +
Tuple[Node, ...]: +
tuple[Node, ...]: Outgoing neighbors.
Tuple[Node, ...]: +
tuple[Node, ...]: All registered nodes.
Tuple[Node, ...]: +
tuple[Node, ...]: Incoming neighbors.
Tuple[Node, ...]: +
tuple[Node, ...]: Entry point nodes.
payload_updateMapping[str, Any]
+ Any
metadata_updateMapping[str, Any]
+ Any
resume_fromint
+ int | None
on_stepStepHook
+ StepHook | None
run_steps_async for async nodes.
resume_fromint
+ int | None
run_steps_async for async nodes.
on_stepAsyncStepHook
+ AsyncStepHook | None
run_steps_async for async nodes.
Tuple[Node, ...]: +
tuple[Node, ...]: Outgoing neighbors.
Tuple[Node, ...]: +
tuple[Node, ...]: All registered nodes.
Tuple[Node, ...]: +
tuple[Node, ...]: Incoming neighbors.
Tuple[Node, ...]: +
tuple[Node, ...]: Entry point nodes.
payload_updateMapping[str, Any]
+ Any
metadata_updateMapping[str, Any]
+ Any
Yields:
+Returns:
| Name | Type | +Type | Description |
|---|---|---|---|
State | + |
Iterable[State]
|
-
Derived execution state(s). +Iterable[State]: +Derived execution state(s). |
Returns:
+Yields:
| Type | +Name | Type | Description | ||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| + | str |
Iterable[str]
|
-
Iterable[str]: -Generator yielding dot-paths. +Dot-path for each leaf node. |
||||||||||||
payload_override |
- Mapping[str, Any]
+ Mapping[str, Any] | None
|
@@ -6183,7 +6213,7 @@ callers can surface counts/lines/errors without coupling the engine to pydantic.
payload_update
- |
Mapping[str, Any]
+ Mapping[str, Any] | None
|
@@ -6211,7 +6241,7 @@ callers can surface counts/lines/errors without coupling the engine to pydantic.
node_id
- |
str
+ str | None
|
@@ -6225,7 +6255,7 @@ callers can surface counts/lines/errors without coupling the engine to pydantic.
metadata_update
- |
Mapping[str, Any]
+ Mapping[str, Any] | None
|
@@ -6464,7 +6494,7 @@ callers can surface counts/lines/errors without coupling the engine to pydantic.
|
@@ -6547,7 +6577,7 @@ Ordered execution lineage (root first).
-
Tuple[State, ...]: + tuple[State, ...]: Ordered execution lineage (root first). states
- |
Tuple[State, ...]
+ tuple[State, ...]
|
@@ -6569,6 +6599,79 @@ Ordered execution lineage (root first).
|
Initialise StepResult.
+ + +Parameters:
+| Name | +Type | +Description | +Default | +
|---|---|---|---|
index |
+
+ int
+ |
+
+
+
+ Ordinal index of the step. + |
+ + required + | +
node_id |
+
+ str
+ |
+
+
+
+ Identifier of the node associated with this step. + |
+ + required + | +
states |
+
+ tuple[State, ...]
+ |
+
+
+
+ States produced by running this step. + |
+ + required + | +
completed |
+
+ bool
+ |
+
+
+
+ Whether this step succeeded (vs. paused/interrupted). + |
+ + required + | +
payload_updateMapping[str, Any]
+ Any
metadata_updateMapping[str, Any]
+ Any
payload_updateMapping[str, Any]
+ Any
metadata_updateMapping[str, Any]
+ Any
Yields:
+Returns:
| Name | Type | +Type | Description |
|---|---|---|---|
State | + |
Iterable[State]
|
-
Derived execution state(s). +Iterable[State]: +Derived execution state(s). |
Returns:
+Yields:
| Type | +Name | Type | Description | |||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|
| + | str |
Iterable[str]
|
-
Iterable[str]: -Generator yielding dot-paths. +Dot-path for each leaf node. |
|||||||||
payload_update |
- Mapping[str, Any]
+ Mapping[str, Any] | None
|
@@ -2303,7 +2302,7 @@ Iterator over top-level keys.
node_id
- |
str
+ str | None
|
@@ -2317,7 +2316,7 @@ Iterator over top-level keys.
metadata_update
- |
Mapping[str, Any]
+ Mapping[str, Any] | None
|
@@ -2556,7 +2555,7 @@ Iterator over top-level keys.
|
diff --git a/dagpipe/lib/yaml_loader/index.html b/dagpipe/lib/yaml_loader/index.html
index 4ed4dae..35291f2 100644
--- a/dagpipe/lib/yaml_loader/index.html
+++ b/dagpipe/lib/yaml_loader/index.html
@@ -1089,7 +1089,7 @@ and initial payloads.
-
Tuple[State, ...]: + tuple[State, ...]: Ordered execution lineage (root first). payload_override
- |
Mapping[str, Any]
+ Mapping[str, Any] | None
|
diff --git a/mail-intake/lib/credentials/index.html b/mail-intake/lib/credentials/index.html
index fbc0e40..7a07da3 100644
--- a/mail-intake/lib/credentials/index.html
+++ b/mail-intake/lib/credentials/index.html
@@ -2112,10 +2112,92 @@ must be shared across multiple processes or nodes.
|
Initialize a Redis-backed credential store.
-Callers supply all runtime dependencies: redis_client is an
-initialized Redis client instance, key names the storage key,
-serialize/deserialize are the encoding and decoding callables,
-and ttl_seconds optionally limits credential lifetime.
Parameters:
+| Name | +Type | +Description | +Default | +
|---|---|---|---|
redis_client |
+
+ Any
+ |
+
+
+
+ Initialized Redis client instance used for persistence. + |
+ + required + | +
key |
+
+ str
+ |
+
+
+
+ Storage key under which credentials are persisted. + |
+ + required + | +
serialize |
+
+ Callable[[T], bytes]
+ |
+
+
+
+ Callable that encodes credentials to bytes for storage. + |
+ + required + | +
deserialize |
+
+ Callable[[bytes], T]
+ |
+
+
+
+ Callable that decodes stored bytes back into credentials. + |
+ + required + | +
ttl_seconds |
+
+ int | None
+ |
+
+
+
+ Optional time-to-live in seconds after which stored
+credentials expire automatically. |
+
+ None
+ |
+
Initialize a Redis-backed credential store.
-Callers supply all runtime dependencies: redis_client is an
-initialized Redis client instance, key names the storage key,
-serialize/deserialize are the encoding and decoding callables,
-and ttl_seconds optionally limits credential lifetime.
Parameters:
+| Name | +Type | +Description | +Default | +
|---|---|---|---|
redis_client |
+
+ Any
+ |
+
+
+
+ Initialized Redis client instance used for persistence. + |
+ + required + | +
key |
+
+ str
+ |
+
+
+
+ Storage key under which credentials are persisted. + |
+ + required + | +
serialize |
+
+ Callable[[T], bytes]
+ |
+
+
+
+ Callable that encodes credentials to bytes for storage. + |
+ + required + | +
deserialize |
+
+ Callable[[bytes], T]
+ |
+
+
+
+ Callable that decodes stored bytes back into credentials. + |
+ + required + | +
ttl_seconds |
+
+ int | None
+ |
+
+
+
+ Optional time-to-live in seconds after which stored
+credentials expire automatically. |
+
+ None
+ |
+
Initialize a Redis-backed credential store.
-Callers supply all runtime dependencies: redis_client is an
-initialized Redis client instance, key names the storage key,
-serialize/deserialize are the encoding and decoding callables,
-and ttl_seconds optionally limits credential lifetime.
Parameters:
+| Name | +Type | +Description | +Default | +
|---|---|---|---|
redis_client |
+
+ Any
+ |
+
+
+
+ Initialized Redis client instance used for persistence. + |
+ + required + | +
key |
+
+ str
+ |
+
+
+
+ Storage key under which credentials are persisted. + |
+ + required + | +
serialize |
+
+ Callable[[T], bytes]
+ |
+
+
+
+ Callable that encodes credentials to bytes for storage. + |
+ + required + | +
deserialize |
+
+ Callable[[bytes], T]
+ |
+
+
+
+ Callable that decodes stored bytes back into credentials. + |
+ + required + | +
ttl_seconds |
+
+ int | None
+ |
+
+
+
+ Optional time-to-live in seconds after which stored
+credentials expire automatically. |
+
+ None
+ |
+
Initialize a Redis-backed credential store.
-Callers supply all runtime dependencies: redis_client is an
-initialized Redis client instance, key names the storage key,
-serialize/deserialize are the encoding and decoding callables,
-and ttl_seconds optionally limits credential lifetime.
Parameters:
+| Name | +Type | +Description | +Default | +
|---|---|---|---|
redis_client |
+
+ Any
+ |
+
+
+
+ Initialized Redis client instance used for persistence. + |
+ + required + | +
key |
+
+ str
+ |
+
+
+
+ Storage key under which credentials are persisted. + |
+ + required + | +
serialize |
+
+ Callable[[T], bytes]
+ |
+
+
+
+ Callable that encodes credentials to bytes for storage. + |
+ + required + | +
deserialize |
+
+ Callable[[bytes], T]
+ |
+
+
+
+ Callable that decodes stored bytes back into credentials. + |
+ + required + | +
ttl_seconds |
+
+ int | None
+ |
+
+
+
+ Optional time-to-live in seconds after which stored
+credentials expire automatically. |
+
+ None
+ |
+
Mail Intake \u2014 provider-agnostic, read-only email ingestion framework.
Mail Intake is a contract-first library designed to ingest, parse, and normalize email data from external providers (such as Gmail) into clean, provider-agnostic domain models.
The library is intentionally structured around clear layers, each exposed as a first-class module at the package root:
adapters: Provider-specific access (e.g., Gmail).auth: Authentication providers and credential lifecycle management.credentials: Credential persistence abstractions and implementations.parsers: Extraction and normalization of message content.ingestion: Orchestration and high-level ingestion workflows.models: Canonical, provider-agnostic data representations.config: Explicit global configuration.exceptions: Library-defined error hierarchy.The package root acts as a namespace, not a facade. Consumers are expected to import functionality explicitly from the appropriate module.
"},{"location":"#mail_intake--installation","title":"Installation","text":"Install using pip:
pip install mail-intake\nOr with Poetry:
poetry add mail-intake\nMail Intake is pure Python and has no runtime dependencies beyond those required by the selected provider (for example, Google APIs for Gmail).
"},{"location":"#mail_intake--quick-start","title":"Quick Start","text":"Minimal Gmail ingestion example (local development):
from mail_intake.ingestion import MailIntakeReader\nfrom mail_intake.adapters import MailIntakeGmailAdapter\nfrom mail_intake.auth import MailIntakeGoogleAuth\nfrom mail_intake.credentials import PickleCredentialStore\n\nstore = PickleCredentialStore(path=\"token.pickle\")\n\nauth = MailIntakeGoogleAuth(\n credentials_path=\"credentials.json\",\n store=store,\n scopes=[\"https://www.googleapis.com/auth/gmail.readonly\"],\n)\n\nadapter = MailIntakeGmailAdapter(auth_provider=auth)\nreader = MailIntakeReader(adapter)\n\nfor message in reader.iter_messages(\"from:recruiter@example.com\"):\n print(message.subject, message.from_email)\nIterating over threads:
for thread in reader.iter_threads(\"subject:Interview\"):\n print(thread.normalized_subject, len(thread.messages))\nMail Intake is designed to be extensible via public contracts exposed through its modules:
adapters.MailIntakeAdapter.auth.MailIntakeAuthProvider[T].credentials.CredentialStore[T].Users SHOULD NOT subclass built-in adapter implementations. Built-in adapters (such as Gmail) are reference implementations and may change internally without notice.
Design Guarantees:
Mail Intake favors correctness, clarity, and explicitness over convenience shortcuts.
Core Philosophy:
Mail Intake is built as a contract-first ingestion pipeline:
The supported public API consists of the following top-level modules:
mail_intake.ingestionmail_intake.adaptersmail_intake.authmail_intake.credentialsmail_intake.parsersmail_intake.modelsmail_intake.configmail_intake.exceptionsClasses and functions should be imported explicitly from these modules. No individual symbols are re-exported at the package root.
"},{"location":"config/","title":"Config","text":""},{"location":"config/#mail_intake.config","title":"mail_intake.config","text":""},{"location":"config/#mail_intake.config--summary","title":"Summary","text":"Global configuration models for Mail Intake.
This module defines the top-level configuration object used to control mail ingestion behavior across adapters, authentication providers, and ingestion workflows.
Configuration is intentionally explicit, immutable, and free of implicit environment reads to ensure predictability and testability.
"},{"location":"config/#mail_intake.config-classes","title":"Classes","text":""},{"location":"config/#mail_intake.config.MailIntakeConfig","title":"MailIntakeConfigdataclass","text":"MailIntakeConfig(\n provider: str = ...,\n user_id: str = ...,\n readonly: bool = ...,\n credentials_path: str | None = ...,\n token_path: str | None = ...,\n)\nGlobal configuration for mail-intake.
Guarantees:
- 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.\nclass-attribute instance-attribute","text":"credentials_path: str | None = None\nOptional path to provider credentials configuration.
"},{"location":"config/#mail_intake.config.MailIntakeConfig.provider","title":"providerclass-attribute instance-attribute","text":"provider: str = 'gmail'\nIdentifier of the mail provider to use (e.g., \"gmail\").
class-attribute instance-attribute","text":"readonly: bool = True\nWhether ingestion should operate in read-only mode.
"},{"location":"config/#mail_intake.config.MailIntakeConfig.token_path","title":"token_pathclass-attribute instance-attribute","text":"token_path: str | None = None\nOptional path to persisted authentication tokens.
"},{"location":"config/#mail_intake.config.MailIntakeConfig.user_id","title":"user_idclass-attribute instance-attribute","text":"user_id: str = 'me'\nProvider-specific user identifier. Defaults to the authenticated user.
"},{"location":"exceptions/","title":"Exceptions","text":""},{"location":"exceptions/#mail_intake.exceptions","title":"mail_intake.exceptions","text":""},{"location":"exceptions/#mail_intake.exceptions--summary","title":"Summary","text":"Exception hierarchy for Mail Intake.
This module defines the canonical exception types used throughout the Mail Intake library.
All library-raised errors derive from MailIntakeError. Consumers are encouraged to catch this base type (or specific subclasses) rather than provider-specific or third-party exceptions.
Bases: MailIntakeError
Errors raised by mail provider adapters.
NotesLifecycle:
- Raised when a provider adapter encounters API errors, transport\n failures, or invalid provider responses.\n Bases: MailIntakeError
Authentication and credential-related failures.
NotesLifecycle:
- Raised when authentication providers are unable to acquire,\n refresh, or persist valid credentials.\n Bases: Exception
Base exception for all Mail Intake errors.
NotesGuarantees:
- 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\n Bases: MailIntakeError
Errors encountered while parsing message content.
NotesLifecycle:
- Raised when raw provider payloads cannot be interpreted or\n normalized into internal domain models.\nMail provider adapter implementations for Mail Intake.
This package contains adapter-layer implementations responsible for interfacing with external mail providers and exposing a normalized, provider-agnostic contract to the rest of the system.
Adapters in this package:
MailIntakeAdapter interface.Provider-specific logic must not leak outside of adapter implementations. All parsings, normalizations, and transformations must be handled by downstream components.
"},{"location":"adapters/#mail_intake.adapters--public-api","title":"Public API","text":"MailIntakeAdapterMailIntakeGmailAdapter Bases: ABC
Base adapter interface for mail providers.
NotesGuarantees:
- Discover messages matching a query.\n- Retrieve full message payloads.\n- Retrieve full thread payloads.\nLifecycle:
- Adapters are intentionally read-only and must not mutate provider state.\nabstractmethod","text":"fetch_message(message_id: str) -> dict[str, Any]\nFetch a full raw message by message identifier.
Parameters:
Name Type Description Defaultmessage_id str Provider-specific message identifier.
requiredReturns:
Type Descriptiondict[str, Any] dict[str, Any]: Provider-native message payload (e.g., Gmail message JSON structure).
"},{"location":"adapters/#mail_intake.adapters.MailIntakeAdapter.fetch_thread","title":"fetch_threadabstractmethod","text":"fetch_thread(thread_id: str) -> dict[str, Any]\nFetch a full raw thread by thread identifier.
Parameters:
Name Type Description Defaultthread_id str Provider-specific thread identifier.
requiredReturns:
Type Descriptiondict[str, Any] dict[str, Any]: Provider-native thread payload.
"},{"location":"adapters/#mail_intake.adapters.MailIntakeAdapter.iter_message_refs","title":"iter_message_refsabstractmethod","text":"iter_message_refs(query: str) -> Iterator[dict[str, str]]\nIterate over lightweight message references matching a query.
Parameters:
Name Type Description Defaultquery str Provider-specific query string used to filter messages.
requiredReturns:
Type DescriptionIterator[dict[str, str]] Iterator[dict[str, str]]: An iterator over lightweight message reference dictionaries.
Yields:
Type Descriptiondict[str, str] dict[str, str]: Dictionaries containing message and thread identifiers.
NotesGuarantees:
- Implementations must yield dictionaries containing at least\n `message_id` and `thread_id`.\nTypical yield:
{\n \"message_id\": \"...\",\n \"thread_id\": \"...\"\n}\nMailIntakeGmailAdapter(\n auth_provider: MailIntakeAuthProvider[Any],\n user_id: str = \"me\",\n)\n Bases: MailIntakeAdapter
Gmail read-only adapter.
This adapter implements the MailIntakeAdapter interface using the Gmail REST API. It translates the generic mail intake contract into Gmail-specific API calls.
Responsibilities:
- This class is the ONLY place where `googleapiclient` is imported.\n- Gmail REST semantics are known.\n- `.execute()` is called.\nConstraints:
- Must remain thin and imperative.\n- Must not perform parsing or interpretation.\n- Must not expose Gmail-specific types beyond this class.\nInitialize the Gmail adapter.
Parameters:
Name Type Description Defaultauth_provider MailIntakeAuthProvider Authentication provider capable of supplying valid Gmail API credentials.
requireduser_id str Gmail user identifier. Defaults to \"me\".
'me'"},{"location":"adapters/#mail_intake.adapters.MailIntakeGmailAdapter-attributes","title":"Attributes","text":""},{"location":"adapters/#mail_intake.adapters.MailIntakeGmailAdapter.service","title":"service property","text":"service: Any\nLazily initialize and return the Gmail API service client.
Raises:
Type DescriptionMailIntakeAdapterError If the Gmail service cannot be initialized.
"},{"location":"adapters/#mail_intake.adapters.MailIntakeGmailAdapter-functions","title":"Functions","text":""},{"location":"adapters/#mail_intake.adapters.MailIntakeGmailAdapter.fetch_message","title":"fetch_message","text":"fetch_message(message_id: str) -> dict[str, Any]\nFetch a full Gmail message by message ID.
Parameters:
Name Type Description Defaultmessage_id str Gmail message identifier.
requiredReturns:
Type Descriptiondict[str, Any] dict[str, Any]: Provider-native Gmail message payload.
Raises:
Type DescriptionMailIntakeAdapterError If the Gmail API returns an error.
"},{"location":"adapters/#mail_intake.adapters.MailIntakeGmailAdapter.fetch_thread","title":"fetch_thread","text":"fetch_thread(thread_id: str) -> dict[str, Any]\nFetch a full Gmail thread by thread ID.
Parameters:
Name Type Description Defaultthread_id str Gmail thread identifier.
requiredReturns:
Type Descriptiondict[str, Any] dict[str, Any]: Provider-native Gmail thread payload.
Raises:
Type DescriptionMailIntakeAdapterError If the Gmail API returns an error.
"},{"location":"adapters/#mail_intake.adapters.MailIntakeGmailAdapter.iter_message_refs","title":"iter_message_refs","text":"iter_message_refs(query: str) -> Iterator[dict[str, str]]\nIterate over message references matching the query.
Parameters:
Name Type Description Defaultquery str Gmail search query string.
requiredYields:
Type Descriptiondict[str, str] dict[str, str]: Dictionaries containing message_id and thread_id.
Raises:
Type DescriptionMailIntakeAdapterError If the Gmail API returns an error.
"},{"location":"adapters/base/","title":"Base","text":""},{"location":"adapters/base/#mail_intake.adapters.base","title":"mail_intake.adapters.base","text":""},{"location":"adapters/base/#mail_intake.adapters.base--summary","title":"Summary","text":"Mail provider adapter contracts for Mail Intake.
This module defines the provider-agnostic adapter interface used for read-only mail ingestion.
Adapters encapsulate all provider-specific access logic and expose a minimal, normalized contract to the rest of the system. No provider-specific types or semantics should leak beyond implementations of this interface.
"},{"location":"adapters/base/#mail_intake.adapters.base-classes","title":"Classes","text":""},{"location":"adapters/base/#mail_intake.adapters.base.MailIntakeAdapter","title":"MailIntakeAdapter","text":" Bases: ABC
Base adapter interface for mail providers.
NotesGuarantees:
- Discover messages matching a query.\n- Retrieve full message payloads.\n- Retrieve full thread payloads.\nLifecycle:
- Adapters are intentionally read-only and must not mutate provider state.\nabstractmethod","text":"fetch_message(message_id: str) -> dict[str, Any]\nFetch a full raw message by message identifier.
Parameters:
Name Type Description Defaultmessage_id str Provider-specific message identifier.
requiredReturns:
Type Descriptiondict[str, Any] dict[str, Any]: Provider-native message payload (e.g., Gmail message JSON structure).
"},{"location":"adapters/base/#mail_intake.adapters.base.MailIntakeAdapter.fetch_thread","title":"fetch_threadabstractmethod","text":"fetch_thread(thread_id: str) -> dict[str, Any]\nFetch a full raw thread by thread identifier.
Parameters:
Name Type Description Defaultthread_id str Provider-specific thread identifier.
requiredReturns:
Type Descriptiondict[str, Any] dict[str, Any]: Provider-native thread payload.
"},{"location":"adapters/base/#mail_intake.adapters.base.MailIntakeAdapter.iter_message_refs","title":"iter_message_refsabstractmethod","text":"iter_message_refs(query: str) -> Iterator[dict[str, str]]\nIterate over lightweight message references matching a query.
Parameters:
Name Type Description Defaultquery str Provider-specific query string used to filter messages.
requiredReturns:
Type DescriptionIterator[dict[str, str]] Iterator[dict[str, str]]: An iterator over lightweight message reference dictionaries.
Yields:
Type Descriptiondict[str, str] dict[str, str]: Dictionaries containing message and thread identifiers.
NotesGuarantees:
- Implementations must yield dictionaries containing at least\n `message_id` and `thread_id`.\nTypical yield:
{\n \"message_id\": \"...\",\n \"thread_id\": \"...\"\n}\nGmail adapter implementation for Mail Intake.
This module provides a Gmail-specific implementation of the MailIntakeAdapter contract.
It is the only place in the codebase where:
googleapiclient is imported..execute() calls are made.All Gmail-specific behavior must be strictly contained within this module.
"},{"location":"adapters/gmail/#mail_intake.adapters.gmail-classes","title":"Classes","text":""},{"location":"adapters/gmail/#mail_intake.adapters.gmail.MailIntakeGmailAdapter","title":"MailIntakeGmailAdapter","text":"MailIntakeGmailAdapter(\n auth_provider: MailIntakeAuthProvider[Any],\n user_id: str = \"me\",\n)\n Bases: MailIntakeAdapter
Gmail read-only adapter.
This adapter implements the MailIntakeAdapter interface using the Gmail REST API. It translates the generic mail intake contract into Gmail-specific API calls.
Responsibilities:
- This class is the ONLY place where `googleapiclient` is imported.\n- Gmail REST semantics are known.\n- `.execute()` is called.\nConstraints:
- Must remain thin and imperative.\n- Must not perform parsing or interpretation.\n- Must not expose Gmail-specific types beyond this class.\nInitialize the Gmail adapter.
Parameters:
Name Type Description Defaultauth_provider MailIntakeAuthProvider Authentication provider capable of supplying valid Gmail API credentials.
requireduser_id str Gmail user identifier. Defaults to \"me\".
'me'"},{"location":"adapters/gmail/#mail_intake.adapters.gmail.MailIntakeGmailAdapter-attributes","title":"Attributes","text":""},{"location":"adapters/gmail/#mail_intake.adapters.gmail.MailIntakeGmailAdapter.service","title":"service property","text":"service: Any\nLazily initialize and return the Gmail API service client.
Raises:
Type DescriptionMailIntakeAdapterError If the Gmail service cannot be initialized.
"},{"location":"adapters/gmail/#mail_intake.adapters.gmail.MailIntakeGmailAdapter-functions","title":"Functions","text":""},{"location":"adapters/gmail/#mail_intake.adapters.gmail.MailIntakeGmailAdapter.fetch_message","title":"fetch_message","text":"fetch_message(message_id: str) -> dict[str, Any]\nFetch a full Gmail message by message ID.
Parameters:
Name Type Description Defaultmessage_id str Gmail message identifier.
requiredReturns:
Type Descriptiondict[str, Any] dict[str, Any]: Provider-native Gmail message payload.
Raises:
Type DescriptionMailIntakeAdapterError If the Gmail API returns an error.
"},{"location":"adapters/gmail/#mail_intake.adapters.gmail.MailIntakeGmailAdapter.fetch_thread","title":"fetch_thread","text":"fetch_thread(thread_id: str) -> dict[str, Any]\nFetch a full Gmail thread by thread ID.
Parameters:
Name Type Description Defaultthread_id str Gmail thread identifier.
requiredReturns:
Type Descriptiondict[str, Any] dict[str, Any]: Provider-native Gmail thread payload.
Raises:
Type DescriptionMailIntakeAdapterError If the Gmail API returns an error.
"},{"location":"adapters/gmail/#mail_intake.adapters.gmail.MailIntakeGmailAdapter.iter_message_refs","title":"iter_message_refs","text":"iter_message_refs(query: str) -> Iterator[dict[str, str]]\nIterate over message references matching the query.
Parameters:
Name Type Description Defaultquery str Gmail search query string.
requiredYields:
Type Descriptiondict[str, str] dict[str, str]: Dictionaries containing message_id and thread_id.
Raises:
Type DescriptionMailIntakeAdapterError If the Gmail API returns an error.
"},{"location":"auth/","title":"Auth","text":""},{"location":"auth/#mail_intake.auth","title":"mail_intake.auth","text":""},{"location":"auth/#mail_intake.auth--summary","title":"Summary","text":"Authentication provider implementations for Mail Intake.
This package defines the authentication layer used by mail adapters to obtain provider-specific credentials.
It exposes:
Authentication providers:
Consumers should depend on the abstract interface and use concrete implementations only where explicitly required.
"},{"location":"auth/#mail_intake.auth--public-api","title":"Public API","text":"MailIntakeAuthProviderMailIntakeGoogleAuth Bases: ABC, Generic[T]
Abstract base class for authentication providers.
This interface enforces a strict contract between authentication providers and mail adapters by requiring providers to explicitly declare the type of credentials they return.
NotesResponsibilities:
- Acquire credentials from an external provider.\n- Refresh or revalidate credentials as needed.\n- Handle authentication-specific failure modes.\n- Coordinate with credential persistence layers where applicable.\nConstraints:
- Mail adapters must treat returned credentials as opaque and\n provider-specific.\n- Mail adapters rely only on the declared credential type expected\n by the adapter.\nabstractmethod","text":"get_credentials() -> T\nRetrieve valid, provider-specific credentials.
Returns:
Name Type DescriptionT T Credentials of type T suitable for immediate use by the corresponding mail adapter.
Raises:
Type DescriptionException An authentication-specific exception indicating that credentials could not be obtained or validated.
NotesGuarantees:
- This method is synchronous by design.\n- Represents the sole entry point through which adapters obtain\n authentication material.\n- Implementations must either return credentials of the declared\n type `T` that are valid at the time of return or raise an exception.\nMailIntakeGoogleAuth(\n credentials_path: str,\n store: CredentialStore[Any],\n scopes: Sequence[str],\n)\n Bases: MailIntakeAuthProvider
Google OAuth provider for Gmail access.
This provider implements the MailIntakeAuthProvider interface using Google's OAuth 2.0 flow and credential management libraries.
Responsibilities:
- Load cached credentials from a credential store when available.\n- Refresh expired credentials when possible.\n- Initiate an interactive OAuth flow only when required.\n- Persist refreshed or newly obtained credentials via the store.\nGuarantees:
- This class is synchronous by design and maintains a minimal\n internal state.\nInitialize the Google authentication provider.
Parameters:
Name Type Description Defaultcredentials_path str Path to the Google OAuth client secrets file used to initiate the OAuth 2.0 flow.
requiredstore CredentialStore[Credentials] Credential store responsible for persisting and retrieving Google OAuth credentials.
requiredscopes Sequence[str] OAuth scopes required for Gmail access.
required"},{"location":"auth/#mail_intake.auth.MailIntakeGoogleAuth-functions","title":"Functions","text":""},{"location":"auth/#mail_intake.auth.MailIntakeGoogleAuth.get_credentials","title":"get_credentials","text":"get_credentials() -> Any\nRetrieve valid Google OAuth credentials.
Returns:
Name Type DescriptionCredentials Any A google.oauth2.credentials.Credentials instance suitable for use with Google API clients.
Raises:
Type DescriptionMailIntakeAuthError If credentials cannot be loaded, refreshed, or obtained via interactive authentication.
NotesLifecycle:
- Load cached credentials from the configured credential store.\n- Refresh expired credentials when possible.\n- Perform an interactive OAuth login as a fallback.\n- Persist valid credentials for future use.\nAuthentication provider contracts for Mail Intake.
This module defines the authentication abstraction layer used by mail adapters to obtain provider-specific credentials.
Authentication concerns are intentionally decoupled from adapter logic. Adapters depend only on this interface and must not be aware of how credentials are acquired, refreshed, or persisted.
"},{"location":"auth/base/#mail_intake.auth.base-classes","title":"Classes","text":""},{"location":"auth/base/#mail_intake.auth.base.MailIntakeAuthProvider","title":"MailIntakeAuthProvider","text":" Bases: ABC, Generic[T]
Abstract base class for authentication providers.
This interface enforces a strict contract between authentication providers and mail adapters by requiring providers to explicitly declare the type of credentials they return.
NotesResponsibilities:
- Acquire credentials from an external provider.\n- Refresh or revalidate credentials as needed.\n- Handle authentication-specific failure modes.\n- Coordinate with credential persistence layers where applicable.\nConstraints:
- Mail adapters must treat returned credentials as opaque and\n provider-specific.\n- Mail adapters rely only on the declared credential type expected\n by the adapter.\nabstractmethod","text":"get_credentials() -> T\nRetrieve valid, provider-specific credentials.
Returns:
Name Type DescriptionT T Credentials of type T suitable for immediate use by the corresponding mail adapter.
Raises:
Type DescriptionException An authentication-specific exception indicating that credentials could not be obtained or validated.
NotesGuarantees:
- This method is synchronous by design.\n- Represents the sole entry point through which adapters obtain\n authentication material.\n- Implementations must either return credentials of the declared\n type `T` that are valid at the time of return or raise an exception.\nGoogle authentication provider implementation for Mail Intake.
This module provides a Google OAuth\u2013based authentication provider used primarily for Gmail access.
It encapsulates all Google-specific authentication concerns, including:
No Google authentication details should leak outside this module.
"},{"location":"auth/google/#mail_intake.auth.google-classes","title":"Classes","text":""},{"location":"auth/google/#mail_intake.auth.google.MailIntakeGoogleAuth","title":"MailIntakeGoogleAuth","text":"MailIntakeGoogleAuth(\n credentials_path: str,\n store: CredentialStore[Any],\n scopes: Sequence[str],\n)\n Bases: MailIntakeAuthProvider
Google OAuth provider for Gmail access.
This provider implements the MailIntakeAuthProvider interface using Google's OAuth 2.0 flow and credential management libraries.
Responsibilities:
- Load cached credentials from a credential store when available.\n- Refresh expired credentials when possible.\n- Initiate an interactive OAuth flow only when required.\n- Persist refreshed or newly obtained credentials via the store.\nGuarantees:
- This class is synchronous by design and maintains a minimal\n internal state.\nInitialize the Google authentication provider.
Parameters:
Name Type Description Defaultcredentials_path str Path to the Google OAuth client secrets file used to initiate the OAuth 2.0 flow.
requiredstore CredentialStore[Credentials] Credential store responsible for persisting and retrieving Google OAuth credentials.
requiredscopes Sequence[str] OAuth scopes required for Gmail access.
required"},{"location":"auth/google/#mail_intake.auth.google.MailIntakeGoogleAuth-functions","title":"Functions","text":""},{"location":"auth/google/#mail_intake.auth.google.MailIntakeGoogleAuth.get_credentials","title":"get_credentials","text":"get_credentials() -> Any\nRetrieve valid Google OAuth credentials.
Returns:
Name Type DescriptionCredentials Any A google.oauth2.credentials.Credentials instance suitable for use with Google API clients.
Raises:
Type DescriptionMailIntakeAuthError If credentials cannot be loaded, refreshed, or obtained via interactive authentication.
NotesLifecycle:
- Load cached credentials from the configured credential store.\n- Refresh expired credentials when possible.\n- Perform an interactive OAuth login as a fallback.\n- Persist valid credentials for future use.\nCredential persistence interfaces and implementations for Mail Intake.
This package defines the abstractions and concrete implementations used to persist authentication credentials across Mail Intake components.
The credential persistence layer is intentionally decoupled from authentication logic. Authentication providers are responsible for credential acquisition, validation, and refresh, while implementations within this package are responsible solely for storage and retrieval.
The package provides:
CredentialStore abstraction defining the persistence contract.Credential lifecycle management, interpretation, and security policy decisions remain the responsibility of authentication providers.
"},{"location":"credentials/#mail_intake.credentials--public-api","title":"Public API","text":"CredentialStorePickleCredentialStoreRedisCredentialStore Bases: ABC, Generic[T]
Abstract base class defining a generic persistence interface.
Used for authentication credentials across different backends.
NotesResponsibilities:
- Provide persistent storage separating life-cycle management from\n storage mechanics.\n- Keep implementation focused only on persistence.\nConstraints:
- 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.\nabstractmethod","text":"clear() -> None\nRemove any persisted credentials from the store.
NotesLifecycle:
- 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\nGuarantees:
- Implementations should treat this operation as idempotent\nabstractmethod","text":"load() -> T | None\nLoad previously persisted credentials.
Returns:
Type DescriptionT | None T | None: An instance of type T if credentials are available and loadable; otherwise None.
Guarantees:
- 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.\nabstractmethod","text":"save(credentials: T) -> None\nPersist credentials to the underlying storage backend.
Parameters:
Name Type Description Defaultcredentials T The credential object to persist.
required NotesLifecycle:
- This method is invoked when credentials are newly obtained or have been refreshed and are known to be valid at the time of persistence\nResponsibilities:
- Ensuring durability appropriate to the deployment context\n- Applying encryption or access controls where required\n- Overwriting any previously stored credentials\nPickleCredentialStore(path: str)\n Bases: CredentialStore[T]
Filesystem-backed credential store using pickle serialization.
This store persists credentials as a pickled object on the local filesystem. It is a simple implementation intended primarily for development, testing, and single-process execution contexts.
NotesGuarantees:
- Stores credentials on the local filesystem.\n- Uses `pickle` for serialization and deserialization.\n- Does not provide encryption, locking, or concurrency guarantees.\nConstraints:
- Credential lifecycle management, validation, and refresh logic are\n explicitly out of scope for this class.\nInitialize a pickle-backed credential store.
Parameters:
Name Type Description Defaultpath str Filesystem path where credentials will be stored. The file will be created or overwritten as needed.
required"},{"location":"credentials/#mail_intake.credentials.PickleCredentialStore-functions","title":"Functions","text":""},{"location":"credentials/#mail_intake.credentials.PickleCredentialStore.clear","title":"clear","text":"clear() -> None\nRemove persisted credentials from the local filesystem.
NotesLifecycle:
- This method deletes the credential file if it exists and should be treated as an idempotent operation\nload() -> T | None\nLoad credentials from the local filesystem.
Returns:
Type DescriptionT | None T | None: An instance of type T if credentials are present and successfully deserialized; otherwise None.
Guarantees:
- 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.\nsave(credentials: T) -> None\nPersist credentials to the local filesystem.
Parameters:
Name Type Description Defaultcredentials T The credential object to persist.
required NotesResponsibilities:
- Any previously stored credentials at the configured path are overwritten\nRedisCredentialStore(\n redis_client: Any,\n key: str,\n serialize: Callable[[T], bytes],\n deserialize: Callable[[bytes], T],\n ttl_seconds: int | None = None,\n)\n Bases: CredentialStore[T]
Redis-backed implementation of CredentialStore.
This store persists credentials in Redis and is suitable for distributed and horizontally scaled deployments where credentials must be shared across multiple processes or nodes.
NotesResponsibilities:
- 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.\nGuarantees:
- 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.\nInitialize a Redis-backed credential store.
Callers supply all runtime dependencies: redis_client is an initialized Redis client instance, key names the storage key, serialize/deserialize are the encoding and decoding callables, and ttl_seconds optionally limits credential lifetime.
clear() -> None\nRemove stored credentials from Redis.
NotesLifecycle:
- This operation deletes the configured Redis key if it exists\n- Implementations should treat this method as idempotent\nload() -> T | None\nLoad credentials from Redis.
Returns:
Type DescriptionT | None T | None: An instance of type T if credentials are present and successfully deserialized; otherwise None.
Guarantees:
- 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.\nsave(credentials: T) -> None\nPersist credentials to Redis.
Parameters:
Name Type Description Defaultcredentials T The credential object to persist.
required NotesResponsibilities:
- 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\nLocal filesystem\u2013based credential persistence for Mail Intake.
This module provides a file-backed implementation of the CredentialStore abstraction using Python's pickle module.
The pickle-based credential store is intended for local development, single-node deployments, and controlled environments where credentials do not need to be shared across processes or machines.
Due to the security and portability risks associated with pickle-based serialization, this implementation is not suitable for distributed or untrusted environments.
PickleCredentialStore(path: str)\n Bases: CredentialStore[T]
Filesystem-backed credential store using pickle serialization.
This store persists credentials as a pickled object on the local filesystem. It is a simple implementation intended primarily for development, testing, and single-process execution contexts.
NotesGuarantees:
- Stores credentials on the local filesystem.\n- Uses `pickle` for serialization and deserialization.\n- Does not provide encryption, locking, or concurrency guarantees.\nConstraints:
- Credential lifecycle management, validation, and refresh logic are\n explicitly out of scope for this class.\nInitialize a pickle-backed credential store.
Parameters:
Name Type Description Defaultpath str Filesystem path where credentials will be stored. The file will be created or overwritten as needed.
required"},{"location":"credentials/pickle/#mail_intake.credentials.pickle.PickleCredentialStore-functions","title":"Functions","text":""},{"location":"credentials/pickle/#mail_intake.credentials.pickle.PickleCredentialStore.clear","title":"clear","text":"clear() -> None\nRemove persisted credentials from the local filesystem.
NotesLifecycle:
- This method deletes the credential file if it exists and should be treated as an idempotent operation\nload() -> T | None\nLoad credentials from the local filesystem.
Returns:
Type DescriptionT | None T | None: An instance of type T if credentials are present and successfully deserialized; otherwise None.
Guarantees:
- 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.\nsave(credentials: T) -> None\nPersist credentials to the local filesystem.
Parameters:
Name Type Description Defaultcredentials T The credential object to persist.
required NotesResponsibilities:
- Any previously stored credentials at the configured path are overwritten\nRedis-backed credential persistence for Mail Intake.
This module provides a Redis-based implementation of the CredentialStore abstraction, enabling credential persistence across distributed and horizontally scaled deployments.
The Redis credential store is designed for environments where authentication credentials must be shared safely across multiple processes, containers, or nodes, such as container orchestration platforms and microservice architectures.
Key characteristics:
pickle.This module is responsible solely for persistence concerns. Credential validation, refresh, rotation, and acquisition remain the responsibility of authentication provider implementations.
"},{"location":"credentials/redis/#mail_intake.credentials.redis-classes","title":"Classes","text":""},{"location":"credentials/redis/#mail_intake.credentials.redis.RedisCredentialStore","title":"RedisCredentialStore","text":"RedisCredentialStore(\n redis_client: Any,\n key: str,\n serialize: Callable[[T], bytes],\n deserialize: Callable[[bytes], T],\n ttl_seconds: int | None = None,\n)\n Bases: CredentialStore[T]
Redis-backed implementation of CredentialStore.
This store persists credentials in Redis and is suitable for distributed and horizontally scaled deployments where credentials must be shared across multiple processes or nodes.
NotesResponsibilities:
- 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.\nGuarantees:
- 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.\nInitialize a Redis-backed credential store.
Callers supply all runtime dependencies: redis_client is an initialized Redis client instance, key names the storage key, serialize/deserialize are the encoding and decoding callables, and ttl_seconds optionally limits credential lifetime.
clear() -> None\nRemove stored credentials from Redis.
NotesLifecycle:
- This operation deletes the configured Redis key if it exists\n- Implementations should treat this method as idempotent\nload() -> T | None\nLoad credentials from Redis.
Returns:
Type DescriptionT | None T | None: An instance of type T if credentials are present and successfully deserialized; otherwise None.
Guarantees:
- 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.\nsave(credentials: T) -> None\nPersist credentials to Redis.
Parameters:
Name Type Description Defaultcredentials T The credential object to persist.
required NotesResponsibilities:
- 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\nCredential persistence abstractions for Mail Intake.
This module defines the generic persistence contract used to store and retrieve authentication credentials across Mail Intake components.
The CredentialStore abstraction establishes a strict separation between credential lifecycle management and credential storage. Authentication providers are responsible for acquiring, validating, refreshing, and revoking credentials, while concrete store implementations are responsible solely for persistence concerns.
By remaining agnostic to credential structure, serialization format, and storage backend, this module enables multiple persistence strategies\u2014such as local files, in-memory caches, distributed stores, or secrets managers\u2014without coupling authentication logic to any specific storage mechanism.
"},{"location":"credentials/store/#mail_intake.credentials.store-classes","title":"Classes","text":""},{"location":"credentials/store/#mail_intake.credentials.store.CredentialStore","title":"CredentialStore","text":" Bases: ABC, Generic[T]
Abstract base class defining a generic persistence interface.
Used for authentication credentials across different backends.
NotesResponsibilities:
- Provide persistent storage separating life-cycle management from\n storage mechanics.\n- Keep implementation focused only on persistence.\nConstraints:
- 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.\nabstractmethod","text":"clear() -> None\nRemove any persisted credentials from the store.
NotesLifecycle:
- 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\nGuarantees:
- Implementations should treat this operation as idempotent\nabstractmethod","text":"load() -> T | None\nLoad previously persisted credentials.
Returns:
Type DescriptionT | None T | None: An instance of type T if credentials are available and loadable; otherwise None.
Guarantees:
- 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.\nabstractmethod","text":"save(credentials: T) -> None\nPersist credentials to the underlying storage backend.
Parameters:
Name Type Description Defaultcredentials T The credential object to persist.
required NotesLifecycle:
- This method is invoked when credentials are newly obtained or have been refreshed and are known to be valid at the time of persistence\nResponsibilities:
- Ensuring durability appropriate to the deployment context\n- Applying encryption or access controls where required\n- Overwriting any previously stored credentials\nMail ingestion orchestration for Mail Intake.
This package contains high-level ingestion components responsible for coordinating mail retrieval, parsing, normalization, and model construction.
It represents the top of the ingestion pipeline and is intended to be the primary interaction surface for library consumers.
Components in this package:
Consumers are expected to construct a mail adapter and pass it to the ingestion layer to begin processing messages and threads.
"},{"location":"ingestion/#mail_intake.ingestion--public-api","title":"Public API","text":"MailIntakeReaderMailIntakeReader(adapter: MailIntakeAdapter)\nHigh-level read-only ingestion interface.
NotesResponsibilities:
- 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.\nConstraints:
- This class is intentionally: Provider-agnostic, stateless beyond\n iteration scope, read-only.\nInitialize the mail reader.
Parameters:
Name Type Description Defaultadapter MailIntakeAdapter Mail adapter implementation used to retrieve raw messages and threads from a mail provider.
required"},{"location":"ingestion/#mail_intake.ingestion.MailIntakeReader-functions","title":"Functions","text":""},{"location":"ingestion/#mail_intake.ingestion.MailIntakeReader.iter_messages","title":"iter_messages","text":"iter_messages(query: str) -> Iterator[MailIntakeMessage]\nIterate over parsed messages matching a provider query.
Parameters:
Name Type Description Defaultquery str Provider-specific query string used to filter messages.
requiredYields:
Name Type DescriptionMailIntakeMessage MailIntakeMessage Fully parsed and normalized MailIntakeMessage instances.
Raises:
Type DescriptionMailIntakeParsingError If a message cannot be parsed.
"},{"location":"ingestion/#mail_intake.ingestion.MailIntakeReader.iter_threads","title":"iter_threads","text":"iter_threads(query: str) -> Iterator[MailIntakeThread]\nIterate over threads constructed from messages matching a query.
Parameters:
Name Type Description Defaultquery str Provider-specific query string used to filter messages.
requiredReturns:
Type DescriptionIterator[MailIntakeThread] Iterator[MailIntakeThread]: An iterator over MailIntakeThread instances.
Raises:
Type Description`MailIntakeParsingError` If a message cannot be parsed.
NotesGuarantees:
- Messages are grouped by `thread_id` and yielded as complete\n thread objects containing all associated messages.\nHigh-level mail ingestion orchestration for Mail Intake.
This module provides the primary, provider-agnostic entry point for reading and processing mail data.
It coordinates:
No provider-specific logic or API semantics are permitted in this layer.
"},{"location":"ingestion/reader/#mail_intake.ingestion.reader-classes","title":"Classes","text":""},{"location":"ingestion/reader/#mail_intake.ingestion.reader.MailIntakeReader","title":"MailIntakeReader","text":"MailIntakeReader(adapter: MailIntakeAdapter)\nHigh-level read-only ingestion interface.
NotesResponsibilities:
- 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.\nConstraints:
- This class is intentionally: Provider-agnostic, stateless beyond\n iteration scope, read-only.\nInitialize the mail reader.
Parameters:
Name Type Description Defaultadapter MailIntakeAdapter Mail adapter implementation used to retrieve raw messages and threads from a mail provider.
required"},{"location":"ingestion/reader/#mail_intake.ingestion.reader.MailIntakeReader-functions","title":"Functions","text":""},{"location":"ingestion/reader/#mail_intake.ingestion.reader.MailIntakeReader.iter_messages","title":"iter_messages","text":"iter_messages(query: str) -> Iterator[MailIntakeMessage]\nIterate over parsed messages matching a provider query.
Parameters:
Name Type Description Defaultquery str Provider-specific query string used to filter messages.
requiredYields:
Name Type DescriptionMailIntakeMessage MailIntakeMessage Fully parsed and normalized MailIntakeMessage instances.
Raises:
Type DescriptionMailIntakeParsingError If a message cannot be parsed.
"},{"location":"ingestion/reader/#mail_intake.ingestion.reader.MailIntakeReader.iter_threads","title":"iter_threads","text":"iter_threads(query: str) -> Iterator[MailIntakeThread]\nIterate over threads constructed from messages matching a query.
Parameters:
Name Type Description Defaultquery str Provider-specific query string used to filter messages.
requiredReturns:
Type DescriptionIterator[MailIntakeThread] Iterator[MailIntakeThread]: An iterator over MailIntakeThread instances.
Raises:
Type Description`MailIntakeParsingError` If a message cannot be parsed.
NotesGuarantees:
- Messages are grouped by `thread_id` and yielded as complete\n thread objects containing all associated messages.\nMail Intake \u2014 provider-agnostic, read-only email ingestion framework.
Mail Intake is a contract-first library designed to ingest, parse, and normalize email data from external providers (such as Gmail) into clean, provider-agnostic domain models.
The library is intentionally structured around clear layers, each exposed as a first-class module at the package root:
adapters: Provider-specific access (e.g., Gmail).auth: Authentication providers and credential lifecycle management.credentials: Credential persistence abstractions and implementations.parsers: Extraction and normalization of message content.ingestion: Orchestration and high-level ingestion workflows.models: Canonical, provider-agnostic data representations.config: Explicit global configuration.exceptions: Library-defined error hierarchy.The package root acts as a namespace, not a facade. Consumers are expected to import functionality explicitly from the appropriate module.
"},{"location":"mail_intake/#mail_intake--installation","title":"Installation","text":"Install using pip:
pip install mail-intake\nOr with Poetry:
poetry add mail-intake\nMail Intake is pure Python and has no runtime dependencies beyond those required by the selected provider (for example, Google APIs for Gmail).
"},{"location":"mail_intake/#mail_intake--quick-start","title":"Quick Start","text":"Minimal Gmail ingestion example (local development):
from mail_intake.ingestion import MailIntakeReader\nfrom mail_intake.adapters import MailIntakeGmailAdapter\nfrom mail_intake.auth import MailIntakeGoogleAuth\nfrom mail_intake.credentials import PickleCredentialStore\n\nstore = PickleCredentialStore(path=\"token.pickle\")\n\nauth = MailIntakeGoogleAuth(\n credentials_path=\"credentials.json\",\n store=store,\n scopes=[\"https://www.googleapis.com/auth/gmail.readonly\"],\n)\n\nadapter = MailIntakeGmailAdapter(auth_provider=auth)\nreader = MailIntakeReader(adapter)\n\nfor message in reader.iter_messages(\"from:recruiter@example.com\"):\n print(message.subject, message.from_email)\nIterating over threads:
for thread in reader.iter_threads(\"subject:Interview\"):\n print(thread.normalized_subject, len(thread.messages))\nMail Intake is designed to be extensible via public contracts exposed through its modules:
adapters.MailIntakeAdapter.auth.MailIntakeAuthProvider[T].credentials.CredentialStore[T].Users SHOULD NOT subclass built-in adapter implementations. Built-in adapters (such as Gmail) are reference implementations and may change internally without notice.
Design Guarantees:
Mail Intake favors correctness, clarity, and explicitness over convenience shortcuts.
Core Philosophy:
Mail Intake is built as a contract-first ingestion pipeline:
The supported public API consists of the following top-level modules:
mail_intake.ingestionmail_intake.adaptersmail_intake.authmail_intake.credentialsmail_intake.parsersmail_intake.modelsmail_intake.configmail_intake.exceptionsClasses and functions should be imported explicitly from these modules. No individual symbols are re-exported at the package root.
"},{"location":"mail_intake/config/","title":"Config","text":""},{"location":"mail_intake/config/#mail_intake.config","title":"mail_intake.config","text":""},{"location":"mail_intake/config/#mail_intake.config--summary","title":"Summary","text":"Global configuration models for Mail Intake.
This module defines the top-level configuration object used to control mail ingestion behavior across adapters, authentication providers, and ingestion workflows.
Configuration is intentionally explicit, immutable, and free of implicit environment reads to ensure predictability and testability.
"},{"location":"mail_intake/config/#mail_intake.config-classes","title":"Classes","text":""},{"location":"mail_intake/config/#mail_intake.config.MailIntakeConfig","title":"MailIntakeConfigdataclass","text":"MailIntakeConfig(\n provider: str = ...,\n user_id: str = ...,\n readonly: bool = ...,\n credentials_path: str | None = ...,\n token_path: str | None = ...,\n)\nGlobal configuration for mail-intake.
Guarantees:
- 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.\nclass-attribute instance-attribute","text":"credentials_path: str | None = None\nOptional path to provider credentials configuration.
"},{"location":"mail_intake/config/#mail_intake.config.MailIntakeConfig.provider","title":"providerclass-attribute instance-attribute","text":"provider: str = 'gmail'\nIdentifier of the mail provider to use (e.g., \"gmail\").
class-attribute instance-attribute","text":"readonly: bool = True\nWhether ingestion should operate in read-only mode.
"},{"location":"mail_intake/config/#mail_intake.config.MailIntakeConfig.token_path","title":"token_pathclass-attribute instance-attribute","text":"token_path: str | None = None\nOptional path to persisted authentication tokens.
"},{"location":"mail_intake/config/#mail_intake.config.MailIntakeConfig.user_id","title":"user_idclass-attribute instance-attribute","text":"user_id: str = 'me'\nProvider-specific user identifier. Defaults to the authenticated user.
"},{"location":"mail_intake/exceptions/","title":"Exceptions","text":""},{"location":"mail_intake/exceptions/#mail_intake.exceptions","title":"mail_intake.exceptions","text":""},{"location":"mail_intake/exceptions/#mail_intake.exceptions--summary","title":"Summary","text":"Exception hierarchy for Mail Intake.
This module defines the canonical exception types used throughout the Mail Intake library.
All library-raised errors derive from MailIntakeError. Consumers are encouraged to catch this base type (or specific subclasses) rather than provider-specific or third-party exceptions.
Bases: MailIntakeError
Errors raised by mail provider adapters.
NotesLifecycle:
- Raised when a provider adapter encounters API errors, transport\n failures, or invalid provider responses.\n Bases: MailIntakeError
Authentication and credential-related failures.
NotesLifecycle:
- Raised when authentication providers are unable to acquire,\n refresh, or persist valid credentials.\n Bases: Exception
Base exception for all Mail Intake errors.
NotesGuarantees:
- 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\n Bases: MailIntakeError
Errors encountered while parsing message content.
NotesLifecycle:
- Raised when raw provider payloads cannot be interpreted or\n normalized into internal domain models.\nMail provider adapter implementations for Mail Intake.
This package contains adapter-layer implementations responsible for interfacing with external mail providers and exposing a normalized, provider-agnostic contract to the rest of the system.
Adapters in this package:
MailIntakeAdapter interface.Provider-specific logic must not leak outside of adapter implementations. All parsings, normalizations, and transformations must be handled by downstream components.
"},{"location":"mail_intake/adapters/#mail_intake.adapters--public-api","title":"Public API","text":"MailIntakeAdapterMailIntakeGmailAdapter Bases: ABC
Base adapter interface for mail providers.
NotesGuarantees:
- Discover messages matching a query.\n- Retrieve full message payloads.\n- Retrieve full thread payloads.\nLifecycle:
- Adapters are intentionally read-only and must not mutate provider state.\nabstractmethod","text":"fetch_message(message_id: str) -> dict[str, Any]\nFetch a full raw message by message identifier.
Parameters:
Name Type Description Defaultmessage_id str Provider-specific message identifier.
requiredReturns:
Type Descriptiondict[str, Any] dict[str, Any]: Provider-native message payload (e.g., Gmail message JSON structure).
"},{"location":"mail_intake/adapters/#mail_intake.adapters.MailIntakeAdapter.fetch_thread","title":"fetch_threadabstractmethod","text":"fetch_thread(thread_id: str) -> dict[str, Any]\nFetch a full raw thread by thread identifier.
Parameters:
Name Type Description Defaultthread_id str Provider-specific thread identifier.
requiredReturns:
Type Descriptiondict[str, Any] dict[str, Any]: Provider-native thread payload.
"},{"location":"mail_intake/adapters/#mail_intake.adapters.MailIntakeAdapter.iter_message_refs","title":"iter_message_refsabstractmethod","text":"iter_message_refs(query: str) -> Iterator[dict[str, str]]\nIterate over lightweight message references matching a query.
Parameters:
Name Type Description Defaultquery str Provider-specific query string used to filter messages.
requiredReturns:
Type DescriptionIterator[dict[str, str]] Iterator[dict[str, str]]: An iterator over lightweight message reference dictionaries.
Yields:
Type Descriptiondict[str, str] dict[str, str]: Dictionaries containing message and thread identifiers.
NotesGuarantees:
- Implementations must yield dictionaries containing at least\n `message_id` and `thread_id`.\nTypical yield:
{\n \"message_id\": \"...\",\n \"thread_id\": \"...\"\n}\nMailIntakeGmailAdapter(\n auth_provider: MailIntakeAuthProvider[Any],\n user_id: str = \"me\",\n)\n Bases: MailIntakeAdapter
Gmail read-only adapter.
This adapter implements the MailIntakeAdapter interface using the Gmail REST API. It translates the generic mail intake contract into Gmail-specific API calls.
Responsibilities:
- This class is the ONLY place where `googleapiclient` is imported.\n- Gmail REST semantics are known.\n- `.execute()` is called.\nConstraints:
- Must remain thin and imperative.\n- Must not perform parsing or interpretation.\n- Must not expose Gmail-specific types beyond this class.\nInitialize the Gmail adapter.
Parameters:
Name Type Description Defaultauth_provider MailIntakeAuthProvider Authentication provider capable of supplying valid Gmail API credentials.
requireduser_id str Gmail user identifier. Defaults to \"me\".
'me'"},{"location":"mail_intake/adapters/#mail_intake.adapters.MailIntakeGmailAdapter-attributes","title":"Attributes","text":""},{"location":"mail_intake/adapters/#mail_intake.adapters.MailIntakeGmailAdapter.service","title":"service property","text":"service: Any\nLazily initialize and return the Gmail API service client.
Raises:
Type DescriptionMailIntakeAdapterError If the Gmail service cannot be initialized.
"},{"location":"mail_intake/adapters/#mail_intake.adapters.MailIntakeGmailAdapter-functions","title":"Functions","text":""},{"location":"mail_intake/adapters/#mail_intake.adapters.MailIntakeGmailAdapter.fetch_message","title":"fetch_message","text":"fetch_message(message_id: str) -> dict[str, Any]\nFetch a full Gmail message by message ID.
Parameters:
Name Type Description Defaultmessage_id str Gmail message identifier.
requiredReturns:
Type Descriptiondict[str, Any] dict[str, Any]: Provider-native Gmail message payload.
Raises:
Type DescriptionMailIntakeAdapterError If the Gmail API returns an error.
"},{"location":"mail_intake/adapters/#mail_intake.adapters.MailIntakeGmailAdapter.fetch_thread","title":"fetch_thread","text":"fetch_thread(thread_id: str) -> dict[str, Any]\nFetch a full Gmail thread by thread ID.
Parameters:
Name Type Description Defaultthread_id str Gmail thread identifier.
requiredReturns:
Type Descriptiondict[str, Any] dict[str, Any]: Provider-native Gmail thread payload.
Raises:
Type DescriptionMailIntakeAdapterError If the Gmail API returns an error.
"},{"location":"mail_intake/adapters/#mail_intake.adapters.MailIntakeGmailAdapter.iter_message_refs","title":"iter_message_refs","text":"iter_message_refs(query: str) -> Iterator[dict[str, str]]\nIterate over message references matching the query.
Parameters:
Name Type Description Defaultquery str Gmail search query string.
requiredYields:
Type Descriptiondict[str, str] dict[str, str]: Dictionaries containing message_id and thread_id.
Raises:
Type DescriptionMailIntakeAdapterError If the Gmail API returns an error.
"},{"location":"mail_intake/adapters/base/","title":"Base","text":""},{"location":"mail_intake/adapters/base/#mail_intake.adapters.base","title":"mail_intake.adapters.base","text":""},{"location":"mail_intake/adapters/base/#mail_intake.adapters.base--summary","title":"Summary","text":"Mail provider adapter contracts for Mail Intake.
This module defines the provider-agnostic adapter interface used for read-only mail ingestion.
Adapters encapsulate all provider-specific access logic and expose a minimal, normalized contract to the rest of the system. No provider-specific types or semantics should leak beyond implementations of this interface.
"},{"location":"mail_intake/adapters/base/#mail_intake.adapters.base-classes","title":"Classes","text":""},{"location":"mail_intake/adapters/base/#mail_intake.adapters.base.MailIntakeAdapter","title":"MailIntakeAdapter","text":" Bases: ABC
Base adapter interface for mail providers.
NotesGuarantees:
- Discover messages matching a query.\n- Retrieve full message payloads.\n- Retrieve full thread payloads.\nLifecycle:
- Adapters are intentionally read-only and must not mutate provider state.\nabstractmethod","text":"fetch_message(message_id: str) -> dict[str, Any]\nFetch a full raw message by message identifier.
Parameters:
Name Type Description Defaultmessage_id str Provider-specific message identifier.
requiredReturns:
Type Descriptiondict[str, Any] dict[str, Any]: Provider-native message payload (e.g., Gmail message JSON structure).
"},{"location":"mail_intake/adapters/base/#mail_intake.adapters.base.MailIntakeAdapter.fetch_thread","title":"fetch_threadabstractmethod","text":"fetch_thread(thread_id: str) -> dict[str, Any]\nFetch a full raw thread by thread identifier.
Parameters:
Name Type Description Defaultthread_id str Provider-specific thread identifier.
requiredReturns:
Type Descriptiondict[str, Any] dict[str, Any]: Provider-native thread payload.
"},{"location":"mail_intake/adapters/base/#mail_intake.adapters.base.MailIntakeAdapter.iter_message_refs","title":"iter_message_refsabstractmethod","text":"iter_message_refs(query: str) -> Iterator[dict[str, str]]\nIterate over lightweight message references matching a query.
Parameters:
Name Type Description Defaultquery str Provider-specific query string used to filter messages.
requiredReturns:
Type DescriptionIterator[dict[str, str]] Iterator[dict[str, str]]: An iterator over lightweight message reference dictionaries.
Yields:
Type Descriptiondict[str, str] dict[str, str]: Dictionaries containing message and thread identifiers.
NotesGuarantees:
- Implementations must yield dictionaries containing at least\n `message_id` and `thread_id`.\nTypical yield:
{\n \"message_id\": \"...\",\n \"thread_id\": \"...\"\n}\nGmail adapter implementation for Mail Intake.
This module provides a Gmail-specific implementation of the MailIntakeAdapter contract.
It is the only place in the codebase where:
googleapiclient is imported..execute() calls are made.All Gmail-specific behavior must be strictly contained within this module.
"},{"location":"mail_intake/adapters/gmail/#mail_intake.adapters.gmail-classes","title":"Classes","text":""},{"location":"mail_intake/adapters/gmail/#mail_intake.adapters.gmail.MailIntakeGmailAdapter","title":"MailIntakeGmailAdapter","text":"MailIntakeGmailAdapter(\n auth_provider: MailIntakeAuthProvider[Any],\n user_id: str = \"me\",\n)\n Bases: MailIntakeAdapter
Gmail read-only adapter.
This adapter implements the MailIntakeAdapter interface using the Gmail REST API. It translates the generic mail intake contract into Gmail-specific API calls.
Responsibilities:
- This class is the ONLY place where `googleapiclient` is imported.\n- Gmail REST semantics are known.\n- `.execute()` is called.\nConstraints:
- Must remain thin and imperative.\n- Must not perform parsing or interpretation.\n- Must not expose Gmail-specific types beyond this class.\nInitialize the Gmail adapter.
Parameters:
Name Type Description Defaultauth_provider MailIntakeAuthProvider Authentication provider capable of supplying valid Gmail API credentials.
requireduser_id str Gmail user identifier. Defaults to \"me\".
'me'"},{"location":"mail_intake/adapters/gmail/#mail_intake.adapters.gmail.MailIntakeGmailAdapter-attributes","title":"Attributes","text":""},{"location":"mail_intake/adapters/gmail/#mail_intake.adapters.gmail.MailIntakeGmailAdapter.service","title":"service property","text":"service: Any\nLazily initialize and return the Gmail API service client.
Raises:
Type DescriptionMailIntakeAdapterError If the Gmail service cannot be initialized.
"},{"location":"mail_intake/adapters/gmail/#mail_intake.adapters.gmail.MailIntakeGmailAdapter-functions","title":"Functions","text":""},{"location":"mail_intake/adapters/gmail/#mail_intake.adapters.gmail.MailIntakeGmailAdapter.fetch_message","title":"fetch_message","text":"fetch_message(message_id: str) -> dict[str, Any]\nFetch a full Gmail message by message ID.
Parameters:
Name Type Description Defaultmessage_id str Gmail message identifier.
requiredReturns:
Type Descriptiondict[str, Any] dict[str, Any]: Provider-native Gmail message payload.
Raises:
Type DescriptionMailIntakeAdapterError If the Gmail API returns an error.
"},{"location":"mail_intake/adapters/gmail/#mail_intake.adapters.gmail.MailIntakeGmailAdapter.fetch_thread","title":"fetch_thread","text":"fetch_thread(thread_id: str) -> dict[str, Any]\nFetch a full Gmail thread by thread ID.
Parameters:
Name Type Description Defaultthread_id str Gmail thread identifier.
requiredReturns:
Type Descriptiondict[str, Any] dict[str, Any]: Provider-native Gmail thread payload.
Raises:
Type DescriptionMailIntakeAdapterError If the Gmail API returns an error.
"},{"location":"mail_intake/adapters/gmail/#mail_intake.adapters.gmail.MailIntakeGmailAdapter.iter_message_refs","title":"iter_message_refs","text":"iter_message_refs(query: str) -> Iterator[dict[str, str]]\nIterate over message references matching the query.
Parameters:
Name Type Description Defaultquery str Gmail search query string.
requiredYields:
Type Descriptiondict[str, str] dict[str, str]: Dictionaries containing message_id and thread_id.
Raises:
Type DescriptionMailIntakeAdapterError If the Gmail API returns an error.
"},{"location":"mail_intake/auth/","title":"Auth","text":"Authentication provider implementations for Mail Intake.
This package defines the authentication layer used by mail adapters to obtain provider-specific credentials.
It exposes:
Authentication providers:
Consumers should depend on the abstract interface and use concrete implementations only where explicitly required.
"},{"location":"mail_intake/auth/#mail_intake.auth--public-api","title":"Public API","text":"MailIntakeAuthProviderMailIntakeGoogleAuth Bases: ABC, Generic[T]
Abstract base class for authentication providers.
This interface enforces a strict contract between authentication providers and mail adapters by requiring providers to explicitly declare the type of credentials they return.
NotesResponsibilities:
- Acquire credentials from an external provider.\n- Refresh or revalidate credentials as needed.\n- Handle authentication-specific failure modes.\n- Coordinate with credential persistence layers where applicable.\nConstraints:
- Mail adapters must treat returned credentials as opaque and\n provider-specific.\n- Mail adapters rely only on the declared credential type expected\n by the adapter.\nabstractmethod","text":"get_credentials() -> T\nRetrieve valid, provider-specific credentials.
Returns:
Name Type DescriptionT T Credentials of type T suitable for immediate use by the corresponding mail adapter.
Raises:
Type DescriptionException An authentication-specific exception indicating that credentials could not be obtained or validated.
NotesGuarantees:
- This method is synchronous by design.\n- Represents the sole entry point through which adapters obtain\n authentication material.\n- Implementations must either return credentials of the declared\n type `T` that are valid at the time of return or raise an exception.\nMailIntakeGoogleAuth(\n credentials_path: str,\n store: CredentialStore[Any],\n scopes: Sequence[str],\n)\n Bases: MailIntakeAuthProvider
Google OAuth provider for Gmail access.
This provider implements the MailIntakeAuthProvider interface using Google's OAuth 2.0 flow and credential management libraries.
Responsibilities:
- Load cached credentials from a credential store when available.\n- Refresh expired credentials when possible.\n- Initiate an interactive OAuth flow only when required.\n- Persist refreshed or newly obtained credentials via the store.\nGuarantees:
- This class is synchronous by design and maintains a minimal\n internal state.\nInitialize the Google authentication provider.
Parameters:
Name Type Description Defaultcredentials_path str Path to the Google OAuth client secrets file used to initiate the OAuth 2.0 flow.
requiredstore CredentialStore[Credentials] Credential store responsible for persisting and retrieving Google OAuth credentials.
requiredscopes Sequence[str] OAuth scopes required for Gmail access.
required"},{"location":"mail_intake/auth/#mail_intake.auth.MailIntakeGoogleAuth-functions","title":"Functions","text":""},{"location":"mail_intake/auth/#mail_intake.auth.MailIntakeGoogleAuth.get_credentials","title":"get_credentials","text":"get_credentials() -> Any\nRetrieve valid Google OAuth credentials.
Returns:
Name Type DescriptionCredentials Any A google.oauth2.credentials.Credentials instance suitable for use with Google API clients.
Raises:
Type DescriptionMailIntakeAuthError If credentials cannot be loaded, refreshed, or obtained via interactive authentication.
NotesLifecycle:
- Load cached credentials from the configured credential store.\n- Refresh expired credentials when possible.\n- Perform an interactive OAuth login as a fallback.\n- Persist valid credentials for future use.\nAuthentication provider contracts for Mail Intake.
This module defines the authentication abstraction layer used by mail adapters to obtain provider-specific credentials.
Authentication concerns are intentionally decoupled from adapter logic. Adapters depend only on this interface and must not be aware of how credentials are acquired, refreshed, or persisted.
"},{"location":"mail_intake/auth/base/#mail_intake.auth.base-classes","title":"Classes","text":""},{"location":"mail_intake/auth/base/#mail_intake.auth.base.MailIntakeAuthProvider","title":"MailIntakeAuthProvider","text":" Bases: ABC, Generic[T]
Abstract base class for authentication providers.
This interface enforces a strict contract between authentication providers and mail adapters by requiring providers to explicitly declare the type of credentials they return.
NotesResponsibilities:
- Acquire credentials from an external provider.\n- Refresh or revalidate credentials as needed.\n- Handle authentication-specific failure modes.\n- Coordinate with credential persistence layers where applicable.\nConstraints:
- Mail adapters must treat returned credentials as opaque and\n provider-specific.\n- Mail adapters rely only on the declared credential type expected\n by the adapter.\nabstractmethod","text":"get_credentials() -> T\nRetrieve valid, provider-specific credentials.
Returns:
Name Type DescriptionT T Credentials of type T suitable for immediate use by the corresponding mail adapter.
Raises:
Type DescriptionException An authentication-specific exception indicating that credentials could not be obtained or validated.
NotesGuarantees:
- This method is synchronous by design.\n- Represents the sole entry point through which adapters obtain\n authentication material.\n- Implementations must either return credentials of the declared\n type `T` that are valid at the time of return or raise an exception.\nGoogle authentication provider implementation for Mail Intake.
This module provides a Google OAuth\u2013based authentication provider used primarily for Gmail access.
It encapsulates all Google-specific authentication concerns, including:
No Google authentication details should leak outside this module.
"},{"location":"mail_intake/auth/google/#mail_intake.auth.google-classes","title":"Classes","text":""},{"location":"mail_intake/auth/google/#mail_intake.auth.google.MailIntakeGoogleAuth","title":"MailIntakeGoogleAuth","text":"MailIntakeGoogleAuth(\n credentials_path: str,\n store: CredentialStore[Any],\n scopes: Sequence[str],\n)\n Bases: MailIntakeAuthProvider
Google OAuth provider for Gmail access.
This provider implements the MailIntakeAuthProvider interface using Google's OAuth 2.0 flow and credential management libraries.
Responsibilities:
- Load cached credentials from a credential store when available.\n- Refresh expired credentials when possible.\n- Initiate an interactive OAuth flow only when required.\n- Persist refreshed or newly obtained credentials via the store.\nGuarantees:
- This class is synchronous by design and maintains a minimal\n internal state.\nInitialize the Google authentication provider.
Parameters:
Name Type Description Defaultcredentials_path str Path to the Google OAuth client secrets file used to initiate the OAuth 2.0 flow.
requiredstore CredentialStore[Credentials] Credential store responsible for persisting and retrieving Google OAuth credentials.
requiredscopes Sequence[str] OAuth scopes required for Gmail access.
required"},{"location":"mail_intake/auth/google/#mail_intake.auth.google.MailIntakeGoogleAuth-functions","title":"Functions","text":""},{"location":"mail_intake/auth/google/#mail_intake.auth.google.MailIntakeGoogleAuth.get_credentials","title":"get_credentials","text":"get_credentials() -> Any\nRetrieve valid Google OAuth credentials.
Returns:
Name Type DescriptionCredentials Any A google.oauth2.credentials.Credentials instance suitable for use with Google API clients.
Raises:
Type DescriptionMailIntakeAuthError If credentials cannot be loaded, refreshed, or obtained via interactive authentication.
NotesLifecycle:
- Load cached credentials from the configured credential store.\n- Refresh expired credentials when possible.\n- Perform an interactive OAuth login as a fallback.\n- Persist valid credentials for future use.\nCredential persistence interfaces and implementations for Mail Intake.
This package defines the abstractions and concrete implementations used to persist authentication credentials across Mail Intake components.
The credential persistence layer is intentionally decoupled from authentication logic. Authentication providers are responsible for credential acquisition, validation, and refresh, while implementations within this package are responsible solely for storage and retrieval.
The package provides:
CredentialStore abstraction defining the persistence contract.Credential lifecycle management, interpretation, and security policy decisions remain the responsibility of authentication providers.
"},{"location":"mail_intake/credentials/#mail_intake.credentials--public-api","title":"Public API","text":"CredentialStorePickleCredentialStoreRedisCredentialStore Bases: ABC, Generic[T]
Abstract base class defining a generic persistence interface.
Used for authentication credentials across different backends.
NotesResponsibilities:
- Provide persistent storage separating life-cycle management from\n storage mechanics.\n- Keep implementation focused only on persistence.\nConstraints:
- 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.\nabstractmethod","text":"clear() -> None\nRemove any persisted credentials from the store.
NotesLifecycle:
- 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\nGuarantees:
- Implementations should treat this operation as idempotent\nabstractmethod","text":"load() -> T | None\nLoad previously persisted credentials.
Returns:
Type DescriptionT | None T | None: An instance of type T if credentials are available and loadable; otherwise None.
Guarantees:
- 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.\nabstractmethod","text":"save(credentials: T) -> None\nPersist credentials to the underlying storage backend.
Parameters:
Name Type Description Defaultcredentials T The credential object to persist.
required NotesLifecycle:
- This method is invoked when credentials are newly obtained or have been refreshed and are known to be valid at the time of persistence\nResponsibilities:
- Ensuring durability appropriate to the deployment context\n- Applying encryption or access controls where required\n- Overwriting any previously stored credentials\nPickleCredentialStore(path: str)\n Bases: CredentialStore[T]
Filesystem-backed credential store using pickle serialization.
This store persists credentials as a pickled object on the local filesystem. It is a simple implementation intended primarily for development, testing, and single-process execution contexts.
NotesGuarantees:
- Stores credentials on the local filesystem.\n- Uses `pickle` for serialization and deserialization.\n- Does not provide encryption, locking, or concurrency guarantees.\nConstraints:
- Credential lifecycle management, validation, and refresh logic are\n explicitly out of scope for this class.\nInitialize a pickle-backed credential store.
Parameters:
Name Type Description Defaultpath str Filesystem path where credentials will be stored. The file will be created or overwritten as needed.
required"},{"location":"mail_intake/credentials/#mail_intake.credentials.PickleCredentialStore-functions","title":"Functions","text":""},{"location":"mail_intake/credentials/#mail_intake.credentials.PickleCredentialStore.clear","title":"clear","text":"clear() -> None\nRemove persisted credentials from the local filesystem.
NotesLifecycle:
- This method deletes the credential file if it exists and should be treated as an idempotent operation\nload() -> T | None\nLoad credentials from the local filesystem.
Returns:
Type DescriptionT | None T | None: An instance of type T if credentials are present and successfully deserialized; otherwise None.
Guarantees:
- 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.\nsave(credentials: T) -> None\nPersist credentials to the local filesystem.
Parameters:
Name Type Description Defaultcredentials T The credential object to persist.
required NotesResponsibilities:
- Any previously stored credentials at the configured path are overwritten\nRedisCredentialStore(\n redis_client: Any,\n key: str,\n serialize: Callable[[T], bytes],\n deserialize: Callable[[bytes], T],\n ttl_seconds: int | None = None,\n)\n Bases: CredentialStore[T]
Redis-backed implementation of CredentialStore.
This store persists credentials in Redis and is suitable for distributed and horizontally scaled deployments where credentials must be shared across multiple processes or nodes.
NotesResponsibilities:
- 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.\nGuarantees:
- 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.\nInitialize a Redis-backed credential store.
Callers supply all runtime dependencies: redis_client is an initialized Redis client instance, key names the storage key, serialize/deserialize are the encoding and decoding callables, and ttl_seconds optionally limits credential lifetime.
clear() -> None\nRemove stored credentials from Redis.
NotesLifecycle:
- This operation deletes the configured Redis key if it exists\n- Implementations should treat this method as idempotent\nload() -> T | None\nLoad credentials from Redis.
Returns:
Type DescriptionT | None T | None: An instance of type T if credentials are present and successfully deserialized; otherwise None.
Guarantees:
- 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.\nsave(credentials: T) -> None\nPersist credentials to Redis.
Parameters:
Name Type Description Defaultcredentials T The credential object to persist.
required NotesResponsibilities:
- 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\nLocal filesystem\u2013based credential persistence for Mail Intake.
This module provides a file-backed implementation of the CredentialStore abstraction using Python's pickle module.
The pickle-based credential store is intended for local development, single-node deployments, and controlled environments where credentials do not need to be shared across processes or machines.
Due to the security and portability risks associated with pickle-based serialization, this implementation is not suitable for distributed or untrusted environments.
PickleCredentialStore(path: str)\n Bases: CredentialStore[T]
Filesystem-backed credential store using pickle serialization.
This store persists credentials as a pickled object on the local filesystem. It is a simple implementation intended primarily for development, testing, and single-process execution contexts.
NotesGuarantees:
- Stores credentials on the local filesystem.\n- Uses `pickle` for serialization and deserialization.\n- Does not provide encryption, locking, or concurrency guarantees.\nConstraints:
- Credential lifecycle management, validation, and refresh logic are\n explicitly out of scope for this class.\nInitialize a pickle-backed credential store.
Parameters:
Name Type Description Defaultpath str Filesystem path where credentials will be stored. The file will be created or overwritten as needed.
required"},{"location":"mail_intake/credentials/pickle/#mail_intake.credentials.pickle.PickleCredentialStore-functions","title":"Functions","text":""},{"location":"mail_intake/credentials/pickle/#mail_intake.credentials.pickle.PickleCredentialStore.clear","title":"clear","text":"clear() -> None\nRemove persisted credentials from the local filesystem.
NotesLifecycle:
- This method deletes the credential file if it exists and should be treated as an idempotent operation\nload() -> T | None\nLoad credentials from the local filesystem.
Returns:
Type DescriptionT | None T | None: An instance of type T if credentials are present and successfully deserialized; otherwise None.
Guarantees:
- 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.\nsave(credentials: T) -> None\nPersist credentials to the local filesystem.
Parameters:
Name Type Description Defaultcredentials T The credential object to persist.
required NotesResponsibilities:
- Any previously stored credentials at the configured path are overwritten\nRedis-backed credential persistence for Mail Intake.
This module provides a Redis-based implementation of the CredentialStore abstraction, enabling credential persistence across distributed and horizontally scaled deployments.
The Redis credential store is designed for environments where authentication credentials must be shared safely across multiple processes, containers, or nodes, such as container orchestration platforms and microservice architectures.
Key characteristics:
pickle.This module is responsible solely for persistence concerns. Credential validation, refresh, rotation, and acquisition remain the responsibility of authentication provider implementations.
"},{"location":"mail_intake/credentials/redis/#mail_intake.credentials.redis-classes","title":"Classes","text":""},{"location":"mail_intake/credentials/redis/#mail_intake.credentials.redis.RedisCredentialStore","title":"RedisCredentialStore","text":"RedisCredentialStore(\n redis_client: Any,\n key: str,\n serialize: Callable[[T], bytes],\n deserialize: Callable[[bytes], T],\n ttl_seconds: int | None = None,\n)\n Bases: CredentialStore[T]
Redis-backed implementation of CredentialStore.
This store persists credentials in Redis and is suitable for distributed and horizontally scaled deployments where credentials must be shared across multiple processes or nodes.
NotesResponsibilities:
- 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.\nGuarantees:
- 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.\nInitialize a Redis-backed credential store.
Callers supply all runtime dependencies: redis_client is an initialized Redis client instance, key names the storage key, serialize/deserialize are the encoding and decoding callables, and ttl_seconds optionally limits credential lifetime.
clear() -> None\nRemove stored credentials from Redis.
NotesLifecycle:
- This operation deletes the configured Redis key if it exists\n- Implementations should treat this method as idempotent\nload() -> T | None\nLoad credentials from Redis.
Returns:
Type DescriptionT | None T | None: An instance of type T if credentials are present and successfully deserialized; otherwise None.
Guarantees:
- 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.\nsave(credentials: T) -> None\nPersist credentials to Redis.
Parameters:
Name Type Description Defaultcredentials T The credential object to persist.
required NotesResponsibilities:
- 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\nCredential persistence abstractions for Mail Intake.
This module defines the generic persistence contract used to store and retrieve authentication credentials across Mail Intake components.
The CredentialStore abstraction establishes a strict separation between credential lifecycle management and credential storage. Authentication providers are responsible for acquiring, validating, refreshing, and revoking credentials, while concrete store implementations are responsible solely for persistence concerns.
By remaining agnostic to credential structure, serialization format, and storage backend, this module enables multiple persistence strategies\u2014such as local files, in-memory caches, distributed stores, or secrets managers\u2014without coupling authentication logic to any specific storage mechanism.
"},{"location":"mail_intake/credentials/store/#mail_intake.credentials.store-classes","title":"Classes","text":""},{"location":"mail_intake/credentials/store/#mail_intake.credentials.store.CredentialStore","title":"CredentialStore","text":" Bases: ABC, Generic[T]
Abstract base class defining a generic persistence interface.
Used for authentication credentials across different backends.
NotesResponsibilities:
- Provide persistent storage separating life-cycle management from\n storage mechanics.\n- Keep implementation focused only on persistence.\nConstraints:
- 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.\nabstractmethod","text":"clear() -> None\nRemove any persisted credentials from the store.
NotesLifecycle:
- 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\nGuarantees:
- Implementations should treat this operation as idempotent\nabstractmethod","text":"load() -> T | None\nLoad previously persisted credentials.
Returns:
Type DescriptionT | None T | None: An instance of type T if credentials are available and loadable; otherwise None.
Guarantees:
- 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.\nabstractmethod","text":"save(credentials: T) -> None\nPersist credentials to the underlying storage backend.
Parameters:
Name Type Description Defaultcredentials T The credential object to persist.
required NotesLifecycle:
- This method is invoked when credentials are newly obtained or have been refreshed and are known to be valid at the time of persistence\nResponsibilities:
- Ensuring durability appropriate to the deployment context\n- Applying encryption or access controls where required\n- Overwriting any previously stored credentials\nMail ingestion orchestration for Mail Intake.
This package contains high-level ingestion components responsible for coordinating mail retrieval, parsing, normalization, and model construction.
It represents the top of the ingestion pipeline and is intended to be the primary interaction surface for library consumers.
Components in this package:
Consumers are expected to construct a mail adapter and pass it to the ingestion layer to begin processing messages and threads.
"},{"location":"mail_intake/ingestion/#mail_intake.ingestion--public-api","title":"Public API","text":"MailIntakeReaderMailIntakeReader(adapter: MailIntakeAdapter)\nHigh-level read-only ingestion interface.
NotesResponsibilities:
- 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.\nConstraints:
- This class is intentionally: Provider-agnostic, stateless beyond\n iteration scope, read-only.\nInitialize the mail reader.
Parameters:
Name Type Description Defaultadapter MailIntakeAdapter Mail adapter implementation used to retrieve raw messages and threads from a mail provider.
required"},{"location":"mail_intake/ingestion/#mail_intake.ingestion.MailIntakeReader-functions","title":"Functions","text":""},{"location":"mail_intake/ingestion/#mail_intake.ingestion.MailIntakeReader.iter_messages","title":"iter_messages","text":"iter_messages(query: str) -> Iterator[MailIntakeMessage]\nIterate over parsed messages matching a provider query.
Parameters:
Name Type Description Defaultquery str Provider-specific query string used to filter messages.
requiredYields:
Name Type DescriptionMailIntakeMessage MailIntakeMessage Fully parsed and normalized MailIntakeMessage instances.
Raises:
Type DescriptionMailIntakeParsingError If a message cannot be parsed.
"},{"location":"mail_intake/ingestion/#mail_intake.ingestion.MailIntakeReader.iter_threads","title":"iter_threads","text":"iter_threads(query: str) -> Iterator[MailIntakeThread]\nIterate over threads constructed from messages matching a query.
Parameters:
Name Type Description Defaultquery str Provider-specific query string used to filter messages.
requiredReturns:
Type DescriptionIterator[MailIntakeThread] Iterator[MailIntakeThread]: An iterator over MailIntakeThread instances.
Raises:
Type Description`MailIntakeParsingError` If a message cannot be parsed.
NotesGuarantees:
- Messages are grouped by `thread_id` and yielded as complete\n thread objects containing all associated messages.\nHigh-level mail ingestion orchestration for Mail Intake.
This module provides the primary, provider-agnostic entry point for reading and processing mail data.
It coordinates:
No provider-specific logic or API semantics are permitted in this layer.
"},{"location":"mail_intake/ingestion/reader/#mail_intake.ingestion.reader-classes","title":"Classes","text":""},{"location":"mail_intake/ingestion/reader/#mail_intake.ingestion.reader.MailIntakeReader","title":"MailIntakeReader","text":"MailIntakeReader(adapter: MailIntakeAdapter)\nHigh-level read-only ingestion interface.
NotesResponsibilities:
- 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.\nConstraints:
- This class is intentionally: Provider-agnostic, stateless beyond\n iteration scope, read-only.\nInitialize the mail reader.
Parameters:
Name Type Description Defaultadapter MailIntakeAdapter Mail adapter implementation used to retrieve raw messages and threads from a mail provider.
required"},{"location":"mail_intake/ingestion/reader/#mail_intake.ingestion.reader.MailIntakeReader-functions","title":"Functions","text":""},{"location":"mail_intake/ingestion/reader/#mail_intake.ingestion.reader.MailIntakeReader.iter_messages","title":"iter_messages","text":"iter_messages(query: str) -> Iterator[MailIntakeMessage]\nIterate over parsed messages matching a provider query.
Parameters:
Name Type Description Defaultquery str Provider-specific query string used to filter messages.
requiredYields:
Name Type DescriptionMailIntakeMessage MailIntakeMessage Fully parsed and normalized MailIntakeMessage instances.
Raises:
Type DescriptionMailIntakeParsingError If a message cannot be parsed.
"},{"location":"mail_intake/ingestion/reader/#mail_intake.ingestion.reader.MailIntakeReader.iter_threads","title":"iter_threads","text":"iter_threads(query: str) -> Iterator[MailIntakeThread]\nIterate over threads constructed from messages matching a query.
Parameters:
Name Type Description Defaultquery str Provider-specific query string used to filter messages.
requiredReturns:
Type DescriptionIterator[MailIntakeThread] Iterator[MailIntakeThread]: An iterator over MailIntakeThread instances.
Raises:
Type Description`MailIntakeParsingError` If a message cannot be parsed.
NotesGuarantees:
- Messages are grouped by `thread_id` and yielded as complete\n thread objects containing all associated messages.\nDomain models for Mail Intake.
This package defines the canonical, provider-agnostic data models used throughout the Mail Intake ingestion pipeline.
Models in this package:
These models form the core internal data contract of the library.
"},{"location":"mail_intake/models/#mail_intake.models--public-api","title":"Public API","text":"MailIntakeMessageMailIntakeThreaddataclass","text":"MailIntakeMessage(\n message_id: str,\n thread_id: str,\n timestamp: datetime,\n from_email: str,\n from_name: str | None,\n subject: str,\n body_text: str,\n snippet: str,\n raw_headers: dict[str, str],\n)\nCanonical internal representation of a single email message.
NotesGuarantees:
- 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.\nConstraints:
- No provider-specific identifiers, payloads, or API semantics\n should appear in this model.\ninstance-attribute","text":"body_text: str\nExtracted plain-text body content of the message.
"},{"location":"mail_intake/models/#mail_intake.models.MailIntakeMessage.from_email","title":"from_emailinstance-attribute","text":"from_email: str\nSender email address.
"},{"location":"mail_intake/models/#mail_intake.models.MailIntakeMessage.from_name","title":"from_nameinstance-attribute","text":"from_name: str | None\nOptional human-readable sender name.
"},{"location":"mail_intake/models/#mail_intake.models.MailIntakeMessage.message_id","title":"message_idinstance-attribute","text":"message_id: str\nProvider-specific message identifier.
"},{"location":"mail_intake/models/#mail_intake.models.MailIntakeMessage.raw_headers","title":"raw_headersinstance-attribute","text":"raw_headers: dict[str, str]\nNormalized mapping of message headers (header name \u2192 value).
"},{"location":"mail_intake/models/#mail_intake.models.MailIntakeMessage.snippet","title":"snippetinstance-attribute","text":"snippet: str\nShort provider-supplied preview snippet of the message.
"},{"location":"mail_intake/models/#mail_intake.models.MailIntakeMessage.subject","title":"subjectinstance-attribute","text":"subject: str\nRaw subject line of the message.
"},{"location":"mail_intake/models/#mail_intake.models.MailIntakeMessage.thread_id","title":"thread_idinstance-attribute","text":"thread_id: str\nProvider-specific thread identifier to which this message belongs.
"},{"location":"mail_intake/models/#mail_intake.models.MailIntakeMessage.timestamp","title":"timestampinstance-attribute","text":"timestamp: datetime\nMessage timestamp as a timezone-naive UTC datetime.
"},{"location":"mail_intake/models/#mail_intake.models.MailIntakeThread","title":"MailIntakeThreaddataclass","text":"MailIntakeThread(\n thread_id: str,\n normalized_subject: str,\n participants: set[str] = ...,\n messages: list[MailIntakeMessage] = ...,\n last_activity_at: datetime | None = ...,\n)\nCanonical internal representation of an email thread.
NotesGuarantees:
- 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.\nclass-attribute instance-attribute","text":"last_activity_at: datetime | None = None\nTimestamp of the most recent message in the thread.
"},{"location":"mail_intake/models/#mail_intake.models.MailIntakeThread.messages","title":"messagesclass-attribute instance-attribute","text":"messages: list[MailIntakeMessage] = field(\n default_factory=list\n)\nOrdered list of messages belonging to this thread.
"},{"location":"mail_intake/models/#mail_intake.models.MailIntakeThread.normalized_subject","title":"normalized_subjectinstance-attribute","text":"normalized_subject: str\nNormalized subject line used to group related messages.
"},{"location":"mail_intake/models/#mail_intake.models.MailIntakeThread.participants","title":"participantsclass-attribute instance-attribute","text":"participants: set[str] = field(default_factory=set)\nSet of unique participant email addresses observed in the thread.
"},{"location":"mail_intake/models/#mail_intake.models.MailIntakeThread.thread_id","title":"thread_idinstance-attribute","text":"thread_id: str\nProvider-specific thread identifier.
"},{"location":"mail_intake/models/#mail_intake.models.MailIntakeThread-functions","title":"Functions","text":""},{"location":"mail_intake/models/#mail_intake.models.MailIntakeThread.add_message","title":"add_message","text":"add_message(message: MailIntakeMessage) -> None\nAdd a message to the thread and update derived fields.
Parameters:
Name Type Description Defaultmessage MailIntakeMessage Parsed mail message to add to the thread.
required NotesResponsibilities:
- Appends the message to the thread.\n- Tracks unique participants.\n- Updates the last activity timestamp.\nMessage domain models for Mail Intake.
This module defines the canonical, provider-agnostic representation of an individual email message as used internally by the Mail Intake ingestion pipeline.
Models in this module are safe to persist and must not contain any provider-specific fields or semantics.
"},{"location":"mail_intake/models/message/#mail_intake.models.message-classes","title":"Classes","text":""},{"location":"mail_intake/models/message/#mail_intake.models.message.MailIntakeMessage","title":"MailIntakeMessagedataclass","text":"MailIntakeMessage(\n message_id: str,\n thread_id: str,\n timestamp: datetime,\n from_email: str,\n from_name: str | None,\n subject: str,\n body_text: str,\n snippet: str,\n raw_headers: dict[str, str],\n)\nCanonical internal representation of a single email message.
NotesGuarantees:
- 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.\nConstraints:
- No provider-specific identifiers, payloads, or API semantics\n should appear in this model.\ninstance-attribute","text":"body_text: str\nExtracted plain-text body content of the message.
"},{"location":"mail_intake/models/message/#mail_intake.models.message.MailIntakeMessage.from_email","title":"from_emailinstance-attribute","text":"from_email: str\nSender email address.
"},{"location":"mail_intake/models/message/#mail_intake.models.message.MailIntakeMessage.from_name","title":"from_nameinstance-attribute","text":"from_name: str | None\nOptional human-readable sender name.
"},{"location":"mail_intake/models/message/#mail_intake.models.message.MailIntakeMessage.message_id","title":"message_idinstance-attribute","text":"message_id: str\nProvider-specific message identifier.
"},{"location":"mail_intake/models/message/#mail_intake.models.message.MailIntakeMessage.raw_headers","title":"raw_headersinstance-attribute","text":"raw_headers: dict[str, str]\nNormalized mapping of message headers (header name \u2192 value).
"},{"location":"mail_intake/models/message/#mail_intake.models.message.MailIntakeMessage.snippet","title":"snippetinstance-attribute","text":"snippet: str\nShort provider-supplied preview snippet of the message.
"},{"location":"mail_intake/models/message/#mail_intake.models.message.MailIntakeMessage.subject","title":"subjectinstance-attribute","text":"subject: str\nRaw subject line of the message.
"},{"location":"mail_intake/models/message/#mail_intake.models.message.MailIntakeMessage.thread_id","title":"thread_idinstance-attribute","text":"thread_id: str\nProvider-specific thread identifier to which this message belongs.
"},{"location":"mail_intake/models/message/#mail_intake.models.message.MailIntakeMessage.timestamp","title":"timestampinstance-attribute","text":"timestamp: datetime\nMessage timestamp as a timezone-naive UTC datetime.
"},{"location":"mail_intake/models/thread/","title":"Thread","text":""},{"location":"mail_intake/models/thread/#mail_intake.models.thread","title":"mail_intake.models.thread","text":""},{"location":"mail_intake/models/thread/#mail_intake.models.thread--summary","title":"Summary","text":"Thread domain models for Mail Intake.
This module defines the canonical, provider-agnostic representation of an email thread as used internally by the Mail Intake ingestion pipeline.
Threads group related messages and serve as the primary unit of reasoning for higher-level correspondence workflows.
"},{"location":"mail_intake/models/thread/#mail_intake.models.thread-classes","title":"Classes","text":""},{"location":"mail_intake/models/thread/#mail_intake.models.thread.MailIntakeThread","title":"MailIntakeThreaddataclass","text":"MailIntakeThread(\n thread_id: str,\n normalized_subject: str,\n participants: set[str] = ...,\n messages: list[MailIntakeMessage] = ...,\n last_activity_at: datetime | None = ...,\n)\nCanonical internal representation of an email thread.
NotesGuarantees:
- 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.\nclass-attribute instance-attribute","text":"last_activity_at: datetime | None = None\nTimestamp of the most recent message in the thread.
"},{"location":"mail_intake/models/thread/#mail_intake.models.thread.MailIntakeThread.messages","title":"messagesclass-attribute instance-attribute","text":"messages: list[MailIntakeMessage] = field(\n default_factory=list\n)\nOrdered list of messages belonging to this thread.
"},{"location":"mail_intake/models/thread/#mail_intake.models.thread.MailIntakeThread.normalized_subject","title":"normalized_subjectinstance-attribute","text":"normalized_subject: str\nNormalized subject line used to group related messages.
"},{"location":"mail_intake/models/thread/#mail_intake.models.thread.MailIntakeThread.participants","title":"participantsclass-attribute instance-attribute","text":"participants: set[str] = field(default_factory=set)\nSet of unique participant email addresses observed in the thread.
"},{"location":"mail_intake/models/thread/#mail_intake.models.thread.MailIntakeThread.thread_id","title":"thread_idinstance-attribute","text":"thread_id: str\nProvider-specific thread identifier.
"},{"location":"mail_intake/models/thread/#mail_intake.models.thread.MailIntakeThread-functions","title":"Functions","text":""},{"location":"mail_intake/models/thread/#mail_intake.models.thread.MailIntakeThread.add_message","title":"add_message","text":"add_message(message: MailIntakeMessage) -> None\nAdd a message to the thread and update derived fields.
Parameters:
Name Type Description Defaultmessage MailIntakeMessage Parsed mail message to add to the thread.
required NotesResponsibilities:
- Appends the message to the thread.\n- Tracks unique participants.\n- Updates the last activity timestamp.\nMessage parsing utilities for Mail Intake.
This package contains provider-aware but adapter-agnostic parsing helpers used to extract and normalize structured information from raw mail payloads.
Parsers in this package are responsible for:
This package does not:
Parsing functions are designed to be composable and are orchestrated by the ingestion layer.
"},{"location":"mail_intake/parsers/#mail_intake.parsers--public-api","title":"Public API","text":"extract_bodyparse_headersextract_sendernormalize_subjectextract_body(payload: dict[str, Any]) -> str\nExtract the best-effort message body from a Gmail payload.
Priority:
text/plaintext/html (stripped to text)Parameters:
Name Type Description Defaultpayload dict[str, Any] Provider-native message payload dictionary.
requiredReturns:
Name Type Descriptionstr str Extracted plain-text message body.
"},{"location":"mail_intake/parsers/#mail_intake.parsers.extract_sender","title":"extract_sender","text":"extract_sender(\n headers: dict[str, str],\n) -> tuple[str, str | None]\nExtract sender email and optional display name from headers.
Parameters:
Name Type Description Defaultheaders dict[str, str] Normalized header dictionary as returned by parse_headers().
Returns:
Type Descriptiontuple[str, str | None] tuple[str, str | None]: A tuple (email, name) where email is the sender email address and name is the display name, or None if unavailable.
Responsibilities:
- This function parses the `From` header and attempts to extract\n sender email address and optional human-readable display name.\nTypical values:
\"John Doe <john@example.com>\" -> (\"john@example.com\", \"John Doe\")\"john@example.com\" -> (\"john@example.com\", None)normalize_subject(subject: str) -> str\nNormalize an email subject for thread-level comparison.
Parameters:
Name Type Description Defaultsubject str Raw subject line from a message header.
requiredReturns:
Name Type Descriptionstr str Normalized subject string suitable for thread grouping.
NotesResponsibilities:
- 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).\nGuarantees:
- This function is intentionally conservative and avoids aggressive\n transformations that could alter the semantic meaning of the subject.\nparse_headers(\n raw_headers: list[dict[str, str]],\n) -> dict[str, str]\nConvert a list of Gmail-style headers into a normalized dict.
Parameters:
Name Type Description Defaultraw_headers list[dict[str, str]] List of header dictionaries, each containing name and value keys.
Returns:
Type Descriptiondict[str, str] dict[str, str]: Dictionary mapping lowercase header names to stripped values.
NotesGuarantees:
- 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.\nTypical usage:
Input:\n [\n {\"name\": \"From\", \"value\": \"John Doe <john@example.com>\"},\n {\"name\": \"Subject\", \"value\": \"Re: Interview Update\"},\n ]\n\nOutput:\n {\n \"from\": \"John Doe <john@example.com>\",\n \"subject\": \"Re: Interview Update\",\n }\nMessage body extraction utilities for Mail Intake.
This module contains helper functions for extracting a best-effort plain-text body from provider-native message payloads.
The logic is intentionally tolerant of malformed or partial data and prefers human-readable text over fidelity to original formatting.
"},{"location":"mail_intake/parsers/body/#mail_intake.parsers.body-classes","title":"Classes","text":""},{"location":"mail_intake/parsers/body/#mail_intake.parsers.body-functions","title":"Functions","text":""},{"location":"mail_intake/parsers/body/#mail_intake.parsers.body.extract_body","title":"extract_body","text":"extract_body(payload: dict[str, Any]) -> str\nExtract the best-effort message body from a Gmail payload.
Priority:
text/plaintext/html (stripped to text)Parameters:
Name Type Description Defaultpayload dict[str, Any] Provider-native message payload dictionary.
requiredReturns:
Name Type Descriptionstr str Extracted plain-text message body.
"},{"location":"mail_intake/parsers/headers/","title":"Headers","text":""},{"location":"mail_intake/parsers/headers/#mail_intake.parsers.headers","title":"mail_intake.parsers.headers","text":""},{"location":"mail_intake/parsers/headers/#mail_intake.parsers.headers--summary","title":"Summary","text":"Message header parsing utilities for Mail Intake.
This module provides helper functions for normalizing and extracting useful information from provider-native message headers.
The functions here are intentionally simple and tolerant of malformed or incomplete header data.
"},{"location":"mail_intake/parsers/headers/#mail_intake.parsers.headers-functions","title":"Functions","text":""},{"location":"mail_intake/parsers/headers/#mail_intake.parsers.headers.extract_sender","title":"extract_sender","text":"extract_sender(\n headers: dict[str, str],\n) -> tuple[str, str | None]\nExtract sender email and optional display name from headers.
Parameters:
Name Type Description Defaultheaders dict[str, str] Normalized header dictionary as returned by parse_headers().
Returns:
Type Descriptiontuple[str, str | None] tuple[str, str | None]: A tuple (email, name) where email is the sender email address and name is the display name, or None if unavailable.
Responsibilities:
- This function parses the `From` header and attempts to extract\n sender email address and optional human-readable display name.\nTypical values:
\"John Doe <john@example.com>\" -> (\"john@example.com\", \"John Doe\")\"john@example.com\" -> (\"john@example.com\", None)parse_headers(\n raw_headers: list[dict[str, str]],\n) -> dict[str, str]\nConvert a list of Gmail-style headers into a normalized dict.
Parameters:
Name Type Description Defaultraw_headers list[dict[str, str]] List of header dictionaries, each containing name and value keys.
Returns:
Type Descriptiondict[str, str] dict[str, str]: Dictionary mapping lowercase header names to stripped values.
NotesGuarantees:
- 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.\nTypical usage:
Input:\n [\n {\"name\": \"From\", \"value\": \"John Doe <john@example.com>\"},\n {\"name\": \"Subject\", \"value\": \"Re: Interview Update\"},\n ]\n\nOutput:\n {\n \"from\": \"John Doe <john@example.com>\",\n \"subject\": \"Re: Interview Update\",\n }\nSubject line normalization utilities for Mail Intake.
This module provides helper functions for normalizing email subject lines to enable reliable thread-level comparison and grouping.
Normalization is intentionally conservative to avoid altering semantic meaning while removing common reply and forward prefixes.
"},{"location":"mail_intake/parsers/subject/#mail_intake.parsers.subject-functions","title":"Functions","text":""},{"location":"mail_intake/parsers/subject/#mail_intake.parsers.subject.normalize_subject","title":"normalize_subject","text":"normalize_subject(subject: str) -> str\nNormalize an email subject for thread-level comparison.
Parameters:
Name Type Description Defaultsubject str Raw subject line from a message header.
requiredReturns:
Name Type Descriptionstr str Normalized subject string suitable for thread grouping.
NotesResponsibilities:
- 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).\nGuarantees:
- This function is intentionally conservative and avoids aggressive\n transformations that could alter the semantic meaning of the subject.\nDomain models for Mail Intake.
This package defines the canonical, provider-agnostic data models used throughout the Mail Intake ingestion pipeline.
Models in this package:
These models form the core internal data contract of the library.
"},{"location":"models/#mail_intake.models--public-api","title":"Public API","text":"MailIntakeMessageMailIntakeThreaddataclass","text":"MailIntakeMessage(\n message_id: str,\n thread_id: str,\n timestamp: datetime,\n from_email: str,\n from_name: str | None,\n subject: str,\n body_text: str,\n snippet: str,\n raw_headers: dict[str, str],\n)\nCanonical internal representation of a single email message.
NotesGuarantees:
- 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.\nConstraints:
- No provider-specific identifiers, payloads, or API semantics\n should appear in this model.\ninstance-attribute","text":"body_text: str\nExtracted plain-text body content of the message.
"},{"location":"models/#mail_intake.models.MailIntakeMessage.from_email","title":"from_emailinstance-attribute","text":"from_email: str\nSender email address.
"},{"location":"models/#mail_intake.models.MailIntakeMessage.from_name","title":"from_nameinstance-attribute","text":"from_name: str | None\nOptional human-readable sender name.
"},{"location":"models/#mail_intake.models.MailIntakeMessage.message_id","title":"message_idinstance-attribute","text":"message_id: str\nProvider-specific message identifier.
"},{"location":"models/#mail_intake.models.MailIntakeMessage.raw_headers","title":"raw_headersinstance-attribute","text":"raw_headers: dict[str, str]\nNormalized mapping of message headers (header name \u2192 value).
"},{"location":"models/#mail_intake.models.MailIntakeMessage.snippet","title":"snippetinstance-attribute","text":"snippet: str\nShort provider-supplied preview snippet of the message.
"},{"location":"models/#mail_intake.models.MailIntakeMessage.subject","title":"subjectinstance-attribute","text":"subject: str\nRaw subject line of the message.
"},{"location":"models/#mail_intake.models.MailIntakeMessage.thread_id","title":"thread_idinstance-attribute","text":"thread_id: str\nProvider-specific thread identifier to which this message belongs.
"},{"location":"models/#mail_intake.models.MailIntakeMessage.timestamp","title":"timestampinstance-attribute","text":"timestamp: datetime\nMessage timestamp as a timezone-naive UTC datetime.
"},{"location":"models/#mail_intake.models.MailIntakeThread","title":"MailIntakeThreaddataclass","text":"MailIntakeThread(\n thread_id: str,\n normalized_subject: str,\n participants: set[str] = ...,\n messages: list[MailIntakeMessage] = ...,\n last_activity_at: datetime | None = ...,\n)\nCanonical internal representation of an email thread.
NotesGuarantees:
- 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.\nclass-attribute instance-attribute","text":"last_activity_at: datetime | None = None\nTimestamp of the most recent message in the thread.
"},{"location":"models/#mail_intake.models.MailIntakeThread.messages","title":"messagesclass-attribute instance-attribute","text":"messages: list[MailIntakeMessage] = field(\n default_factory=list\n)\nOrdered list of messages belonging to this thread.
"},{"location":"models/#mail_intake.models.MailIntakeThread.normalized_subject","title":"normalized_subjectinstance-attribute","text":"normalized_subject: str\nNormalized subject line used to group related messages.
"},{"location":"models/#mail_intake.models.MailIntakeThread.participants","title":"participantsclass-attribute instance-attribute","text":"participants: set[str] = field(default_factory=set)\nSet of unique participant email addresses observed in the thread.
"},{"location":"models/#mail_intake.models.MailIntakeThread.thread_id","title":"thread_idinstance-attribute","text":"thread_id: str\nProvider-specific thread identifier.
"},{"location":"models/#mail_intake.models.MailIntakeThread-functions","title":"Functions","text":""},{"location":"models/#mail_intake.models.MailIntakeThread.add_message","title":"add_message","text":"add_message(message: MailIntakeMessage) -> None\nAdd a message to the thread and update derived fields.
Parameters:
Name Type Description Defaultmessage MailIntakeMessage Parsed mail message to add to the thread.
required NotesResponsibilities:
- Appends the message to the thread.\n- Tracks unique participants.\n- Updates the last activity timestamp.\nMessage domain models for Mail Intake.
This module defines the canonical, provider-agnostic representation of an individual email message as used internally by the Mail Intake ingestion pipeline.
Models in this module are safe to persist and must not contain any provider-specific fields or semantics.
"},{"location":"models/message/#mail_intake.models.message-classes","title":"Classes","text":""},{"location":"models/message/#mail_intake.models.message.MailIntakeMessage","title":"MailIntakeMessagedataclass","text":"MailIntakeMessage(\n message_id: str,\n thread_id: str,\n timestamp: datetime,\n from_email: str,\n from_name: str | None,\n subject: str,\n body_text: str,\n snippet: str,\n raw_headers: dict[str, str],\n)\nCanonical internal representation of a single email message.
NotesGuarantees:
- 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.\nConstraints:
- No provider-specific identifiers, payloads, or API semantics\n should appear in this model.\ninstance-attribute","text":"body_text: str\nExtracted plain-text body content of the message.
"},{"location":"models/message/#mail_intake.models.message.MailIntakeMessage.from_email","title":"from_emailinstance-attribute","text":"from_email: str\nSender email address.
"},{"location":"models/message/#mail_intake.models.message.MailIntakeMessage.from_name","title":"from_nameinstance-attribute","text":"from_name: str | None\nOptional human-readable sender name.
"},{"location":"models/message/#mail_intake.models.message.MailIntakeMessage.message_id","title":"message_idinstance-attribute","text":"message_id: str\nProvider-specific message identifier.
"},{"location":"models/message/#mail_intake.models.message.MailIntakeMessage.raw_headers","title":"raw_headersinstance-attribute","text":"raw_headers: dict[str, str]\nNormalized mapping of message headers (header name \u2192 value).
"},{"location":"models/message/#mail_intake.models.message.MailIntakeMessage.snippet","title":"snippetinstance-attribute","text":"snippet: str\nShort provider-supplied preview snippet of the message.
"},{"location":"models/message/#mail_intake.models.message.MailIntakeMessage.subject","title":"subjectinstance-attribute","text":"subject: str\nRaw subject line of the message.
"},{"location":"models/message/#mail_intake.models.message.MailIntakeMessage.thread_id","title":"thread_idinstance-attribute","text":"thread_id: str\nProvider-specific thread identifier to which this message belongs.
"},{"location":"models/message/#mail_intake.models.message.MailIntakeMessage.timestamp","title":"timestampinstance-attribute","text":"timestamp: datetime\nMessage timestamp as a timezone-naive UTC datetime.
"},{"location":"models/thread/","title":"Thread","text":""},{"location":"models/thread/#mail_intake.models.thread","title":"mail_intake.models.thread","text":""},{"location":"models/thread/#mail_intake.models.thread--summary","title":"Summary","text":"Thread domain models for Mail Intake.
This module defines the canonical, provider-agnostic representation of an email thread as used internally by the Mail Intake ingestion pipeline.
Threads group related messages and serve as the primary unit of reasoning for higher-level correspondence workflows.
"},{"location":"models/thread/#mail_intake.models.thread-classes","title":"Classes","text":""},{"location":"models/thread/#mail_intake.models.thread.MailIntakeThread","title":"MailIntakeThreaddataclass","text":"MailIntakeThread(\n thread_id: str,\n normalized_subject: str,\n participants: set[str] = ...,\n messages: list[MailIntakeMessage] = ...,\n last_activity_at: datetime | None = ...,\n)\nCanonical internal representation of an email thread.
NotesGuarantees:
- 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.\nclass-attribute instance-attribute","text":"last_activity_at: datetime | None = None\nTimestamp of the most recent message in the thread.
"},{"location":"models/thread/#mail_intake.models.thread.MailIntakeThread.messages","title":"messagesclass-attribute instance-attribute","text":"messages: list[MailIntakeMessage] = field(\n default_factory=list\n)\nOrdered list of messages belonging to this thread.
"},{"location":"models/thread/#mail_intake.models.thread.MailIntakeThread.normalized_subject","title":"normalized_subjectinstance-attribute","text":"normalized_subject: str\nNormalized subject line used to group related messages.
"},{"location":"models/thread/#mail_intake.models.thread.MailIntakeThread.participants","title":"participantsclass-attribute instance-attribute","text":"participants: set[str] = field(default_factory=set)\nSet of unique participant email addresses observed in the thread.
"},{"location":"models/thread/#mail_intake.models.thread.MailIntakeThread.thread_id","title":"thread_idinstance-attribute","text":"thread_id: str\nProvider-specific thread identifier.
"},{"location":"models/thread/#mail_intake.models.thread.MailIntakeThread-functions","title":"Functions","text":""},{"location":"models/thread/#mail_intake.models.thread.MailIntakeThread.add_message","title":"add_message","text":"add_message(message: MailIntakeMessage) -> None\nAdd a message to the thread and update derived fields.
Parameters:
Name Type Description Defaultmessage MailIntakeMessage Parsed mail message to add to the thread.
required NotesResponsibilities:
- Appends the message to the thread.\n- Tracks unique participants.\n- Updates the last activity timestamp.\nMessage parsing utilities for Mail Intake.
This package contains provider-aware but adapter-agnostic parsing helpers used to extract and normalize structured information from raw mail payloads.
Parsers in this package are responsible for:
This package does not:
Parsing functions are designed to be composable and are orchestrated by the ingestion layer.
"},{"location":"parsers/#mail_intake.parsers--public-api","title":"Public API","text":"extract_bodyparse_headersextract_sendernormalize_subjectextract_body(payload: dict[str, Any]) -> str\nExtract the best-effort message body from a Gmail payload.
Priority:
text/plaintext/html (stripped to text)Parameters:
Name Type Description Defaultpayload dict[str, Any] Provider-native message payload dictionary.
requiredReturns:
Name Type Descriptionstr str Extracted plain-text message body.
"},{"location":"parsers/#mail_intake.parsers.extract_sender","title":"extract_sender","text":"extract_sender(\n headers: dict[str, str],\n) -> tuple[str, str | None]\nExtract sender email and optional display name from headers.
Parameters:
Name Type Description Defaultheaders dict[str, str] Normalized header dictionary as returned by parse_headers().
Returns:
Type Descriptiontuple[str, str | None] tuple[str, str | None]: A tuple (email, name) where email is the sender email address and name is the display name, or None if unavailable.
Responsibilities:
- This function parses the `From` header and attempts to extract\n sender email address and optional human-readable display name.\nTypical values:
\"John Doe <john@example.com>\" -> (\"john@example.com\", \"John Doe\")\"john@example.com\" -> (\"john@example.com\", None)normalize_subject(subject: str) -> str\nNormalize an email subject for thread-level comparison.
Parameters:
Name Type Description Defaultsubject str Raw subject line from a message header.
requiredReturns:
Name Type Descriptionstr str Normalized subject string suitable for thread grouping.
NotesResponsibilities:
- 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).\nGuarantees:
- This function is intentionally conservative and avoids aggressive\n transformations that could alter the semantic meaning of the subject.\nparse_headers(\n raw_headers: list[dict[str, str]],\n) -> dict[str, str]\nConvert a list of Gmail-style headers into a normalized dict.
Parameters:
Name Type Description Defaultraw_headers list[dict[str, str]] List of header dictionaries, each containing name and value keys.
Returns:
Type Descriptiondict[str, str] dict[str, str]: Dictionary mapping lowercase header names to stripped values.
NotesGuarantees:
- 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.\nTypical usage:
Input:\n [\n {\"name\": \"From\", \"value\": \"John Doe <john@example.com>\"},\n {\"name\": \"Subject\", \"value\": \"Re: Interview Update\"},\n ]\n\nOutput:\n {\n \"from\": \"John Doe <john@example.com>\",\n \"subject\": \"Re: Interview Update\",\n }\nMessage body extraction utilities for Mail Intake.
This module contains helper functions for extracting a best-effort plain-text body from provider-native message payloads.
The logic is intentionally tolerant of malformed or partial data and prefers human-readable text over fidelity to original formatting.
"},{"location":"parsers/body/#mail_intake.parsers.body-classes","title":"Classes","text":""},{"location":"parsers/body/#mail_intake.parsers.body-functions","title":"Functions","text":""},{"location":"parsers/body/#mail_intake.parsers.body.extract_body","title":"extract_body","text":"extract_body(payload: dict[str, Any]) -> str\nExtract the best-effort message body from a Gmail payload.
Priority:
text/plaintext/html (stripped to text)Parameters:
Name Type Description Defaultpayload dict[str, Any] Provider-native message payload dictionary.
requiredReturns:
Name Type Descriptionstr str Extracted plain-text message body.
"},{"location":"parsers/headers/","title":"Headers","text":""},{"location":"parsers/headers/#mail_intake.parsers.headers","title":"mail_intake.parsers.headers","text":""},{"location":"parsers/headers/#mail_intake.parsers.headers--summary","title":"Summary","text":"Message header parsing utilities for Mail Intake.
This module provides helper functions for normalizing and extracting useful information from provider-native message headers.
The functions here are intentionally simple and tolerant of malformed or incomplete header data.
"},{"location":"parsers/headers/#mail_intake.parsers.headers-functions","title":"Functions","text":""},{"location":"parsers/headers/#mail_intake.parsers.headers.extract_sender","title":"extract_sender","text":"extract_sender(\n headers: dict[str, str],\n) -> tuple[str, str | None]\nExtract sender email and optional display name from headers.
Parameters:
Name Type Description Defaultheaders dict[str, str] Normalized header dictionary as returned by parse_headers().
Returns:
Type Descriptiontuple[str, str | None] tuple[str, str | None]: A tuple (email, name) where email is the sender email address and name is the display name, or None if unavailable.
Responsibilities:
- This function parses the `From` header and attempts to extract\n sender email address and optional human-readable display name.\nTypical values:
\"John Doe <john@example.com>\" -> (\"john@example.com\", \"John Doe\")\"john@example.com\" -> (\"john@example.com\", None)parse_headers(\n raw_headers: list[dict[str, str]],\n) -> dict[str, str]\nConvert a list of Gmail-style headers into a normalized dict.
Parameters:
Name Type Description Defaultraw_headers list[dict[str, str]] List of header dictionaries, each containing name and value keys.
Returns:
Type Descriptiondict[str, str] dict[str, str]: Dictionary mapping lowercase header names to stripped values.
NotesGuarantees:
- 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.\nTypical usage:
Input:\n [\n {\"name\": \"From\", \"value\": \"John Doe <john@example.com>\"},\n {\"name\": \"Subject\", \"value\": \"Re: Interview Update\"},\n ]\n\nOutput:\n {\n \"from\": \"John Doe <john@example.com>\",\n \"subject\": \"Re: Interview Update\",\n }\nSubject line normalization utilities for Mail Intake.
This module provides helper functions for normalizing email subject lines to enable reliable thread-level comparison and grouping.
Normalization is intentionally conservative to avoid altering semantic meaning while removing common reply and forward prefixes.
"},{"location":"parsers/subject/#mail_intake.parsers.subject-functions","title":"Functions","text":""},{"location":"parsers/subject/#mail_intake.parsers.subject.normalize_subject","title":"normalize_subject","text":"normalize_subject(subject: str) -> str\nNormalize an email subject for thread-level comparison.
Parameters:
Name Type Description Defaultsubject str Raw subject line from a message header.
requiredReturns:
Name Type Descriptionstr str Normalized subject string suitable for thread grouping.
NotesResponsibilities:
- 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).\nGuarantees:
- This function is intentionally conservative and avoids aggressive\n transformations that could alter the semantic meaning of the subject.\nMail Intake \u2014 provider-agnostic, read-only email ingestion framework.
Mail Intake is a contract-first library designed to ingest, parse, and normalize email data from external providers (such as Gmail) into clean, provider-agnostic domain models.
The library is intentionally structured around clear layers, each exposed as a first-class module at the package root:
adapters: Provider-specific access (e.g., Gmail).auth: Authentication providers and credential lifecycle management.credentials: Credential persistence abstractions and implementations.parsers: Extraction and normalization of message content.ingestion: Orchestration and high-level ingestion workflows.models: Canonical, provider-agnostic data representations.config: Explicit global configuration.exceptions: Library-defined error hierarchy.The package root acts as a namespace, not a facade. Consumers are expected to import functionality explicitly from the appropriate module.
"},{"location":"#mail_intake--installation","title":"Installation","text":"Install using pip:
pip install mail-intake\nOr with Poetry:
poetry add mail-intake\nMail Intake is pure Python and has no runtime dependencies beyond those required by the selected provider (for example, Google APIs for Gmail).
"},{"location":"#mail_intake--quick-start","title":"Quick Start","text":"Minimal Gmail ingestion example (local development):
from mail_intake.ingestion import MailIntakeReader\nfrom mail_intake.adapters import MailIntakeGmailAdapter\nfrom mail_intake.auth import MailIntakeGoogleAuth\nfrom mail_intake.credentials import PickleCredentialStore\n\nstore = PickleCredentialStore(path=\"token.pickle\")\n\nauth = MailIntakeGoogleAuth(\n credentials_path=\"credentials.json\",\n store=store,\n scopes=[\"https://www.googleapis.com/auth/gmail.readonly\"],\n)\n\nadapter = MailIntakeGmailAdapter(auth_provider=auth)\nreader = MailIntakeReader(adapter)\n\nfor message in reader.iter_messages(\"from:recruiter@example.com\"):\n print(message.subject, message.from_email)\nIterating over threads:
for thread in reader.iter_threads(\"subject:Interview\"):\n print(thread.normalized_subject, len(thread.messages))\nMail Intake is designed to be extensible via public contracts exposed through its modules:
adapters.MailIntakeAdapter.auth.MailIntakeAuthProvider[T].credentials.CredentialStore[T].Users SHOULD NOT subclass built-in adapter implementations. Built-in adapters (such as Gmail) are reference implementations and may change internally without notice.
Design Guarantees:
Mail Intake favors correctness, clarity, and explicitness over convenience shortcuts.
Core Philosophy:
Mail Intake is built as a contract-first ingestion pipeline:
The supported public API consists of the following top-level modules:
mail_intake.ingestionmail_intake.adaptersmail_intake.authmail_intake.credentialsmail_intake.parsersmail_intake.modelsmail_intake.configmail_intake.exceptionsClasses and functions should be imported explicitly from these modules. No individual symbols are re-exported at the package root.
"},{"location":"config/","title":"Config","text":""},{"location":"config/#mail_intake.config","title":"mail_intake.config","text":""},{"location":"config/#mail_intake.config--summary","title":"Summary","text":"Global configuration models for Mail Intake.
This module defines the top-level configuration object used to control mail ingestion behavior across adapters, authentication providers, and ingestion workflows.
Configuration is intentionally explicit, immutable, and free of implicit environment reads to ensure predictability and testability.
"},{"location":"config/#mail_intake.config-classes","title":"Classes","text":""},{"location":"config/#mail_intake.config.MailIntakeConfig","title":"MailIntakeConfigdataclass","text":"MailIntakeConfig(\n provider: str = ...,\n user_id: str = ...,\n readonly: bool = ...,\n credentials_path: str | None = ...,\n token_path: str | None = ...,\n)\nGlobal configuration for mail-intake.
Guarantees:
- 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.\nclass-attribute instance-attribute","text":"credentials_path: str | None = None\nOptional path to provider credentials configuration.
"},{"location":"config/#mail_intake.config.MailIntakeConfig.provider","title":"providerclass-attribute instance-attribute","text":"provider: str = 'gmail'\nIdentifier of the mail provider to use (e.g., \"gmail\").
class-attribute instance-attribute","text":"readonly: bool = True\nWhether ingestion should operate in read-only mode.
"},{"location":"config/#mail_intake.config.MailIntakeConfig.token_path","title":"token_pathclass-attribute instance-attribute","text":"token_path: str | None = None\nOptional path to persisted authentication tokens.
"},{"location":"config/#mail_intake.config.MailIntakeConfig.user_id","title":"user_idclass-attribute instance-attribute","text":"user_id: str = 'me'\nProvider-specific user identifier. Defaults to the authenticated user.
"},{"location":"exceptions/","title":"Exceptions","text":""},{"location":"exceptions/#mail_intake.exceptions","title":"mail_intake.exceptions","text":""},{"location":"exceptions/#mail_intake.exceptions--summary","title":"Summary","text":"Exception hierarchy for Mail Intake.
This module defines the canonical exception types used throughout the Mail Intake library.
All library-raised errors derive from MailIntakeError. Consumers are encouraged to catch this base type (or specific subclasses) rather than provider-specific or third-party exceptions.
Bases: MailIntakeError
Errors raised by mail provider adapters.
NotesLifecycle:
- Raised when a provider adapter encounters API errors, transport\n failures, or invalid provider responses.\n Bases: MailIntakeError
Authentication and credential-related failures.
NotesLifecycle:
- Raised when authentication providers are unable to acquire,\n refresh, or persist valid credentials.\n Bases: Exception
Base exception for all Mail Intake errors.
NotesGuarantees:
- 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\n Bases: MailIntakeError
Errors encountered while parsing message content.
NotesLifecycle:
- Raised when raw provider payloads cannot be interpreted or\n normalized into internal domain models.\nMail provider adapter implementations for Mail Intake.
This package contains adapter-layer implementations responsible for interfacing with external mail providers and exposing a normalized, provider-agnostic contract to the rest of the system.
Adapters in this package:
MailIntakeAdapter interface.Provider-specific logic must not leak outside of adapter implementations. All parsings, normalizations, and transformations must be handled by downstream components.
"},{"location":"adapters/#mail_intake.adapters--public-api","title":"Public API","text":"MailIntakeAdapterMailIntakeGmailAdapter Bases: ABC
Base adapter interface for mail providers.
NotesGuarantees:
- Discover messages matching a query.\n- Retrieve full message payloads.\n- Retrieve full thread payloads.\nLifecycle:
- Adapters are intentionally read-only and must not mutate provider state.\nabstractmethod","text":"fetch_message(message_id: str) -> dict[str, Any]\nFetch a full raw message by message identifier.
Parameters:
Name Type Description Defaultmessage_id str Provider-specific message identifier.
requiredReturns:
Type Descriptiondict[str, Any] dict[str, Any]: Provider-native message payload (e.g., Gmail message JSON structure).
"},{"location":"adapters/#mail_intake.adapters.MailIntakeAdapter.fetch_thread","title":"fetch_threadabstractmethod","text":"fetch_thread(thread_id: str) -> dict[str, Any]\nFetch a full raw thread by thread identifier.
Parameters:
Name Type Description Defaultthread_id str Provider-specific thread identifier.
requiredReturns:
Type Descriptiondict[str, Any] dict[str, Any]: Provider-native thread payload.
"},{"location":"adapters/#mail_intake.adapters.MailIntakeAdapter.iter_message_refs","title":"iter_message_refsabstractmethod","text":"iter_message_refs(query: str) -> Iterator[dict[str, str]]\nIterate over lightweight message references matching a query.
Parameters:
Name Type Description Defaultquery str Provider-specific query string used to filter messages.
requiredReturns:
Type DescriptionIterator[dict[str, str]] Iterator[dict[str, str]]: An iterator over lightweight message reference dictionaries.
Yields:
Type Descriptiondict[str, str] dict[str, str]: Dictionaries containing message and thread identifiers.
NotesGuarantees:
- Implementations must yield dictionaries containing at least\n `message_id` and `thread_id`.\nTypical yield:
{\n \"message_id\": \"...\",\n \"thread_id\": \"...\"\n}\nMailIntakeGmailAdapter(\n auth_provider: MailIntakeAuthProvider[Any],\n user_id: str = \"me\",\n)\n Bases: MailIntakeAdapter
Gmail read-only adapter.
This adapter implements the MailIntakeAdapter interface using the Gmail REST API. It translates the generic mail intake contract into Gmail-specific API calls.
Responsibilities:
- This class is the ONLY place where `googleapiclient` is imported.\n- Gmail REST semantics are known.\n- `.execute()` is called.\nConstraints:
- Must remain thin and imperative.\n- Must not perform parsing or interpretation.\n- Must not expose Gmail-specific types beyond this class.\nInitialize the Gmail adapter.
Parameters:
Name Type Description Defaultauth_provider MailIntakeAuthProvider Authentication provider capable of supplying valid Gmail API credentials.
requireduser_id str Gmail user identifier. Defaults to \"me\".
'me'"},{"location":"adapters/#mail_intake.adapters.MailIntakeGmailAdapter-attributes","title":"Attributes","text":""},{"location":"adapters/#mail_intake.adapters.MailIntakeGmailAdapter.service","title":"service property","text":"service: Any\nLazily initialize and return the Gmail API service client.
Raises:
Type DescriptionMailIntakeAdapterError If the Gmail service cannot be initialized.
"},{"location":"adapters/#mail_intake.adapters.MailIntakeGmailAdapter-functions","title":"Functions","text":""},{"location":"adapters/#mail_intake.adapters.MailIntakeGmailAdapter.fetch_message","title":"fetch_message","text":"fetch_message(message_id: str) -> dict[str, Any]\nFetch a full Gmail message by message ID.
Parameters:
Name Type Description Defaultmessage_id str Gmail message identifier.
requiredReturns:
Type Descriptiondict[str, Any] dict[str, Any]: Provider-native Gmail message payload.
Raises:
Type DescriptionMailIntakeAdapterError If the Gmail API returns an error.
"},{"location":"adapters/#mail_intake.adapters.MailIntakeGmailAdapter.fetch_thread","title":"fetch_thread","text":"fetch_thread(thread_id: str) -> dict[str, Any]\nFetch a full Gmail thread by thread ID.
Parameters:
Name Type Description Defaultthread_id str Gmail thread identifier.
requiredReturns:
Type Descriptiondict[str, Any] dict[str, Any]: Provider-native Gmail thread payload.
Raises:
Type DescriptionMailIntakeAdapterError If the Gmail API returns an error.
"},{"location":"adapters/#mail_intake.adapters.MailIntakeGmailAdapter.iter_message_refs","title":"iter_message_refs","text":"iter_message_refs(query: str) -> Iterator[dict[str, str]]\nIterate over message references matching the query.
Parameters:
Name Type Description Defaultquery str Gmail search query string.
requiredYields:
Type Descriptiondict[str, str] dict[str, str]: Dictionaries containing message_id and thread_id.
Raises:
Type DescriptionMailIntakeAdapterError If the Gmail API returns an error.
"},{"location":"adapters/base/","title":"Base","text":""},{"location":"adapters/base/#mail_intake.adapters.base","title":"mail_intake.adapters.base","text":""},{"location":"adapters/base/#mail_intake.adapters.base--summary","title":"Summary","text":"Mail provider adapter contracts for Mail Intake.
This module defines the provider-agnostic adapter interface used for read-only mail ingestion.
Adapters encapsulate all provider-specific access logic and expose a minimal, normalized contract to the rest of the system. No provider-specific types or semantics should leak beyond implementations of this interface.
"},{"location":"adapters/base/#mail_intake.adapters.base-classes","title":"Classes","text":""},{"location":"adapters/base/#mail_intake.adapters.base.MailIntakeAdapter","title":"MailIntakeAdapter","text":" Bases: ABC
Base adapter interface for mail providers.
NotesGuarantees:
- Discover messages matching a query.\n- Retrieve full message payloads.\n- Retrieve full thread payloads.\nLifecycle:
- Adapters are intentionally read-only and must not mutate provider state.\nabstractmethod","text":"fetch_message(message_id: str) -> dict[str, Any]\nFetch a full raw message by message identifier.
Parameters:
Name Type Description Defaultmessage_id str Provider-specific message identifier.
requiredReturns:
Type Descriptiondict[str, Any] dict[str, Any]: Provider-native message payload (e.g., Gmail message JSON structure).
"},{"location":"adapters/base/#mail_intake.adapters.base.MailIntakeAdapter.fetch_thread","title":"fetch_threadabstractmethod","text":"fetch_thread(thread_id: str) -> dict[str, Any]\nFetch a full raw thread by thread identifier.
Parameters:
Name Type Description Defaultthread_id str Provider-specific thread identifier.
requiredReturns:
Type Descriptiondict[str, Any] dict[str, Any]: Provider-native thread payload.
"},{"location":"adapters/base/#mail_intake.adapters.base.MailIntakeAdapter.iter_message_refs","title":"iter_message_refsabstractmethod","text":"iter_message_refs(query: str) -> Iterator[dict[str, str]]\nIterate over lightweight message references matching a query.
Parameters:
Name Type Description Defaultquery str Provider-specific query string used to filter messages.
requiredReturns:
Type DescriptionIterator[dict[str, str]] Iterator[dict[str, str]]: An iterator over lightweight message reference dictionaries.
Yields:
Type Descriptiondict[str, str] dict[str, str]: Dictionaries containing message and thread identifiers.
NotesGuarantees:
- Implementations must yield dictionaries containing at least\n `message_id` and `thread_id`.\nTypical yield:
{\n \"message_id\": \"...\",\n \"thread_id\": \"...\"\n}\nGmail adapter implementation for Mail Intake.
This module provides a Gmail-specific implementation of the MailIntakeAdapter contract.
It is the only place in the codebase where:
googleapiclient is imported..execute() calls are made.All Gmail-specific behavior must be strictly contained within this module.
"},{"location":"adapters/gmail/#mail_intake.adapters.gmail-classes","title":"Classes","text":""},{"location":"adapters/gmail/#mail_intake.adapters.gmail.MailIntakeGmailAdapter","title":"MailIntakeGmailAdapter","text":"MailIntakeGmailAdapter(\n auth_provider: MailIntakeAuthProvider[Any],\n user_id: str = \"me\",\n)\n Bases: MailIntakeAdapter
Gmail read-only adapter.
This adapter implements the MailIntakeAdapter interface using the Gmail REST API. It translates the generic mail intake contract into Gmail-specific API calls.
Responsibilities:
- This class is the ONLY place where `googleapiclient` is imported.\n- Gmail REST semantics are known.\n- `.execute()` is called.\nConstraints:
- Must remain thin and imperative.\n- Must not perform parsing or interpretation.\n- Must not expose Gmail-specific types beyond this class.\nInitialize the Gmail adapter.
Parameters:
Name Type Description Defaultauth_provider MailIntakeAuthProvider Authentication provider capable of supplying valid Gmail API credentials.
requireduser_id str Gmail user identifier. Defaults to \"me\".
'me'"},{"location":"adapters/gmail/#mail_intake.adapters.gmail.MailIntakeGmailAdapter-attributes","title":"Attributes","text":""},{"location":"adapters/gmail/#mail_intake.adapters.gmail.MailIntakeGmailAdapter.service","title":"service property","text":"service: Any\nLazily initialize and return the Gmail API service client.
Raises:
Type DescriptionMailIntakeAdapterError If the Gmail service cannot be initialized.
"},{"location":"adapters/gmail/#mail_intake.adapters.gmail.MailIntakeGmailAdapter-functions","title":"Functions","text":""},{"location":"adapters/gmail/#mail_intake.adapters.gmail.MailIntakeGmailAdapter.fetch_message","title":"fetch_message","text":"fetch_message(message_id: str) -> dict[str, Any]\nFetch a full Gmail message by message ID.
Parameters:
Name Type Description Defaultmessage_id str Gmail message identifier.
requiredReturns:
Type Descriptiondict[str, Any] dict[str, Any]: Provider-native Gmail message payload.
Raises:
Type DescriptionMailIntakeAdapterError If the Gmail API returns an error.
"},{"location":"adapters/gmail/#mail_intake.adapters.gmail.MailIntakeGmailAdapter.fetch_thread","title":"fetch_thread","text":"fetch_thread(thread_id: str) -> dict[str, Any]\nFetch a full Gmail thread by thread ID.
Parameters:
Name Type Description Defaultthread_id str Gmail thread identifier.
requiredReturns:
Type Descriptiondict[str, Any] dict[str, Any]: Provider-native Gmail thread payload.
Raises:
Type DescriptionMailIntakeAdapterError If the Gmail API returns an error.
"},{"location":"adapters/gmail/#mail_intake.adapters.gmail.MailIntakeGmailAdapter.iter_message_refs","title":"iter_message_refs","text":"iter_message_refs(query: str) -> Iterator[dict[str, str]]\nIterate over message references matching the query.
Parameters:
Name Type Description Defaultquery str Gmail search query string.
requiredYields:
Type Descriptiondict[str, str] dict[str, str]: Dictionaries containing message_id and thread_id.
Raises:
Type DescriptionMailIntakeAdapterError If the Gmail API returns an error.
"},{"location":"auth/","title":"Auth","text":""},{"location":"auth/#mail_intake.auth","title":"mail_intake.auth","text":""},{"location":"auth/#mail_intake.auth--summary","title":"Summary","text":"Authentication provider implementations for Mail Intake.
This package defines the authentication layer used by mail adapters to obtain provider-specific credentials.
It exposes:
Authentication providers:
Consumers should depend on the abstract interface and use concrete implementations only where explicitly required.
"},{"location":"auth/#mail_intake.auth--public-api","title":"Public API","text":"MailIntakeAuthProviderMailIntakeGoogleAuth Bases: ABC, Generic[T]
Abstract base class for authentication providers.
This interface enforces a strict contract between authentication providers and mail adapters by requiring providers to explicitly declare the type of credentials they return.
NotesResponsibilities:
- Acquire credentials from an external provider.\n- Refresh or revalidate credentials as needed.\n- Handle authentication-specific failure modes.\n- Coordinate with credential persistence layers where applicable.\nConstraints:
- Mail adapters must treat returned credentials as opaque and\n provider-specific.\n- Mail adapters rely only on the declared credential type expected\n by the adapter.\nabstractmethod","text":"get_credentials() -> T\nRetrieve valid, provider-specific credentials.
Returns:
Name Type DescriptionT T Credentials of type T suitable for immediate use by the corresponding mail adapter.
Raises:
Type DescriptionException An authentication-specific exception indicating that credentials could not be obtained or validated.
NotesGuarantees:
- This method is synchronous by design.\n- Represents the sole entry point through which adapters obtain\n authentication material.\n- Implementations must either return credentials of the declared\n type `T` that are valid at the time of return or raise an exception.\nMailIntakeGoogleAuth(\n credentials_path: str,\n store: CredentialStore[Any],\n scopes: Sequence[str],\n)\n Bases: MailIntakeAuthProvider
Google OAuth provider for Gmail access.
This provider implements the MailIntakeAuthProvider interface using Google's OAuth 2.0 flow and credential management libraries.
Responsibilities:
- Load cached credentials from a credential store when available.\n- Refresh expired credentials when possible.\n- Initiate an interactive OAuth flow only when required.\n- Persist refreshed or newly obtained credentials via the store.\nGuarantees:
- This class is synchronous by design and maintains a minimal\n internal state.\nInitialize the Google authentication provider.
Parameters:
Name Type Description Defaultcredentials_path str Path to the Google OAuth client secrets file used to initiate the OAuth 2.0 flow.
requiredstore CredentialStore[Credentials] Credential store responsible for persisting and retrieving Google OAuth credentials.
requiredscopes Sequence[str] OAuth scopes required for Gmail access.
required"},{"location":"auth/#mail_intake.auth.MailIntakeGoogleAuth-functions","title":"Functions","text":""},{"location":"auth/#mail_intake.auth.MailIntakeGoogleAuth.get_credentials","title":"get_credentials","text":"get_credentials() -> Any\nRetrieve valid Google OAuth credentials.
Returns:
Name Type DescriptionCredentials Any A google.oauth2.credentials.Credentials instance suitable for use with Google API clients.
Raises:
Type DescriptionMailIntakeAuthError If credentials cannot be loaded, refreshed, or obtained via interactive authentication.
NotesLifecycle:
- Load cached credentials from the configured credential store.\n- Refresh expired credentials when possible.\n- Perform an interactive OAuth login as a fallback.\n- Persist valid credentials for future use.\nAuthentication provider contracts for Mail Intake.
This module defines the authentication abstraction layer used by mail adapters to obtain provider-specific credentials.
Authentication concerns are intentionally decoupled from adapter logic. Adapters depend only on this interface and must not be aware of how credentials are acquired, refreshed, or persisted.
"},{"location":"auth/base/#mail_intake.auth.base-classes","title":"Classes","text":""},{"location":"auth/base/#mail_intake.auth.base.MailIntakeAuthProvider","title":"MailIntakeAuthProvider","text":" Bases: ABC, Generic[T]
Abstract base class for authentication providers.
This interface enforces a strict contract between authentication providers and mail adapters by requiring providers to explicitly declare the type of credentials they return.
NotesResponsibilities:
- Acquire credentials from an external provider.\n- Refresh or revalidate credentials as needed.\n- Handle authentication-specific failure modes.\n- Coordinate with credential persistence layers where applicable.\nConstraints:
- Mail adapters must treat returned credentials as opaque and\n provider-specific.\n- Mail adapters rely only on the declared credential type expected\n by the adapter.\nabstractmethod","text":"get_credentials() -> T\nRetrieve valid, provider-specific credentials.
Returns:
Name Type DescriptionT T Credentials of type T suitable for immediate use by the corresponding mail adapter.
Raises:
Type DescriptionException An authentication-specific exception indicating that credentials could not be obtained or validated.
NotesGuarantees:
- This method is synchronous by design.\n- Represents the sole entry point through which adapters obtain\n authentication material.\n- Implementations must either return credentials of the declared\n type `T` that are valid at the time of return or raise an exception.\nGoogle authentication provider implementation for Mail Intake.
This module provides a Google OAuth\u2013based authentication provider used primarily for Gmail access.
It encapsulates all Google-specific authentication concerns, including:
No Google authentication details should leak outside this module.
"},{"location":"auth/google/#mail_intake.auth.google-classes","title":"Classes","text":""},{"location":"auth/google/#mail_intake.auth.google.MailIntakeGoogleAuth","title":"MailIntakeGoogleAuth","text":"MailIntakeGoogleAuth(\n credentials_path: str,\n store: CredentialStore[Any],\n scopes: Sequence[str],\n)\n Bases: MailIntakeAuthProvider
Google OAuth provider for Gmail access.
This provider implements the MailIntakeAuthProvider interface using Google's OAuth 2.0 flow and credential management libraries.
Responsibilities:
- Load cached credentials from a credential store when available.\n- Refresh expired credentials when possible.\n- Initiate an interactive OAuth flow only when required.\n- Persist refreshed or newly obtained credentials via the store.\nGuarantees:
- This class is synchronous by design and maintains a minimal\n internal state.\nInitialize the Google authentication provider.
Parameters:
Name Type Description Defaultcredentials_path str Path to the Google OAuth client secrets file used to initiate the OAuth 2.0 flow.
requiredstore CredentialStore[Credentials] Credential store responsible for persisting and retrieving Google OAuth credentials.
requiredscopes Sequence[str] OAuth scopes required for Gmail access.
required"},{"location":"auth/google/#mail_intake.auth.google.MailIntakeGoogleAuth-functions","title":"Functions","text":""},{"location":"auth/google/#mail_intake.auth.google.MailIntakeGoogleAuth.get_credentials","title":"get_credentials","text":"get_credentials() -> Any\nRetrieve valid Google OAuth credentials.
Returns:
Name Type DescriptionCredentials Any A google.oauth2.credentials.Credentials instance suitable for use with Google API clients.
Raises:
Type DescriptionMailIntakeAuthError If credentials cannot be loaded, refreshed, or obtained via interactive authentication.
NotesLifecycle:
- Load cached credentials from the configured credential store.\n- Refresh expired credentials when possible.\n- Perform an interactive OAuth login as a fallback.\n- Persist valid credentials for future use.\nCredential persistence interfaces and implementations for Mail Intake.
This package defines the abstractions and concrete implementations used to persist authentication credentials across Mail Intake components.
The credential persistence layer is intentionally decoupled from authentication logic. Authentication providers are responsible for credential acquisition, validation, and refresh, while implementations within this package are responsible solely for storage and retrieval.
The package provides:
CredentialStore abstraction defining the persistence contract.Credential lifecycle management, interpretation, and security policy decisions remain the responsibility of authentication providers.
"},{"location":"credentials/#mail_intake.credentials--public-api","title":"Public API","text":"CredentialStorePickleCredentialStoreRedisCredentialStore Bases: ABC, Generic[T]
Abstract base class defining a generic persistence interface.
Used for authentication credentials across different backends.
NotesResponsibilities:
- Provide persistent storage separating life-cycle management from\n storage mechanics.\n- Keep implementation focused only on persistence.\nConstraints:
- 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.\nabstractmethod","text":"clear() -> None\nRemove any persisted credentials from the store.
NotesLifecycle:
- 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\nGuarantees:
- Implementations should treat this operation as idempotent\nabstractmethod","text":"load() -> T | None\nLoad previously persisted credentials.
Returns:
Type DescriptionT | None T | None: An instance of type T if credentials are available and loadable; otherwise None.
Guarantees:
- 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.\nabstractmethod","text":"save(credentials: T) -> None\nPersist credentials to the underlying storage backend.
Parameters:
Name Type Description Defaultcredentials T The credential object to persist.
required NotesLifecycle:
- This method is invoked when credentials are newly obtained or have been refreshed and are known to be valid at the time of persistence\nResponsibilities:
- Ensuring durability appropriate to the deployment context\n- Applying encryption or access controls where required\n- Overwriting any previously stored credentials\nPickleCredentialStore(path: str)\n Bases: CredentialStore[T]
Filesystem-backed credential store using pickle serialization.
This store persists credentials as a pickled object on the local filesystem. It is a simple implementation intended primarily for development, testing, and single-process execution contexts.
NotesGuarantees:
- Stores credentials on the local filesystem.\n- Uses `pickle` for serialization and deserialization.\n- Does not provide encryption, locking, or concurrency guarantees.\nConstraints:
- Credential lifecycle management, validation, and refresh logic are\n explicitly out of scope for this class.\nInitialize a pickle-backed credential store.
Parameters:
Name Type Description Defaultpath str Filesystem path where credentials will be stored. The file will be created or overwritten as needed.
required"},{"location":"credentials/#mail_intake.credentials.PickleCredentialStore-functions","title":"Functions","text":""},{"location":"credentials/#mail_intake.credentials.PickleCredentialStore.clear","title":"clear","text":"clear() -> None\nRemove persisted credentials from the local filesystem.
NotesLifecycle:
- This method deletes the credential file if it exists and should be treated as an idempotent operation\nload() -> T | None\nLoad credentials from the local filesystem.
Returns:
Type DescriptionT | None T | None: An instance of type T if credentials are present and successfully deserialized; otherwise None.
Guarantees:
- 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.\nsave(credentials: T) -> None\nPersist credentials to the local filesystem.
Parameters:
Name Type Description Defaultcredentials T The credential object to persist.
required NotesResponsibilities:
- Any previously stored credentials at the configured path are overwritten\nRedisCredentialStore(\n redis_client: Any,\n key: str,\n serialize: Callable[[T], bytes],\n deserialize: Callable[[bytes], T],\n ttl_seconds: int | None = None,\n)\n Bases: CredentialStore[T]
Redis-backed implementation of CredentialStore.
This store persists credentials in Redis and is suitable for distributed and horizontally scaled deployments where credentials must be shared across multiple processes or nodes.
NotesResponsibilities:
- 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.\nGuarantees:
- 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.\nInitialize a Redis-backed credential store.
Parameters:
Name Type Description Defaultredis_client Any Initialized Redis client instance used for persistence.
requiredkey str Storage key under which credentials are persisted.
requiredserialize Callable[[T], bytes] Callable that encodes credentials to bytes for storage.
requireddeserialize Callable[[bytes], T] Callable that decodes stored bytes back into credentials.
requiredttl_seconds int | None Optional time-to-live in seconds after which stored credentials expire automatically. None disables expiry.
None"},{"location":"credentials/#mail_intake.credentials.RedisCredentialStore-functions","title":"Functions","text":""},{"location":"credentials/#mail_intake.credentials.RedisCredentialStore.clear","title":"clear","text":"clear() -> None\nRemove stored credentials from Redis.
NotesLifecycle:
- This operation deletes the configured Redis key if it exists\n- Implementations should treat this method as idempotent\nload() -> T | None\nLoad credentials from Redis.
Returns:
Type DescriptionT | None T | None: An instance of type T if credentials are present and successfully deserialized; otherwise None.
Guarantees:
- 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.\nsave(credentials: T) -> None\nPersist credentials to Redis.
Parameters:
Name Type Description Defaultcredentials T The credential object to persist.
required NotesResponsibilities:
- 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\nLocal filesystem\u2013based credential persistence for Mail Intake.
This module provides a file-backed implementation of the CredentialStore abstraction using Python's pickle module.
The pickle-based credential store is intended for local development, single-node deployments, and controlled environments where credentials do not need to be shared across processes or machines.
Due to the security and portability risks associated with pickle-based serialization, this implementation is not suitable for distributed or untrusted environments.
PickleCredentialStore(path: str)\n Bases: CredentialStore[T]
Filesystem-backed credential store using pickle serialization.
This store persists credentials as a pickled object on the local filesystem. It is a simple implementation intended primarily for development, testing, and single-process execution contexts.
NotesGuarantees:
- Stores credentials on the local filesystem.\n- Uses `pickle` for serialization and deserialization.\n- Does not provide encryption, locking, or concurrency guarantees.\nConstraints:
- Credential lifecycle management, validation, and refresh logic are\n explicitly out of scope for this class.\nInitialize a pickle-backed credential store.
Parameters:
Name Type Description Defaultpath str Filesystem path where credentials will be stored. The file will be created or overwritten as needed.
required"},{"location":"credentials/pickle/#mail_intake.credentials.pickle.PickleCredentialStore-functions","title":"Functions","text":""},{"location":"credentials/pickle/#mail_intake.credentials.pickle.PickleCredentialStore.clear","title":"clear","text":"clear() -> None\nRemove persisted credentials from the local filesystem.
NotesLifecycle:
- This method deletes the credential file if it exists and should be treated as an idempotent operation\nload() -> T | None\nLoad credentials from the local filesystem.
Returns:
Type DescriptionT | None T | None: An instance of type T if credentials are present and successfully deserialized; otherwise None.
Guarantees:
- 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.\nsave(credentials: T) -> None\nPersist credentials to the local filesystem.
Parameters:
Name Type Description Defaultcredentials T The credential object to persist.
required NotesResponsibilities:
- Any previously stored credentials at the configured path are overwritten\nRedis-backed credential persistence for Mail Intake.
This module provides a Redis-based implementation of the CredentialStore abstraction, enabling credential persistence across distributed and horizontally scaled deployments.
The Redis credential store is designed for environments where authentication credentials must be shared safely across multiple processes, containers, or nodes, such as container orchestration platforms and microservice architectures.
Key characteristics:
pickle.This module is responsible solely for persistence concerns. Credential validation, refresh, rotation, and acquisition remain the responsibility of authentication provider implementations.
"},{"location":"credentials/redis/#mail_intake.credentials.redis-classes","title":"Classes","text":""},{"location":"credentials/redis/#mail_intake.credentials.redis.RedisCredentialStore","title":"RedisCredentialStore","text":"RedisCredentialStore(\n redis_client: Any,\n key: str,\n serialize: Callable[[T], bytes],\n deserialize: Callable[[bytes], T],\n ttl_seconds: int | None = None,\n)\n Bases: CredentialStore[T]
Redis-backed implementation of CredentialStore.
This store persists credentials in Redis and is suitable for distributed and horizontally scaled deployments where credentials must be shared across multiple processes or nodes.
NotesResponsibilities:
- 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.\nGuarantees:
- 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.\nInitialize a Redis-backed credential store.
Parameters:
Name Type Description Defaultredis_client Any Initialized Redis client instance used for persistence.
requiredkey str Storage key under which credentials are persisted.
requiredserialize Callable[[T], bytes] Callable that encodes credentials to bytes for storage.
requireddeserialize Callable[[bytes], T] Callable that decodes stored bytes back into credentials.
requiredttl_seconds int | None Optional time-to-live in seconds after which stored credentials expire automatically. None disables expiry.
None"},{"location":"credentials/redis/#mail_intake.credentials.redis.RedisCredentialStore-functions","title":"Functions","text":""},{"location":"credentials/redis/#mail_intake.credentials.redis.RedisCredentialStore.clear","title":"clear","text":"clear() -> None\nRemove stored credentials from Redis.
NotesLifecycle:
- This operation deletes the configured Redis key if it exists\n- Implementations should treat this method as idempotent\nload() -> T | None\nLoad credentials from Redis.
Returns:
Type DescriptionT | None T | None: An instance of type T if credentials are present and successfully deserialized; otherwise None.
Guarantees:
- 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.\nsave(credentials: T) -> None\nPersist credentials to Redis.
Parameters:
Name Type Description Defaultcredentials T The credential object to persist.
required NotesResponsibilities:
- 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\nCredential persistence abstractions for Mail Intake.
This module defines the generic persistence contract used to store and retrieve authentication credentials across Mail Intake components.
The CredentialStore abstraction establishes a strict separation between credential lifecycle management and credential storage. Authentication providers are responsible for acquiring, validating, refreshing, and revoking credentials, while concrete store implementations are responsible solely for persistence concerns.
By remaining agnostic to credential structure, serialization format, and storage backend, this module enables multiple persistence strategies\u2014such as local files, in-memory caches, distributed stores, or secrets managers\u2014without coupling authentication logic to any specific storage mechanism.
"},{"location":"credentials/store/#mail_intake.credentials.store-classes","title":"Classes","text":""},{"location":"credentials/store/#mail_intake.credentials.store.CredentialStore","title":"CredentialStore","text":" Bases: ABC, Generic[T]
Abstract base class defining a generic persistence interface.
Used for authentication credentials across different backends.
NotesResponsibilities:
- Provide persistent storage separating life-cycle management from\n storage mechanics.\n- Keep implementation focused only on persistence.\nConstraints:
- 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.\nabstractmethod","text":"clear() -> None\nRemove any persisted credentials from the store.
NotesLifecycle:
- 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\nGuarantees:
- Implementations should treat this operation as idempotent\nabstractmethod","text":"load() -> T | None\nLoad previously persisted credentials.
Returns:
Type DescriptionT | None T | None: An instance of type T if credentials are available and loadable; otherwise None.
Guarantees:
- 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.\nabstractmethod","text":"save(credentials: T) -> None\nPersist credentials to the underlying storage backend.
Parameters:
Name Type Description Defaultcredentials T The credential object to persist.
required NotesLifecycle:
- This method is invoked when credentials are newly obtained or have been refreshed and are known to be valid at the time of persistence\nResponsibilities:
- Ensuring durability appropriate to the deployment context\n- Applying encryption or access controls where required\n- Overwriting any previously stored credentials\nMail ingestion orchestration for Mail Intake.
This package contains high-level ingestion components responsible for coordinating mail retrieval, parsing, normalization, and model construction.
It represents the top of the ingestion pipeline and is intended to be the primary interaction surface for library consumers.
Components in this package:
Consumers are expected to construct a mail adapter and pass it to the ingestion layer to begin processing messages and threads.
"},{"location":"ingestion/#mail_intake.ingestion--public-api","title":"Public API","text":"MailIntakeReaderMailIntakeReader(adapter: MailIntakeAdapter)\nHigh-level read-only ingestion interface.
NotesResponsibilities:
- 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.\nConstraints:
- This class is intentionally: Provider-agnostic, stateless beyond\n iteration scope, read-only.\nInitialize the mail reader.
Parameters:
Name Type Description Defaultadapter MailIntakeAdapter Mail adapter implementation used to retrieve raw messages and threads from a mail provider.
required"},{"location":"ingestion/#mail_intake.ingestion.MailIntakeReader-functions","title":"Functions","text":""},{"location":"ingestion/#mail_intake.ingestion.MailIntakeReader.iter_messages","title":"iter_messages","text":"iter_messages(query: str) -> Iterator[MailIntakeMessage]\nIterate over parsed messages matching a provider query.
Parameters:
Name Type Description Defaultquery str Provider-specific query string used to filter messages.
requiredYields:
Name Type DescriptionMailIntakeMessage MailIntakeMessage Fully parsed and normalized MailIntakeMessage instances.
Raises:
Type DescriptionMailIntakeParsingError If a message cannot be parsed.
"},{"location":"ingestion/#mail_intake.ingestion.MailIntakeReader.iter_threads","title":"iter_threads","text":"iter_threads(query: str) -> Iterator[MailIntakeThread]\nIterate over threads constructed from messages matching a query.
Parameters:
Name Type Description Defaultquery str Provider-specific query string used to filter messages.
requiredReturns:
Type DescriptionIterator[MailIntakeThread] Iterator[MailIntakeThread]: An iterator over MailIntakeThread instances.
Raises:
Type Description`MailIntakeParsingError` If a message cannot be parsed.
NotesGuarantees:
- Messages are grouped by `thread_id` and yielded as complete\n thread objects containing all associated messages.\nHigh-level mail ingestion orchestration for Mail Intake.
This module provides the primary, provider-agnostic entry point for reading and processing mail data.
It coordinates:
No provider-specific logic or API semantics are permitted in this layer.
"},{"location":"ingestion/reader/#mail_intake.ingestion.reader-classes","title":"Classes","text":""},{"location":"ingestion/reader/#mail_intake.ingestion.reader.MailIntakeReader","title":"MailIntakeReader","text":"MailIntakeReader(adapter: MailIntakeAdapter)\nHigh-level read-only ingestion interface.
NotesResponsibilities:
- 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.\nConstraints:
- This class is intentionally: Provider-agnostic, stateless beyond\n iteration scope, read-only.\nInitialize the mail reader.
Parameters:
Name Type Description Defaultadapter MailIntakeAdapter Mail adapter implementation used to retrieve raw messages and threads from a mail provider.
required"},{"location":"ingestion/reader/#mail_intake.ingestion.reader.MailIntakeReader-functions","title":"Functions","text":""},{"location":"ingestion/reader/#mail_intake.ingestion.reader.MailIntakeReader.iter_messages","title":"iter_messages","text":"iter_messages(query: str) -> Iterator[MailIntakeMessage]\nIterate over parsed messages matching a provider query.
Parameters:
Name Type Description Defaultquery str Provider-specific query string used to filter messages.
requiredYields:
Name Type DescriptionMailIntakeMessage MailIntakeMessage Fully parsed and normalized MailIntakeMessage instances.
Raises:
Type DescriptionMailIntakeParsingError If a message cannot be parsed.
"},{"location":"ingestion/reader/#mail_intake.ingestion.reader.MailIntakeReader.iter_threads","title":"iter_threads","text":"iter_threads(query: str) -> Iterator[MailIntakeThread]\nIterate over threads constructed from messages matching a query.
Parameters:
Name Type Description Defaultquery str Provider-specific query string used to filter messages.
requiredReturns:
Type DescriptionIterator[MailIntakeThread] Iterator[MailIntakeThread]: An iterator over MailIntakeThread instances.
Raises:
Type Description`MailIntakeParsingError` If a message cannot be parsed.
NotesGuarantees:
- Messages are grouped by `thread_id` and yielded as complete\n thread objects containing all associated messages.\nMail Intake \u2014 provider-agnostic, read-only email ingestion framework.
Mail Intake is a contract-first library designed to ingest, parse, and normalize email data from external providers (such as Gmail) into clean, provider-agnostic domain models.
The library is intentionally structured around clear layers, each exposed as a first-class module at the package root:
adapters: Provider-specific access (e.g., Gmail).auth: Authentication providers and credential lifecycle management.credentials: Credential persistence abstractions and implementations.parsers: Extraction and normalization of message content.ingestion: Orchestration and high-level ingestion workflows.models: Canonical, provider-agnostic data representations.config: Explicit global configuration.exceptions: Library-defined error hierarchy.The package root acts as a namespace, not a facade. Consumers are expected to import functionality explicitly from the appropriate module.
"},{"location":"mail_intake/#mail_intake--installation","title":"Installation","text":"Install using pip:
pip install mail-intake\nOr with Poetry:
poetry add mail-intake\nMail Intake is pure Python and has no runtime dependencies beyond those required by the selected provider (for example, Google APIs for Gmail).
"},{"location":"mail_intake/#mail_intake--quick-start","title":"Quick Start","text":"Minimal Gmail ingestion example (local development):
from mail_intake.ingestion import MailIntakeReader\nfrom mail_intake.adapters import MailIntakeGmailAdapter\nfrom mail_intake.auth import MailIntakeGoogleAuth\nfrom mail_intake.credentials import PickleCredentialStore\n\nstore = PickleCredentialStore(path=\"token.pickle\")\n\nauth = MailIntakeGoogleAuth(\n credentials_path=\"credentials.json\",\n store=store,\n scopes=[\"https://www.googleapis.com/auth/gmail.readonly\"],\n)\n\nadapter = MailIntakeGmailAdapter(auth_provider=auth)\nreader = MailIntakeReader(adapter)\n\nfor message in reader.iter_messages(\"from:recruiter@example.com\"):\n print(message.subject, message.from_email)\nIterating over threads:
for thread in reader.iter_threads(\"subject:Interview\"):\n print(thread.normalized_subject, len(thread.messages))\nMail Intake is designed to be extensible via public contracts exposed through its modules:
adapters.MailIntakeAdapter.auth.MailIntakeAuthProvider[T].credentials.CredentialStore[T].Users SHOULD NOT subclass built-in adapter implementations. Built-in adapters (such as Gmail) are reference implementations and may change internally without notice.
Design Guarantees:
Mail Intake favors correctness, clarity, and explicitness over convenience shortcuts.
Core Philosophy:
Mail Intake is built as a contract-first ingestion pipeline:
The supported public API consists of the following top-level modules:
mail_intake.ingestionmail_intake.adaptersmail_intake.authmail_intake.credentialsmail_intake.parsersmail_intake.modelsmail_intake.configmail_intake.exceptionsClasses and functions should be imported explicitly from these modules. No individual symbols are re-exported at the package root.
"},{"location":"mail_intake/config/","title":"Config","text":""},{"location":"mail_intake/config/#mail_intake.config","title":"mail_intake.config","text":""},{"location":"mail_intake/config/#mail_intake.config--summary","title":"Summary","text":"Global configuration models for Mail Intake.
This module defines the top-level configuration object used to control mail ingestion behavior across adapters, authentication providers, and ingestion workflows.
Configuration is intentionally explicit, immutable, and free of implicit environment reads to ensure predictability and testability.
"},{"location":"mail_intake/config/#mail_intake.config-classes","title":"Classes","text":""},{"location":"mail_intake/config/#mail_intake.config.MailIntakeConfig","title":"MailIntakeConfigdataclass","text":"MailIntakeConfig(\n provider: str = ...,\n user_id: str = ...,\n readonly: bool = ...,\n credentials_path: str | None = ...,\n token_path: str | None = ...,\n)\nGlobal configuration for mail-intake.
Guarantees:
- 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.\nclass-attribute instance-attribute","text":"credentials_path: str | None = None\nOptional path to provider credentials configuration.
"},{"location":"mail_intake/config/#mail_intake.config.MailIntakeConfig.provider","title":"providerclass-attribute instance-attribute","text":"provider: str = 'gmail'\nIdentifier of the mail provider to use (e.g., \"gmail\").
class-attribute instance-attribute","text":"readonly: bool = True\nWhether ingestion should operate in read-only mode.
"},{"location":"mail_intake/config/#mail_intake.config.MailIntakeConfig.token_path","title":"token_pathclass-attribute instance-attribute","text":"token_path: str | None = None\nOptional path to persisted authentication tokens.
"},{"location":"mail_intake/config/#mail_intake.config.MailIntakeConfig.user_id","title":"user_idclass-attribute instance-attribute","text":"user_id: str = 'me'\nProvider-specific user identifier. Defaults to the authenticated user.
"},{"location":"mail_intake/exceptions/","title":"Exceptions","text":""},{"location":"mail_intake/exceptions/#mail_intake.exceptions","title":"mail_intake.exceptions","text":""},{"location":"mail_intake/exceptions/#mail_intake.exceptions--summary","title":"Summary","text":"Exception hierarchy for Mail Intake.
This module defines the canonical exception types used throughout the Mail Intake library.
All library-raised errors derive from MailIntakeError. Consumers are encouraged to catch this base type (or specific subclasses) rather than provider-specific or third-party exceptions.
Bases: MailIntakeError
Errors raised by mail provider adapters.
NotesLifecycle:
- Raised when a provider adapter encounters API errors, transport\n failures, or invalid provider responses.\n Bases: MailIntakeError
Authentication and credential-related failures.
NotesLifecycle:
- Raised when authentication providers are unable to acquire,\n refresh, or persist valid credentials.\n Bases: Exception
Base exception for all Mail Intake errors.
NotesGuarantees:
- 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\n Bases: MailIntakeError
Errors encountered while parsing message content.
NotesLifecycle:
- Raised when raw provider payloads cannot be interpreted or\n normalized into internal domain models.\nMail provider adapter implementations for Mail Intake.
This package contains adapter-layer implementations responsible for interfacing with external mail providers and exposing a normalized, provider-agnostic contract to the rest of the system.
Adapters in this package:
MailIntakeAdapter interface.Provider-specific logic must not leak outside of adapter implementations. All parsings, normalizations, and transformations must be handled by downstream components.
"},{"location":"mail_intake/adapters/#mail_intake.adapters--public-api","title":"Public API","text":"MailIntakeAdapterMailIntakeGmailAdapter Bases: ABC
Base adapter interface for mail providers.
NotesGuarantees:
- Discover messages matching a query.\n- Retrieve full message payloads.\n- Retrieve full thread payloads.\nLifecycle:
- Adapters are intentionally read-only and must not mutate provider state.\nabstractmethod","text":"fetch_message(message_id: str) -> dict[str, Any]\nFetch a full raw message by message identifier.
Parameters:
Name Type Description Defaultmessage_id str Provider-specific message identifier.
requiredReturns:
Type Descriptiondict[str, Any] dict[str, Any]: Provider-native message payload (e.g., Gmail message JSON structure).
"},{"location":"mail_intake/adapters/#mail_intake.adapters.MailIntakeAdapter.fetch_thread","title":"fetch_threadabstractmethod","text":"fetch_thread(thread_id: str) -> dict[str, Any]\nFetch a full raw thread by thread identifier.
Parameters:
Name Type Description Defaultthread_id str Provider-specific thread identifier.
requiredReturns:
Type Descriptiondict[str, Any] dict[str, Any]: Provider-native thread payload.
"},{"location":"mail_intake/adapters/#mail_intake.adapters.MailIntakeAdapter.iter_message_refs","title":"iter_message_refsabstractmethod","text":"iter_message_refs(query: str) -> Iterator[dict[str, str]]\nIterate over lightweight message references matching a query.
Parameters:
Name Type Description Defaultquery str Provider-specific query string used to filter messages.
requiredReturns:
Type DescriptionIterator[dict[str, str]] Iterator[dict[str, str]]: An iterator over lightweight message reference dictionaries.
Yields:
Type Descriptiondict[str, str] dict[str, str]: Dictionaries containing message and thread identifiers.
NotesGuarantees:
- Implementations must yield dictionaries containing at least\n `message_id` and `thread_id`.\nTypical yield:
{\n \"message_id\": \"...\",\n \"thread_id\": \"...\"\n}\nMailIntakeGmailAdapter(\n auth_provider: MailIntakeAuthProvider[Any],\n user_id: str = \"me\",\n)\n Bases: MailIntakeAdapter
Gmail read-only adapter.
This adapter implements the MailIntakeAdapter interface using the Gmail REST API. It translates the generic mail intake contract into Gmail-specific API calls.
Responsibilities:
- This class is the ONLY place where `googleapiclient` is imported.\n- Gmail REST semantics are known.\n- `.execute()` is called.\nConstraints:
- Must remain thin and imperative.\n- Must not perform parsing or interpretation.\n- Must not expose Gmail-specific types beyond this class.\nInitialize the Gmail adapter.
Parameters:
Name Type Description Defaultauth_provider MailIntakeAuthProvider Authentication provider capable of supplying valid Gmail API credentials.
requireduser_id str Gmail user identifier. Defaults to \"me\".
'me'"},{"location":"mail_intake/adapters/#mail_intake.adapters.MailIntakeGmailAdapter-attributes","title":"Attributes","text":""},{"location":"mail_intake/adapters/#mail_intake.adapters.MailIntakeGmailAdapter.service","title":"service property","text":"service: Any\nLazily initialize and return the Gmail API service client.
Raises:
Type DescriptionMailIntakeAdapterError If the Gmail service cannot be initialized.
"},{"location":"mail_intake/adapters/#mail_intake.adapters.MailIntakeGmailAdapter-functions","title":"Functions","text":""},{"location":"mail_intake/adapters/#mail_intake.adapters.MailIntakeGmailAdapter.fetch_message","title":"fetch_message","text":"fetch_message(message_id: str) -> dict[str, Any]\nFetch a full Gmail message by message ID.
Parameters:
Name Type Description Defaultmessage_id str Gmail message identifier.
requiredReturns:
Type Descriptiondict[str, Any] dict[str, Any]: Provider-native Gmail message payload.
Raises:
Type DescriptionMailIntakeAdapterError If the Gmail API returns an error.
"},{"location":"mail_intake/adapters/#mail_intake.adapters.MailIntakeGmailAdapter.fetch_thread","title":"fetch_thread","text":"fetch_thread(thread_id: str) -> dict[str, Any]\nFetch a full Gmail thread by thread ID.
Parameters:
Name Type Description Defaultthread_id str Gmail thread identifier.
requiredReturns:
Type Descriptiondict[str, Any] dict[str, Any]: Provider-native Gmail thread payload.
Raises:
Type DescriptionMailIntakeAdapterError If the Gmail API returns an error.
"},{"location":"mail_intake/adapters/#mail_intake.adapters.MailIntakeGmailAdapter.iter_message_refs","title":"iter_message_refs","text":"iter_message_refs(query: str) -> Iterator[dict[str, str]]\nIterate over message references matching the query.
Parameters:
Name Type Description Defaultquery str Gmail search query string.
requiredYields:
Type Descriptiondict[str, str] dict[str, str]: Dictionaries containing message_id and thread_id.
Raises:
Type DescriptionMailIntakeAdapterError If the Gmail API returns an error.
"},{"location":"mail_intake/adapters/base/","title":"Base","text":""},{"location":"mail_intake/adapters/base/#mail_intake.adapters.base","title":"mail_intake.adapters.base","text":""},{"location":"mail_intake/adapters/base/#mail_intake.adapters.base--summary","title":"Summary","text":"Mail provider adapter contracts for Mail Intake.
This module defines the provider-agnostic adapter interface used for read-only mail ingestion.
Adapters encapsulate all provider-specific access logic and expose a minimal, normalized contract to the rest of the system. No provider-specific types or semantics should leak beyond implementations of this interface.
"},{"location":"mail_intake/adapters/base/#mail_intake.adapters.base-classes","title":"Classes","text":""},{"location":"mail_intake/adapters/base/#mail_intake.adapters.base.MailIntakeAdapter","title":"MailIntakeAdapter","text":" Bases: ABC
Base adapter interface for mail providers.
NotesGuarantees:
- Discover messages matching a query.\n- Retrieve full message payloads.\n- Retrieve full thread payloads.\nLifecycle:
- Adapters are intentionally read-only and must not mutate provider state.\nabstractmethod","text":"fetch_message(message_id: str) -> dict[str, Any]\nFetch a full raw message by message identifier.
Parameters:
Name Type Description Defaultmessage_id str Provider-specific message identifier.
requiredReturns:
Type Descriptiondict[str, Any] dict[str, Any]: Provider-native message payload (e.g., Gmail message JSON structure).
"},{"location":"mail_intake/adapters/base/#mail_intake.adapters.base.MailIntakeAdapter.fetch_thread","title":"fetch_threadabstractmethod","text":"fetch_thread(thread_id: str) -> dict[str, Any]\nFetch a full raw thread by thread identifier.
Parameters:
Name Type Description Defaultthread_id str Provider-specific thread identifier.
requiredReturns:
Type Descriptiondict[str, Any] dict[str, Any]: Provider-native thread payload.
"},{"location":"mail_intake/adapters/base/#mail_intake.adapters.base.MailIntakeAdapter.iter_message_refs","title":"iter_message_refsabstractmethod","text":"iter_message_refs(query: str) -> Iterator[dict[str, str]]\nIterate over lightweight message references matching a query.
Parameters:
Name Type Description Defaultquery str Provider-specific query string used to filter messages.
requiredReturns:
Type DescriptionIterator[dict[str, str]] Iterator[dict[str, str]]: An iterator over lightweight message reference dictionaries.
Yields:
Type Descriptiondict[str, str] dict[str, str]: Dictionaries containing message and thread identifiers.
NotesGuarantees:
- Implementations must yield dictionaries containing at least\n `message_id` and `thread_id`.\nTypical yield:
{\n \"message_id\": \"...\",\n \"thread_id\": \"...\"\n}\nGmail adapter implementation for Mail Intake.
This module provides a Gmail-specific implementation of the MailIntakeAdapter contract.
It is the only place in the codebase where:
googleapiclient is imported..execute() calls are made.All Gmail-specific behavior must be strictly contained within this module.
"},{"location":"mail_intake/adapters/gmail/#mail_intake.adapters.gmail-classes","title":"Classes","text":""},{"location":"mail_intake/adapters/gmail/#mail_intake.adapters.gmail.MailIntakeGmailAdapter","title":"MailIntakeGmailAdapter","text":"MailIntakeGmailAdapter(\n auth_provider: MailIntakeAuthProvider[Any],\n user_id: str = \"me\",\n)\n Bases: MailIntakeAdapter
Gmail read-only adapter.
This adapter implements the MailIntakeAdapter interface using the Gmail REST API. It translates the generic mail intake contract into Gmail-specific API calls.
Responsibilities:
- This class is the ONLY place where `googleapiclient` is imported.\n- Gmail REST semantics are known.\n- `.execute()` is called.\nConstraints:
- Must remain thin and imperative.\n- Must not perform parsing or interpretation.\n- Must not expose Gmail-specific types beyond this class.\nInitialize the Gmail adapter.
Parameters:
Name Type Description Defaultauth_provider MailIntakeAuthProvider Authentication provider capable of supplying valid Gmail API credentials.
requireduser_id str Gmail user identifier. Defaults to \"me\".
'me'"},{"location":"mail_intake/adapters/gmail/#mail_intake.adapters.gmail.MailIntakeGmailAdapter-attributes","title":"Attributes","text":""},{"location":"mail_intake/adapters/gmail/#mail_intake.adapters.gmail.MailIntakeGmailAdapter.service","title":"service property","text":"service: Any\nLazily initialize and return the Gmail API service client.
Raises:
Type DescriptionMailIntakeAdapterError If the Gmail service cannot be initialized.
"},{"location":"mail_intake/adapters/gmail/#mail_intake.adapters.gmail.MailIntakeGmailAdapter-functions","title":"Functions","text":""},{"location":"mail_intake/adapters/gmail/#mail_intake.adapters.gmail.MailIntakeGmailAdapter.fetch_message","title":"fetch_message","text":"fetch_message(message_id: str) -> dict[str, Any]\nFetch a full Gmail message by message ID.
Parameters:
Name Type Description Defaultmessage_id str Gmail message identifier.
requiredReturns:
Type Descriptiondict[str, Any] dict[str, Any]: Provider-native Gmail message payload.
Raises:
Type DescriptionMailIntakeAdapterError If the Gmail API returns an error.
"},{"location":"mail_intake/adapters/gmail/#mail_intake.adapters.gmail.MailIntakeGmailAdapter.fetch_thread","title":"fetch_thread","text":"fetch_thread(thread_id: str) -> dict[str, Any]\nFetch a full Gmail thread by thread ID.
Parameters:
Name Type Description Defaultthread_id str Gmail thread identifier.
requiredReturns:
Type Descriptiondict[str, Any] dict[str, Any]: Provider-native Gmail thread payload.
Raises:
Type DescriptionMailIntakeAdapterError If the Gmail API returns an error.
"},{"location":"mail_intake/adapters/gmail/#mail_intake.adapters.gmail.MailIntakeGmailAdapter.iter_message_refs","title":"iter_message_refs","text":"iter_message_refs(query: str) -> Iterator[dict[str, str]]\nIterate over message references matching the query.
Parameters:
Name Type Description Defaultquery str Gmail search query string.
requiredYields:
Type Descriptiondict[str, str] dict[str, str]: Dictionaries containing message_id and thread_id.
Raises:
Type DescriptionMailIntakeAdapterError If the Gmail API returns an error.
"},{"location":"mail_intake/auth/","title":"Auth","text":"Authentication provider implementations for Mail Intake.
This package defines the authentication layer used by mail adapters to obtain provider-specific credentials.
It exposes:
Authentication providers:
Consumers should depend on the abstract interface and use concrete implementations only where explicitly required.
"},{"location":"mail_intake/auth/#mail_intake.auth--public-api","title":"Public API","text":"MailIntakeAuthProviderMailIntakeGoogleAuth Bases: ABC, Generic[T]
Abstract base class for authentication providers.
This interface enforces a strict contract between authentication providers and mail adapters by requiring providers to explicitly declare the type of credentials they return.
NotesResponsibilities:
- Acquire credentials from an external provider.\n- Refresh or revalidate credentials as needed.\n- Handle authentication-specific failure modes.\n- Coordinate with credential persistence layers where applicable.\nConstraints:
- Mail adapters must treat returned credentials as opaque and\n provider-specific.\n- Mail adapters rely only on the declared credential type expected\n by the adapter.\nabstractmethod","text":"get_credentials() -> T\nRetrieve valid, provider-specific credentials.
Returns:
Name Type DescriptionT T Credentials of type T suitable for immediate use by the corresponding mail adapter.
Raises:
Type DescriptionException An authentication-specific exception indicating that credentials could not be obtained or validated.
NotesGuarantees:
- This method is synchronous by design.\n- Represents the sole entry point through which adapters obtain\n authentication material.\n- Implementations must either return credentials of the declared\n type `T` that are valid at the time of return or raise an exception.\nMailIntakeGoogleAuth(\n credentials_path: str,\n store: CredentialStore[Any],\n scopes: Sequence[str],\n)\n Bases: MailIntakeAuthProvider
Google OAuth provider for Gmail access.
This provider implements the MailIntakeAuthProvider interface using Google's OAuth 2.0 flow and credential management libraries.
Responsibilities:
- Load cached credentials from a credential store when available.\n- Refresh expired credentials when possible.\n- Initiate an interactive OAuth flow only when required.\n- Persist refreshed or newly obtained credentials via the store.\nGuarantees:
- This class is synchronous by design and maintains a minimal\n internal state.\nInitialize the Google authentication provider.
Parameters:
Name Type Description Defaultcredentials_path str Path to the Google OAuth client secrets file used to initiate the OAuth 2.0 flow.
requiredstore CredentialStore[Credentials] Credential store responsible for persisting and retrieving Google OAuth credentials.
requiredscopes Sequence[str] OAuth scopes required for Gmail access.
required"},{"location":"mail_intake/auth/#mail_intake.auth.MailIntakeGoogleAuth-functions","title":"Functions","text":""},{"location":"mail_intake/auth/#mail_intake.auth.MailIntakeGoogleAuth.get_credentials","title":"get_credentials","text":"get_credentials() -> Any\nRetrieve valid Google OAuth credentials.
Returns:
Name Type DescriptionCredentials Any A google.oauth2.credentials.Credentials instance suitable for use with Google API clients.
Raises:
Type DescriptionMailIntakeAuthError If credentials cannot be loaded, refreshed, or obtained via interactive authentication.
NotesLifecycle:
- Load cached credentials from the configured credential store.\n- Refresh expired credentials when possible.\n- Perform an interactive OAuth login as a fallback.\n- Persist valid credentials for future use.\nAuthentication provider contracts for Mail Intake.
This module defines the authentication abstraction layer used by mail adapters to obtain provider-specific credentials.
Authentication concerns are intentionally decoupled from adapter logic. Adapters depend only on this interface and must not be aware of how credentials are acquired, refreshed, or persisted.
"},{"location":"mail_intake/auth/base/#mail_intake.auth.base-classes","title":"Classes","text":""},{"location":"mail_intake/auth/base/#mail_intake.auth.base.MailIntakeAuthProvider","title":"MailIntakeAuthProvider","text":" Bases: ABC, Generic[T]
Abstract base class for authentication providers.
This interface enforces a strict contract between authentication providers and mail adapters by requiring providers to explicitly declare the type of credentials they return.
NotesResponsibilities:
- Acquire credentials from an external provider.\n- Refresh or revalidate credentials as needed.\n- Handle authentication-specific failure modes.\n- Coordinate with credential persistence layers where applicable.\nConstraints:
- Mail adapters must treat returned credentials as opaque and\n provider-specific.\n- Mail adapters rely only on the declared credential type expected\n by the adapter.\nabstractmethod","text":"get_credentials() -> T\nRetrieve valid, provider-specific credentials.
Returns:
Name Type DescriptionT T Credentials of type T suitable for immediate use by the corresponding mail adapter.
Raises:
Type DescriptionException An authentication-specific exception indicating that credentials could not be obtained or validated.
NotesGuarantees:
- This method is synchronous by design.\n- Represents the sole entry point through which adapters obtain\n authentication material.\n- Implementations must either return credentials of the declared\n type `T` that are valid at the time of return or raise an exception.\nGoogle authentication provider implementation for Mail Intake.
This module provides a Google OAuth\u2013based authentication provider used primarily for Gmail access.
It encapsulates all Google-specific authentication concerns, including:
No Google authentication details should leak outside this module.
"},{"location":"mail_intake/auth/google/#mail_intake.auth.google-classes","title":"Classes","text":""},{"location":"mail_intake/auth/google/#mail_intake.auth.google.MailIntakeGoogleAuth","title":"MailIntakeGoogleAuth","text":"MailIntakeGoogleAuth(\n credentials_path: str,\n store: CredentialStore[Any],\n scopes: Sequence[str],\n)\n Bases: MailIntakeAuthProvider
Google OAuth provider for Gmail access.
This provider implements the MailIntakeAuthProvider interface using Google's OAuth 2.0 flow and credential management libraries.
Responsibilities:
- Load cached credentials from a credential store when available.\n- Refresh expired credentials when possible.\n- Initiate an interactive OAuth flow only when required.\n- Persist refreshed or newly obtained credentials via the store.\nGuarantees:
- This class is synchronous by design and maintains a minimal\n internal state.\nInitialize the Google authentication provider.
Parameters:
Name Type Description Defaultcredentials_path str Path to the Google OAuth client secrets file used to initiate the OAuth 2.0 flow.
requiredstore CredentialStore[Credentials] Credential store responsible for persisting and retrieving Google OAuth credentials.
requiredscopes Sequence[str] OAuth scopes required for Gmail access.
required"},{"location":"mail_intake/auth/google/#mail_intake.auth.google.MailIntakeGoogleAuth-functions","title":"Functions","text":""},{"location":"mail_intake/auth/google/#mail_intake.auth.google.MailIntakeGoogleAuth.get_credentials","title":"get_credentials","text":"get_credentials() -> Any\nRetrieve valid Google OAuth credentials.
Returns:
Name Type DescriptionCredentials Any A google.oauth2.credentials.Credentials instance suitable for use with Google API clients.
Raises:
Type DescriptionMailIntakeAuthError If credentials cannot be loaded, refreshed, or obtained via interactive authentication.
NotesLifecycle:
- Load cached credentials from the configured credential store.\n- Refresh expired credentials when possible.\n- Perform an interactive OAuth login as a fallback.\n- Persist valid credentials for future use.\nCredential persistence interfaces and implementations for Mail Intake.
This package defines the abstractions and concrete implementations used to persist authentication credentials across Mail Intake components.
The credential persistence layer is intentionally decoupled from authentication logic. Authentication providers are responsible for credential acquisition, validation, and refresh, while implementations within this package are responsible solely for storage and retrieval.
The package provides:
CredentialStore abstraction defining the persistence contract.Credential lifecycle management, interpretation, and security policy decisions remain the responsibility of authentication providers.
"},{"location":"mail_intake/credentials/#mail_intake.credentials--public-api","title":"Public API","text":"CredentialStorePickleCredentialStoreRedisCredentialStore Bases: ABC, Generic[T]
Abstract base class defining a generic persistence interface.
Used for authentication credentials across different backends.
NotesResponsibilities:
- Provide persistent storage separating life-cycle management from\n storage mechanics.\n- Keep implementation focused only on persistence.\nConstraints:
- 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.\nabstractmethod","text":"clear() -> None\nRemove any persisted credentials from the store.
NotesLifecycle:
- 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\nGuarantees:
- Implementations should treat this operation as idempotent\nabstractmethod","text":"load() -> T | None\nLoad previously persisted credentials.
Returns:
Type DescriptionT | None T | None: An instance of type T if credentials are available and loadable; otherwise None.
Guarantees:
- 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.\nabstractmethod","text":"save(credentials: T) -> None\nPersist credentials to the underlying storage backend.
Parameters:
Name Type Description Defaultcredentials T The credential object to persist.
required NotesLifecycle:
- This method is invoked when credentials are newly obtained or have been refreshed and are known to be valid at the time of persistence\nResponsibilities:
- Ensuring durability appropriate to the deployment context\n- Applying encryption or access controls where required\n- Overwriting any previously stored credentials\nPickleCredentialStore(path: str)\n Bases: CredentialStore[T]
Filesystem-backed credential store using pickle serialization.
This store persists credentials as a pickled object on the local filesystem. It is a simple implementation intended primarily for development, testing, and single-process execution contexts.
NotesGuarantees:
- Stores credentials on the local filesystem.\n- Uses `pickle` for serialization and deserialization.\n- Does not provide encryption, locking, or concurrency guarantees.\nConstraints:
- Credential lifecycle management, validation, and refresh logic are\n explicitly out of scope for this class.\nInitialize a pickle-backed credential store.
Parameters:
Name Type Description Defaultpath str Filesystem path where credentials will be stored. The file will be created or overwritten as needed.
required"},{"location":"mail_intake/credentials/#mail_intake.credentials.PickleCredentialStore-functions","title":"Functions","text":""},{"location":"mail_intake/credentials/#mail_intake.credentials.PickleCredentialStore.clear","title":"clear","text":"clear() -> None\nRemove persisted credentials from the local filesystem.
NotesLifecycle:
- This method deletes the credential file if it exists and should be treated as an idempotent operation\nload() -> T | None\nLoad credentials from the local filesystem.
Returns:
Type DescriptionT | None T | None: An instance of type T if credentials are present and successfully deserialized; otherwise None.
Guarantees:
- 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.\nsave(credentials: T) -> None\nPersist credentials to the local filesystem.
Parameters:
Name Type Description Defaultcredentials T The credential object to persist.
required NotesResponsibilities:
- Any previously stored credentials at the configured path are overwritten\nRedisCredentialStore(\n redis_client: Any,\n key: str,\n serialize: Callable[[T], bytes],\n deserialize: Callable[[bytes], T],\n ttl_seconds: int | None = None,\n)\n Bases: CredentialStore[T]
Redis-backed implementation of CredentialStore.
This store persists credentials in Redis and is suitable for distributed and horizontally scaled deployments where credentials must be shared across multiple processes or nodes.
NotesResponsibilities:
- 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.\nGuarantees:
- 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.\nInitialize a Redis-backed credential store.
Parameters:
Name Type Description Defaultredis_client Any Initialized Redis client instance used for persistence.
requiredkey str Storage key under which credentials are persisted.
requiredserialize Callable[[T], bytes] Callable that encodes credentials to bytes for storage.
requireddeserialize Callable[[bytes], T] Callable that decodes stored bytes back into credentials.
requiredttl_seconds int | None Optional time-to-live in seconds after which stored credentials expire automatically. None disables expiry.
None"},{"location":"mail_intake/credentials/#mail_intake.credentials.RedisCredentialStore-functions","title":"Functions","text":""},{"location":"mail_intake/credentials/#mail_intake.credentials.RedisCredentialStore.clear","title":"clear","text":"clear() -> None\nRemove stored credentials from Redis.
NotesLifecycle:
- This operation deletes the configured Redis key if it exists\n- Implementations should treat this method as idempotent\nload() -> T | None\nLoad credentials from Redis.
Returns:
Type DescriptionT | None T | None: An instance of type T if credentials are present and successfully deserialized; otherwise None.
Guarantees:
- 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.\nsave(credentials: T) -> None\nPersist credentials to Redis.
Parameters:
Name Type Description Defaultcredentials T The credential object to persist.
required NotesResponsibilities:
- 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\nLocal filesystem\u2013based credential persistence for Mail Intake.
This module provides a file-backed implementation of the CredentialStore abstraction using Python's pickle module.
The pickle-based credential store is intended for local development, single-node deployments, and controlled environments where credentials do not need to be shared across processes or machines.
Due to the security and portability risks associated with pickle-based serialization, this implementation is not suitable for distributed or untrusted environments.
PickleCredentialStore(path: str)\n Bases: CredentialStore[T]
Filesystem-backed credential store using pickle serialization.
This store persists credentials as a pickled object on the local filesystem. It is a simple implementation intended primarily for development, testing, and single-process execution contexts.
NotesGuarantees:
- Stores credentials on the local filesystem.\n- Uses `pickle` for serialization and deserialization.\n- Does not provide encryption, locking, or concurrency guarantees.\nConstraints:
- Credential lifecycle management, validation, and refresh logic are\n explicitly out of scope for this class.\nInitialize a pickle-backed credential store.
Parameters:
Name Type Description Defaultpath str Filesystem path where credentials will be stored. The file will be created or overwritten as needed.
required"},{"location":"mail_intake/credentials/pickle/#mail_intake.credentials.pickle.PickleCredentialStore-functions","title":"Functions","text":""},{"location":"mail_intake/credentials/pickle/#mail_intake.credentials.pickle.PickleCredentialStore.clear","title":"clear","text":"clear() -> None\nRemove persisted credentials from the local filesystem.
NotesLifecycle:
- This method deletes the credential file if it exists and should be treated as an idempotent operation\nload() -> T | None\nLoad credentials from the local filesystem.
Returns:
Type DescriptionT | None T | None: An instance of type T if credentials are present and successfully deserialized; otherwise None.
Guarantees:
- 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.\nsave(credentials: T) -> None\nPersist credentials to the local filesystem.
Parameters:
Name Type Description Defaultcredentials T The credential object to persist.
required NotesResponsibilities:
- Any previously stored credentials at the configured path are overwritten\nRedis-backed credential persistence for Mail Intake.
This module provides a Redis-based implementation of the CredentialStore abstraction, enabling credential persistence across distributed and horizontally scaled deployments.
The Redis credential store is designed for environments where authentication credentials must be shared safely across multiple processes, containers, or nodes, such as container orchestration platforms and microservice architectures.
Key characteristics:
pickle.This module is responsible solely for persistence concerns. Credential validation, refresh, rotation, and acquisition remain the responsibility of authentication provider implementations.
"},{"location":"mail_intake/credentials/redis/#mail_intake.credentials.redis-classes","title":"Classes","text":""},{"location":"mail_intake/credentials/redis/#mail_intake.credentials.redis.RedisCredentialStore","title":"RedisCredentialStore","text":"RedisCredentialStore(\n redis_client: Any,\n key: str,\n serialize: Callable[[T], bytes],\n deserialize: Callable[[bytes], T],\n ttl_seconds: int | None = None,\n)\n Bases: CredentialStore[T]
Redis-backed implementation of CredentialStore.
This store persists credentials in Redis and is suitable for distributed and horizontally scaled deployments where credentials must be shared across multiple processes or nodes.
NotesResponsibilities:
- 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.\nGuarantees:
- 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.\nInitialize a Redis-backed credential store.
Parameters:
Name Type Description Defaultredis_client Any Initialized Redis client instance used for persistence.
requiredkey str Storage key under which credentials are persisted.
requiredserialize Callable[[T], bytes] Callable that encodes credentials to bytes for storage.
requireddeserialize Callable[[bytes], T] Callable that decodes stored bytes back into credentials.
requiredttl_seconds int | None Optional time-to-live in seconds after which stored credentials expire automatically. None disables expiry.
None"},{"location":"mail_intake/credentials/redis/#mail_intake.credentials.redis.RedisCredentialStore-functions","title":"Functions","text":""},{"location":"mail_intake/credentials/redis/#mail_intake.credentials.redis.RedisCredentialStore.clear","title":"clear","text":"clear() -> None\nRemove stored credentials from Redis.
NotesLifecycle:
- This operation deletes the configured Redis key if it exists\n- Implementations should treat this method as idempotent\nload() -> T | None\nLoad credentials from Redis.
Returns:
Type DescriptionT | None T | None: An instance of type T if credentials are present and successfully deserialized; otherwise None.
Guarantees:
- 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.\nsave(credentials: T) -> None\nPersist credentials to Redis.
Parameters:
Name Type Description Defaultcredentials T The credential object to persist.
required NotesResponsibilities:
- 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\nCredential persistence abstractions for Mail Intake.
This module defines the generic persistence contract used to store and retrieve authentication credentials across Mail Intake components.
The CredentialStore abstraction establishes a strict separation between credential lifecycle management and credential storage. Authentication providers are responsible for acquiring, validating, refreshing, and revoking credentials, while concrete store implementations are responsible solely for persistence concerns.
By remaining agnostic to credential structure, serialization format, and storage backend, this module enables multiple persistence strategies\u2014such as local files, in-memory caches, distributed stores, or secrets managers\u2014without coupling authentication logic to any specific storage mechanism.
"},{"location":"mail_intake/credentials/store/#mail_intake.credentials.store-classes","title":"Classes","text":""},{"location":"mail_intake/credentials/store/#mail_intake.credentials.store.CredentialStore","title":"CredentialStore","text":" Bases: ABC, Generic[T]
Abstract base class defining a generic persistence interface.
Used for authentication credentials across different backends.
NotesResponsibilities:
- Provide persistent storage separating life-cycle management from\n storage mechanics.\n- Keep implementation focused only on persistence.\nConstraints:
- 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.\nabstractmethod","text":"clear() -> None\nRemove any persisted credentials from the store.
NotesLifecycle:
- 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\nGuarantees:
- Implementations should treat this operation as idempotent\nabstractmethod","text":"load() -> T | None\nLoad previously persisted credentials.
Returns:
Type DescriptionT | None T | None: An instance of type T if credentials are available and loadable; otherwise None.
Guarantees:
- 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.\nabstractmethod","text":"save(credentials: T) -> None\nPersist credentials to the underlying storage backend.
Parameters:
Name Type Description Defaultcredentials T The credential object to persist.
required NotesLifecycle:
- This method is invoked when credentials are newly obtained or have been refreshed and are known to be valid at the time of persistence\nResponsibilities:
- Ensuring durability appropriate to the deployment context\n- Applying encryption or access controls where required\n- Overwriting any previously stored credentials\nMail ingestion orchestration for Mail Intake.
This package contains high-level ingestion components responsible for coordinating mail retrieval, parsing, normalization, and model construction.
It represents the top of the ingestion pipeline and is intended to be the primary interaction surface for library consumers.
Components in this package:
Consumers are expected to construct a mail adapter and pass it to the ingestion layer to begin processing messages and threads.
"},{"location":"mail_intake/ingestion/#mail_intake.ingestion--public-api","title":"Public API","text":"MailIntakeReaderMailIntakeReader(adapter: MailIntakeAdapter)\nHigh-level read-only ingestion interface.
NotesResponsibilities:
- 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.\nConstraints:
- This class is intentionally: Provider-agnostic, stateless beyond\n iteration scope, read-only.\nInitialize the mail reader.
Parameters:
Name Type Description Defaultadapter MailIntakeAdapter Mail adapter implementation used to retrieve raw messages and threads from a mail provider.
required"},{"location":"mail_intake/ingestion/#mail_intake.ingestion.MailIntakeReader-functions","title":"Functions","text":""},{"location":"mail_intake/ingestion/#mail_intake.ingestion.MailIntakeReader.iter_messages","title":"iter_messages","text":"iter_messages(query: str) -> Iterator[MailIntakeMessage]\nIterate over parsed messages matching a provider query.
Parameters:
Name Type Description Defaultquery str Provider-specific query string used to filter messages.
requiredYields:
Name Type DescriptionMailIntakeMessage MailIntakeMessage Fully parsed and normalized MailIntakeMessage instances.
Raises:
Type DescriptionMailIntakeParsingError If a message cannot be parsed.
"},{"location":"mail_intake/ingestion/#mail_intake.ingestion.MailIntakeReader.iter_threads","title":"iter_threads","text":"iter_threads(query: str) -> Iterator[MailIntakeThread]\nIterate over threads constructed from messages matching a query.
Parameters:
Name Type Description Defaultquery str Provider-specific query string used to filter messages.
requiredReturns:
Type DescriptionIterator[MailIntakeThread] Iterator[MailIntakeThread]: An iterator over MailIntakeThread instances.
Raises:
Type Description`MailIntakeParsingError` If a message cannot be parsed.
NotesGuarantees:
- Messages are grouped by `thread_id` and yielded as complete\n thread objects containing all associated messages.\nHigh-level mail ingestion orchestration for Mail Intake.
This module provides the primary, provider-agnostic entry point for reading and processing mail data.
It coordinates:
No provider-specific logic or API semantics are permitted in this layer.
"},{"location":"mail_intake/ingestion/reader/#mail_intake.ingestion.reader-classes","title":"Classes","text":""},{"location":"mail_intake/ingestion/reader/#mail_intake.ingestion.reader.MailIntakeReader","title":"MailIntakeReader","text":"MailIntakeReader(adapter: MailIntakeAdapter)\nHigh-level read-only ingestion interface.
NotesResponsibilities:
- 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.\nConstraints:
- This class is intentionally: Provider-agnostic, stateless beyond\n iteration scope, read-only.\nInitialize the mail reader.
Parameters:
Name Type Description Defaultadapter MailIntakeAdapter Mail adapter implementation used to retrieve raw messages and threads from a mail provider.
required"},{"location":"mail_intake/ingestion/reader/#mail_intake.ingestion.reader.MailIntakeReader-functions","title":"Functions","text":""},{"location":"mail_intake/ingestion/reader/#mail_intake.ingestion.reader.MailIntakeReader.iter_messages","title":"iter_messages","text":"iter_messages(query: str) -> Iterator[MailIntakeMessage]\nIterate over parsed messages matching a provider query.
Parameters:
Name Type Description Defaultquery str Provider-specific query string used to filter messages.
requiredYields:
Name Type DescriptionMailIntakeMessage MailIntakeMessage Fully parsed and normalized MailIntakeMessage instances.
Raises:
Type DescriptionMailIntakeParsingError If a message cannot be parsed.
"},{"location":"mail_intake/ingestion/reader/#mail_intake.ingestion.reader.MailIntakeReader.iter_threads","title":"iter_threads","text":"iter_threads(query: str) -> Iterator[MailIntakeThread]\nIterate over threads constructed from messages matching a query.
Parameters:
Name Type Description Defaultquery str Provider-specific query string used to filter messages.
requiredReturns:
Type DescriptionIterator[MailIntakeThread] Iterator[MailIntakeThread]: An iterator over MailIntakeThread instances.
Raises:
Type Description`MailIntakeParsingError` If a message cannot be parsed.
NotesGuarantees:
- Messages are grouped by `thread_id` and yielded as complete\n thread objects containing all associated messages.\nDomain models for Mail Intake.
This package defines the canonical, provider-agnostic data models used throughout the Mail Intake ingestion pipeline.
Models in this package:
These models form the core internal data contract of the library.
"},{"location":"mail_intake/models/#mail_intake.models--public-api","title":"Public API","text":"MailIntakeMessageMailIntakeThreaddataclass","text":"MailIntakeMessage(\n message_id: str,\n thread_id: str,\n timestamp: datetime,\n from_email: str,\n from_name: str | None,\n subject: str,\n body_text: str,\n snippet: str,\n raw_headers: dict[str, str],\n)\nCanonical internal representation of a single email message.
NotesGuarantees:
- 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.\nConstraints:
- No provider-specific identifiers, payloads, or API semantics\n should appear in this model.\ninstance-attribute","text":"body_text: str\nExtracted plain-text body content of the message.
"},{"location":"mail_intake/models/#mail_intake.models.MailIntakeMessage.from_email","title":"from_emailinstance-attribute","text":"from_email: str\nSender email address.
"},{"location":"mail_intake/models/#mail_intake.models.MailIntakeMessage.from_name","title":"from_nameinstance-attribute","text":"from_name: str | None\nOptional human-readable sender name.
"},{"location":"mail_intake/models/#mail_intake.models.MailIntakeMessage.message_id","title":"message_idinstance-attribute","text":"message_id: str\nProvider-specific message identifier.
"},{"location":"mail_intake/models/#mail_intake.models.MailIntakeMessage.raw_headers","title":"raw_headersinstance-attribute","text":"raw_headers: dict[str, str]\nNormalized mapping of message headers (header name \u2192 value).
"},{"location":"mail_intake/models/#mail_intake.models.MailIntakeMessage.snippet","title":"snippetinstance-attribute","text":"snippet: str\nShort provider-supplied preview snippet of the message.
"},{"location":"mail_intake/models/#mail_intake.models.MailIntakeMessage.subject","title":"subjectinstance-attribute","text":"subject: str\nRaw subject line of the message.
"},{"location":"mail_intake/models/#mail_intake.models.MailIntakeMessage.thread_id","title":"thread_idinstance-attribute","text":"thread_id: str\nProvider-specific thread identifier to which this message belongs.
"},{"location":"mail_intake/models/#mail_intake.models.MailIntakeMessage.timestamp","title":"timestampinstance-attribute","text":"timestamp: datetime\nMessage timestamp as a timezone-naive UTC datetime.
"},{"location":"mail_intake/models/#mail_intake.models.MailIntakeThread","title":"MailIntakeThreaddataclass","text":"MailIntakeThread(\n thread_id: str,\n normalized_subject: str,\n participants: set[str] = ...,\n messages: list[MailIntakeMessage] = ...,\n last_activity_at: datetime | None = ...,\n)\nCanonical internal representation of an email thread.
NotesGuarantees:
- 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.\nclass-attribute instance-attribute","text":"last_activity_at: datetime | None = None\nTimestamp of the most recent message in the thread.
"},{"location":"mail_intake/models/#mail_intake.models.MailIntakeThread.messages","title":"messagesclass-attribute instance-attribute","text":"messages: list[MailIntakeMessage] = field(\n default_factory=list\n)\nOrdered list of messages belonging to this thread.
"},{"location":"mail_intake/models/#mail_intake.models.MailIntakeThread.normalized_subject","title":"normalized_subjectinstance-attribute","text":"normalized_subject: str\nNormalized subject line used to group related messages.
"},{"location":"mail_intake/models/#mail_intake.models.MailIntakeThread.participants","title":"participantsclass-attribute instance-attribute","text":"participants: set[str] = field(default_factory=set)\nSet of unique participant email addresses observed in the thread.
"},{"location":"mail_intake/models/#mail_intake.models.MailIntakeThread.thread_id","title":"thread_idinstance-attribute","text":"thread_id: str\nProvider-specific thread identifier.
"},{"location":"mail_intake/models/#mail_intake.models.MailIntakeThread-functions","title":"Functions","text":""},{"location":"mail_intake/models/#mail_intake.models.MailIntakeThread.add_message","title":"add_message","text":"add_message(message: MailIntakeMessage) -> None\nAdd a message to the thread and update derived fields.
Parameters:
Name Type Description Defaultmessage MailIntakeMessage Parsed mail message to add to the thread.
required NotesResponsibilities:
- Appends the message to the thread.\n- Tracks unique participants.\n- Updates the last activity timestamp.\nMessage domain models for Mail Intake.
This module defines the canonical, provider-agnostic representation of an individual email message as used internally by the Mail Intake ingestion pipeline.
Models in this module are safe to persist and must not contain any provider-specific fields or semantics.
"},{"location":"mail_intake/models/message/#mail_intake.models.message-classes","title":"Classes","text":""},{"location":"mail_intake/models/message/#mail_intake.models.message.MailIntakeMessage","title":"MailIntakeMessagedataclass","text":"MailIntakeMessage(\n message_id: str,\n thread_id: str,\n timestamp: datetime,\n from_email: str,\n from_name: str | None,\n subject: str,\n body_text: str,\n snippet: str,\n raw_headers: dict[str, str],\n)\nCanonical internal representation of a single email message.
NotesGuarantees:
- 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.\nConstraints:
- No provider-specific identifiers, payloads, or API semantics\n should appear in this model.\ninstance-attribute","text":"body_text: str\nExtracted plain-text body content of the message.
"},{"location":"mail_intake/models/message/#mail_intake.models.message.MailIntakeMessage.from_email","title":"from_emailinstance-attribute","text":"from_email: str\nSender email address.
"},{"location":"mail_intake/models/message/#mail_intake.models.message.MailIntakeMessage.from_name","title":"from_nameinstance-attribute","text":"from_name: str | None\nOptional human-readable sender name.
"},{"location":"mail_intake/models/message/#mail_intake.models.message.MailIntakeMessage.message_id","title":"message_idinstance-attribute","text":"message_id: str\nProvider-specific message identifier.
"},{"location":"mail_intake/models/message/#mail_intake.models.message.MailIntakeMessage.raw_headers","title":"raw_headersinstance-attribute","text":"raw_headers: dict[str, str]\nNormalized mapping of message headers (header name \u2192 value).
"},{"location":"mail_intake/models/message/#mail_intake.models.message.MailIntakeMessage.snippet","title":"snippetinstance-attribute","text":"snippet: str\nShort provider-supplied preview snippet of the message.
"},{"location":"mail_intake/models/message/#mail_intake.models.message.MailIntakeMessage.subject","title":"subjectinstance-attribute","text":"subject: str\nRaw subject line of the message.
"},{"location":"mail_intake/models/message/#mail_intake.models.message.MailIntakeMessage.thread_id","title":"thread_idinstance-attribute","text":"thread_id: str\nProvider-specific thread identifier to which this message belongs.
"},{"location":"mail_intake/models/message/#mail_intake.models.message.MailIntakeMessage.timestamp","title":"timestampinstance-attribute","text":"timestamp: datetime\nMessage timestamp as a timezone-naive UTC datetime.
"},{"location":"mail_intake/models/thread/","title":"Thread","text":""},{"location":"mail_intake/models/thread/#mail_intake.models.thread","title":"mail_intake.models.thread","text":""},{"location":"mail_intake/models/thread/#mail_intake.models.thread--summary","title":"Summary","text":"Thread domain models for Mail Intake.
This module defines the canonical, provider-agnostic representation of an email thread as used internally by the Mail Intake ingestion pipeline.
Threads group related messages and serve as the primary unit of reasoning for higher-level correspondence workflows.
"},{"location":"mail_intake/models/thread/#mail_intake.models.thread-classes","title":"Classes","text":""},{"location":"mail_intake/models/thread/#mail_intake.models.thread.MailIntakeThread","title":"MailIntakeThreaddataclass","text":"MailIntakeThread(\n thread_id: str,\n normalized_subject: str,\n participants: set[str] = ...,\n messages: list[MailIntakeMessage] = ...,\n last_activity_at: datetime | None = ...,\n)\nCanonical internal representation of an email thread.
NotesGuarantees:
- 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.\nclass-attribute instance-attribute","text":"last_activity_at: datetime | None = None\nTimestamp of the most recent message in the thread.
"},{"location":"mail_intake/models/thread/#mail_intake.models.thread.MailIntakeThread.messages","title":"messagesclass-attribute instance-attribute","text":"messages: list[MailIntakeMessage] = field(\n default_factory=list\n)\nOrdered list of messages belonging to this thread.
"},{"location":"mail_intake/models/thread/#mail_intake.models.thread.MailIntakeThread.normalized_subject","title":"normalized_subjectinstance-attribute","text":"normalized_subject: str\nNormalized subject line used to group related messages.
"},{"location":"mail_intake/models/thread/#mail_intake.models.thread.MailIntakeThread.participants","title":"participantsclass-attribute instance-attribute","text":"participants: set[str] = field(default_factory=set)\nSet of unique participant email addresses observed in the thread.
"},{"location":"mail_intake/models/thread/#mail_intake.models.thread.MailIntakeThread.thread_id","title":"thread_idinstance-attribute","text":"thread_id: str\nProvider-specific thread identifier.
"},{"location":"mail_intake/models/thread/#mail_intake.models.thread.MailIntakeThread-functions","title":"Functions","text":""},{"location":"mail_intake/models/thread/#mail_intake.models.thread.MailIntakeThread.add_message","title":"add_message","text":"add_message(message: MailIntakeMessage) -> None\nAdd a message to the thread and update derived fields.
Parameters:
Name Type Description Defaultmessage MailIntakeMessage Parsed mail message to add to the thread.
required NotesResponsibilities:
- Appends the message to the thread.\n- Tracks unique participants.\n- Updates the last activity timestamp.\nMessage parsing utilities for Mail Intake.
This package contains provider-aware but adapter-agnostic parsing helpers used to extract and normalize structured information from raw mail payloads.
Parsers in this package are responsible for:
This package does not:
Parsing functions are designed to be composable and are orchestrated by the ingestion layer.
"},{"location":"mail_intake/parsers/#mail_intake.parsers--public-api","title":"Public API","text":"extract_bodyparse_headersextract_sendernormalize_subjectextract_body(payload: dict[str, Any]) -> str\nExtract the best-effort message body from a Gmail payload.
Priority:
text/plaintext/html (stripped to text)Parameters:
Name Type Description Defaultpayload dict[str, Any] Provider-native message payload dictionary.
requiredReturns:
Name Type Descriptionstr str Extracted plain-text message body.
"},{"location":"mail_intake/parsers/#mail_intake.parsers.extract_sender","title":"extract_sender","text":"extract_sender(\n headers: dict[str, str],\n) -> tuple[str, str | None]\nExtract sender email and optional display name from headers.
Parameters:
Name Type Description Defaultheaders dict[str, str] Normalized header dictionary as returned by parse_headers().
Returns:
Type Descriptiontuple[str, str | None] tuple[str, str | None]: A tuple (email, name) where email is the sender email address and name is the display name, or None if unavailable.
Responsibilities:
- This function parses the `From` header and attempts to extract\n sender email address and optional human-readable display name.\nTypical values:
\"John Doe <john@example.com>\" -> (\"john@example.com\", \"John Doe\")\"john@example.com\" -> (\"john@example.com\", None)normalize_subject(subject: str) -> str\nNormalize an email subject for thread-level comparison.
Parameters:
Name Type Description Defaultsubject str Raw subject line from a message header.
requiredReturns:
Name Type Descriptionstr str Normalized subject string suitable for thread grouping.
NotesResponsibilities:
- 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).\nGuarantees:
- This function is intentionally conservative and avoids aggressive\n transformations that could alter the semantic meaning of the subject.\nparse_headers(\n raw_headers: list[dict[str, str]],\n) -> dict[str, str]\nConvert a list of Gmail-style headers into a normalized dict.
Parameters:
Name Type Description Defaultraw_headers list[dict[str, str]] List of header dictionaries, each containing name and value keys.
Returns:
Type Descriptiondict[str, str] dict[str, str]: Dictionary mapping lowercase header names to stripped values.
NotesGuarantees:
- 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.\nTypical usage:
Input:\n [\n {\"name\": \"From\", \"value\": \"John Doe <john@example.com>\"},\n {\"name\": \"Subject\", \"value\": \"Re: Interview Update\"},\n ]\n\nOutput:\n {\n \"from\": \"John Doe <john@example.com>\",\n \"subject\": \"Re: Interview Update\",\n }\nMessage body extraction utilities for Mail Intake.
This module contains helper functions for extracting a best-effort plain-text body from provider-native message payloads.
The logic is intentionally tolerant of malformed or partial data and prefers human-readable text over fidelity to original formatting.
"},{"location":"mail_intake/parsers/body/#mail_intake.parsers.body-classes","title":"Classes","text":""},{"location":"mail_intake/parsers/body/#mail_intake.parsers.body-functions","title":"Functions","text":""},{"location":"mail_intake/parsers/body/#mail_intake.parsers.body.extract_body","title":"extract_body","text":"extract_body(payload: dict[str, Any]) -> str\nExtract the best-effort message body from a Gmail payload.
Priority:
text/plaintext/html (stripped to text)Parameters:
Name Type Description Defaultpayload dict[str, Any] Provider-native message payload dictionary.
requiredReturns:
Name Type Descriptionstr str Extracted plain-text message body.
"},{"location":"mail_intake/parsers/headers/","title":"Headers","text":""},{"location":"mail_intake/parsers/headers/#mail_intake.parsers.headers","title":"mail_intake.parsers.headers","text":""},{"location":"mail_intake/parsers/headers/#mail_intake.parsers.headers--summary","title":"Summary","text":"Message header parsing utilities for Mail Intake.
This module provides helper functions for normalizing and extracting useful information from provider-native message headers.
The functions here are intentionally simple and tolerant of malformed or incomplete header data.
"},{"location":"mail_intake/parsers/headers/#mail_intake.parsers.headers-functions","title":"Functions","text":""},{"location":"mail_intake/parsers/headers/#mail_intake.parsers.headers.extract_sender","title":"extract_sender","text":"extract_sender(\n headers: dict[str, str],\n) -> tuple[str, str | None]\nExtract sender email and optional display name from headers.
Parameters:
Name Type Description Defaultheaders dict[str, str] Normalized header dictionary as returned by parse_headers().
Returns:
Type Descriptiontuple[str, str | None] tuple[str, str | None]: A tuple (email, name) where email is the sender email address and name is the display name, or None if unavailable.
Responsibilities:
- This function parses the `From` header and attempts to extract\n sender email address and optional human-readable display name.\nTypical values:
\"John Doe <john@example.com>\" -> (\"john@example.com\", \"John Doe\")\"john@example.com\" -> (\"john@example.com\", None)parse_headers(\n raw_headers: list[dict[str, str]],\n) -> dict[str, str]\nConvert a list of Gmail-style headers into a normalized dict.
Parameters:
Name Type Description Defaultraw_headers list[dict[str, str]] List of header dictionaries, each containing name and value keys.
Returns:
Type Descriptiondict[str, str] dict[str, str]: Dictionary mapping lowercase header names to stripped values.
NotesGuarantees:
- 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.\nTypical usage:
Input:\n [\n {\"name\": \"From\", \"value\": \"John Doe <john@example.com>\"},\n {\"name\": \"Subject\", \"value\": \"Re: Interview Update\"},\n ]\n\nOutput:\n {\n \"from\": \"John Doe <john@example.com>\",\n \"subject\": \"Re: Interview Update\",\n }\nSubject line normalization utilities for Mail Intake.
This module provides helper functions for normalizing email subject lines to enable reliable thread-level comparison and grouping.
Normalization is intentionally conservative to avoid altering semantic meaning while removing common reply and forward prefixes.
"},{"location":"mail_intake/parsers/subject/#mail_intake.parsers.subject-functions","title":"Functions","text":""},{"location":"mail_intake/parsers/subject/#mail_intake.parsers.subject.normalize_subject","title":"normalize_subject","text":"normalize_subject(subject: str) -> str\nNormalize an email subject for thread-level comparison.
Parameters:
Name Type Description Defaultsubject str Raw subject line from a message header.
requiredReturns:
Name Type Descriptionstr str Normalized subject string suitable for thread grouping.
NotesResponsibilities:
- 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).\nGuarantees:
- This function is intentionally conservative and avoids aggressive\n transformations that could alter the semantic meaning of the subject.\nDomain models for Mail Intake.
This package defines the canonical, provider-agnostic data models used throughout the Mail Intake ingestion pipeline.
Models in this package:
These models form the core internal data contract of the library.
"},{"location":"models/#mail_intake.models--public-api","title":"Public API","text":"MailIntakeMessageMailIntakeThreaddataclass","text":"MailIntakeMessage(\n message_id: str,\n thread_id: str,\n timestamp: datetime,\n from_email: str,\n from_name: str | None,\n subject: str,\n body_text: str,\n snippet: str,\n raw_headers: dict[str, str],\n)\nCanonical internal representation of a single email message.
NotesGuarantees:
- 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.\nConstraints:
- No provider-specific identifiers, payloads, or API semantics\n should appear in this model.\ninstance-attribute","text":"body_text: str\nExtracted plain-text body content of the message.
"},{"location":"models/#mail_intake.models.MailIntakeMessage.from_email","title":"from_emailinstance-attribute","text":"from_email: str\nSender email address.
"},{"location":"models/#mail_intake.models.MailIntakeMessage.from_name","title":"from_nameinstance-attribute","text":"from_name: str | None\nOptional human-readable sender name.
"},{"location":"models/#mail_intake.models.MailIntakeMessage.message_id","title":"message_idinstance-attribute","text":"message_id: str\nProvider-specific message identifier.
"},{"location":"models/#mail_intake.models.MailIntakeMessage.raw_headers","title":"raw_headersinstance-attribute","text":"raw_headers: dict[str, str]\nNormalized mapping of message headers (header name \u2192 value).
"},{"location":"models/#mail_intake.models.MailIntakeMessage.snippet","title":"snippetinstance-attribute","text":"snippet: str\nShort provider-supplied preview snippet of the message.
"},{"location":"models/#mail_intake.models.MailIntakeMessage.subject","title":"subjectinstance-attribute","text":"subject: str\nRaw subject line of the message.
"},{"location":"models/#mail_intake.models.MailIntakeMessage.thread_id","title":"thread_idinstance-attribute","text":"thread_id: str\nProvider-specific thread identifier to which this message belongs.
"},{"location":"models/#mail_intake.models.MailIntakeMessage.timestamp","title":"timestampinstance-attribute","text":"timestamp: datetime\nMessage timestamp as a timezone-naive UTC datetime.
"},{"location":"models/#mail_intake.models.MailIntakeThread","title":"MailIntakeThreaddataclass","text":"MailIntakeThread(\n thread_id: str,\n normalized_subject: str,\n participants: set[str] = ...,\n messages: list[MailIntakeMessage] = ...,\n last_activity_at: datetime | None = ...,\n)\nCanonical internal representation of an email thread.
NotesGuarantees:
- 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.\nclass-attribute instance-attribute","text":"last_activity_at: datetime | None = None\nTimestamp of the most recent message in the thread.
"},{"location":"models/#mail_intake.models.MailIntakeThread.messages","title":"messagesclass-attribute instance-attribute","text":"messages: list[MailIntakeMessage] = field(\n default_factory=list\n)\nOrdered list of messages belonging to this thread.
"},{"location":"models/#mail_intake.models.MailIntakeThread.normalized_subject","title":"normalized_subjectinstance-attribute","text":"normalized_subject: str\nNormalized subject line used to group related messages.
"},{"location":"models/#mail_intake.models.MailIntakeThread.participants","title":"participantsclass-attribute instance-attribute","text":"participants: set[str] = field(default_factory=set)\nSet of unique participant email addresses observed in the thread.
"},{"location":"models/#mail_intake.models.MailIntakeThread.thread_id","title":"thread_idinstance-attribute","text":"thread_id: str\nProvider-specific thread identifier.
"},{"location":"models/#mail_intake.models.MailIntakeThread-functions","title":"Functions","text":""},{"location":"models/#mail_intake.models.MailIntakeThread.add_message","title":"add_message","text":"add_message(message: MailIntakeMessage) -> None\nAdd a message to the thread and update derived fields.
Parameters:
Name Type Description Defaultmessage MailIntakeMessage Parsed mail message to add to the thread.
required NotesResponsibilities:
- Appends the message to the thread.\n- Tracks unique participants.\n- Updates the last activity timestamp.\nMessage domain models for Mail Intake.
This module defines the canonical, provider-agnostic representation of an individual email message as used internally by the Mail Intake ingestion pipeline.
Models in this module are safe to persist and must not contain any provider-specific fields or semantics.
"},{"location":"models/message/#mail_intake.models.message-classes","title":"Classes","text":""},{"location":"models/message/#mail_intake.models.message.MailIntakeMessage","title":"MailIntakeMessagedataclass","text":"MailIntakeMessage(\n message_id: str,\n thread_id: str,\n timestamp: datetime,\n from_email: str,\n from_name: str | None,\n subject: str,\n body_text: str,\n snippet: str,\n raw_headers: dict[str, str],\n)\nCanonical internal representation of a single email message.
NotesGuarantees:
- 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.\nConstraints:
- No provider-specific identifiers, payloads, or API semantics\n should appear in this model.\ninstance-attribute","text":"body_text: str\nExtracted plain-text body content of the message.
"},{"location":"models/message/#mail_intake.models.message.MailIntakeMessage.from_email","title":"from_emailinstance-attribute","text":"from_email: str\nSender email address.
"},{"location":"models/message/#mail_intake.models.message.MailIntakeMessage.from_name","title":"from_nameinstance-attribute","text":"from_name: str | None\nOptional human-readable sender name.
"},{"location":"models/message/#mail_intake.models.message.MailIntakeMessage.message_id","title":"message_idinstance-attribute","text":"message_id: str\nProvider-specific message identifier.
"},{"location":"models/message/#mail_intake.models.message.MailIntakeMessage.raw_headers","title":"raw_headersinstance-attribute","text":"raw_headers: dict[str, str]\nNormalized mapping of message headers (header name \u2192 value).
"},{"location":"models/message/#mail_intake.models.message.MailIntakeMessage.snippet","title":"snippetinstance-attribute","text":"snippet: str\nShort provider-supplied preview snippet of the message.
"},{"location":"models/message/#mail_intake.models.message.MailIntakeMessage.subject","title":"subjectinstance-attribute","text":"subject: str\nRaw subject line of the message.
"},{"location":"models/message/#mail_intake.models.message.MailIntakeMessage.thread_id","title":"thread_idinstance-attribute","text":"thread_id: str\nProvider-specific thread identifier to which this message belongs.
"},{"location":"models/message/#mail_intake.models.message.MailIntakeMessage.timestamp","title":"timestampinstance-attribute","text":"timestamp: datetime\nMessage timestamp as a timezone-naive UTC datetime.
"},{"location":"models/thread/","title":"Thread","text":""},{"location":"models/thread/#mail_intake.models.thread","title":"mail_intake.models.thread","text":""},{"location":"models/thread/#mail_intake.models.thread--summary","title":"Summary","text":"Thread domain models for Mail Intake.
This module defines the canonical, provider-agnostic representation of an email thread as used internally by the Mail Intake ingestion pipeline.
Threads group related messages and serve as the primary unit of reasoning for higher-level correspondence workflows.
"},{"location":"models/thread/#mail_intake.models.thread-classes","title":"Classes","text":""},{"location":"models/thread/#mail_intake.models.thread.MailIntakeThread","title":"MailIntakeThreaddataclass","text":"MailIntakeThread(\n thread_id: str,\n normalized_subject: str,\n participants: set[str] = ...,\n messages: list[MailIntakeMessage] = ...,\n last_activity_at: datetime | None = ...,\n)\nCanonical internal representation of an email thread.
NotesGuarantees:
- 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.\nclass-attribute instance-attribute","text":"last_activity_at: datetime | None = None\nTimestamp of the most recent message in the thread.
"},{"location":"models/thread/#mail_intake.models.thread.MailIntakeThread.messages","title":"messagesclass-attribute instance-attribute","text":"messages: list[MailIntakeMessage] = field(\n default_factory=list\n)\nOrdered list of messages belonging to this thread.
"},{"location":"models/thread/#mail_intake.models.thread.MailIntakeThread.normalized_subject","title":"normalized_subjectinstance-attribute","text":"normalized_subject: str\nNormalized subject line used to group related messages.
"},{"location":"models/thread/#mail_intake.models.thread.MailIntakeThread.participants","title":"participantsclass-attribute instance-attribute","text":"participants: set[str] = field(default_factory=set)\nSet of unique participant email addresses observed in the thread.
"},{"location":"models/thread/#mail_intake.models.thread.MailIntakeThread.thread_id","title":"thread_idinstance-attribute","text":"thread_id: str\nProvider-specific thread identifier.
"},{"location":"models/thread/#mail_intake.models.thread.MailIntakeThread-functions","title":"Functions","text":""},{"location":"models/thread/#mail_intake.models.thread.MailIntakeThread.add_message","title":"add_message","text":"add_message(message: MailIntakeMessage) -> None\nAdd a message to the thread and update derived fields.
Parameters:
Name Type Description Defaultmessage MailIntakeMessage Parsed mail message to add to the thread.
required NotesResponsibilities:
- Appends the message to the thread.\n- Tracks unique participants.\n- Updates the last activity timestamp.\nMessage parsing utilities for Mail Intake.
This package contains provider-aware but adapter-agnostic parsing helpers used to extract and normalize structured information from raw mail payloads.
Parsers in this package are responsible for:
This package does not:
Parsing functions are designed to be composable and are orchestrated by the ingestion layer.
"},{"location":"parsers/#mail_intake.parsers--public-api","title":"Public API","text":"extract_bodyparse_headersextract_sendernormalize_subjectextract_body(payload: dict[str, Any]) -> str\nExtract the best-effort message body from a Gmail payload.
Priority:
text/plaintext/html (stripped to text)Parameters:
Name Type Description Defaultpayload dict[str, Any] Provider-native message payload dictionary.
requiredReturns:
Name Type Descriptionstr str Extracted plain-text message body.
"},{"location":"parsers/#mail_intake.parsers.extract_sender","title":"extract_sender","text":"extract_sender(\n headers: dict[str, str],\n) -> tuple[str, str | None]\nExtract sender email and optional display name from headers.
Parameters:
Name Type Description Defaultheaders dict[str, str] Normalized header dictionary as returned by parse_headers().
Returns:
Type Descriptiontuple[str, str | None] tuple[str, str | None]: A tuple (email, name) where email is the sender email address and name is the display name, or None if unavailable.
Responsibilities:
- This function parses the `From` header and attempts to extract\n sender email address and optional human-readable display name.\nTypical values:
\"John Doe <john@example.com>\" -> (\"john@example.com\", \"John Doe\")\"john@example.com\" -> (\"john@example.com\", None)normalize_subject(subject: str) -> str\nNormalize an email subject for thread-level comparison.
Parameters:
Name Type Description Defaultsubject str Raw subject line from a message header.
requiredReturns:
Name Type Descriptionstr str Normalized subject string suitable for thread grouping.
NotesResponsibilities:
- 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).\nGuarantees:
- This function is intentionally conservative and avoids aggressive\n transformations that could alter the semantic meaning of the subject.\nparse_headers(\n raw_headers: list[dict[str, str]],\n) -> dict[str, str]\nConvert a list of Gmail-style headers into a normalized dict.
Parameters:
Name Type Description Defaultraw_headers list[dict[str, str]] List of header dictionaries, each containing name and value keys.
Returns:
Type Descriptiondict[str, str] dict[str, str]: Dictionary mapping lowercase header names to stripped values.
NotesGuarantees:
- 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.\nTypical usage:
Input:\n [\n {\"name\": \"From\", \"value\": \"John Doe <john@example.com>\"},\n {\"name\": \"Subject\", \"value\": \"Re: Interview Update\"},\n ]\n\nOutput:\n {\n \"from\": \"John Doe <john@example.com>\",\n \"subject\": \"Re: Interview Update\",\n }\nMessage body extraction utilities for Mail Intake.
This module contains helper functions for extracting a best-effort plain-text body from provider-native message payloads.
The logic is intentionally tolerant of malformed or partial data and prefers human-readable text over fidelity to original formatting.
"},{"location":"parsers/body/#mail_intake.parsers.body-classes","title":"Classes","text":""},{"location":"parsers/body/#mail_intake.parsers.body-functions","title":"Functions","text":""},{"location":"parsers/body/#mail_intake.parsers.body.extract_body","title":"extract_body","text":"extract_body(payload: dict[str, Any]) -> str\nExtract the best-effort message body from a Gmail payload.
Priority:
text/plaintext/html (stripped to text)Parameters:
Name Type Description Defaultpayload dict[str, Any] Provider-native message payload dictionary.
requiredReturns:
Name Type Descriptionstr str Extracted plain-text message body.
"},{"location":"parsers/headers/","title":"Headers","text":""},{"location":"parsers/headers/#mail_intake.parsers.headers","title":"mail_intake.parsers.headers","text":""},{"location":"parsers/headers/#mail_intake.parsers.headers--summary","title":"Summary","text":"Message header parsing utilities for Mail Intake.
This module provides helper functions for normalizing and extracting useful information from provider-native message headers.
The functions here are intentionally simple and tolerant of malformed or incomplete header data.
"},{"location":"parsers/headers/#mail_intake.parsers.headers-functions","title":"Functions","text":""},{"location":"parsers/headers/#mail_intake.parsers.headers.extract_sender","title":"extract_sender","text":"extract_sender(\n headers: dict[str, str],\n) -> tuple[str, str | None]\nExtract sender email and optional display name from headers.
Parameters:
Name Type Description Defaultheaders dict[str, str] Normalized header dictionary as returned by parse_headers().
Returns:
Type Descriptiontuple[str, str | None] tuple[str, str | None]: A tuple (email, name) where email is the sender email address and name is the display name, or None if unavailable.
Responsibilities:
- This function parses the `From` header and attempts to extract\n sender email address and optional human-readable display name.\nTypical values:
\"John Doe <john@example.com>\" -> (\"john@example.com\", \"John Doe\")\"john@example.com\" -> (\"john@example.com\", None)parse_headers(\n raw_headers: list[dict[str, str]],\n) -> dict[str, str]\nConvert a list of Gmail-style headers into a normalized dict.
Parameters:
Name Type Description Defaultraw_headers list[dict[str, str]] List of header dictionaries, each containing name and value keys.
Returns:
Type Descriptiondict[str, str] dict[str, str]: Dictionary mapping lowercase header names to stripped values.
NotesGuarantees:
- 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.\nTypical usage:
Input:\n [\n {\"name\": \"From\", \"value\": \"John Doe <john@example.com>\"},\n {\"name\": \"Subject\", \"value\": \"Re: Interview Update\"},\n ]\n\nOutput:\n {\n \"from\": \"John Doe <john@example.com>\",\n \"subject\": \"Re: Interview Update\",\n }\nSubject line normalization utilities for Mail Intake.
This module provides helper functions for normalizing email subject lines to enable reliable thread-level comparison and grouping.
Normalization is intentionally conservative to avoid altering semantic meaning while removing common reply and forward prefixes.
"},{"location":"parsers/subject/#mail_intake.parsers.subject-functions","title":"Functions","text":""},{"location":"parsers/subject/#mail_intake.parsers.subject.normalize_subject","title":"normalize_subject","text":"normalize_subject(subject: str) -> str\nNormalize an email subject for thread-level comparison.
Parameters:
Name Type Description Defaultsubject str Raw subject line from a message header.
requiredReturns:
Name Type Descriptionstr str Normalized subject string suitable for thread grouping.
NotesResponsibilities:
- 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).\nGuarantees:
- This function is intentionally conservative and avoids aggressive\n transformations that could alter the semantic meaning of the subject.\nroutes_moduleAny
+ ModuleType
operationId<
6operationId<
app
- Any
+ FastAPI
@@ -849,7 +849,7 @@ between OpenAPI operations and Python handler functions using operationId<
spec
- dict
+ dict[str, Any]
@@ -863,7 +863,7 @@ between OpenAPI operations and Python handler functions using operationId<
routes_module
- Any
+ ModuleType
diff --git a/openapi-first/lib/openapi_first/app/index.html b/openapi-first/lib/openapi_first/app/index.html
index 3fc0cb2..520ab1a 100644
--- a/openapi-first/lib/openapi_first/app/index.html
+++ b/openapi-first/lib/openapi_first/app/index.html
@@ -820,7 +820,7 @@ specification is treated as the authoritative API contract.
routes_module
- Any
+ ModuleType
diff --git a/openapi-first/lib/openapi_first/binder/index.html b/openapi-first/lib/openapi_first/binder/index.html
index 0bb9d7d..89f2565 100644
--- a/openapi-first/lib/openapi_first/binder/index.html
+++ b/openapi-first/lib/openapi_first/binder/index.html
@@ -708,7 +708,7 @@ between OpenAPI operations and Python handler functions using operationId<
6
@@ -732,7 +732,7 @@ between OpenAPI operations and Python handler functions using operationId<
app
- Any
+ FastAPI
@@ -746,7 +746,7 @@ between OpenAPI operations and Python handler functions using operationId<
spec
- dict
+ dict[str, Any]
@@ -760,7 +760,7 @@ between OpenAPI operations and Python handler functions using operationId<
routes_module
- Any
+ ModuleType
diff --git a/openapi-first/lib/search/search_index.json b/openapi-first/lib/search/search_index.json
index 026feec..81e230a 100644
--- a/openapi-first/lib/search/search_index.json
+++ b/openapi-first/lib/search/search_index.json
@@ -1 +1 @@
-{"config":{"lang":["en"],"separator":"[\\s\\-]+","pipeline":["stopWordFilter"]},"docs":[{"location":"","title":"openapi_first","text":" - Openapi First
"},{"location":"#openapi_first","title":"openapi_first","text":""},{"location":"#openapi_first--summary","title":"Summary","text":"FastAPI OpenAPI First \u2014 strict OpenAPI-first application bootstrap for FastAPI.
FastAPI OpenAPI First is a contract-first infrastructure library that enforces OpenAPI as the single source of truth for FastAPI services.
The library removes decorator-driven routing and replaces it with deterministic, spec-driven application assembly. Every HTTP route, method, and operation is defined in OpenAPI first and bound to Python handlers explicitly via operationId.
"},{"location":"#openapi_first--installation","title":"Installation","text":"Install using pip:
pip install openapi-first\n
Or with Poetry:
poetry add openapi-first\n
"},{"location":"#openapi_first--quick-start","title":"Quick Start","text":"Minimal OpenAPI-first FastAPI application:
from openapi_first import app\nimport my_service.routes as routes\n\napi = app.OpenAPIFirstApp(\n openapi_path=\"openapi.yaml\",\n routes_module=routes,\n title=\"My Service\",\n version=\"1.0.0\",\n)\n
OperationId-driven HTTP client:
from openapi_first.loader import load_openapi\nfrom openapi_first.client import OpenAPIClient\n\nspec = load_openapi(\"openapi.yaml\")\nclient = OpenAPIClient(spec)\n\nresponse = client.get_health()\n
"},{"location":"#openapi_first--architecture","title":"Architecture","text":"The library is structured around four core responsibilities:
loader: Load and validate OpenAPI 3.x specifications (JSON/YAML).binder: Bind OpenAPI operations to FastAPI routes via operationId.app: OpenAPI-first FastAPI application bootstrap.client: OpenAPI-first HTTP client driven by the same specification.errors: Explicit error hierarchy for contract violations.
"},{"location":"#openapi_first--public-api","title":"Public API","text":"The supported public API consists of the following top-level modules:
openapi_first.appopenapi_first.binderopenapi_first.loaderopenapi_first.clientopenapi_first.errors
"},{"location":"#openapi_first--design-guarantees","title":"Design Guarantees","text":" - OpenAPI is the single source of truth.
- No undocumented routes can exist.
- No OpenAPI operation can exist without a handler or client callable.
- All contract violations fail at application startup or client creation.
- No hidden FastAPI magic or implicit behavior.
- Deterministic, testable application assembly.
"},{"location":"app/","title":"App","text":""},{"location":"app/#openapi_first.app","title":"openapi_first.app","text":""},{"location":"app/#openapi_first.app--summary","title":"Summary","text":"OpenAPI-first application bootstrap for FastAPI.
This module provides OpenAPIFirstApp, a thin but strict abstraction that enforces OpenAPI as the single source of truth for a FastAPI service.
Notes Core Principles:
- The OpenAPI specification (JSON or YAML) defines the entire API surface.\n- Every `operationId` in the OpenAPI spec must have a corresponding\n Python handler function.\n- Handlers are plain Python callables (no FastAPI decorators).\n- FastAPI route registration is derived exclusively from the spec.\n- FastAPI's autogenerated OpenAPI schema is fully overridden.\n
Responsibilities:
- Loads and validates an OpenAPI 3.x specification.\n- Dynamically binds HTTP routes to handler functions using `operationId`.\n- Registers routes with FastAPI at application startup.\n- Ensures runtime behavior matches the OpenAPI contract exactly.\n
Constraints:
- This module intentionally does NOT:\n - Generate OpenAPI specs.\n - Generate client code.\n - Introduce a new framework or lifecycle.\n - Alter FastAPI dependency injection semantics.\n
"},{"location":"app/#openapi_first.app-classes","title":"Classes","text":""},{"location":"app/#openapi_first.app.OpenAPIFirstApp","title":"OpenAPIFirstApp","text":"OpenAPIFirstApp(\n *,\n openapi_path: str,\n routes_module: Any,\n **fastapi_kwargs: Any\n)\n
Bases: FastAPI
FastAPI application enforcing OpenAPI-first design.
Notes Responsibilities:
- `OpenAPIFirstApp` subclasses `FastAPI` and replaces manual route\n registration with OpenAPI-driven binding.\n- All routes are derived from the provided OpenAPI specification,\n and each ``operationId`` is mapped to a Python function in the\n supplied routes module.\n- Auth dependencies are auto-injected from the spec's\n ``securitySchemes`` and per-operation ``security`` fields.\n
Guarantees:
- No route can exist without an OpenAPI declaration.\n- No OpenAPI operation can exist without a handler.\n- Swagger UI and ``/openapi.json`` always reflect the provided spec.\n- Handler functions remain framework-agnostic and testable.\n- Auth enforcement is driven entirely by the spec \u2014 no manual\n middleware or decorators required.\n
Example from openapi_first import OpenAPIFirstApp\nimport app.routes as routes\n\napp = OpenAPIFirstApp(\n openapi_path=\"app/openapi.json\",\n routes_module=routes,\n title=\"Example Service\",\n)\n
Initialize the application.
Parameters:
Name Type Description Default openapi_path str Filesystem path to the OpenAPI 3.x specification file. This specification is treated as the authoritative API contract.
required routes_module Any Python module containing handler functions whose names correspond exactly to OpenAPI operationId values.
required **fastapi_kwargs Any Additional keyword arguments passed directly to fastapi.FastAPI (e.g., title, version, middleware, lifespan handlers).
{} Raises:
Type Description OpenAPIFirstError If the OpenAPI specification is invalid, or if any declared operationId does not have a corresponding handler function.
"},{"location":"app/#openapi_first.app.OpenAPIFirstApp-functions","title":"Functions","text":""},{"location":"app/#openapi_first.app-functions","title":"Functions","text":""},{"location":"binder/","title":"Binder","text":""},{"location":"binder/#openapi_first.binder","title":"openapi_first.binder","text":""},{"location":"binder/#openapi_first.binder--summary","title":"Summary","text":"OpenAPI-driven route binding for FastAPI.
This module is responsible for translating an OpenAPI 3.x specification into concrete FastAPI routes. It enforces a strict one-to-one mapping between OpenAPI operations and Python handler functions using operationId.
Notes Core Responsibility:
- Read path + method definitions from an OpenAPI specification.\n- Resolve each `operationId` to a Python callable.\n- Register routes with FastAPI using `APIRoute`.\n- Fail fast when contract violations are detected.\n
Design Constraints:
- All routes MUST be declared in the OpenAPI specification.\n- All OpenAPI operations MUST define an `operationId`.\n- Every `operationId` MUST resolve to a handler function.\n- Handlers are plain Python callables (no decorators required).\n- No implicit route creation or inference is allowed.\n
Constraints:
- This module intentionally does NOT:\n - Perform request or response validation.\n - Generate Pydantic models.\n - Modify FastAPI dependency injection.\n - Interpret OpenAPI semantics beyond routing metadata.\n
"},{"location":"binder/#openapi_first.binder-classes","title":"Classes","text":""},{"location":"binder/#openapi_first.binder-functions","title":"Functions","text":""},{"location":"binder/#openapi_first.binder.bind_routes","title":"bind_routes","text":"bind_routes(\n app: FastAPI,\n spec: dict[str, Any],\n routes_module: Any,\n security_deps: dict[str, list[Any]] | None = None,\n) -> None\n
Bind OpenAPI operations to FastAPI routes.
Parameters:
Name Type Description Default app Any The FastAPI application instance to which routes will be added.
required spec dict Parsed OpenAPI 3.x specification dictionary.
required routes_module Any Python module containing handler functions. Each handler's name MUST exactly match an OpenAPI operationId.
required security_deps dict[str, list[Any]] | None Optional mapping of METHOD:/path \u2192 list[Depends(...)] generated from the spec's securitySchemes and per-operation security fields.
None Raises:
Type Description MissingOperationHandler If an operationId is missing from the spec or if no corresponding handler function exists in the routes module.
Notes Responsibilities:
- Iterates through the OpenAPI specification paths and methods.\n- Resolves each ``operationId`` to a handler function, and registers\n a corresponding ``APIRoute`` on the FastAPI application.\n- Injects FastAPI ``Depends()`` for each security requirement found\n on the operation or inherited from the top-level ``security`` field.\n
Guarantees:
- Route registration is deterministic and spec-driven. No route\n decorators are required or supported. Handler resolution errors\n surface at application startup.\n
"},{"location":"cli/","title":"Cli","text":""},{"location":"cli/#openapi_first.cli","title":"openapi_first.cli","text":""},{"location":"cli/#openapi_first.cli--summary","title":"Summary","text":"Command-line interface for FastAPI OpenAPI-first scaffolding utilities.
This CLI bootstraps OpenAPI-first FastAPI applications from versioned, bundled templates packaged with the library.
"},{"location":"cli/#openapi_first.cli-functions","title":"Functions","text":""},{"location":"cli/#openapi_first.cli.available_templates","title":"available_templates","text":"available_templates() -> list[str]\n
Return a list of available application templates.
Returns:
Type Description list[str] list[str]: Sorted list of template names found in the internal templates directory.
"},{"location":"cli/#openapi_first.cli.copy_template","title":"copy_template","text":"copy_template(template: str, target_dir: Path) -> None\n
Copy a bundled OpenAPI-first application template into a directory.
Parameters:
Name Type Description Default template str Name of the template to copy.
required target_dir Path Filesystem path where the template should be copied.
required Raises:
Type Description FileNotFoundError If the requested template does not exist.
"},{"location":"client/","title":"Client","text":""},{"location":"client/#openapi_first.client","title":"openapi_first.client","text":""},{"location":"client/#openapi_first.client--summary","title":"Summary","text":"OpenAPI-first HTTP client for contract-driven services.
This module provides OpenAPIClient, a thin, strict HTTP client that derives all callable operations directly from an OpenAPI 3.x specification.
It is the client counterpart to OpenAPIFirstApp.
Notes Core Principles:
- The OpenAPI specification is the single source of truth\n- Each operationId becomes a callable Python method\n- No implicit schema mutation or inference\n- No code generation step\n- Minimal abstraction over httpx\n
Responsibilities:
- Parses an OpenAPI 3.x specification\n- Dynamically creates one callable per operationId\n- Enforces presence of servers, paths, and operationId\n- Formats path parameters safely\n- Handles JSON request bodies explicitly\n- Returns raw `httpx.Response` objects\n
Constraints:
- This module intentionally does NOT: Generate client code, validate request/response schemas, deserialize responses, retry requests, implement authentication helpers, or assume non-2xx responses are failures.\n
"},{"location":"client/#openapi_first.client-classes","title":"Classes","text":""},{"location":"client/#openapi_first.client.OpenAPIClient","title":"OpenAPIClient","text":"OpenAPIClient(\n spec: dict[str, Any],\n base_url: str | None = None,\n client: httpx.Client | None = None,\n)\n
OpenAPI-first HTTP client (httpx-based).
Notes Responsibilities:
- This client derives all callable methods directly from an\n OpenAPI 3.x specification. Each `operationId` becomes a method\n on the client instance.\n
Guarantees:
- One callable per `operationId`.\n- Explicit parameters (path, query, headers, body).\n- No implicit schema inference or mutation.\n- Returns raw `httpx.Response` objects.\n- No response validation or deserialization.\n
Example from openapi_first import loader, client\n\nspec = loader.load_openapi(\"openapi.yaml\")\n\napi = client.OpenAPIClient(\n spec=spec,\n base_url=\"http://localhost:8000\",\n)\n\n# Call operationId: getUser\nresponse = api.getUser(\n path_params={\"user_id\": 123}\n)\n\nprint(response.status_code)\nprint(response.json())\n
Initialize the OpenAPI client.
Parameters:
Name Type Description Default spec dict[str, Any] Parsed OpenAPI 3.x specification.
required base_url str | None Base URL of the target service. If omitted, the first entry in the OpenAPI servers list is used.
None client Client | None Optional preconfigured httpx client instance.
None Raises:
Type Description OpenAPIClientError If no servers are defined, spec has no paths, operationIds are missing/duplicate, or required parameters are missing.
"},{"location":"client/#openapi_first.client.OpenAPIClient-functions","title":"Functions","text":""},{"location":"client/#openapi_first.client.OpenAPIClientError","title":"OpenAPIClientError","text":" Bases: OpenAPIFirstError
Raised when an OpenAPI client operation fails.
"},{"location":"codegen/","title":"Codegen","text":""},{"location":"codegen/#openapi_first.codegen","title":"openapi_first.codegen","text":""},{"location":"codegen/#openapi_first.codegen--summary","title":"Summary","text":"Core logic for generating Python source code from OpenAPI specifications.
This module provides reusable utilities for code generation, specifically generating Pydantic models and route handler stubs from OpenAPI 3.x schema definitions.
"},{"location":"codegen/#openapi_first.codegen-functions","title":"Functions","text":""},{"location":"codegen/#openapi_first.codegen.generate_models","title":"generate_models","text":"generate_models(\n spec_path: Path,\n output_path: Path,\n pydantic_version: int = 2,\n) -> None\n
Generate Pydantic models from an OpenAPI specification.
Parameters:
Name Type Description Default spec_path Path Path to the OpenAPI specification file (YAML or JSON).
required output_path Path Path where the generated Python code should be written.
required pydantic_version int The Pydantic version to target (1 or 2). Defaults to 2.
2 Notes Reusability: This function is designed to be used by the CLI and can be exposed as an MCP tool without modification.
"},{"location":"codegen/#openapi_first.codegen.generate_routes","title":"generate_routes","text":"generate_routes(\n spec_path: Path,\n output_dir: Path,\n *,\n use_models: bool = False,\n models_module: str = \"models\"\n) -> list[Path]\n
Generate route handler stubs from an OpenAPI specification.
Creates one <resource>.py file per resource in output_dir. Resources are derived from the first path segment (e.g. /pets and /pets/{id} both group under pets).
Parameters:
Name Type Description Default spec_path Path Path to the OpenAPI specification file (YAML or JSON).
required output_dir Path Directory where the generated route files are written. Created automatically if it does not exist.
required use_models bool If True, import Pydantic models from models_module for request-body schemas referenced via $ref.
False models_module str Dotted Python module path from which to import models (e.g. \"models\", \"app.models\").
'models' Returns:
Type Description list[Path] list[Path]: Absolute paths of every generated route file.
Raises:
Type Description OpenAPISpecLoadError If the spec cannot be loaded or validated.
ValueError If any operation is missing operationId.
"},{"location":"codegen_routes/","title":"Codegen Routes","text":""},{"location":"codegen_routes/#openapi_first.codegen_routes","title":"openapi_first.codegen_routes","text":""},{"location":"codegen_routes/#openapi_first.codegen_routes--summary","title":"Summary","text":"Route handler code generation from OpenAPI specifications.
This module generates Python route handler stubs from an OpenAPI 3.x specification. Each resource (derived from the first path segment) gets its own file under the output directory. Every OpenAPI operation must define an operationId, which becomes the handler function name.
Notes Design constraints:
- ``operationId`` is required on every operation (matching\n ``binder.bind_routes``).\n- Handlers are stubs raising ``NotImplementedError``.\n- Sub-resources (e.g. ``/pets/{id}/photo``) are grouped with their\n parent resource (``pets``).\n- Parameter types and defaults are inferred from the spec.\n- ``response: Response`` is injected for non-200 success codes.\n
"},{"location":"codegen_routes/#openapi_first.codegen_routes-functions","title":"Functions","text":""},{"location":"codegen_routes/#openapi_first.codegen_routes.generate_routes","title":"generate_routes","text":"generate_routes(\n spec_path: Path,\n output_dir: Path,\n *,\n use_models: bool = False,\n models_module: str = \"models\"\n) -> list[Path]\n
Generate route handler stubs from an OpenAPI specification.
Creates one <resource>.py file per resource in output_dir. Resources are derived from the first path segment (e.g. /pets and /pets/{id} both group under pets).
Parameters:
Name Type Description Default spec_path Path Path to the OpenAPI specification file (YAML or JSON).
required output_dir Path Directory where the generated route files are written. Created automatically if it does not exist.
required use_models bool If True, import Pydantic models from models_module for request-body schemas referenced via $ref.
False models_module str Dotted Python module path from which to import models (e.g. \"models\", \"app.models\").
'models' Returns:
Type Description list[Path] list[Path]: Absolute paths of every generated route file.
Raises:
Type Description OpenAPISpecLoadError If the spec cannot be loaded or validated.
ValueError If any operation is missing operationId.
"},{"location":"errors/","title":"Errors","text":""},{"location":"errors/#openapi_first.errors","title":"openapi_first.errors","text":""},{"location":"errors/#openapi_first.errors--summary","title":"Summary","text":"Exceptions for OpenAPI-first FastAPI applications.
This module defines a small hierarchy of explicit, intention-revealing exceptions used to signal contract violations between an OpenAPI specification and its Python implementation.
Notes Design Principles:
- Errors represent programmer mistakes, not runtime conditions.\n- All errors are raised during application startup.\n- Messages are actionable and suitable for CI/CD output.\n- Exceptions are explicit rather than reused from generic built-ins.\n
These errors should normally cause immediate application failure.
"},{"location":"errors/#openapi_first.errors-classes","title":"Classes","text":""},{"location":"errors/#openapi_first.errors.MissingOperationHandler","title":"MissingOperationHandler","text":"MissingOperationHandler(\n *,\n path: str,\n method: str,\n operation_id: str | None = None\n)\n
Bases: OpenAPIFirstError
Raised when an OpenAPI operation cannot be resolved to a handler.
Notes Scenarios:
- An OpenAPI operation does not define an `operationId`.\n- An `operationId` is defined but no matching function exists in\n the provided routes module.\n
Guarantees:
- This represents a violation of the OpenAPI-first contract and\n indicates that the specification and implementation are out of\n sync.\n
Initialize the error.
Parameters:
Name Type Description Default path str The HTTP path declared in the OpenAPI specification.
required method str The HTTP method (as declared in the OpenAPI spec).
required operation_id str | None The operationId declared in the OpenAPI spec, if present.
None"},{"location":"errors/#openapi_first.errors.MissingOperationHandler-functions","title":"Functions","text":""},{"location":"errors/#openapi_first.errors.OpenAPIFirstError","title":"OpenAPIFirstError","text":" Bases: Exception
Base exception for all OpenAPI-first enforcement errors.
Notes Responsibilities:
- This exception exists to allow callers, test suites, and CI\n pipelines to catch and distinguish OpenAPI contract violations\n from unrelated runtime errors.\n- All exceptions raised by the OpenAPI-first core should inherit\n from this type.\n
"},{"location":"loader/","title":"Loader","text":""},{"location":"loader/#openapi_first.loader","title":"openapi_first.loader","text":""},{"location":"loader/#openapi_first.loader--summary","title":"Summary","text":"OpenAPI specification loading and validation utilities.
This module is responsible for loading an OpenAPI 3.x specification from disk and validating it before it is used by the application.
It enforces the principle that an invalid or malformed OpenAPI document must never reach the routing or runtime layers.
Notes Design Principles:
- OpenAPI is treated as an authoritative contract.\n- Invalid specifications fail fast at application startup.\n- Supported formats are JSON and YAML.\n- Validation errors are surfaced clearly and early.\n
Constraints:
- This module intentionally does NOT:\n - Modify the OpenAPI document.\n - Infer missing fields.\n - Generate models or code.\n - Perform request/response validation at runtime.\n
"},{"location":"loader/#openapi_first.loader-classes","title":"Classes","text":""},{"location":"loader/#openapi_first.loader.OpenAPISpecLoadError","title":"OpenAPISpecLoadError","text":" Bases: OpenAPIFirstError
Raised when an OpenAPI specification cannot be loaded or validated.
Notes Guarantees:
- This error indicates that the OpenAPI document is unreadable,\n malformed, or violates the OpenAPI 3.x specification.\n
"},{"location":"loader/#openapi_first.loader-functions","title":"Functions","text":""},{"location":"loader/#openapi_first.loader.load_openapi","title":"load_openapi","text":"load_openapi(path: str | Path) -> dict[str, Any]\n
Load and validate an OpenAPI 3.x specification from disk.
Parameters:
Name Type Description Default path str | Path Filesystem path to an OpenAPI specification file. Supported extensions: .json, .yaml, .yml.
required Returns:
Type Description dict[str, Any] dict[str, Any]: Parsed and validated OpenAPI specification.
Raises:
Type Description OpenAPISpecLoadError If the file does not exist, cannot be parsed, or fails OpenAPI schema validation.
Notes Guarantees:
- The specification is parsed based on file extension and validated\n using a strict OpenAPI schema validator.\n- Any error results in an immediate exception, preventing\n application startup.\n
"},{"location":"security/","title":"Security","text":""},{"location":"security/#openapi_first.security","title":"openapi_first.security","text":""},{"location":"security/#openapi_first.security--summary","title":"Summary","text":"OpenAPI security scheme parsing and auto-generated auth dependencies.
This module reads securitySchemes and per-operation security from an OpenAPI spec, resolves {ENV_VAR} placeholders in x- extension fields, and generates FastAPI dependencies for token validation (e.g., Bearer JWT introspection).
"},{"location":"security/#openapi_first.security-functions","title":"Functions","text":""},{"location":"security/#openapi_first.security.make_security_dependencies","title":"make_security_dependencies","text":"make_security_dependencies(\n spec: dict[str, Any],\n security_schemes: dict[str, dict[str, Any]],\n) -> dict[str, list[Any]]\n
Build a mapping of METHOD:/path \u2192 list of Depends(...).
The effective security for each operation is resolved by:
- Using the operation-level
security field if present. - Falling back to the top-level
security field. - An empty list means no auth required for that operation.
"},{"location":"security/#openapi_first.security.parse_security_schemes","title":"parse_security_schemes","text":"parse_security_schemes(\n spec: dict[str, Any],\n) -> dict[str, dict[str, Any]]\n
Extract and resolve environment variables in security schemes.
"},{"location":"openapi_first/","title":"Openapi First","text":" - App
- Binder
- Cli
- Client
- Codegen
- Codegen Routes
- Errors
- Loader
- Security
- Templates
"},{"location":"openapi_first/#openapi_first","title":"openapi_first","text":""},{"location":"openapi_first/#openapi_first--summary","title":"Summary","text":"FastAPI OpenAPI First \u2014 strict OpenAPI-first application bootstrap for FastAPI.
FastAPI OpenAPI First is a contract-first infrastructure library that enforces OpenAPI as the single source of truth for FastAPI services.
The library removes decorator-driven routing and replaces it with deterministic, spec-driven application assembly. Every HTTP route, method, and operation is defined in OpenAPI first and bound to Python handlers explicitly via operationId.
"},{"location":"openapi_first/#openapi_first--installation","title":"Installation","text":"Install using pip:
pip install openapi-first\n
Or with Poetry:
poetry add openapi-first\n
"},{"location":"openapi_first/#openapi_first--quick-start","title":"Quick Start","text":"Minimal OpenAPI-first FastAPI application:
from openapi_first import app\nimport my_service.routes as routes\n\napi = app.OpenAPIFirstApp(\n openapi_path=\"openapi.yaml\",\n routes_module=routes,\n title=\"My Service\",\n version=\"1.0.0\",\n)\n
OperationId-driven HTTP client:
from openapi_first.loader import load_openapi\nfrom openapi_first.client import OpenAPIClient\n\nspec = load_openapi(\"openapi.yaml\")\nclient = OpenAPIClient(spec)\n\nresponse = client.get_health()\n
"},{"location":"openapi_first/#openapi_first--architecture","title":"Architecture","text":"The library is structured around four core responsibilities:
loader: Load and validate OpenAPI 3.x specifications (JSON/YAML).binder: Bind OpenAPI operations to FastAPI routes via operationId.app: OpenAPI-first FastAPI application bootstrap.client: OpenAPI-first HTTP client driven by the same specification.errors: Explicit error hierarchy for contract violations.
"},{"location":"openapi_first/#openapi_first--public-api","title":"Public API","text":"The supported public API consists of the following top-level modules:
openapi_first.appopenapi_first.binderopenapi_first.loaderopenapi_first.clientopenapi_first.errors
"},{"location":"openapi_first/#openapi_first--design-guarantees","title":"Design Guarantees","text":" - OpenAPI is the single source of truth.
- No undocumented routes can exist.
- No OpenAPI operation can exist without a handler or client callable.
- All contract violations fail at application startup or client creation.
- No hidden FastAPI magic or implicit behavior.
- Deterministic, testable application assembly.
"},{"location":"openapi_first/app/","title":"App","text":""},{"location":"openapi_first/app/#openapi_first.app","title":"openapi_first.app","text":""},{"location":"openapi_first/app/#openapi_first.app--summary","title":"Summary","text":"OpenAPI-first application bootstrap for FastAPI.
This module provides OpenAPIFirstApp, a thin but strict abstraction that enforces OpenAPI as the single source of truth for a FastAPI service.
Notes Core Principles:
- The OpenAPI specification (JSON or YAML) defines the entire API surface.\n- Every `operationId` in the OpenAPI spec must have a corresponding\n Python handler function.\n- Handlers are plain Python callables (no FastAPI decorators).\n- FastAPI route registration is derived exclusively from the spec.\n- FastAPI's autogenerated OpenAPI schema is fully overridden.\n
Responsibilities:
- Loads and validates an OpenAPI 3.x specification.\n- Dynamically binds HTTP routes to handler functions using `operationId`.\n- Registers routes with FastAPI at application startup.\n- Ensures runtime behavior matches the OpenAPI contract exactly.\n
Constraints:
- This module intentionally does NOT:\n - Generate OpenAPI specs.\n - Generate client code.\n - Introduce a new framework or lifecycle.\n - Alter FastAPI dependency injection semantics.\n
"},{"location":"openapi_first/app/#openapi_first.app-classes","title":"Classes","text":""},{"location":"openapi_first/app/#openapi_first.app.OpenAPIFirstApp","title":"OpenAPIFirstApp","text":"OpenAPIFirstApp(\n *,\n openapi_path: str,\n routes_module: Any,\n **fastapi_kwargs: Any\n)\n
Bases: FastAPI
FastAPI application enforcing OpenAPI-first design.
Notes Responsibilities:
- `OpenAPIFirstApp` subclasses `FastAPI` and replaces manual route\n registration with OpenAPI-driven binding.\n- All routes are derived from the provided OpenAPI specification,\n and each ``operationId`` is mapped to a Python function in the\n supplied routes module.\n- Auth dependencies are auto-injected from the spec's\n ``securitySchemes`` and per-operation ``security`` fields.\n
Guarantees:
- No route can exist without an OpenAPI declaration.\n- No OpenAPI operation can exist without a handler.\n- Swagger UI and ``/openapi.json`` always reflect the provided spec.\n- Handler functions remain framework-agnostic and testable.\n- Auth enforcement is driven entirely by the spec \u2014 no manual\n middleware or decorators required.\n
Example from openapi_first import OpenAPIFirstApp\nimport app.routes as routes\n\napp = OpenAPIFirstApp(\n openapi_path=\"app/openapi.json\",\n routes_module=routes,\n title=\"Example Service\",\n)\n
Initialize the application.
Parameters:
Name Type Description Default openapi_path str Filesystem path to the OpenAPI 3.x specification file. This specification is treated as the authoritative API contract.
required routes_module Any Python module containing handler functions whose names correspond exactly to OpenAPI operationId values.
required **fastapi_kwargs Any Additional keyword arguments passed directly to fastapi.FastAPI (e.g., title, version, middleware, lifespan handlers).
{} Raises:
Type Description OpenAPIFirstError If the OpenAPI specification is invalid, or if any declared operationId does not have a corresponding handler function.
"},{"location":"openapi_first/app/#openapi_first.app.OpenAPIFirstApp-functions","title":"Functions","text":""},{"location":"openapi_first/app/#openapi_first.app-functions","title":"Functions","text":""},{"location":"openapi_first/binder/","title":"Binder","text":""},{"location":"openapi_first/binder/#openapi_first.binder","title":"openapi_first.binder","text":""},{"location":"openapi_first/binder/#openapi_first.binder--summary","title":"Summary","text":"OpenAPI-driven route binding for FastAPI.
This module is responsible for translating an OpenAPI 3.x specification into concrete FastAPI routes. It enforces a strict one-to-one mapping between OpenAPI operations and Python handler functions using operationId.
Notes Core Responsibility:
- Read path + method definitions from an OpenAPI specification.\n- Resolve each `operationId` to a Python callable.\n- Register routes with FastAPI using `APIRoute`.\n- Fail fast when contract violations are detected.\n
Design Constraints:
- All routes MUST be declared in the OpenAPI specification.\n- All OpenAPI operations MUST define an `operationId`.\n- Every `operationId` MUST resolve to a handler function.\n- Handlers are plain Python callables (no decorators required).\n- No implicit route creation or inference is allowed.\n
Constraints:
- This module intentionally does NOT:\n - Perform request or response validation.\n - Generate Pydantic models.\n - Modify FastAPI dependency injection.\n - Interpret OpenAPI semantics beyond routing metadata.\n
"},{"location":"openapi_first/binder/#openapi_first.binder-classes","title":"Classes","text":""},{"location":"openapi_first/binder/#openapi_first.binder-functions","title":"Functions","text":""},{"location":"openapi_first/binder/#openapi_first.binder.bind_routes","title":"bind_routes","text":"bind_routes(\n app: FastAPI,\n spec: dict[str, Any],\n routes_module: Any,\n security_deps: dict[str, list[Any]] | None = None,\n) -> None\n
Bind OpenAPI operations to FastAPI routes.
Parameters:
Name Type Description Default app Any The FastAPI application instance to which routes will be added.
required spec dict Parsed OpenAPI 3.x specification dictionary.
required routes_module Any Python module containing handler functions. Each handler's name MUST exactly match an OpenAPI operationId.
required security_deps dict[str, list[Any]] | None Optional mapping of METHOD:/path \u2192 list[Depends(...)] generated from the spec's securitySchemes and per-operation security fields.
None Raises:
Type Description MissingOperationHandler If an operationId is missing from the spec or if no corresponding handler function exists in the routes module.
Notes Responsibilities:
- Iterates through the OpenAPI specification paths and methods.\n- Resolves each ``operationId`` to a handler function, and registers\n a corresponding ``APIRoute`` on the FastAPI application.\n- Injects FastAPI ``Depends()`` for each security requirement found\n on the operation or inherited from the top-level ``security`` field.\n
Guarantees:
- Route registration is deterministic and spec-driven. No route\n decorators are required or supported. Handler resolution errors\n surface at application startup.\n
"},{"location":"openapi_first/cli/","title":"Cli","text":""},{"location":"openapi_first/cli/#openapi_first.cli","title":"openapi_first.cli","text":""},{"location":"openapi_first/cli/#openapi_first.cli--summary","title":"Summary","text":"Command-line interface for FastAPI OpenAPI-first scaffolding utilities.
This CLI bootstraps OpenAPI-first FastAPI applications from versioned, bundled templates packaged with the library.
"},{"location":"openapi_first/cli/#openapi_first.cli-functions","title":"Functions","text":""},{"location":"openapi_first/cli/#openapi_first.cli.available_templates","title":"available_templates","text":"available_templates() -> list[str]\n
Return a list of available application templates.
Returns:
Type Description list[str] list[str]: Sorted list of template names found in the internal templates directory.
"},{"location":"openapi_first/cli/#openapi_first.cli.copy_template","title":"copy_template","text":"copy_template(template: str, target_dir: Path) -> None\n
Copy a bundled OpenAPI-first application template into a directory.
Parameters:
Name Type Description Default template str Name of the template to copy.
required target_dir Path Filesystem path where the template should be copied.
required Raises:
Type Description FileNotFoundError If the requested template does not exist.
"},{"location":"openapi_first/client/","title":"Client","text":""},{"location":"openapi_first/client/#openapi_first.client","title":"openapi_first.client","text":""},{"location":"openapi_first/client/#openapi_first.client--summary","title":"Summary","text":"OpenAPI-first HTTP client for contract-driven services.
This module provides OpenAPIClient, a thin, strict HTTP client that derives all callable operations directly from an OpenAPI 3.x specification.
It is the client counterpart to OpenAPIFirstApp.
Notes Core Principles:
- The OpenAPI specification is the single source of truth\n- Each operationId becomes a callable Python method\n- No implicit schema mutation or inference\n- No code generation step\n- Minimal abstraction over httpx\n
Responsibilities:
- Parses an OpenAPI 3.x specification\n- Dynamically creates one callable per operationId\n- Enforces presence of servers, paths, and operationId\n- Formats path parameters safely\n- Handles JSON request bodies explicitly\n- Returns raw `httpx.Response` objects\n
Constraints:
- This module intentionally does NOT: Generate client code, validate request/response schemas, deserialize responses, retry requests, implement authentication helpers, or assume non-2xx responses are failures.\n
"},{"location":"openapi_first/client/#openapi_first.client-classes","title":"Classes","text":""},{"location":"openapi_first/client/#openapi_first.client.OpenAPIClient","title":"OpenAPIClient","text":"OpenAPIClient(\n spec: dict[str, Any],\n base_url: str | None = None,\n client: httpx.Client | None = None,\n)\n
OpenAPI-first HTTP client (httpx-based).
Notes Responsibilities:
- This client derives all callable methods directly from an\n OpenAPI 3.x specification. Each `operationId` becomes a method\n on the client instance.\n
Guarantees:
- One callable per `operationId`.\n- Explicit parameters (path, query, headers, body).\n- No implicit schema inference or mutation.\n- Returns raw `httpx.Response` objects.\n- No response validation or deserialization.\n
Example from openapi_first import loader, client\n\nspec = loader.load_openapi(\"openapi.yaml\")\n\napi = client.OpenAPIClient(\n spec=spec,\n base_url=\"http://localhost:8000\",\n)\n\n# Call operationId: getUser\nresponse = api.getUser(\n path_params={\"user_id\": 123}\n)\n\nprint(response.status_code)\nprint(response.json())\n
Initialize the OpenAPI client.
Parameters:
Name Type Description Default spec dict[str, Any] Parsed OpenAPI 3.x specification.
required base_url str | None Base URL of the target service. If omitted, the first entry in the OpenAPI servers list is used.
None client Client | None Optional preconfigured httpx client instance.
None Raises:
Type Description OpenAPIClientError If no servers are defined, spec has no paths, operationIds are missing/duplicate, or required parameters are missing.
"},{"location":"openapi_first/client/#openapi_first.client.OpenAPIClient-functions","title":"Functions","text":""},{"location":"openapi_first/client/#openapi_first.client.OpenAPIClientError","title":"OpenAPIClientError","text":" Bases: OpenAPIFirstError
Raised when an OpenAPI client operation fails.
"},{"location":"openapi_first/codegen/","title":"Codegen","text":""},{"location":"openapi_first/codegen/#openapi_first.codegen","title":"openapi_first.codegen","text":""},{"location":"openapi_first/codegen/#openapi_first.codegen--summary","title":"Summary","text":"Core logic for generating Python source code from OpenAPI specifications.
This module provides reusable utilities for code generation, specifically generating Pydantic models and route handler stubs from OpenAPI 3.x schema definitions.
"},{"location":"openapi_first/codegen/#openapi_first.codegen-functions","title":"Functions","text":""},{"location":"openapi_first/codegen/#openapi_first.codegen.generate_models","title":"generate_models","text":"generate_models(\n spec_path: Path,\n output_path: Path,\n pydantic_version: int = 2,\n) -> None\n
Generate Pydantic models from an OpenAPI specification.
Parameters:
Name Type Description Default spec_path Path Path to the OpenAPI specification file (YAML or JSON).
required output_path Path Path where the generated Python code should be written.
required pydantic_version int The Pydantic version to target (1 or 2). Defaults to 2.
2 Notes Reusability: This function is designed to be used by the CLI and can be exposed as an MCP tool without modification.
"},{"location":"openapi_first/codegen/#openapi_first.codegen.generate_routes","title":"generate_routes","text":"generate_routes(\n spec_path: Path,\n output_dir: Path,\n *,\n use_models: bool = False,\n models_module: str = \"models\"\n) -> list[Path]\n
Generate route handler stubs from an OpenAPI specification.
Creates one <resource>.py file per resource in output_dir. Resources are derived from the first path segment (e.g. /pets and /pets/{id} both group under pets).
Parameters:
Name Type Description Default spec_path Path Path to the OpenAPI specification file (YAML or JSON).
required output_dir Path Directory where the generated route files are written. Created automatically if it does not exist.
required use_models bool If True, import Pydantic models from models_module for request-body schemas referenced via $ref.
False models_module str Dotted Python module path from which to import models (e.g. \"models\", \"app.models\").
'models' Returns:
Type Description list[Path] list[Path]: Absolute paths of every generated route file.
Raises:
Type Description OpenAPISpecLoadError If the spec cannot be loaded or validated.
ValueError If any operation is missing operationId.
"},{"location":"openapi_first/codegen_routes/","title":"Codegen Routes","text":""},{"location":"openapi_first/codegen_routes/#openapi_first.codegen_routes","title":"openapi_first.codegen_routes","text":""},{"location":"openapi_first/codegen_routes/#openapi_first.codegen_routes--summary","title":"Summary","text":"Route handler code generation from OpenAPI specifications.
This module generates Python route handler stubs from an OpenAPI 3.x specification. Each resource (derived from the first path segment) gets its own file under the output directory. Every OpenAPI operation must define an operationId, which becomes the handler function name.
Notes Design constraints:
- ``operationId`` is required on every operation (matching\n ``binder.bind_routes``).\n- Handlers are stubs raising ``NotImplementedError``.\n- Sub-resources (e.g. ``/pets/{id}/photo``) are grouped with their\n parent resource (``pets``).\n- Parameter types and defaults are inferred from the spec.\n- ``response: Response`` is injected for non-200 success codes.\n
"},{"location":"openapi_first/codegen_routes/#openapi_first.codegen_routes-functions","title":"Functions","text":""},{"location":"openapi_first/codegen_routes/#openapi_first.codegen_routes.generate_routes","title":"generate_routes","text":"generate_routes(\n spec_path: Path,\n output_dir: Path,\n *,\n use_models: bool = False,\n models_module: str = \"models\"\n) -> list[Path]\n
Generate route handler stubs from an OpenAPI specification.
Creates one <resource>.py file per resource in output_dir. Resources are derived from the first path segment (e.g. /pets and /pets/{id} both group under pets).
Parameters:
Name Type Description Default spec_path Path Path to the OpenAPI specification file (YAML or JSON).
required output_dir Path Directory where the generated route files are written. Created automatically if it does not exist.
required use_models bool If True, import Pydantic models from models_module for request-body schemas referenced via $ref.
False models_module str Dotted Python module path from which to import models (e.g. \"models\", \"app.models\").
'models' Returns:
Type Description list[Path] list[Path]: Absolute paths of every generated route file.
Raises:
Type Description OpenAPISpecLoadError If the spec cannot be loaded or validated.
ValueError If any operation is missing operationId.
"},{"location":"openapi_first/errors/","title":"Errors","text":""},{"location":"openapi_first/errors/#openapi_first.errors","title":"openapi_first.errors","text":""},{"location":"openapi_first/errors/#openapi_first.errors--summary","title":"Summary","text":"Exceptions for OpenAPI-first FastAPI applications.
This module defines a small hierarchy of explicit, intention-revealing exceptions used to signal contract violations between an OpenAPI specification and its Python implementation.
Notes Design Principles:
- Errors represent programmer mistakes, not runtime conditions.\n- All errors are raised during application startup.\n- Messages are actionable and suitable for CI/CD output.\n- Exceptions are explicit rather than reused from generic built-ins.\n
These errors should normally cause immediate application failure.
"},{"location":"openapi_first/errors/#openapi_first.errors-classes","title":"Classes","text":""},{"location":"openapi_first/errors/#openapi_first.errors.MissingOperationHandler","title":"MissingOperationHandler","text":"MissingOperationHandler(\n *,\n path: str,\n method: str,\n operation_id: str | None = None\n)\n
Bases: OpenAPIFirstError
Raised when an OpenAPI operation cannot be resolved to a handler.
Notes Scenarios:
- An OpenAPI operation does not define an `operationId`.\n- An `operationId` is defined but no matching function exists in\n the provided routes module.\n
Guarantees:
- This represents a violation of the OpenAPI-first contract and\n indicates that the specification and implementation are out of\n sync.\n
Initialize the error.
Parameters:
Name Type Description Default path str The HTTP path declared in the OpenAPI specification.
required method str The HTTP method (as declared in the OpenAPI spec).
required operation_id str | None The operationId declared in the OpenAPI spec, if present.
None"},{"location":"openapi_first/errors/#openapi_first.errors.MissingOperationHandler-functions","title":"Functions","text":""},{"location":"openapi_first/errors/#openapi_first.errors.OpenAPIFirstError","title":"OpenAPIFirstError","text":" Bases: Exception
Base exception for all OpenAPI-first enforcement errors.
Notes Responsibilities:
- This exception exists to allow callers, test suites, and CI\n pipelines to catch and distinguish OpenAPI contract violations\n from unrelated runtime errors.\n- All exceptions raised by the OpenAPI-first core should inherit\n from this type.\n
"},{"location":"openapi_first/loader/","title":"Loader","text":""},{"location":"openapi_first/loader/#openapi_first.loader","title":"openapi_first.loader","text":""},{"location":"openapi_first/loader/#openapi_first.loader--summary","title":"Summary","text":"OpenAPI specification loading and validation utilities.
This module is responsible for loading an OpenAPI 3.x specification from disk and validating it before it is used by the application.
It enforces the principle that an invalid or malformed OpenAPI document must never reach the routing or runtime layers.
Notes Design Principles:
- OpenAPI is treated as an authoritative contract.\n- Invalid specifications fail fast at application startup.\n- Supported formats are JSON and YAML.\n- Validation errors are surfaced clearly and early.\n
Constraints:
- This module intentionally does NOT:\n - Modify the OpenAPI document.\n - Infer missing fields.\n - Generate models or code.\n - Perform request/response validation at runtime.\n
"},{"location":"openapi_first/loader/#openapi_first.loader-classes","title":"Classes","text":""},{"location":"openapi_first/loader/#openapi_first.loader.OpenAPISpecLoadError","title":"OpenAPISpecLoadError","text":" Bases: OpenAPIFirstError
Raised when an OpenAPI specification cannot be loaded or validated.
Notes Guarantees:
- This error indicates that the OpenAPI document is unreadable,\n malformed, or violates the OpenAPI 3.x specification.\n
"},{"location":"openapi_first/loader/#openapi_first.loader-functions","title":"Functions","text":""},{"location":"openapi_first/loader/#openapi_first.loader.load_openapi","title":"load_openapi","text":"load_openapi(path: str | Path) -> dict[str, Any]\n
Load and validate an OpenAPI 3.x specification from disk.
Parameters:
Name Type Description Default path str | Path Filesystem path to an OpenAPI specification file. Supported extensions: .json, .yaml, .yml.
required Returns:
Type Description dict[str, Any] dict[str, Any]: Parsed and validated OpenAPI specification.
Raises:
Type Description OpenAPISpecLoadError If the file does not exist, cannot be parsed, or fails OpenAPI schema validation.
Notes Guarantees:
- The specification is parsed based on file extension and validated\n using a strict OpenAPI schema validator.\n- Any error results in an immediate exception, preventing\n application startup.\n
"},{"location":"openapi_first/security/","title":"Security","text":""},{"location":"openapi_first/security/#openapi_first.security","title":"openapi_first.security","text":""},{"location":"openapi_first/security/#openapi_first.security--summary","title":"Summary","text":"OpenAPI security scheme parsing and auto-generated auth dependencies.
This module reads securitySchemes and per-operation security from an OpenAPI spec, resolves {ENV_VAR} placeholders in x- extension fields, and generates FastAPI dependencies for token validation (e.g., Bearer JWT introspection).
"},{"location":"openapi_first/security/#openapi_first.security-functions","title":"Functions","text":""},{"location":"openapi_first/security/#openapi_first.security.make_security_dependencies","title":"make_security_dependencies","text":"make_security_dependencies(\n spec: dict[str, Any],\n security_schemes: dict[str, dict[str, Any]],\n) -> dict[str, list[Any]]\n
Build a mapping of METHOD:/path \u2192 list of Depends(...).
The effective security for each operation is resolved by:
- Using the operation-level
security field if present. - Falling back to the top-level
security field. - An empty list means no auth required for that operation.
"},{"location":"openapi_first/security/#openapi_first.security.parse_security_schemes","title":"parse_security_schemes","text":"parse_security_schemes(\n spec: dict[str, Any],\n) -> dict[str, dict[str, Any]]\n
Extract and resolve environment variables in security schemes.
"},{"location":"openapi_first/templates/","title":"Templates","text":" - Crud App
- Health App
- Model App
- Vet App
"},{"location":"openapi_first/templates/#openapi_first.templates","title":"openapi_first.templates","text":"Application templates for FastAPI OpenAPI First.
This package contains example and scaffolding templates intended to be copied into user projects via the openapi-first CLI.
Templates in this package are: - Reference implementations of OpenAPI-first services - Not part of the openapi_first public or internal API - Not intended to be imported as runtime dependencies
The presence of this file exists solely to: - Mark the directory as an explicit Python package - Enable deterministic tooling behavior (documentation, packaging) - Avoid accidental traversal of non-package directories
No code in this package should be imported by library consumers.
"},{"location":"openapi_first/templates/crud_app/","title":"Crud App","text":" - Data
- Main
- Routes
- Test Crud App
"},{"location":"openapi_first/templates/crud_app/#openapi_first.templates.crud_app","title":"openapi_first.templates.crud_app","text":"OpenAPI-first CRUD application template.
This package contains a complete, minimal example of an OpenAPI-first CRUD service built using the openapi_first library.
The application is assembled exclusively from: - an OpenAPI specification (openapi.yaml) - a handler namespace implementing CRUD operations (routes) - an in-memory mock data store (data)
All HTTP routes, methods, schemas, and operation bindings are defined in the OpenAPI specification and enforced at application startup. No decorator-driven routing or implicit framework behavior is used.
This template demonstrates: - operationId-driven server-side route binding - explicit HTTP status code control in handlers - operationId-driven client usage against the same OpenAPI contract - end-to-end validation using in-memory data and tests
"},{"location":"openapi_first/templates/crud_app/#openapi_first.templates.crud_app--scaffolding-via-cli","title":"Scaffolding via CLI","text":"Create a new CRUD example service using the bundled template:
openapi-first crud_app\n
Create the service in a custom directory:
openapi-first crud_app my-crud-service\n
List all available application templates:
openapi-first --list\n
The CLI copies template files verbatim into the target directory. No code is generated or modified beyond the copied scaffold.
"},{"location":"openapi_first/templates/crud_app/#openapi_first.templates.crud_app--client-usage-example","title":"Client Usage Example","text":"The same OpenAPI specification used by the server can be used to construct a strict, operationId-driven HTTP client.
Example client calls for CRUD operations:
from openapi_first.loader import load_openapi\nfrom openapi_first.client import OpenAPIClient\n\nspec = load_openapi(\"openapi.yaml\")\nclient = OpenAPIClient(spec)\n\n# List items\nresponse = client.list_items()\n\n# Get item by ID\nresponse = client.get_item(\n path_params={\"item_id\": 1}\n)\n\n# Create item\nresponse = client.create_item(\n body={\"name\": \"Orange\", \"price\": 0.8}\n)\n\n# Update item\nresponse = client.update_item(\n path_params={\"item_id\": 1},\n body={\"name\": \"Green Apple\", \"price\": 0.6},\n)\n\n# Delete item\nresponse = client.delete_item(\n path_params={\"item_id\": 1}\n)\n
Client guarantees: - One callable per OpenAPI operationId - No hardcoded URLs or HTTP methods in user code - Path and request parameters must match the OpenAPI specification - Invalid or incomplete OpenAPI specs fail at client construction time
"},{"location":"openapi_first/templates/crud_app/#openapi_first.templates.crud_app--non-goals","title":"Non-Goals","text":"This template is intentionally minimal and is NOT: - production-ready - persistent or concurrency-safe - a reference architecture for data storage
It exists solely as a copyable example for learning, testing, and bootstrapping OpenAPI-first services.
This package is not part of the openapi_first library API surface.
"},{"location":"openapi_first/templates/crud_app/data/","title":"Data","text":""},{"location":"openapi_first/templates/crud_app/data/#openapi_first.templates.crud_app.data","title":"openapi_first.templates.crud_app.data","text":"In-memory mock data store for CRUD example.
This module intentionally avoids persistence and concurrency guarantees. It is suitable for demos, tests, and scaffolding only.
It intentionally avoids - persistence - concurrency guarantees - validation - error handling
The implementation is suitable for: - demonstrations - tests - scaffolding and example services
It is explicitly NOT suitable for production use.
This module is not part of the openapi_first library API surface.
"},{"location":"openapi_first/templates/crud_app/data/#openapi_first.templates.crud_app.data-functions","title":"Functions","text":""},{"location":"openapi_first/templates/crud_app/data/#openapi_first.templates.crud_app.data.create_item","title":"create_item","text":"create_item(payload: dict)\n
Create a new item in the data store.
A new integer ID is assigned automatically. No validation is performed on the provided payload.
"},{"location":"openapi_first/templates/crud_app/data/#openapi_first.templates.crud_app.data.create_item--parameters","title":"Parameters","text":"payload : dict Item attributes excluding the id field.
"},{"location":"openapi_first/templates/crud_app/data/#openapi_first.templates.crud_app.data.create_item--returns","title":"Returns","text":"dict The newly created item, including its assigned ID.
"},{"location":"openapi_first/templates/crud_app/data/#openapi_first.templates.crud_app.data.delete_item","title":"delete_item","text":"delete_item(item_id: int)\n
Remove an item from the data store.
This function assumes the item exists and will raise KeyError if the ID is not present.
"},{"location":"openapi_first/templates/crud_app/data/#openapi_first.templates.crud_app.data.delete_item--parameters","title":"Parameters","text":"item_id : int Identifier of the item to delete.
"},{"location":"openapi_first/templates/crud_app/data/#openapi_first.templates.crud_app.data.get_item","title":"get_item","text":"get_item(item_id: int)\n
Retrieve a single item by ID.
This function assumes the item exists and will raise KeyError if the ID is not present in the store.
"},{"location":"openapi_first/templates/crud_app/data/#openapi_first.templates.crud_app.data.get_item--parameters","title":"Parameters","text":"item_id : int Identifier of the item to retrieve.
"},{"location":"openapi_first/templates/crud_app/data/#openapi_first.templates.crud_app.data.get_item--returns","title":"Returns","text":"dict The stored item representation.
"},{"location":"openapi_first/templates/crud_app/data/#openapi_first.templates.crud_app.data.list_items","title":"list_items","text":"list_items()\n
Return all items in the data store.
This function performs no filtering, pagination, or sorting. The returned collection reflects the current in-memory state.
"},{"location":"openapi_first/templates/crud_app/data/#openapi_first.templates.crud_app.data.list_items--returns","title":"Returns","text":"list[dict] A list of item representations.
"},{"location":"openapi_first/templates/crud_app/data/#openapi_first.templates.crud_app.data.update_item","title":"update_item","text":"update_item(item_id: int, payload: dict)\n
Replace an existing item in the data store.
This function overwrites the existing item entirely and does not perform partial updates or validation. If the item does not exist, it will be created implicitly.
"},{"location":"openapi_first/templates/crud_app/data/#openapi_first.templates.crud_app.data.update_item--parameters","title":"Parameters","text":"item_id : int Identifier of the item to update. payload : dict Item attributes excluding the id field.
"},{"location":"openapi_first/templates/crud_app/data/#openapi_first.templates.crud_app.data.update_item--returns","title":"Returns","text":"dict The updated item representation.
"},{"location":"openapi_first/templates/crud_app/main/","title":"Main","text":""},{"location":"openapi_first/templates/crud_app/main/#openapi_first.templates.crud_app.main","title":"openapi_first.templates.crud_app.main","text":"Application entry point for an OpenAPI-first CRUD example service.
This module constructs a FastAPI application exclusively from an OpenAPI specification and a handler namespace, without using decorator-driven routing.
All HTTP routes, methods, request/response schemas, and operation bindings are defined in the OpenAPI document referenced by openapi_path. Python callables defined in the routes module are bound to OpenAPI operations strictly via operationId.
This module contains no routing logic, persistence concerns, or framework configuration beyond application assembly.
Design guarantees: - OpenAPI is the single source of truth - No undocumented routes can exist - Every OpenAPI operationId must resolve to exactly one handler - All contract violations fail at application startup
This file is intended to be used as the ASGI entry point.
Example uvicorn main:app
"},{"location":"openapi_first/templates/crud_app/main/#openapi_first.templates.crud_app.main-classes","title":"Classes","text":""},{"location":"openapi_first/templates/crud_app/routes/","title":"Routes","text":""},{"location":"openapi_first/templates/crud_app/routes/#openapi_first.templates.crud_app.routes","title":"openapi_first.templates.crud_app.routes","text":"CRUD route handlers bound via OpenAPI operationId.
These handlers explicitly control HTTP status codes to ensure runtime behavior matches the OpenAPI contract.
This module defines OpenAPI-bound operation handlers for a simple CRUD service. Functions in this module are bound to HTTP routes exclusively via OpenAPI operationId values.
Handlers explicitly control HTTP response status codes to ensure runtime behavior matches the OpenAPI contract. Error conditions are translated into explicit HTTP responses rather than relying on implicit framework behavior.
No routing decorators or path definitions appear in this module. All routing, HTTP methods, and schemas are defined in the OpenAPI specification.
"},{"location":"openapi_first/templates/crud_app/routes/#openapi_first.templates.crud_app.routes-functions","title":"Functions","text":""},{"location":"openapi_first/templates/crud_app/routes/#openapi_first.templates.crud_app.routes.create_item","title":"create_item","text":"create_item(payload: dict, response: Response)\n
Create a new item.
Implements the OpenAPI operation identified by operationId: create_item.
"},{"location":"openapi_first/templates/crud_app/routes/#openapi_first.templates.crud_app.routes.create_item--parameters","title":"Parameters","text":"payload : dict Item attributes excluding the id field. response : fastapi.Response Response object used to set the HTTP status code.
"},{"location":"openapi_first/templates/crud_app/routes/#openapi_first.templates.crud_app.routes.create_item--returns","title":"Returns","text":"dict The newly created item.
"},{"location":"openapi_first/templates/crud_app/routes/#openapi_first.templates.crud_app.routes.delete_item","title":"delete_item","text":"delete_item(item_id: int, response: Response)\n
Delete an existing item.
Implements the OpenAPI operation identified by operationId: delete_item.
"},{"location":"openapi_first/templates/crud_app/routes/#openapi_first.templates.crud_app.routes.delete_item--parameters","title":"Parameters","text":"item_id : int Identifier of the item to delete. response : fastapi.Response Response object used to set the HTTP status code.
"},{"location":"openapi_first/templates/crud_app/routes/#openapi_first.templates.crud_app.routes.delete_item--returns","title":"Returns","text":"None No content.
"},{"location":"openapi_first/templates/crud_app/routes/#openapi_first.templates.crud_app.routes.delete_item--raises","title":"Raises","text":"HTTPException 404 if the item does not exist.
"},{"location":"openapi_first/templates/crud_app/routes/#openapi_first.templates.crud_app.routes.get_item","title":"get_item","text":"get_item(item_id: int)\n
Retrieve a single item by ID.
Implements the OpenAPI operation identified by operationId: get_item.
"},{"location":"openapi_first/templates/crud_app/routes/#openapi_first.templates.crud_app.routes.get_item--parameters","title":"Parameters","text":"item_id : int Identifier of the item to retrieve.
"},{"location":"openapi_first/templates/crud_app/routes/#openapi_first.templates.crud_app.routes.get_item--returns","title":"Returns","text":"dict The requested item.
"},{"location":"openapi_first/templates/crud_app/routes/#openapi_first.templates.crud_app.routes.get_item--raises","title":"Raises","text":"HTTPException 404 if the item does not exist.
"},{"location":"openapi_first/templates/crud_app/routes/#openapi_first.templates.crud_app.routes.list_items","title":"list_items","text":"list_items()\n
List all items.
Implements the OpenAPI operation identified by operationId: list_items.
"},{"location":"openapi_first/templates/crud_app/routes/#openapi_first.templates.crud_app.routes.list_items--returns","title":"Returns","text":"list[dict] A list of item representations.
"},{"location":"openapi_first/templates/crud_app/routes/#openapi_first.templates.crud_app.routes.update_item","title":"update_item","text":"update_item(item_id: int, payload: dict)\n
Update an existing item.
Implements the OpenAPI operation identified by operationId: update_item.
"},{"location":"openapi_first/templates/crud_app/routes/#openapi_first.templates.crud_app.routes.update_item--parameters","title":"Parameters","text":"item_id : int Identifier of the item to update. payload : dict Item attributes excluding the id field.
"},{"location":"openapi_first/templates/crud_app/routes/#openapi_first.templates.crud_app.routes.update_item--returns","title":"Returns","text":"dict The updated item.
"},{"location":"openapi_first/templates/crud_app/routes/#openapi_first.templates.crud_app.routes.update_item--raises","title":"Raises","text":"HTTPException 404 if the item does not exist.
"},{"location":"openapi_first/templates/crud_app/test_crud_app/","title":"Test Crud App","text":""},{"location":"openapi_first/templates/crud_app/test_crud_app/#openapi_first.templates.crud_app.test_crud_app","title":"openapi_first.templates.crud_app.test_crud_app","text":"End-to-end tests for the OpenAPI-first CRUD example app.
These tests validate that all CRUD operations behave correctly against the in-memory mock data store. - OpenAPI specification loading - OperationId-driven route binding on the server - OperationId-driven client invocation - Correct HTTP status codes and response payloads
The tests exercise all CRUD operations against an in-memory mock data store and assume deterministic behavior within a single process.
The tests assume: - OpenAPI-first route binding - In-memory storage (no persistence guarantees) - Deterministic behavior in a single process - One-to-one correspondence between OpenAPI operationId values and server/client callables
"},{"location":"openapi_first/templates/crud_app/test_crud_app/#openapi_first.templates.crud_app.test_crud_app-classes","title":"Classes","text":""},{"location":"openapi_first/templates/crud_app/test_crud_app/#openapi_first.templates.crud_app.test_crud_app-functions","title":"Functions","text":""},{"location":"openapi_first/templates/crud_app/test_crud_app/#openapi_first.templates.crud_app.test_crud_app.test_create_item","title":"test_create_item","text":"test_create_item()\n
Creating a new item should return the created entity.
"},{"location":"openapi_first/templates/crud_app/test_crud_app/#openapi_first.templates.crud_app.test_crud_app.test_delete_item","title":"test_delete_item","text":"test_delete_item()\n
Deleting an item should remove it from the store.
"},{"location":"openapi_first/templates/crud_app/test_crud_app/#openapi_first.templates.crud_app.test_crud_app.test_get_item","title":"test_get_item","text":"test_get_item()\n
Existing item should be retrievable by ID.
"},{"location":"openapi_first/templates/crud_app/test_crud_app/#openapi_first.templates.crud_app.test_crud_app.test_list_items_initial","title":"test_list_items_initial","text":"test_list_items_initial()\n
Initial items should be present.
"},{"location":"openapi_first/templates/crud_app/test_crud_app/#openapi_first.templates.crud_app.test_crud_app.test_update_item","title":"test_update_item","text":"test_update_item()\n
Updating an item should replace its values.
"},{"location":"openapi_first/templates/health_app/","title":"Health App","text":" - Main
- Routes
"},{"location":"openapi_first/templates/health_app/#openapi_first.templates.health_app","title":"openapi_first.templates.health_app","text":"OpenAPI-first FastAPI application template.
This package contains a minimal, fully working example of an OpenAPI-first FastAPI service built using the openapi_first library.
The application is assembled exclusively from: - an OpenAPI specification (openapi.yaml) - a handler namespace (routes)
No routing decorators, implicit behavior, or framework-specific convenience abstractions are used. All HTTP routes, methods, and operation bindings are defined in OpenAPI and enforced at application startup.
This package is intended to be copied as a starting point for new services via the openapi-first CLI. It is not part of the openapi_first library API surface.
"},{"location":"openapi_first/templates/health_app/#openapi_first.templates.health_app--scaffolding-via-cli","title":"Scaffolding via CLI","text":"Create a new OpenAPI-first health check service using the bundled template:
openapi-first health_app\n
Create the service in a custom directory:
openapi-first health_app my-health-service\n
List all available application templates:
openapi-first --list\n
The CLI copies template files verbatim into the target directory. No code is generated or modified beyond the copied scaffold.
"},{"location":"openapi_first/templates/health_app/#openapi_first.templates.health_app--client-usage-example","title":"Client Usage Example","text":"The same OpenAPI specification used by the server can be used to construct a strict, operationId-driven HTTP client.
Example client call for the get_health operation:
from openapi_first.loader import load_openapi\nfrom openapi_first.client import OpenAPIClient\n\nspec = load_openapi(\"openapi.yaml\")\nclient = OpenAPIClient(spec)\n\nresponse = client.get_health()\n\nassert response.status_code == 200\nassert response.json() == {\"status\": \"ok\"}\n
Client guarantees: - One callable per OpenAPI operationId - No hardcoded URLs or HTTP methods in user code - Path and request parameters must match the OpenAPI specification - Invalid or incomplete OpenAPI specs fail at client construction time
"},{"location":"openapi_first/templates/health_app/main/","title":"Main","text":""},{"location":"openapi_first/templates/health_app/main/#openapi_first.templates.health_app.main","title":"openapi_first.templates.health_app.main","text":"Application entry point for an OpenAPI-first FastAPI service.
This module constructs a FastAPI application exclusively from an OpenAPI specification and a handler namespace, without using decorator-driven routing.
All HTTP routes, methods, and operation bindings are defined in the OpenAPI document referenced by openapi_path. Python callables defined in the routes module are bound to OpenAPI operations strictly via operationId.
This module contains no routing logic, request handling, or framework configuration beyond application assembly.
Design guarantees: - OpenAPI is the single source of truth - No undocumented routes can exist - Every OpenAPI operationId must resolve to exactly one handler - All contract violations fail at application startup
This file is intended to be used as the ASGI entry point.
Example uvicorn main:app
"},{"location":"openapi_first/templates/health_app/main/#openapi_first.templates.health_app.main-classes","title":"Classes","text":""},{"location":"openapi_first/templates/health_app/routes/","title":"Routes","text":""},{"location":"openapi_first/templates/health_app/routes/#openapi_first.templates.health_app.routes","title":"openapi_first.templates.health_app.routes","text":"OpenAPI operation handlers.
This module defines pure Python callables that implement OpenAPI operations for this service. Functions in this module are bound to HTTP routes exclusively via OpenAPI operationId values.
No routing decorators, HTTP metadata, or framework-specific logic should appear here. All request/response semantics are defined in the OpenAPI specification.
This module serves solely as an operationId namespace.
"},{"location":"openapi_first/templates/health_app/routes/#openapi_first.templates.health_app.routes-functions","title":"Functions","text":""},{"location":"openapi_first/templates/health_app/routes/#openapi_first.templates.health_app.routes.get_health","title":"get_health","text":"get_health()\n
Health check operation handler.
This function implements the OpenAPI operation identified by operationId: get_health.
It contains no routing metadata or framework-specific logic. Request binding, HTTP method, and response semantics are defined exclusively by the OpenAPI specification.
"},{"location":"openapi_first/templates/health_app/routes/#openapi_first.templates.health_app.routes.get_health--returns","title":"Returns","text":"dict A minimal liveness payload indicating service health.
"},{"location":"openapi_first/templates/model_app/","title":"Model App","text":" - Data
- Main
- Models
- Routes
- Test Model App
"},{"location":"openapi_first/templates/model_app/#openapi_first.templates.model_app","title":"openapi_first.templates.model_app","text":"OpenAPI-first model-based CRUD application template.
This package contains a complete, minimal example of an OpenAPI-first CRUD service that uses explicit Pydantic domain models for request and response schemas.
The application is assembled exclusively from: - an OpenAPI specification (openapi.yaml) - a handler namespace implementing CRUD operations (routes) - Pydantic domain models (models) - an in-memory mock data store (data)
All HTTP routes, methods, schemas, and operation bindings are defined in the OpenAPI specification and enforced at application startup. No decorator-driven routing or implicit framework behavior is used.
This template demonstrates: - operationId-driven server-side route binding - explicit request and response modeling with Pydantic - explicit HTTP status code control in handlers - operationId-driven client usage against the same OpenAPI contract - end-to-end validation using in-memory data and tests
"},{"location":"openapi_first/templates/model_app/#openapi_first.templates.model_app--scaffolding-via-cli","title":"Scaffolding via CLI","text":"Create a new model-based CRUD example service using the bundled template:
openapi-first model_app\n
Create the service in a custom directory:
openapi-first model_app my-model-service\n
List all available application templates:
openapi-first --list\n
The CLI copies template files verbatim into the target directory. No code is generated or modified beyond the copied scaffold.
"},{"location":"openapi_first/templates/model_app/#openapi_first.templates.model_app--client-usage-example","title":"Client Usage Example","text":"The same OpenAPI specification used by the server can be used to construct a strict, operationId-driven HTTP client.
Example client calls for model-based CRUD operations:
from openapi_first.loader import load_openapi\nfrom openapi_first.client import OpenAPIClient\n\nspec = load_openapi(\"openapi.yaml\")\nclient = OpenAPIClient(spec)\n\n# List items\nresponse = client.list_items()\n\n# Get item by ID\nresponse = client.get_item(\n path_params={\"item_id\": 1}\n)\n\n# Create item\nresponse = client.create_item(\n body={\"name\": \"Orange\", \"price\": 0.8}\n)\n\n# Update item\nresponse = client.update_item(\n path_params={\"item_id\": 1},\n body={\"name\": \"Green Apple\", \"price\": 0.6},\n)\n\n# Delete item\nresponse = client.delete_item(\n path_params={\"item_id\": 1}\n)\n
Client guarantees: - One callable per OpenAPI operationId - No hardcoded URLs or HTTP methods in user code - Request and response payloads conform to Pydantic models - Invalid or incomplete OpenAPI specs fail at client construction time
"},{"location":"openapi_first/templates/model_app/#openapi_first.templates.model_app--non-goals","title":"Non-Goals","text":"This template is intentionally minimal and is NOT: - production-ready - persistent or concurrency-safe - a reference architecture for data storage
It exists solely as a copyable example for learning, testing, and bootstrapping OpenAPI-first services.
This package is not part of the openapi_first library API surface.
"},{"location":"openapi_first/templates/model_app/data/","title":"Data","text":""},{"location":"openapi_first/templates/model_app/data/#openapi_first.templates.model_app.data","title":"openapi_first.templates.model_app.data","text":"In-memory data store using Pydantic models.
This module is NOT thread-safe and is intended for demos and scaffolds only. This module provides a minimal, process-local data store for the model-based CRUD example application. It stores and returns domain objects defined using Pydantic models and is intended solely for demonstration and scaffolding purposes.
The implementation intentionally avoids: - persistence - concurrency guarantees - transactional semantics - validation beyond what Pydantic provides
It is not part of the openapi_first library API surface.
"},{"location":"openapi_first/templates/model_app/data/#openapi_first.templates.model_app.data-functions","title":"Functions","text":""},{"location":"openapi_first/templates/model_app/data/#openapi_first.templates.model_app.data.create_item","title":"create_item","text":"create_item(payload: ItemCreate) -> Item\n
Create a new item in the data store.
A new identifier is assigned automatically. No additional validation is performed beyond Pydantic model validation.
"},{"location":"openapi_first/templates/model_app/data/#openapi_first.templates.model_app.data.create_item--parameters","title":"Parameters","text":"payload : ItemCreate Data required to create a new item.
"},{"location":"openapi_first/templates/model_app/data/#openapi_first.templates.model_app.data.create_item--returns","title":"Returns","text":"Item The newly created item.
"},{"location":"openapi_first/templates/model_app/data/#openapi_first.templates.model_app.data.delete_item","title":"delete_item","text":"delete_item(item_id: int) -> None\n
Remove an item from the data store.
"},{"location":"openapi_first/templates/model_app/data/#openapi_first.templates.model_app.data.delete_item--parameters","title":"Parameters","text":"item_id : int Identifier of the item to delete.
"},{"location":"openapi_first/templates/model_app/data/#openapi_first.templates.model_app.data.delete_item--raises","title":"Raises","text":"KeyError If the item does not exist.
"},{"location":"openapi_first/templates/model_app/data/#openapi_first.templates.model_app.data.get_item","title":"get_item","text":"get_item(item_id: int) -> Item\n
Retrieve a single item by ID.
"},{"location":"openapi_first/templates/model_app/data/#openapi_first.templates.model_app.data.get_item--parameters","title":"Parameters","text":"item_id : int Identifier of the item to retrieve.
"},{"location":"openapi_first/templates/model_app/data/#openapi_first.templates.model_app.data.get_item--returns","title":"Returns","text":"Item The requested item.
"},{"location":"openapi_first/templates/model_app/data/#openapi_first.templates.model_app.data.get_item--raises","title":"Raises","text":"KeyError If the item does not exist.
"},{"location":"openapi_first/templates/model_app/data/#openapi_first.templates.model_app.data.list_items","title":"list_items","text":"list_items() -> list[Item]\n
Return all items in the data store.
"},{"location":"openapi_first/templates/model_app/data/#openapi_first.templates.model_app.data.list_items--returns","title":"Returns","text":"list[Item] A list of item domain objects.
"},{"location":"openapi_first/templates/model_app/data/#openapi_first.templates.model_app.data.update_item","title":"update_item","text":"update_item(item_id: int, payload: ItemCreate) -> Item\n
Replace an existing item in the data store.
This function performs a full replacement of the stored item. Partial updates are not supported.
"},{"location":"openapi_first/templates/model_app/data/#openapi_first.templates.model_app.data.update_item--parameters","title":"Parameters","text":"item_id : int Identifier of the item to update. payload : ItemCreate New item data.
"},{"location":"openapi_first/templates/model_app/data/#openapi_first.templates.model_app.data.update_item--returns","title":"Returns","text":"Item The updated item.
"},{"location":"openapi_first/templates/model_app/data/#openapi_first.templates.model_app.data.update_item--raises","title":"Raises","text":"KeyError If the item does not exist.
"},{"location":"openapi_first/templates/model_app/main/","title":"Main","text":""},{"location":"openapi_first/templates/model_app/main/#openapi_first.templates.model_app.main","title":"openapi_first.templates.model_app.main","text":"Application entry point for an OpenAPI-first model-based CRUD example service.
This module constructs a FastAPI application exclusively from an OpenAPI specification and a handler namespace, without using decorator-driven routing.
All HTTP routes, methods, request/response schemas, and operation bindings are defined in the OpenAPI document referenced by openapi_path. Python callables defined in the routes module are bound to OpenAPI operations strictly via operationId.
This module contains no routing logic, persistence concerns, or framework configuration beyond application assembly.
Design guarantees: - OpenAPI is the single source of truth - No undocumented routes can exist - Every OpenAPI operationId must resolve to exactly one handler - All contract violations fail at application startup
This file is intended to be used as the ASGI entry point.
Example uvicorn main:app
"},{"location":"openapi_first/templates/model_app/main/#openapi_first.templates.model_app.main-classes","title":"Classes","text":""},{"location":"openapi_first/templates/model_app/models/","title":"Models","text":""},{"location":"openapi_first/templates/model_app/models/#openapi_first.templates.model_app.models","title":"openapi_first.templates.model_app.models","text":"Pydantic domain models for the CRUD example.
This module defines Pydantic models that represent the domain entities used by the service. These models are referenced by the OpenAPI specification for request and response schemas.
The models are declarative and framework-agnostic. They contain no persistence logic, validation beyond type constraints, or business behavior.
This module is not part of the openapi_first library API surface. It exists solely to support the example application template.
"},{"location":"openapi_first/templates/model_app/models/#openapi_first.templates.model_app.models-classes","title":"Classes","text":""},{"location":"openapi_first/templates/model_app/models/#openapi_first.templates.model_app.models.Item","title":"Item","text":" Bases: ItemBase
Domain model for a persisted item.
This model represents the full item state returned in responses, including the server-assigned identifier.
"},{"location":"openapi_first/templates/model_app/models/#openapi_first.templates.model_app.models.ItemBase","title":"ItemBase","text":" Bases: BaseModel
Base domain model for an item.
Defines fields common to all item representations.
"},{"location":"openapi_first/templates/model_app/models/#openapi_first.templates.model_app.models.ItemCreate","title":"ItemCreate","text":" Bases: ItemBase
Domain model for item creation requests.
This model is used for request bodies when creating new items. It intentionally excludes the id field, which is assigned by the service.
"},{"location":"openapi_first/templates/model_app/routes/","title":"Routes","text":""},{"location":"openapi_first/templates/model_app/routes/#openapi_first.templates.model_app.routes","title":"openapi_first.templates.model_app.routes","text":"CRUD route handlers bound via OpenAPI operationId.
This module defines OpenAPI-bound operation handlers for a model-based CRUD service. Functions in this module are bound to HTTP routes exclusively via OpenAPI operationId values.
Handlers explicitly control HTTP response status codes to ensure runtime behavior matches the OpenAPI contract. Domain models defined using Pydantic are used for request and response payloads.
No routing decorators, path definitions, or implicit framework behavior appear in this module. All routing, HTTP methods, and schemas are defined in the OpenAPI specification.
"},{"location":"openapi_first/templates/model_app/routes/#openapi_first.templates.model_app.routes-functions","title":"Functions","text":""},{"location":"openapi_first/templates/model_app/routes/#openapi_first.templates.model_app.routes.create_item","title":"create_item","text":"create_item(payload: ItemCreate, response: Response)\n
Create a new item.
Implements the OpenAPI operation identified by operationId: create_item.
"},{"location":"openapi_first/templates/model_app/routes/#openapi_first.templates.model_app.routes.create_item--parameters","title":"Parameters","text":"payload : ItemCreate Request body describing the item to create. response : fastapi.Response Response object used to set the HTTP status code.
"},{"location":"openapi_first/templates/model_app/routes/#openapi_first.templates.model_app.routes.create_item--returns","title":"Returns","text":"Item The newly created item.
"},{"location":"openapi_first/templates/model_app/routes/#openapi_first.templates.model_app.routes.delete_item","title":"delete_item","text":"delete_item(item_id: int, response: Response)\n
Delete an existing item.
Implements the OpenAPI operation identified by operationId: delete_item.
"},{"location":"openapi_first/templates/model_app/routes/#openapi_first.templates.model_app.routes.delete_item--parameters","title":"Parameters","text":"item_id : int Identifier of the item to delete. response : fastapi.Response Response object used to set the HTTP status code.
"},{"location":"openapi_first/templates/model_app/routes/#openapi_first.templates.model_app.routes.delete_item--returns","title":"Returns","text":"None No content.
"},{"location":"openapi_first/templates/model_app/routes/#openapi_first.templates.model_app.routes.delete_item--raises","title":"Raises","text":"HTTPException 404 if the item does not exist.
"},{"location":"openapi_first/templates/model_app/routes/#openapi_first.templates.model_app.routes.get_item","title":"get_item","text":"get_item(item_id: int)\n
Retrieve a single item by ID.
Implements the OpenAPI operation identified by operationId: get_item.
"},{"location":"openapi_first/templates/model_app/routes/#openapi_first.templates.model_app.routes.get_item--parameters","title":"Parameters","text":"item_id : int Identifier of the item to retrieve.
"},{"location":"openapi_first/templates/model_app/routes/#openapi_first.templates.model_app.routes.get_item--returns","title":"Returns","text":"Item The requested item.
"},{"location":"openapi_first/templates/model_app/routes/#openapi_first.templates.model_app.routes.get_item--raises","title":"Raises","text":"HTTPException 404 if the item does not exist.
"},{"location":"openapi_first/templates/model_app/routes/#openapi_first.templates.model_app.routes.list_items","title":"list_items","text":"list_items()\n
List all items.
Implements the OpenAPI operation identified by operationId: list_items.
"},{"location":"openapi_first/templates/model_app/routes/#openapi_first.templates.model_app.routes.list_items--returns","title":"Returns","text":"list[Item] A list of item domain objects.
"},{"location":"openapi_first/templates/model_app/routes/#openapi_first.templates.model_app.routes.update_item","title":"update_item","text":"update_item(item_id: int, payload: ItemCreate)\n
Update an existing item.
Implements the OpenAPI operation identified by operationId: update_item.
"},{"location":"openapi_first/templates/model_app/routes/#openapi_first.templates.model_app.routes.update_item--parameters","title":"Parameters","text":"item_id : int Identifier of the item to update. payload : ItemCreate New item data.
"},{"location":"openapi_first/templates/model_app/routes/#openapi_first.templates.model_app.routes.update_item--returns","title":"Returns","text":"Item The updated item.
"},{"location":"openapi_first/templates/model_app/routes/#openapi_first.templates.model_app.routes.update_item--raises","title":"Raises","text":"HTTPException 404 if the item does not exist.
"},{"location":"openapi_first/templates/model_app/test_model_app/","title":"Test Model App","text":""},{"location":"openapi_first/templates/model_app/test_model_app/#openapi_first.templates.model_app.test_model_app","title":"openapi_first.templates.model_app.test_model_app","text":"End-to-end tests for the OpenAPI-first model CRUD example app.
These tests validate that all CRUD operations behave correctly against the in-memory mock data store using Pydantic models. - OpenAPI specification loading - OperationId-driven route binding on the server - OperationId-driven client invocation - Pydantic model-based request and response handling
All CRUD operations are exercised against an in-memory mock data store backed by Pydantic domain models.
The tests assume: - OpenAPI-first route binding - Pydantic model validation - In-memory storage (no persistence guarantees) - Deterministic behavior in a single process
"},{"location":"openapi_first/templates/model_app/test_model_app/#openapi_first.templates.model_app.test_model_app-classes","title":"Classes","text":""},{"location":"openapi_first/templates/model_app/test_model_app/#openapi_first.templates.model_app.test_model_app-functions","title":"Functions","text":""},{"location":"openapi_first/templates/model_app/test_model_app/#openapi_first.templates.model_app.test_model_app.test_create_item","title":"test_create_item","text":"test_create_item()\n
Creating a new item should return the created entity.
"},{"location":"openapi_first/templates/model_app/test_model_app/#openapi_first.templates.model_app.test_model_app.test_delete_item","title":"test_delete_item","text":"test_delete_item()\n
Deleting an item should remove it from the store.
"},{"location":"openapi_first/templates/model_app/test_model_app/#openapi_first.templates.model_app.test_model_app.test_get_item","title":"test_get_item","text":"test_get_item()\n
Existing item should be retrievable by ID.
"},{"location":"openapi_first/templates/model_app/test_model_app/#openapi_first.templates.model_app.test_model_app.test_list_items_initial","title":"test_list_items_initial","text":"test_list_items_initial()\n
Initial items should be present.
"},{"location":"openapi_first/templates/model_app/test_model_app/#openapi_first.templates.model_app.test_model_app.test_update_item","title":"test_update_item","text":"test_update_item()\n
Updating an item should replace its values.
"},{"location":"openapi_first/templates/vet_app/","title":"Vet App","text":" - Data
- Main
- Models
- Routes
- Sse
- Test Vet App
"},{"location":"openapi_first/templates/vet_app/#openapi_first.templates.vet_app","title":"openapi_first.templates.vet_app","text":"OpenAPI-first Veterinary Clinic application template.
This package contains a complete, runnable example of an OpenAPI-first veterinary clinic management service. It demonstrates all x- extension fields consumed by the react-openapi admin panel renderer.
The application manages five resources:
- Parents \u2014 pet owners with contact details
- Vets \u2014 veterinarians with specializations
- Treatments \u2014 medical procedure catalog
- Pets \u2014 animals with species, age, weight, and photos
- Appointments \u2014 scheduled visits linking pets, vets, and treatments
All HTTP routes, methods, schemas, and operation bindings are defined in the OpenAPI specification (openapi.yaml). Every operation has an explicit operationId that maps to a Python handler in routes.py.
This file is a copyable template. It is not part of the openapi_first library API surface.
"},{"location":"openapi_first/templates/vet_app/#openapi_first.templates.vet_app--openapi-x-extension-fields-demonstrated","title":"OpenAPI x- extension fields demonstrated","text":"Schema-level extensions (display metadata for resource endpoints):
x-primary-key (REQUIRED) Primary key property name x-display-format (REQUIRED) Human-readable label template x-list-columns (REQUIRED) Columns for the datatable
Property-level extensions (control UI rendering):
x-label (REQUIRED) Human-readable field label x-order (REQUIRED) Field ordering in forms/detail x-description (optional) Helper text below form fields x-hidden (optional) Visibility in form / list / detail x-filterable (optional) Allows column filtering x-sortable (optional) Allows column sorting x-fk (optional) Foreign key \u2014 renders as dropdown x-fk.resource (REQUIRED for FK) Target resource name x-fk.prefetch (optional) Preload all FK options on mount x-ui-type (optional) Custom UI type (e.g. image upload) x-upload-url (optional) Upload endpoint for binary fields
"},{"location":"openapi_first/templates/vet_app/#openapi_first.templates.vet_app--scaffolding-via-cli","title":"Scaffolding via CLI","text":"Create a new vet clinic service using the bundled template:
openapi-first vet_app\n
Create the service in a custom directory:
openapi-first vet_app my-vet-clinic\n
"},{"location":"openapi_first/templates/vet_app/#openapi_first.templates.vet_app--client-usage-example","title":"Client Usage Example","text":"from openapi_first.loader import load_openapi\nfrom openapi_first.client import OpenAPIClient\n\nspec = load_openapi(\"openapi.yaml\")\nclient = OpenAPIClient(spec)\n\n# List pets with pagination\nresponse = client.list_pets(query_params={\"limit\": 10, \"offset\": 0})\n\n# Create a pet with FK references\nresponse = client.create_pet(\n body={\"name\": \"Fido\", \"species\": \"dog\", \"parents\": [1, 2]}\n)\n\n# Upload a pet photo\nresponse = client.upload_pet_photo(\n path_params={\"id\": 1},\n body={\"file\": open(\"photo.jpg\", \"rb\")},\n)\n
"},{"location":"openapi_first/templates/vet_app/#openapi_first.templates.vet_app--non-goals","title":"Non-Goals","text":"This template is intentionally minimal and is NOT: - production-ready - persistent or concurrency-safe - a reference architecture for data storage
It exists solely as a copyable example for learning, testing, and bootstrapping OpenAPI-first services.
This package is not part of the openapi_first library API surface.
"},{"location":"openapi_first/templates/vet_app/data/","title":"Data","text":""},{"location":"openapi_first/templates/vet_app/data/#openapi_first.templates.vet_app.data","title":"openapi_first.templates.vet_app.data","text":"In-memory data store for the Veterinary Clinic example.
This module is NOT thread-safe and is intended for demos and scaffolds only.
It provides minimal, process-local data stores for the five veterinary clinic entities. Each store exposes standard CRUD operations backed by a simple dictionary.
This module intentionally avoids: - persistence - concurrency guarantees - transactional semantics - validation beyond what Pydantic provides
This module is not part of the openapi_first library API surface.
"},{"location":"openapi_first/templates/vet_app/main/","title":"Main","text":""},{"location":"openapi_first/templates/vet_app/main/#openapi_first.templates.vet_app.main","title":"openapi_first.templates.vet_app.main","text":"Application entry point for an OpenAPI-first Veterinary Clinic service.
This module constructs a FastAPI application exclusively from an OpenAPI specification and a handler namespace, without using decorator-driven routing.
All HTTP routes, methods, request/response schemas, and operation bindings are defined in the OpenAPI document referenced by openapi_path. Python callables defined in the routes module are bound to OpenAPI operations strictly via operationId.
This module contains no routing logic, persistence concerns, or framework configuration beyond application assembly.
Design guarantees: - OpenAPI is the single source of truth - No undocumented routes can exist - Every OpenAPI operationId must resolve to exactly one handler - All contract violations fail at application startup
This file is intended to be used as the ASGI entry point.
Example uvicorn main:app
"},{"location":"openapi_first/templates/vet_app/main/#openapi_first.templates.vet_app.main-classes","title":"Classes","text":""},{"location":"openapi_first/templates/vet_app/models/","title":"Models","text":""},{"location":"openapi_first/templates/vet_app/models/#openapi_first.templates.vet_app.models","title":"openapi_first.templates.vet_app.models","text":""},{"location":"openapi_first/templates/vet_app/routes/","title":"Routes","text":""},{"location":"openapi_first/templates/vet_app/routes/#openapi_first.templates.vet_app.routes","title":"openapi_first.templates.vet_app.routes","text":"Veterinary Clinic route handlers bound via OpenAPI operationId.
Handlers explicitly control HTTP response status codes to ensure runtime behavior matches the OpenAPI contract. Domain models defined using Pydantic are used for request and response payloads.
No routing decorators, path definitions, or implicit framework behavior appear in this module. All routing, HTTP methods, and schemas are defined in the OpenAPI specification.
"},{"location":"openapi_first/templates/vet_app/routes/#openapi_first.templates.vet_app.routes-functions","title":"Functions","text":""},{"location":"openapi_first/templates/vet_app/routes/#openapi_first.templates.vet_app.routes.create_appointment","title":"create_appointment","text":"create_appointment(\n payload: AppointmentCreate, response: Response\n)\n
Create an appointment.
"},{"location":"openapi_first/templates/vet_app/routes/#openapi_first.templates.vet_app.routes.create_parent","title":"create_parent","text":"create_parent(payload: ParentCreate, response: Response)\n
Create a parent.
"},{"location":"openapi_first/templates/vet_app/routes/#openapi_first.templates.vet_app.routes.create_parent--parameters","title":"Parameters","text":"payload : ParentCreate Parent data excluding the id field.
"},{"location":"openapi_first/templates/vet_app/routes/#openapi_first.templates.vet_app.routes.create_parent--returns","title":"Returns","text":"Parent The newly created parent.
"},{"location":"openapi_first/templates/vet_app/routes/#openapi_first.templates.vet_app.routes.create_pet","title":"create_pet","text":"create_pet(payload: PetCreate, response: Response)\n
Create a pet.
"},{"location":"openapi_first/templates/vet_app/routes/#openapi_first.templates.vet_app.routes.create_treatment","title":"create_treatment","text":"create_treatment(\n payload: TreatmentCreate, response: Response\n)\n
Add a treatment (admin only).
"},{"location":"openapi_first/templates/vet_app/routes/#openapi_first.templates.vet_app.routes.create_vet","title":"create_vet","text":"create_vet(payload: VetCreate, response: Response)\n
Create a vet.
"},{"location":"openapi_first/templates/vet_app/routes/#openapi_first.templates.vet_app.routes.delete_appointment","title":"delete_appointment","text":"delete_appointment(id: int, response: Response)\n
Delete an existing appointment.
"},{"location":"openapi_first/templates/vet_app/routes/#openapi_first.templates.vet_app.routes.delete_parent","title":"delete_parent","text":"delete_parent(id: int, response: Response)\n
Delete an existing parent.
"},{"location":"openapi_first/templates/vet_app/routes/#openapi_first.templates.vet_app.routes.delete_parent--parameters","title":"Parameters","text":"id : int Identifier of the parent.
"},{"location":"openapi_first/templates/vet_app/routes/#openapi_first.templates.vet_app.routes.delete_parent--raises","title":"Raises","text":"HTTPException 404 if the parent does not exist.
"},{"location":"openapi_first/templates/vet_app/routes/#openapi_first.templates.vet_app.routes.delete_pet","title":"delete_pet","text":"delete_pet(id: int, response: Response)\n
Delete an existing pet.
"},{"location":"openapi_first/templates/vet_app/routes/#openapi_first.templates.vet_app.routes.delete_treatment","title":"delete_treatment","text":"delete_treatment(id: int, response: Response)\n
Delete an existing treatment.
"},{"location":"openapi_first/templates/vet_app/routes/#openapi_first.templates.vet_app.routes.delete_vet","title":"delete_vet","text":"delete_vet(id: int, response: Response)\n
Delete an existing vet.
"},{"location":"openapi_first/templates/vet_app/routes/#openapi_first.templates.vet_app.routes.get_appointment","title":"get_appointment","text":"get_appointment(id: int)\n
Retrieve a single appointment by ID.
"},{"location":"openapi_first/templates/vet_app/routes/#openapi_first.templates.vet_app.routes.get_parent","title":"get_parent","text":"get_parent(id: int)\n
Retrieve a single parent by ID.
"},{"location":"openapi_first/templates/vet_app/routes/#openapi_first.templates.vet_app.routes.get_parent--parameters","title":"Parameters","text":"id : int Identifier of the parent.
"},{"location":"openapi_first/templates/vet_app/routes/#openapi_first.templates.vet_app.routes.get_parent--returns","title":"Returns","text":"Parent The requested parent.
"},{"location":"openapi_first/templates/vet_app/routes/#openapi_first.templates.vet_app.routes.get_parent--raises","title":"Raises","text":"HTTPException 404 if the parent does not exist.
"},{"location":"openapi_first/templates/vet_app/routes/#openapi_first.templates.vet_app.routes.get_pet","title":"get_pet","text":"get_pet(id: int)\n
Retrieve a single pet by ID.
"},{"location":"openapi_first/templates/vet_app/routes/#openapi_first.templates.vet_app.routes.get_treatment","title":"get_treatment","text":"get_treatment(id: int)\n
Retrieve a single treatment by ID.
"},{"location":"openapi_first/templates/vet_app/routes/#openapi_first.templates.vet_app.routes.get_vet","title":"get_vet","text":"get_vet(id: int)\n
Retrieve a single vet by ID.
"},{"location":"openapi_first/templates/vet_app/routes/#openapi_first.templates.vet_app.routes.list_appointments","title":"list_appointments","text":"list_appointments(\n limit: int = 20,\n offset: int = 0,\n date: str = None,\n vet: int = None,\n pet: int = None,\n)\n
List appointments (paginated, filterable).
"},{"location":"openapi_first/templates/vet_app/routes/#openapi_first.templates.vet_app.routes.list_parents","title":"list_parents","text":"list_parents(limit: int = 20, offset: int = 0)\n
List parents (paginated).
"},{"location":"openapi_first/templates/vet_app/routes/#openapi_first.templates.vet_app.routes.list_parents--parameters","title":"Parameters","text":"limit : int Maximum number of records to return. offset : int Number of records to skip.
"},{"location":"openapi_first/templates/vet_app/routes/#openapi_first.templates.vet_app.routes.list_parents--returns","title":"Returns","text":"dict Paginated response with total and items.
"},{"location":"openapi_first/templates/vet_app/routes/#openapi_first.templates.vet_app.routes.list_pets","title":"list_pets","text":"list_pets(limit: int = 20, offset: int = 0)\n
List pets (paginated).
"},{"location":"openapi_first/templates/vet_app/routes/#openapi_first.templates.vet_app.routes.list_treatments","title":"list_treatments","text":"list_treatments()\n
List treatments (catalogue).
"},{"location":"openapi_first/templates/vet_app/routes/#openapi_first.templates.vet_app.routes.list_treatments--returns","title":"Returns","text":"list[Treatment] A list of treatment domain objects.
"},{"location":"openapi_first/templates/vet_app/routes/#openapi_first.templates.vet_app.routes.list_vets","title":"list_vets","text":"list_vets(limit: int = 20, offset: int = 0)\n
List vets (paginated).
"},{"location":"openapi_first/templates/vet_app/routes/#openapi_first.templates.vet_app.routes.stream_actions","title":"stream_actions async","text":"stream_actions(id: int)\n
Stream animal actions via SSE, scoped to a pet's species.
"},{"location":"openapi_first/templates/vet_app/routes/#openapi_first.templates.vet_app.routes.update_appointment","title":"update_appointment","text":"update_appointment(id: int, payload: AppointmentCreate)\n
Update an existing appointment.
"},{"location":"openapi_first/templates/vet_app/routes/#openapi_first.templates.vet_app.routes.update_parent","title":"update_parent","text":"update_parent(id: int, payload: ParentCreate)\n
Update an existing parent.
"},{"location":"openapi_first/templates/vet_app/routes/#openapi_first.templates.vet_app.routes.update_parent--parameters","title":"Parameters","text":"id : int Identifier of the parent. payload : ParentCreate Updated parent data.
"},{"location":"openapi_first/templates/vet_app/routes/#openapi_first.templates.vet_app.routes.update_parent--returns","title":"Returns","text":"Parent The updated parent.
"},{"location":"openapi_first/templates/vet_app/routes/#openapi_first.templates.vet_app.routes.update_parent--raises","title":"Raises","text":"HTTPException 404 if the parent does not exist.
"},{"location":"openapi_first/templates/vet_app/routes/#openapi_first.templates.vet_app.routes.update_pet","title":"update_pet","text":"update_pet(id: int, payload: PetCreate)\n
Update an existing pet.
"},{"location":"openapi_first/templates/vet_app/routes/#openapi_first.templates.vet_app.routes.update_treatment","title":"update_treatment","text":"update_treatment(id: int, payload: TreatmentCreate)\n
Update an existing treatment.
"},{"location":"openapi_first/templates/vet_app/routes/#openapi_first.templates.vet_app.routes.update_vet","title":"update_vet","text":"update_vet(id: int, payload: VetCreate)\n
Update an existing vet.
"},{"location":"openapi_first/templates/vet_app/routes/#openapi_first.templates.vet_app.routes.upload_pet_photo","title":"upload_pet_photo","text":"upload_pet_photo(id: int, file: UploadFile)\n
Upload a pet photo.
"},{"location":"openapi_first/templates/vet_app/routes/#openapi_first.templates.vet_app.routes.upload_pet_photo--parameters","title":"Parameters","text":"id : int Identifier of the pet. file : UploadFile Image file to upload.
"},{"location":"openapi_first/templates/vet_app/routes/#openapi_first.templates.vet_app.routes.upload_pet_photo--returns","title":"Returns","text":"dict A confirmation with the pet ID.
"},{"location":"openapi_first/templates/vet_app/sse/","title":"Sse","text":""},{"location":"openapi_first/templates/vet_app/sse/#openapi_first.templates.vet_app.sse","title":"openapi_first.templates.vet_app.sse","text":""},{"location":"openapi_first/templates/vet_app/test_vet_app/","title":"Test Vet App","text":""},{"location":"openapi_first/templates/vet_app/test_vet_app/#openapi_first.templates.vet_app.test_vet_app","title":"openapi_first.templates.vet_app.test_vet_app","text":"End-to-end tests for the OpenAPI-first Veterinary Clinic example app.
These tests validate that all CRUD operations behave correctly against the in-memory mock data store using Pydantic models.
"},{"location":"openapi_first/templates/vet_app/test_vet_app/#openapi_first.templates.vet_app.test_vet_app-classes","title":"Classes","text":""},{"location":"openapi_first/templates/vet_app/test_vet_app/#openapi_first.templates.vet_app.test_vet_app-functions","title":"Functions","text":""},{"location":"openapi_first/templates/vet_app/test_vet_app/#openapi_first.templates.vet_app.test_vet_app.test_create_parent","title":"test_create_parent","text":"test_create_parent()\n
Creating a parent returns 201 with the created entity.
"},{"location":"openapi_first/templates/vet_app/test_vet_app/#openapi_first.templates.vet_app.test_vet_app.test_create_pet","title":"test_create_pet","text":"test_create_pet()\n
Creating a pet links FK references.
"},{"location":"openapi_first/templates/vet_app/test_vet_app/#openapi_first.templates.vet_app.test_vet_app.test_create_treatment","title":"test_create_treatment","text":"test_create_treatment()\n
Creating a treatment returns 201.
"},{"location":"openapi_first/templates/vet_app/test_vet_app/#openapi_first.templates.vet_app.test_vet_app.test_create_vet","title":"test_create_vet","text":"test_create_vet()\n
Creating a vet returns 201.
"},{"location":"openapi_first/templates/vet_app/test_vet_app/#openapi_first.templates.vet_app.test_vet_app.test_delete_parent","title":"test_delete_parent","text":"test_delete_parent()\n
Delete parent returns 204 and removes the entity.
"},{"location":"openapi_first/templates/vet_app/test_vet_app/#openapi_first.templates.vet_app.test_vet_app.test_full_appointment_lifecycle","title":"test_full_appointment_lifecycle","text":"test_full_appointment_lifecycle()\n
Create a parent, vet, treatment, pet, then an appointment.
"},{"location":"openapi_first/templates/vet_app/test_vet_app/#openapi_first.templates.vet_app.test_vet_app.test_get_parent","title":"test_get_parent","text":"test_get_parent()\n
Get parent by ID returns the entity.
"},{"location":"openapi_first/templates/vet_app/test_vet_app/#openapi_first.templates.vet_app.test_vet_app.test_list_appointments","title":"test_list_appointments","text":"test_list_appointments()\n
List appointments returns paginated response with filter params.
"},{"location":"openapi_first/templates/vet_app/test_vet_app/#openapi_first.templates.vet_app.test_vet_app.test_list_parents","title":"test_list_parents","text":"test_list_parents()\n
List parents returns paginated response.
"},{"location":"openapi_first/templates/vet_app/test_vet_app/#openapi_first.templates.vet_app.test_vet_app.test_list_treatments","title":"test_list_treatments","text":"test_list_treatments()\n
List treatments returns an array.
"},{"location":"openapi_first/templates/vet_app/test_vet_app/#openapi_first.templates.vet_app.test_vet_app.test_list_vets","title":"test_list_vets","text":"test_list_vets()\n
List vets returns paginated response.
"},{"location":"openapi_first/templates/vet_app/test_vet_app/#openapi_first.templates.vet_app.test_vet_app.test_update_parent","title":"test_update_parent","text":"test_update_parent()\n
Update parent replaces its values.
"},{"location":"openapi_first/templates/vet_app/test_vet_app/#openapi_first.templates.vet_app.test_vet_app.test_upload_pet_photo","title":"test_upload_pet_photo","text":"test_upload_pet_photo()\n
Upload pet photo returns 200.
"}]}
\ No newline at end of file
+{"config":{"lang":["en"],"separator":"[\\s\\-]+","pipeline":["stopWordFilter"]},"docs":[{"location":"","title":"openapi_first","text":" - Openapi First
"},{"location":"#openapi_first","title":"openapi_first","text":""},{"location":"#openapi_first--summary","title":"Summary","text":"FastAPI OpenAPI First \u2014 strict OpenAPI-first application bootstrap for FastAPI.
FastAPI OpenAPI First is a contract-first infrastructure library that enforces OpenAPI as the single source of truth for FastAPI services.
The library removes decorator-driven routing and replaces it with deterministic, spec-driven application assembly. Every HTTP route, method, and operation is defined in OpenAPI first and bound to Python handlers explicitly via operationId.
"},{"location":"#openapi_first--installation","title":"Installation","text":"Install using pip:
pip install openapi-first\n
Or with Poetry:
poetry add openapi-first\n
"},{"location":"#openapi_first--quick-start","title":"Quick Start","text":"Minimal OpenAPI-first FastAPI application:
from openapi_first import app\nimport my_service.routes as routes\n\napi = app.OpenAPIFirstApp(\n openapi_path=\"openapi.yaml\",\n routes_module=routes,\n title=\"My Service\",\n version=\"1.0.0\",\n)\n
OperationId-driven HTTP client:
from openapi_first.loader import load_openapi\nfrom openapi_first.client import OpenAPIClient\n\nspec = load_openapi(\"openapi.yaml\")\nclient = OpenAPIClient(spec)\n\nresponse = client.get_health()\n
"},{"location":"#openapi_first--architecture","title":"Architecture","text":"The library is structured around four core responsibilities:
loader: Load and validate OpenAPI 3.x specifications (JSON/YAML).binder: Bind OpenAPI operations to FastAPI routes via operationId.app: OpenAPI-first FastAPI application bootstrap.client: OpenAPI-first HTTP client driven by the same specification.errors: Explicit error hierarchy for contract violations.
"},{"location":"#openapi_first--public-api","title":"Public API","text":"The supported public API consists of the following top-level modules:
openapi_first.appopenapi_first.binderopenapi_first.loaderopenapi_first.clientopenapi_first.errors
"},{"location":"#openapi_first--design-guarantees","title":"Design Guarantees","text":" - OpenAPI is the single source of truth.
- No undocumented routes can exist.
- No OpenAPI operation can exist without a handler or client callable.
- All contract violations fail at application startup or client creation.
- No hidden FastAPI magic or implicit behavior.
- Deterministic, testable application assembly.
"},{"location":"app/","title":"App","text":""},{"location":"app/#openapi_first.app","title":"openapi_first.app","text":""},{"location":"app/#openapi_first.app--summary","title":"Summary","text":"OpenAPI-first application bootstrap for FastAPI.
This module provides OpenAPIFirstApp, a thin but strict abstraction that enforces OpenAPI as the single source of truth for a FastAPI service.
Notes Core Principles:
- The OpenAPI specification (JSON or YAML) defines the entire API surface.\n- Every `operationId` in the OpenAPI spec must have a corresponding\n Python handler function.\n- Handlers are plain Python callables (no FastAPI decorators).\n- FastAPI route registration is derived exclusively from the spec.\n- FastAPI's autogenerated OpenAPI schema is fully overridden.\n
Responsibilities:
- Loads and validates an OpenAPI 3.x specification.\n- Dynamically binds HTTP routes to handler functions using `operationId`.\n- Registers routes with FastAPI at application startup.\n- Ensures runtime behavior matches the OpenAPI contract exactly.\n
Constraints:
- This module intentionally does NOT:\n - Generate OpenAPI specs.\n - Generate client code.\n - Introduce a new framework or lifecycle.\n - Alter FastAPI dependency injection semantics.\n
"},{"location":"app/#openapi_first.app-classes","title":"Classes","text":""},{"location":"app/#openapi_first.app.OpenAPIFirstApp","title":"OpenAPIFirstApp","text":"OpenAPIFirstApp(\n *,\n openapi_path: str,\n routes_module: Any,\n **fastapi_kwargs: Any\n)\n
Bases: FastAPI
FastAPI application enforcing OpenAPI-first design.
Notes Responsibilities:
- `OpenAPIFirstApp` subclasses `FastAPI` and replaces manual route\n registration with OpenAPI-driven binding.\n- All routes are derived from the provided OpenAPI specification,\n and each ``operationId`` is mapped to a Python function in the\n supplied routes module.\n- Auth dependencies are auto-injected from the spec's\n ``securitySchemes`` and per-operation ``security`` fields.\n
Guarantees:
- No route can exist without an OpenAPI declaration.\n- No OpenAPI operation can exist without a handler.\n- Swagger UI and ``/openapi.json`` always reflect the provided spec.\n- Handler functions remain framework-agnostic and testable.\n- Auth enforcement is driven entirely by the spec \u2014 no manual\n middleware or decorators required.\n
Example from openapi_first import OpenAPIFirstApp\nimport app.routes as routes\n\napp = OpenAPIFirstApp(\n openapi_path=\"app/openapi.json\",\n routes_module=routes,\n title=\"Example Service\",\n)\n
Initialize the application.
Parameters:
Name Type Description Default openapi_path str Filesystem path to the OpenAPI 3.x specification file. This specification is treated as the authoritative API contract.
required routes_module ModuleType Python module containing handler functions whose names correspond exactly to OpenAPI operationId values.
required **fastapi_kwargs Any Additional keyword arguments passed directly to fastapi.FastAPI (e.g., title, version, middleware, lifespan handlers).
{} Raises:
Type Description OpenAPIFirstError If the OpenAPI specification is invalid, or if any declared operationId does not have a corresponding handler function.
"},{"location":"app/#openapi_first.app.OpenAPIFirstApp-functions","title":"Functions","text":""},{"location":"app/#openapi_first.app-functions","title":"Functions","text":""},{"location":"binder/","title":"Binder","text":""},{"location":"binder/#openapi_first.binder","title":"openapi_first.binder","text":""},{"location":"binder/#openapi_first.binder--summary","title":"Summary","text":"OpenAPI-driven route binding for FastAPI.
This module is responsible for translating an OpenAPI 3.x specification into concrete FastAPI routes. It enforces a strict one-to-one mapping between OpenAPI operations and Python handler functions using operationId.
Notes Core Responsibility:
- Read path + method definitions from an OpenAPI specification.\n- Resolve each `operationId` to a Python callable.\n- Register routes with FastAPI using `APIRoute`.\n- Fail fast when contract violations are detected.\n
Design Constraints:
- All routes MUST be declared in the OpenAPI specification.\n- All OpenAPI operations MUST define an `operationId`.\n- Every `operationId` MUST resolve to a handler function.\n- Handlers are plain Python callables (no decorators required).\n- No implicit route creation or inference is allowed.\n
Constraints:
- This module intentionally does NOT:\n - Perform request or response validation.\n - Generate Pydantic models.\n - Modify FastAPI dependency injection.\n - Interpret OpenAPI semantics beyond routing metadata.\n
"},{"location":"binder/#openapi_first.binder-classes","title":"Classes","text":""},{"location":"binder/#openapi_first.binder-functions","title":"Functions","text":""},{"location":"binder/#openapi_first.binder.bind_routes","title":"bind_routes","text":"bind_routes(\n app: FastAPI,\n spec: dict[str, Any],\n routes_module: ModuleType,\n security_deps: dict[str, list[Any]] | None = None,\n) -> None\n
Bind OpenAPI operations to FastAPI routes.
Parameters:
Name Type Description Default app FastAPI The FastAPI application instance to which routes will be added.
required spec dict[str, Any] Parsed OpenAPI 3.x specification dictionary.
required routes_module ModuleType Python module containing handler functions. Each handler's name MUST exactly match an OpenAPI operationId.
required security_deps dict[str, list[Any]] | None Optional mapping of METHOD:/path \u2192 list[Depends(...)] generated from the spec's securitySchemes and per-operation security fields.
None Raises:
Type Description MissingOperationHandler If an operationId is missing from the spec or if no corresponding handler function exists in the routes module.
Notes Responsibilities:
- Iterates through the OpenAPI specification paths and methods.\n- Resolves each ``operationId`` to a handler function, and registers\n a corresponding ``APIRoute`` on the FastAPI application.\n- Injects FastAPI ``Depends()`` for each security requirement found\n on the operation or inherited from the top-level ``security`` field.\n
Guarantees:
- Route registration is deterministic and spec-driven. No route\n decorators are required or supported. Handler resolution errors\n surface at application startup.\n
"},{"location":"cli/","title":"Cli","text":""},{"location":"cli/#openapi_first.cli","title":"openapi_first.cli","text":""},{"location":"cli/#openapi_first.cli--summary","title":"Summary","text":"Command-line interface for FastAPI OpenAPI-first scaffolding utilities.
This CLI bootstraps OpenAPI-first FastAPI applications from versioned, bundled templates packaged with the library.
"},{"location":"cli/#openapi_first.cli-functions","title":"Functions","text":""},{"location":"cli/#openapi_first.cli.available_templates","title":"available_templates","text":"available_templates() -> list[str]\n
Return a list of available application templates.
Returns:
Type Description list[str] list[str]: Sorted list of template names found in the internal templates directory.
"},{"location":"cli/#openapi_first.cli.copy_template","title":"copy_template","text":"copy_template(template: str, target_dir: Path) -> None\n
Copy a bundled OpenAPI-first application template into a directory.
Parameters:
Name Type Description Default template str Name of the template to copy.
required target_dir Path Filesystem path where the template should be copied.
required Raises:
Type Description FileNotFoundError If the requested template does not exist.
"},{"location":"client/","title":"Client","text":""},{"location":"client/#openapi_first.client","title":"openapi_first.client","text":""},{"location":"client/#openapi_first.client--summary","title":"Summary","text":"OpenAPI-first HTTP client for contract-driven services.
This module provides OpenAPIClient, a thin, strict HTTP client that derives all callable operations directly from an OpenAPI 3.x specification.
It is the client counterpart to OpenAPIFirstApp.
Notes Core Principles:
- The OpenAPI specification is the single source of truth\n- Each operationId becomes a callable Python method\n- No implicit schema mutation or inference\n- No code generation step\n- Minimal abstraction over httpx\n
Responsibilities:
- Parses an OpenAPI 3.x specification\n- Dynamically creates one callable per operationId\n- Enforces presence of servers, paths, and operationId\n- Formats path parameters safely\n- Handles JSON request bodies explicitly\n- Returns raw `httpx.Response` objects\n
Constraints:
- This module intentionally does NOT: Generate client code, validate request/response schemas, deserialize responses, retry requests, implement authentication helpers, or assume non-2xx responses are failures.\n
"},{"location":"client/#openapi_first.client-classes","title":"Classes","text":""},{"location":"client/#openapi_first.client.OpenAPIClient","title":"OpenAPIClient","text":"OpenAPIClient(\n spec: dict[str, Any],\n base_url: str | None = None,\n client: httpx.Client | None = None,\n)\n
OpenAPI-first HTTP client (httpx-based).
Notes Responsibilities:
- This client derives all callable methods directly from an\n OpenAPI 3.x specification. Each `operationId` becomes a method\n on the client instance.\n
Guarantees:
- One callable per `operationId`.\n- Explicit parameters (path, query, headers, body).\n- No implicit schema inference or mutation.\n- Returns raw `httpx.Response` objects.\n- No response validation or deserialization.\n
Example from openapi_first import loader, client\n\nspec = loader.load_openapi(\"openapi.yaml\")\n\napi = client.OpenAPIClient(\n spec=spec,\n base_url=\"http://localhost:8000\",\n)\n\n# Call operationId: getUser\nresponse = api.getUser(\n path_params={\"user_id\": 123}\n)\n\nprint(response.status_code)\nprint(response.json())\n
Initialize the OpenAPI client.
Parameters:
Name Type Description Default spec dict[str, Any] Parsed OpenAPI 3.x specification.
required base_url str | None Base URL of the target service. If omitted, the first entry in the OpenAPI servers list is used.
None client Client | None Optional preconfigured httpx client instance.
None Raises:
Type Description OpenAPIClientError If no servers are defined, spec has no paths, operationIds are missing/duplicate, or required parameters are missing.
"},{"location":"client/#openapi_first.client.OpenAPIClient-functions","title":"Functions","text":""},{"location":"client/#openapi_first.client.OpenAPIClientError","title":"OpenAPIClientError","text":" Bases: OpenAPIFirstError
Raised when an OpenAPI client operation fails.
"},{"location":"codegen/","title":"Codegen","text":""},{"location":"codegen/#openapi_first.codegen","title":"openapi_first.codegen","text":""},{"location":"codegen/#openapi_first.codegen--summary","title":"Summary","text":"Core logic for generating Python source code from OpenAPI specifications.
This module provides reusable utilities for code generation, specifically generating Pydantic models and route handler stubs from OpenAPI 3.x schema definitions.
"},{"location":"codegen/#openapi_first.codegen-functions","title":"Functions","text":""},{"location":"codegen/#openapi_first.codegen.generate_models","title":"generate_models","text":"generate_models(\n spec_path: Path,\n output_path: Path,\n pydantic_version: int = 2,\n) -> None\n
Generate Pydantic models from an OpenAPI specification.
Parameters:
Name Type Description Default spec_path Path Path to the OpenAPI specification file (YAML or JSON).
required output_path Path Path where the generated Python code should be written.
required pydantic_version int The Pydantic version to target (1 or 2). Defaults to 2.
2 Notes Reusability: This function is designed to be used by the CLI and can be exposed as an MCP tool without modification.
"},{"location":"codegen/#openapi_first.codegen.generate_routes","title":"generate_routes","text":"generate_routes(\n spec_path: Path,\n output_dir: Path,\n *,\n use_models: bool = False,\n models_module: str = \"models\"\n) -> list[Path]\n
Generate route handler stubs from an OpenAPI specification.
Creates one <resource>.py file per resource in output_dir. Resources are derived from the first path segment (e.g. /pets and /pets/{id} both group under pets).
Parameters:
Name Type Description Default spec_path Path Path to the OpenAPI specification file (YAML or JSON).
required output_dir Path Directory where the generated route files are written. Created automatically if it does not exist.
required use_models bool If True, import Pydantic models from models_module for request-body schemas referenced via $ref.
False models_module str Dotted Python module path from which to import models (e.g. \"models\", \"app.models\").
'models' Returns:
Type Description list[Path] list[Path]: Absolute paths of every generated route file.
Raises:
Type Description OpenAPISpecLoadError If the spec cannot be loaded or validated.
ValueError If any operation is missing operationId.
"},{"location":"codegen_routes/","title":"Codegen Routes","text":""},{"location":"codegen_routes/#openapi_first.codegen_routes","title":"openapi_first.codegen_routes","text":""},{"location":"codegen_routes/#openapi_first.codegen_routes--summary","title":"Summary","text":"Route handler code generation from OpenAPI specifications.
This module generates Python route handler stubs from an OpenAPI 3.x specification. Each resource (derived from the first path segment) gets its own file under the output directory. Every OpenAPI operation must define an operationId, which becomes the handler function name.
Notes Design constraints:
- ``operationId`` is required on every operation (matching\n ``binder.bind_routes``).\n- Handlers are stubs raising ``NotImplementedError``.\n- Sub-resources (e.g. ``/pets/{id}/photo``) are grouped with their\n parent resource (``pets``).\n- Parameter types and defaults are inferred from the spec.\n- ``response: Response`` is injected for non-200 success codes.\n
"},{"location":"codegen_routes/#openapi_first.codegen_routes-functions","title":"Functions","text":""},{"location":"codegen_routes/#openapi_first.codegen_routes.generate_routes","title":"generate_routes","text":"generate_routes(\n spec_path: Path,\n output_dir: Path,\n *,\n use_models: bool = False,\n models_module: str = \"models\"\n) -> list[Path]\n
Generate route handler stubs from an OpenAPI specification.
Creates one <resource>.py file per resource in output_dir. Resources are derived from the first path segment (e.g. /pets and /pets/{id} both group under pets).
Parameters:
Name Type Description Default spec_path Path Path to the OpenAPI specification file (YAML or JSON).
required output_dir Path Directory where the generated route files are written. Created automatically if it does not exist.
required use_models bool If True, import Pydantic models from models_module for request-body schemas referenced via $ref.
False models_module str Dotted Python module path from which to import models (e.g. \"models\", \"app.models\").
'models' Returns:
Type Description list[Path] list[Path]: Absolute paths of every generated route file.
Raises:
Type Description OpenAPISpecLoadError If the spec cannot be loaded or validated.
ValueError If any operation is missing operationId.
"},{"location":"errors/","title":"Errors","text":""},{"location":"errors/#openapi_first.errors","title":"openapi_first.errors","text":""},{"location":"errors/#openapi_first.errors--summary","title":"Summary","text":"Exceptions for OpenAPI-first FastAPI applications.
This module defines a small hierarchy of explicit, intention-revealing exceptions used to signal contract violations between an OpenAPI specification and its Python implementation.
Notes Design Principles:
- Errors represent programmer mistakes, not runtime conditions.\n- All errors are raised during application startup.\n- Messages are actionable and suitable for CI/CD output.\n- Exceptions are explicit rather than reused from generic built-ins.\n
These errors should normally cause immediate application failure.
"},{"location":"errors/#openapi_first.errors-classes","title":"Classes","text":""},{"location":"errors/#openapi_first.errors.MissingOperationHandler","title":"MissingOperationHandler","text":"MissingOperationHandler(\n *,\n path: str,\n method: str,\n operation_id: str | None = None\n)\n
Bases: OpenAPIFirstError
Raised when an OpenAPI operation cannot be resolved to a handler.
Notes Scenarios:
- An OpenAPI operation does not define an `operationId`.\n- An `operationId` is defined but no matching function exists in\n the provided routes module.\n
Guarantees:
- This represents a violation of the OpenAPI-first contract and\n indicates that the specification and implementation are out of\n sync.\n
Initialize the error.
Parameters:
Name Type Description Default path str The HTTP path declared in the OpenAPI specification.
required method str The HTTP method (as declared in the OpenAPI spec).
required operation_id str | None The operationId declared in the OpenAPI spec, if present.
None"},{"location":"errors/#openapi_first.errors.MissingOperationHandler-functions","title":"Functions","text":""},{"location":"errors/#openapi_first.errors.OpenAPIFirstError","title":"OpenAPIFirstError","text":" Bases: Exception
Base exception for all OpenAPI-first enforcement errors.
Notes Responsibilities:
- This exception exists to allow callers, test suites, and CI\n pipelines to catch and distinguish OpenAPI contract violations\n from unrelated runtime errors.\n- All exceptions raised by the OpenAPI-first core should inherit\n from this type.\n
"},{"location":"loader/","title":"Loader","text":""},{"location":"loader/#openapi_first.loader","title":"openapi_first.loader","text":""},{"location":"loader/#openapi_first.loader--summary","title":"Summary","text":"OpenAPI specification loading and validation utilities.
This module is responsible for loading an OpenAPI 3.x specification from disk and validating it before it is used by the application.
It enforces the principle that an invalid or malformed OpenAPI document must never reach the routing or runtime layers.
Notes Design Principles:
- OpenAPI is treated as an authoritative contract.\n- Invalid specifications fail fast at application startup.\n- Supported formats are JSON and YAML.\n- Validation errors are surfaced clearly and early.\n
Constraints:
- This module intentionally does NOT:\n - Modify the OpenAPI document.\n - Infer missing fields.\n - Generate models or code.\n - Perform request/response validation at runtime.\n
"},{"location":"loader/#openapi_first.loader-classes","title":"Classes","text":""},{"location":"loader/#openapi_first.loader.OpenAPISpecLoadError","title":"OpenAPISpecLoadError","text":" Bases: OpenAPIFirstError
Raised when an OpenAPI specification cannot be loaded or validated.
Notes Guarantees:
- This error indicates that the OpenAPI document is unreadable,\n malformed, or violates the OpenAPI 3.x specification.\n
"},{"location":"loader/#openapi_first.loader-functions","title":"Functions","text":""},{"location":"loader/#openapi_first.loader.load_openapi","title":"load_openapi","text":"load_openapi(path: str | Path) -> dict[str, Any]\n
Load and validate an OpenAPI 3.x specification from disk.
Parameters:
Name Type Description Default path str | Path Filesystem path to an OpenAPI specification file. Supported extensions: .json, .yaml, .yml.
required Returns:
Type Description dict[str, Any] dict[str, Any]: Parsed and validated OpenAPI specification.
Raises:
Type Description OpenAPISpecLoadError If the file does not exist, cannot be parsed, or fails OpenAPI schema validation.
Notes Guarantees:
- The specification is parsed based on file extension and validated\n using a strict OpenAPI schema validator.\n- Any error results in an immediate exception, preventing\n application startup.\n
"},{"location":"security/","title":"Security","text":""},{"location":"security/#openapi_first.security","title":"openapi_first.security","text":""},{"location":"security/#openapi_first.security--summary","title":"Summary","text":"OpenAPI security scheme parsing and auto-generated auth dependencies.
This module reads securitySchemes and per-operation security from an OpenAPI spec, resolves {ENV_VAR} placeholders in x- extension fields, and generates FastAPI dependencies for token validation (e.g., Bearer JWT introspection).
"},{"location":"security/#openapi_first.security-functions","title":"Functions","text":""},{"location":"security/#openapi_first.security.make_security_dependencies","title":"make_security_dependencies","text":"make_security_dependencies(\n spec: dict[str, Any],\n security_schemes: dict[str, dict[str, Any]],\n) -> dict[str, list[Any]]\n
Build a mapping of METHOD:/path \u2192 list of Depends(...).
The effective security for each operation is resolved by:
- Using the operation-level
security field if present. - Falling back to the top-level
security field. - An empty list means no auth required for that operation.
"},{"location":"security/#openapi_first.security.parse_security_schemes","title":"parse_security_schemes","text":"parse_security_schemes(\n spec: dict[str, Any],\n) -> dict[str, dict[str, Any]]\n
Extract and resolve environment variables in security schemes.
"},{"location":"openapi_first/","title":"Openapi First","text":" - App
- Binder
- Cli
- Client
- Codegen
- Codegen Routes
- Errors
- Loader
- Security
- Templates
"},{"location":"openapi_first/#openapi_first","title":"openapi_first","text":""},{"location":"openapi_first/#openapi_first--summary","title":"Summary","text":"FastAPI OpenAPI First \u2014 strict OpenAPI-first application bootstrap for FastAPI.
FastAPI OpenAPI First is a contract-first infrastructure library that enforces OpenAPI as the single source of truth for FastAPI services.
The library removes decorator-driven routing and replaces it with deterministic, spec-driven application assembly. Every HTTP route, method, and operation is defined in OpenAPI first and bound to Python handlers explicitly via operationId.
"},{"location":"openapi_first/#openapi_first--installation","title":"Installation","text":"Install using pip:
pip install openapi-first\n
Or with Poetry:
poetry add openapi-first\n
"},{"location":"openapi_first/#openapi_first--quick-start","title":"Quick Start","text":"Minimal OpenAPI-first FastAPI application:
from openapi_first import app\nimport my_service.routes as routes\n\napi = app.OpenAPIFirstApp(\n openapi_path=\"openapi.yaml\",\n routes_module=routes,\n title=\"My Service\",\n version=\"1.0.0\",\n)\n
OperationId-driven HTTP client:
from openapi_first.loader import load_openapi\nfrom openapi_first.client import OpenAPIClient\n\nspec = load_openapi(\"openapi.yaml\")\nclient = OpenAPIClient(spec)\n\nresponse = client.get_health()\n
"},{"location":"openapi_first/#openapi_first--architecture","title":"Architecture","text":"The library is structured around four core responsibilities:
loader: Load and validate OpenAPI 3.x specifications (JSON/YAML).binder: Bind OpenAPI operations to FastAPI routes via operationId.app: OpenAPI-first FastAPI application bootstrap.client: OpenAPI-first HTTP client driven by the same specification.errors: Explicit error hierarchy for contract violations.
"},{"location":"openapi_first/#openapi_first--public-api","title":"Public API","text":"The supported public API consists of the following top-level modules:
openapi_first.appopenapi_first.binderopenapi_first.loaderopenapi_first.clientopenapi_first.errors
"},{"location":"openapi_first/#openapi_first--design-guarantees","title":"Design Guarantees","text":" - OpenAPI is the single source of truth.
- No undocumented routes can exist.
- No OpenAPI operation can exist without a handler or client callable.
- All contract violations fail at application startup or client creation.
- No hidden FastAPI magic or implicit behavior.
- Deterministic, testable application assembly.
"},{"location":"openapi_first/app/","title":"App","text":""},{"location":"openapi_first/app/#openapi_first.app","title":"openapi_first.app","text":""},{"location":"openapi_first/app/#openapi_first.app--summary","title":"Summary","text":"OpenAPI-first application bootstrap for FastAPI.
This module provides OpenAPIFirstApp, a thin but strict abstraction that enforces OpenAPI as the single source of truth for a FastAPI service.
Notes Core Principles:
- The OpenAPI specification (JSON or YAML) defines the entire API surface.\n- Every `operationId` in the OpenAPI spec must have a corresponding\n Python handler function.\n- Handlers are plain Python callables (no FastAPI decorators).\n- FastAPI route registration is derived exclusively from the spec.\n- FastAPI's autogenerated OpenAPI schema is fully overridden.\n
Responsibilities:
- Loads and validates an OpenAPI 3.x specification.\n- Dynamically binds HTTP routes to handler functions using `operationId`.\n- Registers routes with FastAPI at application startup.\n- Ensures runtime behavior matches the OpenAPI contract exactly.\n
Constraints:
- This module intentionally does NOT:\n - Generate OpenAPI specs.\n - Generate client code.\n - Introduce a new framework or lifecycle.\n - Alter FastAPI dependency injection semantics.\n
"},{"location":"openapi_first/app/#openapi_first.app-classes","title":"Classes","text":""},{"location":"openapi_first/app/#openapi_first.app.OpenAPIFirstApp","title":"OpenAPIFirstApp","text":"OpenAPIFirstApp(\n *,\n openapi_path: str,\n routes_module: Any,\n **fastapi_kwargs: Any\n)\n
Bases: FastAPI
FastAPI application enforcing OpenAPI-first design.
Notes Responsibilities:
- `OpenAPIFirstApp` subclasses `FastAPI` and replaces manual route\n registration with OpenAPI-driven binding.\n- All routes are derived from the provided OpenAPI specification,\n and each ``operationId`` is mapped to a Python function in the\n supplied routes module.\n- Auth dependencies are auto-injected from the spec's\n ``securitySchemes`` and per-operation ``security`` fields.\n
Guarantees:
- No route can exist without an OpenAPI declaration.\n- No OpenAPI operation can exist without a handler.\n- Swagger UI and ``/openapi.json`` always reflect the provided spec.\n- Handler functions remain framework-agnostic and testable.\n- Auth enforcement is driven entirely by the spec \u2014 no manual\n middleware or decorators required.\n
Example from openapi_first import OpenAPIFirstApp\nimport app.routes as routes\n\napp = OpenAPIFirstApp(\n openapi_path=\"app/openapi.json\",\n routes_module=routes,\n title=\"Example Service\",\n)\n
Initialize the application.
Parameters:
Name Type Description Default openapi_path str Filesystem path to the OpenAPI 3.x specification file. This specification is treated as the authoritative API contract.
required routes_module ModuleType Python module containing handler functions whose names correspond exactly to OpenAPI operationId values.
required **fastapi_kwargs Any Additional keyword arguments passed directly to fastapi.FastAPI (e.g., title, version, middleware, lifespan handlers).
{} Raises:
Type Description OpenAPIFirstError If the OpenAPI specification is invalid, or if any declared operationId does not have a corresponding handler function.
"},{"location":"openapi_first/app/#openapi_first.app.OpenAPIFirstApp-functions","title":"Functions","text":""},{"location":"openapi_first/app/#openapi_first.app-functions","title":"Functions","text":""},{"location":"openapi_first/binder/","title":"Binder","text":""},{"location":"openapi_first/binder/#openapi_first.binder","title":"openapi_first.binder","text":""},{"location":"openapi_first/binder/#openapi_first.binder--summary","title":"Summary","text":"OpenAPI-driven route binding for FastAPI.
This module is responsible for translating an OpenAPI 3.x specification into concrete FastAPI routes. It enforces a strict one-to-one mapping between OpenAPI operations and Python handler functions using operationId.
Notes Core Responsibility:
- Read path + method definitions from an OpenAPI specification.\n- Resolve each `operationId` to a Python callable.\n- Register routes with FastAPI using `APIRoute`.\n- Fail fast when contract violations are detected.\n
Design Constraints:
- All routes MUST be declared in the OpenAPI specification.\n- All OpenAPI operations MUST define an `operationId`.\n- Every `operationId` MUST resolve to a handler function.\n- Handlers are plain Python callables (no decorators required).\n- No implicit route creation or inference is allowed.\n
Constraints:
- This module intentionally does NOT:\n - Perform request or response validation.\n - Generate Pydantic models.\n - Modify FastAPI dependency injection.\n - Interpret OpenAPI semantics beyond routing metadata.\n
"},{"location":"openapi_first/binder/#openapi_first.binder-classes","title":"Classes","text":""},{"location":"openapi_first/binder/#openapi_first.binder-functions","title":"Functions","text":""},{"location":"openapi_first/binder/#openapi_first.binder.bind_routes","title":"bind_routes","text":"bind_routes(\n app: FastAPI,\n spec: dict[str, Any],\n routes_module: ModuleType,\n security_deps: dict[str, list[Any]] | None = None,\n) -> None\n
Bind OpenAPI operations to FastAPI routes.
Parameters:
Name Type Description Default app FastAPI The FastAPI application instance to which routes will be added.
required spec dict[str, Any] Parsed OpenAPI 3.x specification dictionary.
required routes_module ModuleType Python module containing handler functions. Each handler's name MUST exactly match an OpenAPI operationId.
required security_deps dict[str, list[Any]] | None Optional mapping of METHOD:/path \u2192 list[Depends(...)] generated from the spec's securitySchemes and per-operation security fields.
None Raises:
Type Description MissingOperationHandler If an operationId is missing from the spec or if no corresponding handler function exists in the routes module.
Notes Responsibilities:
- Iterates through the OpenAPI specification paths and methods.\n- Resolves each ``operationId`` to a handler function, and registers\n a corresponding ``APIRoute`` on the FastAPI application.\n- Injects FastAPI ``Depends()`` for each security requirement found\n on the operation or inherited from the top-level ``security`` field.\n
Guarantees:
- Route registration is deterministic and spec-driven. No route\n decorators are required or supported. Handler resolution errors\n surface at application startup.\n
"},{"location":"openapi_first/cli/","title":"Cli","text":""},{"location":"openapi_first/cli/#openapi_first.cli","title":"openapi_first.cli","text":""},{"location":"openapi_first/cli/#openapi_first.cli--summary","title":"Summary","text":"Command-line interface for FastAPI OpenAPI-first scaffolding utilities.
This CLI bootstraps OpenAPI-first FastAPI applications from versioned, bundled templates packaged with the library.
"},{"location":"openapi_first/cli/#openapi_first.cli-functions","title":"Functions","text":""},{"location":"openapi_first/cli/#openapi_first.cli.available_templates","title":"available_templates","text":"available_templates() -> list[str]\n
Return a list of available application templates.
Returns:
Type Description list[str] list[str]: Sorted list of template names found in the internal templates directory.
"},{"location":"openapi_first/cli/#openapi_first.cli.copy_template","title":"copy_template","text":"copy_template(template: str, target_dir: Path) -> None\n
Copy a bundled OpenAPI-first application template into a directory.
Parameters:
Name Type Description Default template str Name of the template to copy.
required target_dir Path Filesystem path where the template should be copied.
required Raises:
Type Description FileNotFoundError If the requested template does not exist.
"},{"location":"openapi_first/client/","title":"Client","text":""},{"location":"openapi_first/client/#openapi_first.client","title":"openapi_first.client","text":""},{"location":"openapi_first/client/#openapi_first.client--summary","title":"Summary","text":"OpenAPI-first HTTP client for contract-driven services.
This module provides OpenAPIClient, a thin, strict HTTP client that derives all callable operations directly from an OpenAPI 3.x specification.
It is the client counterpart to OpenAPIFirstApp.
Notes Core Principles:
- The OpenAPI specification is the single source of truth\n- Each operationId becomes a callable Python method\n- No implicit schema mutation or inference\n- No code generation step\n- Minimal abstraction over httpx\n
Responsibilities:
- Parses an OpenAPI 3.x specification\n- Dynamically creates one callable per operationId\n- Enforces presence of servers, paths, and operationId\n- Formats path parameters safely\n- Handles JSON request bodies explicitly\n- Returns raw `httpx.Response` objects\n
Constraints:
- This module intentionally does NOT: Generate client code, validate request/response schemas, deserialize responses, retry requests, implement authentication helpers, or assume non-2xx responses are failures.\n
"},{"location":"openapi_first/client/#openapi_first.client-classes","title":"Classes","text":""},{"location":"openapi_first/client/#openapi_first.client.OpenAPIClient","title":"OpenAPIClient","text":"OpenAPIClient(\n spec: dict[str, Any],\n base_url: str | None = None,\n client: httpx.Client | None = None,\n)\n
OpenAPI-first HTTP client (httpx-based).
Notes Responsibilities:
- This client derives all callable methods directly from an\n OpenAPI 3.x specification. Each `operationId` becomes a method\n on the client instance.\n
Guarantees:
- One callable per `operationId`.\n- Explicit parameters (path, query, headers, body).\n- No implicit schema inference or mutation.\n- Returns raw `httpx.Response` objects.\n- No response validation or deserialization.\n
Example from openapi_first import loader, client\n\nspec = loader.load_openapi(\"openapi.yaml\")\n\napi = client.OpenAPIClient(\n spec=spec,\n base_url=\"http://localhost:8000\",\n)\n\n# Call operationId: getUser\nresponse = api.getUser(\n path_params={\"user_id\": 123}\n)\n\nprint(response.status_code)\nprint(response.json())\n
Initialize the OpenAPI client.
Parameters:
Name Type Description Default spec dict[str, Any] Parsed OpenAPI 3.x specification.
required base_url str | None Base URL of the target service. If omitted, the first entry in the OpenAPI servers list is used.
None client Client | None Optional preconfigured httpx client instance.
None Raises:
Type Description OpenAPIClientError If no servers are defined, spec has no paths, operationIds are missing/duplicate, or required parameters are missing.
"},{"location":"openapi_first/client/#openapi_first.client.OpenAPIClient-functions","title":"Functions","text":""},{"location":"openapi_first/client/#openapi_first.client.OpenAPIClientError","title":"OpenAPIClientError","text":" Bases: OpenAPIFirstError
Raised when an OpenAPI client operation fails.
"},{"location":"openapi_first/codegen/","title":"Codegen","text":""},{"location":"openapi_first/codegen/#openapi_first.codegen","title":"openapi_first.codegen","text":""},{"location":"openapi_first/codegen/#openapi_first.codegen--summary","title":"Summary","text":"Core logic for generating Python source code from OpenAPI specifications.
This module provides reusable utilities for code generation, specifically generating Pydantic models and route handler stubs from OpenAPI 3.x schema definitions.
"},{"location":"openapi_first/codegen/#openapi_first.codegen-functions","title":"Functions","text":""},{"location":"openapi_first/codegen/#openapi_first.codegen.generate_models","title":"generate_models","text":"generate_models(\n spec_path: Path,\n output_path: Path,\n pydantic_version: int = 2,\n) -> None\n
Generate Pydantic models from an OpenAPI specification.
Parameters:
Name Type Description Default spec_path Path Path to the OpenAPI specification file (YAML or JSON).
required output_path Path Path where the generated Python code should be written.
required pydantic_version int The Pydantic version to target (1 or 2). Defaults to 2.
2 Notes Reusability: This function is designed to be used by the CLI and can be exposed as an MCP tool without modification.
"},{"location":"openapi_first/codegen/#openapi_first.codegen.generate_routes","title":"generate_routes","text":"generate_routes(\n spec_path: Path,\n output_dir: Path,\n *,\n use_models: bool = False,\n models_module: str = \"models\"\n) -> list[Path]\n
Generate route handler stubs from an OpenAPI specification.
Creates one <resource>.py file per resource in output_dir. Resources are derived from the first path segment (e.g. /pets and /pets/{id} both group under pets).
Parameters:
Name Type Description Default spec_path Path Path to the OpenAPI specification file (YAML or JSON).
required output_dir Path Directory where the generated route files are written. Created automatically if it does not exist.
required use_models bool If True, import Pydantic models from models_module for request-body schemas referenced via $ref.
False models_module str Dotted Python module path from which to import models (e.g. \"models\", \"app.models\").
'models' Returns:
Type Description list[Path] list[Path]: Absolute paths of every generated route file.
Raises:
Type Description OpenAPISpecLoadError If the spec cannot be loaded or validated.
ValueError If any operation is missing operationId.
"},{"location":"openapi_first/codegen_routes/","title":"Codegen Routes","text":""},{"location":"openapi_first/codegen_routes/#openapi_first.codegen_routes","title":"openapi_first.codegen_routes","text":""},{"location":"openapi_first/codegen_routes/#openapi_first.codegen_routes--summary","title":"Summary","text":"Route handler code generation from OpenAPI specifications.
This module generates Python route handler stubs from an OpenAPI 3.x specification. Each resource (derived from the first path segment) gets its own file under the output directory. Every OpenAPI operation must define an operationId, which becomes the handler function name.
Notes Design constraints:
- ``operationId`` is required on every operation (matching\n ``binder.bind_routes``).\n- Handlers are stubs raising ``NotImplementedError``.\n- Sub-resources (e.g. ``/pets/{id}/photo``) are grouped with their\n parent resource (``pets``).\n- Parameter types and defaults are inferred from the spec.\n- ``response: Response`` is injected for non-200 success codes.\n
"},{"location":"openapi_first/codegen_routes/#openapi_first.codegen_routes-functions","title":"Functions","text":""},{"location":"openapi_first/codegen_routes/#openapi_first.codegen_routes.generate_routes","title":"generate_routes","text":"generate_routes(\n spec_path: Path,\n output_dir: Path,\n *,\n use_models: bool = False,\n models_module: str = \"models\"\n) -> list[Path]\n
Generate route handler stubs from an OpenAPI specification.
Creates one <resource>.py file per resource in output_dir. Resources are derived from the first path segment (e.g. /pets and /pets/{id} both group under pets).
Parameters:
Name Type Description Default spec_path Path Path to the OpenAPI specification file (YAML or JSON).
required output_dir Path Directory where the generated route files are written. Created automatically if it does not exist.
required use_models bool If True, import Pydantic models from models_module for request-body schemas referenced via $ref.
False models_module str Dotted Python module path from which to import models (e.g. \"models\", \"app.models\").
'models' Returns:
Type Description list[Path] list[Path]: Absolute paths of every generated route file.
Raises:
Type Description OpenAPISpecLoadError If the spec cannot be loaded or validated.
ValueError If any operation is missing operationId.
"},{"location":"openapi_first/errors/","title":"Errors","text":""},{"location":"openapi_first/errors/#openapi_first.errors","title":"openapi_first.errors","text":""},{"location":"openapi_first/errors/#openapi_first.errors--summary","title":"Summary","text":"Exceptions for OpenAPI-first FastAPI applications.
This module defines a small hierarchy of explicit, intention-revealing exceptions used to signal contract violations between an OpenAPI specification and its Python implementation.
Notes Design Principles:
- Errors represent programmer mistakes, not runtime conditions.\n- All errors are raised during application startup.\n- Messages are actionable and suitable for CI/CD output.\n- Exceptions are explicit rather than reused from generic built-ins.\n
These errors should normally cause immediate application failure.
"},{"location":"openapi_first/errors/#openapi_first.errors-classes","title":"Classes","text":""},{"location":"openapi_first/errors/#openapi_first.errors.MissingOperationHandler","title":"MissingOperationHandler","text":"MissingOperationHandler(\n *,\n path: str,\n method: str,\n operation_id: str | None = None\n)\n
Bases: OpenAPIFirstError
Raised when an OpenAPI operation cannot be resolved to a handler.
Notes Scenarios:
- An OpenAPI operation does not define an `operationId`.\n- An `operationId` is defined but no matching function exists in\n the provided routes module.\n
Guarantees:
- This represents a violation of the OpenAPI-first contract and\n indicates that the specification and implementation are out of\n sync.\n
Initialize the error.
Parameters:
Name Type Description Default path str The HTTP path declared in the OpenAPI specification.
required method str The HTTP method (as declared in the OpenAPI spec).
required operation_id str | None The operationId declared in the OpenAPI spec, if present.
None"},{"location":"openapi_first/errors/#openapi_first.errors.MissingOperationHandler-functions","title":"Functions","text":""},{"location":"openapi_first/errors/#openapi_first.errors.OpenAPIFirstError","title":"OpenAPIFirstError","text":" Bases: Exception
Base exception for all OpenAPI-first enforcement errors.
Notes Responsibilities:
- This exception exists to allow callers, test suites, and CI\n pipelines to catch and distinguish OpenAPI contract violations\n from unrelated runtime errors.\n- All exceptions raised by the OpenAPI-first core should inherit\n from this type.\n
"},{"location":"openapi_first/loader/","title":"Loader","text":""},{"location":"openapi_first/loader/#openapi_first.loader","title":"openapi_first.loader","text":""},{"location":"openapi_first/loader/#openapi_first.loader--summary","title":"Summary","text":"OpenAPI specification loading and validation utilities.
This module is responsible for loading an OpenAPI 3.x specification from disk and validating it before it is used by the application.
It enforces the principle that an invalid or malformed OpenAPI document must never reach the routing or runtime layers.
Notes Design Principles:
- OpenAPI is treated as an authoritative contract.\n- Invalid specifications fail fast at application startup.\n- Supported formats are JSON and YAML.\n- Validation errors are surfaced clearly and early.\n
Constraints:
- This module intentionally does NOT:\n - Modify the OpenAPI document.\n - Infer missing fields.\n - Generate models or code.\n - Perform request/response validation at runtime.\n
"},{"location":"openapi_first/loader/#openapi_first.loader-classes","title":"Classes","text":""},{"location":"openapi_first/loader/#openapi_first.loader.OpenAPISpecLoadError","title":"OpenAPISpecLoadError","text":" Bases: OpenAPIFirstError
Raised when an OpenAPI specification cannot be loaded or validated.
Notes Guarantees:
- This error indicates that the OpenAPI document is unreadable,\n malformed, or violates the OpenAPI 3.x specification.\n
"},{"location":"openapi_first/loader/#openapi_first.loader-functions","title":"Functions","text":""},{"location":"openapi_first/loader/#openapi_first.loader.load_openapi","title":"load_openapi","text":"load_openapi(path: str | Path) -> dict[str, Any]\n
Load and validate an OpenAPI 3.x specification from disk.
Parameters:
Name Type Description Default path str | Path Filesystem path to an OpenAPI specification file. Supported extensions: .json, .yaml, .yml.
required Returns:
Type Description dict[str, Any] dict[str, Any]: Parsed and validated OpenAPI specification.
Raises:
Type Description OpenAPISpecLoadError If the file does not exist, cannot be parsed, or fails OpenAPI schema validation.
Notes Guarantees:
- The specification is parsed based on file extension and validated\n using a strict OpenAPI schema validator.\n- Any error results in an immediate exception, preventing\n application startup.\n
"},{"location":"openapi_first/security/","title":"Security","text":""},{"location":"openapi_first/security/#openapi_first.security","title":"openapi_first.security","text":""},{"location":"openapi_first/security/#openapi_first.security--summary","title":"Summary","text":"OpenAPI security scheme parsing and auto-generated auth dependencies.
This module reads securitySchemes and per-operation security from an OpenAPI spec, resolves {ENV_VAR} placeholders in x- extension fields, and generates FastAPI dependencies for token validation (e.g., Bearer JWT introspection).
"},{"location":"openapi_first/security/#openapi_first.security-functions","title":"Functions","text":""},{"location":"openapi_first/security/#openapi_first.security.make_security_dependencies","title":"make_security_dependencies","text":"make_security_dependencies(\n spec: dict[str, Any],\n security_schemes: dict[str, dict[str, Any]],\n) -> dict[str, list[Any]]\n
Build a mapping of METHOD:/path \u2192 list of Depends(...).
The effective security for each operation is resolved by:
- Using the operation-level
security field if present. - Falling back to the top-level
security field. - An empty list means no auth required for that operation.
"},{"location":"openapi_first/security/#openapi_first.security.parse_security_schemes","title":"parse_security_schemes","text":"parse_security_schemes(\n spec: dict[str, Any],\n) -> dict[str, dict[str, Any]]\n
Extract and resolve environment variables in security schemes.
"},{"location":"openapi_first/templates/","title":"Templates","text":" - Crud App
- Health App
- Model App
- Vet App
"},{"location":"openapi_first/templates/#openapi_first.templates","title":"openapi_first.templates","text":"Application templates for FastAPI OpenAPI First.
This package contains example and scaffolding templates intended to be copied into user projects via the openapi-first CLI.
Templates in this package are: - Reference implementations of OpenAPI-first services - Not part of the openapi_first public or internal API - Not intended to be imported as runtime dependencies
The presence of this file exists solely to: - Mark the directory as an explicit Python package - Enable deterministic tooling behavior (documentation, packaging) - Avoid accidental traversal of non-package directories
No code in this package should be imported by library consumers.
"},{"location":"openapi_first/templates/crud_app/","title":"Crud App","text":" - Data
- Main
- Routes
- Test Crud App
"},{"location":"openapi_first/templates/crud_app/#openapi_first.templates.crud_app","title":"openapi_first.templates.crud_app","text":"OpenAPI-first CRUD application template.
This package contains a complete, minimal example of an OpenAPI-first CRUD service built using the openapi_first library.
The application is assembled exclusively from: - an OpenAPI specification (openapi.yaml) - a handler namespace implementing CRUD operations (routes) - an in-memory mock data store (data)
All HTTP routes, methods, schemas, and operation bindings are defined in the OpenAPI specification and enforced at application startup. No decorator-driven routing or implicit framework behavior is used.
This template demonstrates: - operationId-driven server-side route binding - explicit HTTP status code control in handlers - operationId-driven client usage against the same OpenAPI contract - end-to-end validation using in-memory data and tests
"},{"location":"openapi_first/templates/crud_app/#openapi_first.templates.crud_app--scaffolding-via-cli","title":"Scaffolding via CLI","text":"Create a new CRUD example service using the bundled template:
openapi-first crud_app\n
Create the service in a custom directory:
openapi-first crud_app my-crud-service\n
List all available application templates:
openapi-first --list\n
The CLI copies template files verbatim into the target directory. No code is generated or modified beyond the copied scaffold.
"},{"location":"openapi_first/templates/crud_app/#openapi_first.templates.crud_app--client-usage-example","title":"Client Usage Example","text":"The same OpenAPI specification used by the server can be used to construct a strict, operationId-driven HTTP client.
Example client calls for CRUD operations:
from openapi_first.loader import load_openapi\nfrom openapi_first.client import OpenAPIClient\n\nspec = load_openapi(\"openapi.yaml\")\nclient = OpenAPIClient(spec)\n\n# List items\nresponse = client.list_items()\n\n# Get item by ID\nresponse = client.get_item(\n path_params={\"item_id\": 1}\n)\n\n# Create item\nresponse = client.create_item(\n body={\"name\": \"Orange\", \"price\": 0.8}\n)\n\n# Update item\nresponse = client.update_item(\n path_params={\"item_id\": 1},\n body={\"name\": \"Green Apple\", \"price\": 0.6},\n)\n\n# Delete item\nresponse = client.delete_item(\n path_params={\"item_id\": 1}\n)\n
Client guarantees: - One callable per OpenAPI operationId - No hardcoded URLs or HTTP methods in user code - Path and request parameters must match the OpenAPI specification - Invalid or incomplete OpenAPI specs fail at client construction time
"},{"location":"openapi_first/templates/crud_app/#openapi_first.templates.crud_app--non-goals","title":"Non-Goals","text":"This template is intentionally minimal and is NOT: - production-ready - persistent or concurrency-safe - a reference architecture for data storage
It exists solely as a copyable example for learning, testing, and bootstrapping OpenAPI-first services.
This package is not part of the openapi_first library API surface.
"},{"location":"openapi_first/templates/crud_app/data/","title":"Data","text":""},{"location":"openapi_first/templates/crud_app/data/#openapi_first.templates.crud_app.data","title":"openapi_first.templates.crud_app.data","text":"In-memory mock data store for CRUD example.
This module intentionally avoids persistence and concurrency guarantees. It is suitable for demos, tests, and scaffolding only.
It intentionally avoids - persistence - concurrency guarantees - validation - error handling
The implementation is suitable for: - demonstrations - tests - scaffolding and example services
It is explicitly NOT suitable for production use.
This module is not part of the openapi_first library API surface.
"},{"location":"openapi_first/templates/crud_app/data/#openapi_first.templates.crud_app.data-functions","title":"Functions","text":""},{"location":"openapi_first/templates/crud_app/data/#openapi_first.templates.crud_app.data.create_item","title":"create_item","text":"create_item(payload: dict)\n
Create a new item in the data store.
A new integer ID is assigned automatically. No validation is performed on the provided payload.
"},{"location":"openapi_first/templates/crud_app/data/#openapi_first.templates.crud_app.data.create_item--parameters","title":"Parameters","text":"payload : dict Item attributes excluding the id field.
"},{"location":"openapi_first/templates/crud_app/data/#openapi_first.templates.crud_app.data.create_item--returns","title":"Returns","text":"dict The newly created item, including its assigned ID.
"},{"location":"openapi_first/templates/crud_app/data/#openapi_first.templates.crud_app.data.delete_item","title":"delete_item","text":"delete_item(item_id: int)\n
Remove an item from the data store.
This function assumes the item exists and will raise KeyError if the ID is not present.
"},{"location":"openapi_first/templates/crud_app/data/#openapi_first.templates.crud_app.data.delete_item--parameters","title":"Parameters","text":"item_id : int Identifier of the item to delete.
"},{"location":"openapi_first/templates/crud_app/data/#openapi_first.templates.crud_app.data.get_item","title":"get_item","text":"get_item(item_id: int)\n
Retrieve a single item by ID.
This function assumes the item exists and will raise KeyError if the ID is not present in the store.
"},{"location":"openapi_first/templates/crud_app/data/#openapi_first.templates.crud_app.data.get_item--parameters","title":"Parameters","text":"item_id : int Identifier of the item to retrieve.
"},{"location":"openapi_first/templates/crud_app/data/#openapi_first.templates.crud_app.data.get_item--returns","title":"Returns","text":"dict The stored item representation.
"},{"location":"openapi_first/templates/crud_app/data/#openapi_first.templates.crud_app.data.list_items","title":"list_items","text":"list_items()\n
Return all items in the data store.
This function performs no filtering, pagination, or sorting. The returned collection reflects the current in-memory state.
"},{"location":"openapi_first/templates/crud_app/data/#openapi_first.templates.crud_app.data.list_items--returns","title":"Returns","text":"list[dict] A list of item representations.
"},{"location":"openapi_first/templates/crud_app/data/#openapi_first.templates.crud_app.data.update_item","title":"update_item","text":"update_item(item_id: int, payload: dict)\n
Replace an existing item in the data store.
This function overwrites the existing item entirely and does not perform partial updates or validation. If the item does not exist, it will be created implicitly.
"},{"location":"openapi_first/templates/crud_app/data/#openapi_first.templates.crud_app.data.update_item--parameters","title":"Parameters","text":"item_id : int Identifier of the item to update. payload : dict Item attributes excluding the id field.
"},{"location":"openapi_first/templates/crud_app/data/#openapi_first.templates.crud_app.data.update_item--returns","title":"Returns","text":"dict The updated item representation.
"},{"location":"openapi_first/templates/crud_app/main/","title":"Main","text":""},{"location":"openapi_first/templates/crud_app/main/#openapi_first.templates.crud_app.main","title":"openapi_first.templates.crud_app.main","text":"Application entry point for an OpenAPI-first CRUD example service.
This module constructs a FastAPI application exclusively from an OpenAPI specification and a handler namespace, without using decorator-driven routing.
All HTTP routes, methods, request/response schemas, and operation bindings are defined in the OpenAPI document referenced by openapi_path. Python callables defined in the routes module are bound to OpenAPI operations strictly via operationId.
This module contains no routing logic, persistence concerns, or framework configuration beyond application assembly.
Design guarantees: - OpenAPI is the single source of truth - No undocumented routes can exist - Every OpenAPI operationId must resolve to exactly one handler - All contract violations fail at application startup
This file is intended to be used as the ASGI entry point.
Example uvicorn main:app
"},{"location":"openapi_first/templates/crud_app/main/#openapi_first.templates.crud_app.main-classes","title":"Classes","text":""},{"location":"openapi_first/templates/crud_app/routes/","title":"Routes","text":""},{"location":"openapi_first/templates/crud_app/routes/#openapi_first.templates.crud_app.routes","title":"openapi_first.templates.crud_app.routes","text":"CRUD route handlers bound via OpenAPI operationId.
These handlers explicitly control HTTP status codes to ensure runtime behavior matches the OpenAPI contract.
This module defines OpenAPI-bound operation handlers for a simple CRUD service. Functions in this module are bound to HTTP routes exclusively via OpenAPI operationId values.
Handlers explicitly control HTTP response status codes to ensure runtime behavior matches the OpenAPI contract. Error conditions are translated into explicit HTTP responses rather than relying on implicit framework behavior.
No routing decorators or path definitions appear in this module. All routing, HTTP methods, and schemas are defined in the OpenAPI specification.
"},{"location":"openapi_first/templates/crud_app/routes/#openapi_first.templates.crud_app.routes-functions","title":"Functions","text":""},{"location":"openapi_first/templates/crud_app/routes/#openapi_first.templates.crud_app.routes.create_item","title":"create_item","text":"create_item(payload: dict, response: Response)\n
Create a new item.
Implements the OpenAPI operation identified by operationId: create_item.
"},{"location":"openapi_first/templates/crud_app/routes/#openapi_first.templates.crud_app.routes.create_item--parameters","title":"Parameters","text":"payload : dict Item attributes excluding the id field. response : fastapi.Response Response object used to set the HTTP status code.
"},{"location":"openapi_first/templates/crud_app/routes/#openapi_first.templates.crud_app.routes.create_item--returns","title":"Returns","text":"dict The newly created item.
"},{"location":"openapi_first/templates/crud_app/routes/#openapi_first.templates.crud_app.routes.delete_item","title":"delete_item","text":"delete_item(item_id: int, response: Response)\n
Delete an existing item.
Implements the OpenAPI operation identified by operationId: delete_item.
"},{"location":"openapi_first/templates/crud_app/routes/#openapi_first.templates.crud_app.routes.delete_item--parameters","title":"Parameters","text":"item_id : int Identifier of the item to delete. response : fastapi.Response Response object used to set the HTTP status code.
"},{"location":"openapi_first/templates/crud_app/routes/#openapi_first.templates.crud_app.routes.delete_item--returns","title":"Returns","text":"None No content.
"},{"location":"openapi_first/templates/crud_app/routes/#openapi_first.templates.crud_app.routes.delete_item--raises","title":"Raises","text":"HTTPException 404 if the item does not exist.
"},{"location":"openapi_first/templates/crud_app/routes/#openapi_first.templates.crud_app.routes.get_item","title":"get_item","text":"get_item(item_id: int)\n
Retrieve a single item by ID.
Implements the OpenAPI operation identified by operationId: get_item.
"},{"location":"openapi_first/templates/crud_app/routes/#openapi_first.templates.crud_app.routes.get_item--parameters","title":"Parameters","text":"item_id : int Identifier of the item to retrieve.
"},{"location":"openapi_first/templates/crud_app/routes/#openapi_first.templates.crud_app.routes.get_item--returns","title":"Returns","text":"dict The requested item.
"},{"location":"openapi_first/templates/crud_app/routes/#openapi_first.templates.crud_app.routes.get_item--raises","title":"Raises","text":"HTTPException 404 if the item does not exist.
"},{"location":"openapi_first/templates/crud_app/routes/#openapi_first.templates.crud_app.routes.list_items","title":"list_items","text":"list_items()\n
List all items.
Implements the OpenAPI operation identified by operationId: list_items.
"},{"location":"openapi_first/templates/crud_app/routes/#openapi_first.templates.crud_app.routes.list_items--returns","title":"Returns","text":"list[dict] A list of item representations.
"},{"location":"openapi_first/templates/crud_app/routes/#openapi_first.templates.crud_app.routes.update_item","title":"update_item","text":"update_item(item_id: int, payload: dict)\n
Update an existing item.
Implements the OpenAPI operation identified by operationId: update_item.
"},{"location":"openapi_first/templates/crud_app/routes/#openapi_first.templates.crud_app.routes.update_item--parameters","title":"Parameters","text":"item_id : int Identifier of the item to update. payload : dict Item attributes excluding the id field.
"},{"location":"openapi_first/templates/crud_app/routes/#openapi_first.templates.crud_app.routes.update_item--returns","title":"Returns","text":"dict The updated item.
"},{"location":"openapi_first/templates/crud_app/routes/#openapi_first.templates.crud_app.routes.update_item--raises","title":"Raises","text":"HTTPException 404 if the item does not exist.
"},{"location":"openapi_first/templates/crud_app/test_crud_app/","title":"Test Crud App","text":""},{"location":"openapi_first/templates/crud_app/test_crud_app/#openapi_first.templates.crud_app.test_crud_app","title":"openapi_first.templates.crud_app.test_crud_app","text":"End-to-end tests for the OpenAPI-first CRUD example app.
These tests validate that all CRUD operations behave correctly against the in-memory mock data store. - OpenAPI specification loading - OperationId-driven route binding on the server - OperationId-driven client invocation - Correct HTTP status codes and response payloads
The tests exercise all CRUD operations against an in-memory mock data store and assume deterministic behavior within a single process.
The tests assume: - OpenAPI-first route binding - In-memory storage (no persistence guarantees) - Deterministic behavior in a single process - One-to-one correspondence between OpenAPI operationId values and server/client callables
"},{"location":"openapi_first/templates/crud_app/test_crud_app/#openapi_first.templates.crud_app.test_crud_app-classes","title":"Classes","text":""},{"location":"openapi_first/templates/crud_app/test_crud_app/#openapi_first.templates.crud_app.test_crud_app-functions","title":"Functions","text":""},{"location":"openapi_first/templates/crud_app/test_crud_app/#openapi_first.templates.crud_app.test_crud_app.test_create_item","title":"test_create_item","text":"test_create_item()\n
Creating a new item should return the created entity.
"},{"location":"openapi_first/templates/crud_app/test_crud_app/#openapi_first.templates.crud_app.test_crud_app.test_delete_item","title":"test_delete_item","text":"test_delete_item()\n
Deleting an item should remove it from the store.
"},{"location":"openapi_first/templates/crud_app/test_crud_app/#openapi_first.templates.crud_app.test_crud_app.test_get_item","title":"test_get_item","text":"test_get_item()\n
Existing item should be retrievable by ID.
"},{"location":"openapi_first/templates/crud_app/test_crud_app/#openapi_first.templates.crud_app.test_crud_app.test_list_items_initial","title":"test_list_items_initial","text":"test_list_items_initial()\n
Initial items should be present.
"},{"location":"openapi_first/templates/crud_app/test_crud_app/#openapi_first.templates.crud_app.test_crud_app.test_update_item","title":"test_update_item","text":"test_update_item()\n
Updating an item should replace its values.
"},{"location":"openapi_first/templates/health_app/","title":"Health App","text":" - Main
- Routes
"},{"location":"openapi_first/templates/health_app/#openapi_first.templates.health_app","title":"openapi_first.templates.health_app","text":"OpenAPI-first FastAPI application template.
This package contains a minimal, fully working example of an OpenAPI-first FastAPI service built using the openapi_first library.
The application is assembled exclusively from: - an OpenAPI specification (openapi.yaml) - a handler namespace (routes)
No routing decorators, implicit behavior, or framework-specific convenience abstractions are used. All HTTP routes, methods, and operation bindings are defined in OpenAPI and enforced at application startup.
This package is intended to be copied as a starting point for new services via the openapi-first CLI. It is not part of the openapi_first library API surface.
"},{"location":"openapi_first/templates/health_app/#openapi_first.templates.health_app--scaffolding-via-cli","title":"Scaffolding via CLI","text":"Create a new OpenAPI-first health check service using the bundled template:
openapi-first health_app\n
Create the service in a custom directory:
openapi-first health_app my-health-service\n
List all available application templates:
openapi-first --list\n
The CLI copies template files verbatim into the target directory. No code is generated or modified beyond the copied scaffold.
"},{"location":"openapi_first/templates/health_app/#openapi_first.templates.health_app--client-usage-example","title":"Client Usage Example","text":"The same OpenAPI specification used by the server can be used to construct a strict, operationId-driven HTTP client.
Example client call for the get_health operation:
from openapi_first.loader import load_openapi\nfrom openapi_first.client import OpenAPIClient\n\nspec = load_openapi(\"openapi.yaml\")\nclient = OpenAPIClient(spec)\n\nresponse = client.get_health()\n\nassert response.status_code == 200\nassert response.json() == {\"status\": \"ok\"}\n
Client guarantees: - One callable per OpenAPI operationId - No hardcoded URLs or HTTP methods in user code - Path and request parameters must match the OpenAPI specification - Invalid or incomplete OpenAPI specs fail at client construction time
"},{"location":"openapi_first/templates/health_app/main/","title":"Main","text":""},{"location":"openapi_first/templates/health_app/main/#openapi_first.templates.health_app.main","title":"openapi_first.templates.health_app.main","text":"Application entry point for an OpenAPI-first FastAPI service.
This module constructs a FastAPI application exclusively from an OpenAPI specification and a handler namespace, without using decorator-driven routing.
All HTTP routes, methods, and operation bindings are defined in the OpenAPI document referenced by openapi_path. Python callables defined in the routes module are bound to OpenAPI operations strictly via operationId.
This module contains no routing logic, request handling, or framework configuration beyond application assembly.
Design guarantees: - OpenAPI is the single source of truth - No undocumented routes can exist - Every OpenAPI operationId must resolve to exactly one handler - All contract violations fail at application startup
This file is intended to be used as the ASGI entry point.
Example uvicorn main:app
"},{"location":"openapi_first/templates/health_app/main/#openapi_first.templates.health_app.main-classes","title":"Classes","text":""},{"location":"openapi_first/templates/health_app/routes/","title":"Routes","text":""},{"location":"openapi_first/templates/health_app/routes/#openapi_first.templates.health_app.routes","title":"openapi_first.templates.health_app.routes","text":"OpenAPI operation handlers.
This module defines pure Python callables that implement OpenAPI operations for this service. Functions in this module are bound to HTTP routes exclusively via OpenAPI operationId values.
No routing decorators, HTTP metadata, or framework-specific logic should appear here. All request/response semantics are defined in the OpenAPI specification.
This module serves solely as an operationId namespace.
"},{"location":"openapi_first/templates/health_app/routes/#openapi_first.templates.health_app.routes-functions","title":"Functions","text":""},{"location":"openapi_first/templates/health_app/routes/#openapi_first.templates.health_app.routes.get_health","title":"get_health","text":"get_health()\n
Health check operation handler.
This function implements the OpenAPI operation identified by operationId: get_health.
It contains no routing metadata or framework-specific logic. Request binding, HTTP method, and response semantics are defined exclusively by the OpenAPI specification.
"},{"location":"openapi_first/templates/health_app/routes/#openapi_first.templates.health_app.routes.get_health--returns","title":"Returns","text":"dict A minimal liveness payload indicating service health.
"},{"location":"openapi_first/templates/model_app/","title":"Model App","text":" - Data
- Main
- Models
- Routes
- Test Model App
"},{"location":"openapi_first/templates/model_app/#openapi_first.templates.model_app","title":"openapi_first.templates.model_app","text":"OpenAPI-first model-based CRUD application template.
This package contains a complete, minimal example of an OpenAPI-first CRUD service that uses explicit Pydantic domain models for request and response schemas.
The application is assembled exclusively from: - an OpenAPI specification (openapi.yaml) - a handler namespace implementing CRUD operations (routes) - Pydantic domain models (models) - an in-memory mock data store (data)
All HTTP routes, methods, schemas, and operation bindings are defined in the OpenAPI specification and enforced at application startup. No decorator-driven routing or implicit framework behavior is used.
This template demonstrates: - operationId-driven server-side route binding - explicit request and response modeling with Pydantic - explicit HTTP status code control in handlers - operationId-driven client usage against the same OpenAPI contract - end-to-end validation using in-memory data and tests
"},{"location":"openapi_first/templates/model_app/#openapi_first.templates.model_app--scaffolding-via-cli","title":"Scaffolding via CLI","text":"Create a new model-based CRUD example service using the bundled template:
openapi-first model_app\n
Create the service in a custom directory:
openapi-first model_app my-model-service\n
List all available application templates:
openapi-first --list\n
The CLI copies template files verbatim into the target directory. No code is generated or modified beyond the copied scaffold.
"},{"location":"openapi_first/templates/model_app/#openapi_first.templates.model_app--client-usage-example","title":"Client Usage Example","text":"The same OpenAPI specification used by the server can be used to construct a strict, operationId-driven HTTP client.
Example client calls for model-based CRUD operations:
from openapi_first.loader import load_openapi\nfrom openapi_first.client import OpenAPIClient\n\nspec = load_openapi(\"openapi.yaml\")\nclient = OpenAPIClient(spec)\n\n# List items\nresponse = client.list_items()\n\n# Get item by ID\nresponse = client.get_item(\n path_params={\"item_id\": 1}\n)\n\n# Create item\nresponse = client.create_item(\n body={\"name\": \"Orange\", \"price\": 0.8}\n)\n\n# Update item\nresponse = client.update_item(\n path_params={\"item_id\": 1},\n body={\"name\": \"Green Apple\", \"price\": 0.6},\n)\n\n# Delete item\nresponse = client.delete_item(\n path_params={\"item_id\": 1}\n)\n
Client guarantees: - One callable per OpenAPI operationId - No hardcoded URLs or HTTP methods in user code - Request and response payloads conform to Pydantic models - Invalid or incomplete OpenAPI specs fail at client construction time
"},{"location":"openapi_first/templates/model_app/#openapi_first.templates.model_app--non-goals","title":"Non-Goals","text":"This template is intentionally minimal and is NOT: - production-ready - persistent or concurrency-safe - a reference architecture for data storage
It exists solely as a copyable example for learning, testing, and bootstrapping OpenAPI-first services.
This package is not part of the openapi_first library API surface.
"},{"location":"openapi_first/templates/model_app/data/","title":"Data","text":""},{"location":"openapi_first/templates/model_app/data/#openapi_first.templates.model_app.data","title":"openapi_first.templates.model_app.data","text":"In-memory data store using Pydantic models.
This module is NOT thread-safe and is intended for demos and scaffolds only. This module provides a minimal, process-local data store for the model-based CRUD example application. It stores and returns domain objects defined using Pydantic models and is intended solely for demonstration and scaffolding purposes.
The implementation intentionally avoids: - persistence - concurrency guarantees - transactional semantics - validation beyond what Pydantic provides
It is not part of the openapi_first library API surface.
"},{"location":"openapi_first/templates/model_app/data/#openapi_first.templates.model_app.data-functions","title":"Functions","text":""},{"location":"openapi_first/templates/model_app/data/#openapi_first.templates.model_app.data.create_item","title":"create_item","text":"create_item(payload: ItemCreate) -> Item\n
Create a new item in the data store.
A new identifier is assigned automatically. No additional validation is performed beyond Pydantic model validation.
"},{"location":"openapi_first/templates/model_app/data/#openapi_first.templates.model_app.data.create_item--parameters","title":"Parameters","text":"payload : ItemCreate Data required to create a new item.
"},{"location":"openapi_first/templates/model_app/data/#openapi_first.templates.model_app.data.create_item--returns","title":"Returns","text":"Item The newly created item.
"},{"location":"openapi_first/templates/model_app/data/#openapi_first.templates.model_app.data.delete_item","title":"delete_item","text":"delete_item(item_id: int) -> None\n
Remove an item from the data store.
"},{"location":"openapi_first/templates/model_app/data/#openapi_first.templates.model_app.data.delete_item--parameters","title":"Parameters","text":"item_id : int Identifier of the item to delete.
"},{"location":"openapi_first/templates/model_app/data/#openapi_first.templates.model_app.data.delete_item--raises","title":"Raises","text":"KeyError If the item does not exist.
"},{"location":"openapi_first/templates/model_app/data/#openapi_first.templates.model_app.data.get_item","title":"get_item","text":"get_item(item_id: int) -> Item\n
Retrieve a single item by ID.
"},{"location":"openapi_first/templates/model_app/data/#openapi_first.templates.model_app.data.get_item--parameters","title":"Parameters","text":"item_id : int Identifier of the item to retrieve.
"},{"location":"openapi_first/templates/model_app/data/#openapi_first.templates.model_app.data.get_item--returns","title":"Returns","text":"Item The requested item.
"},{"location":"openapi_first/templates/model_app/data/#openapi_first.templates.model_app.data.get_item--raises","title":"Raises","text":"KeyError If the item does not exist.
"},{"location":"openapi_first/templates/model_app/data/#openapi_first.templates.model_app.data.list_items","title":"list_items","text":"list_items() -> list[Item]\n
Return all items in the data store.
"},{"location":"openapi_first/templates/model_app/data/#openapi_first.templates.model_app.data.list_items--returns","title":"Returns","text":"list[Item] A list of item domain objects.
"},{"location":"openapi_first/templates/model_app/data/#openapi_first.templates.model_app.data.update_item","title":"update_item","text":"update_item(item_id: int, payload: ItemCreate) -> Item\n
Replace an existing item in the data store.
This function performs a full replacement of the stored item. Partial updates are not supported.
"},{"location":"openapi_first/templates/model_app/data/#openapi_first.templates.model_app.data.update_item--parameters","title":"Parameters","text":"item_id : int Identifier of the item to update. payload : ItemCreate New item data.
"},{"location":"openapi_first/templates/model_app/data/#openapi_first.templates.model_app.data.update_item--returns","title":"Returns","text":"Item The updated item.
"},{"location":"openapi_first/templates/model_app/data/#openapi_first.templates.model_app.data.update_item--raises","title":"Raises","text":"KeyError If the item does not exist.
"},{"location":"openapi_first/templates/model_app/main/","title":"Main","text":""},{"location":"openapi_first/templates/model_app/main/#openapi_first.templates.model_app.main","title":"openapi_first.templates.model_app.main","text":"Application entry point for an OpenAPI-first model-based CRUD example service.
This module constructs a FastAPI application exclusively from an OpenAPI specification and a handler namespace, without using decorator-driven routing.
All HTTP routes, methods, request/response schemas, and operation bindings are defined in the OpenAPI document referenced by openapi_path. Python callables defined in the routes module are bound to OpenAPI operations strictly via operationId.
This module contains no routing logic, persistence concerns, or framework configuration beyond application assembly.
Design guarantees: - OpenAPI is the single source of truth - No undocumented routes can exist - Every OpenAPI operationId must resolve to exactly one handler - All contract violations fail at application startup
This file is intended to be used as the ASGI entry point.
Example uvicorn main:app
"},{"location":"openapi_first/templates/model_app/main/#openapi_first.templates.model_app.main-classes","title":"Classes","text":""},{"location":"openapi_first/templates/model_app/models/","title":"Models","text":""},{"location":"openapi_first/templates/model_app/models/#openapi_first.templates.model_app.models","title":"openapi_first.templates.model_app.models","text":"Pydantic domain models for the CRUD example.
This module defines Pydantic models that represent the domain entities used by the service. These models are referenced by the OpenAPI specification for request and response schemas.
The models are declarative and framework-agnostic. They contain no persistence logic, validation beyond type constraints, or business behavior.
This module is not part of the openapi_first library API surface. It exists solely to support the example application template.
"},{"location":"openapi_first/templates/model_app/models/#openapi_first.templates.model_app.models-classes","title":"Classes","text":""},{"location":"openapi_first/templates/model_app/models/#openapi_first.templates.model_app.models.Item","title":"Item","text":" Bases: ItemBase
Domain model for a persisted item.
This model represents the full item state returned in responses, including the server-assigned identifier.
"},{"location":"openapi_first/templates/model_app/models/#openapi_first.templates.model_app.models.ItemBase","title":"ItemBase","text":" Bases: BaseModel
Base domain model for an item.
Defines fields common to all item representations.
"},{"location":"openapi_first/templates/model_app/models/#openapi_first.templates.model_app.models.ItemCreate","title":"ItemCreate","text":" Bases: ItemBase
Domain model for item creation requests.
This model is used for request bodies when creating new items. It intentionally excludes the id field, which is assigned by the service.
"},{"location":"openapi_first/templates/model_app/routes/","title":"Routes","text":""},{"location":"openapi_first/templates/model_app/routes/#openapi_first.templates.model_app.routes","title":"openapi_first.templates.model_app.routes","text":"CRUD route handlers bound via OpenAPI operationId.
This module defines OpenAPI-bound operation handlers for a model-based CRUD service. Functions in this module are bound to HTTP routes exclusively via OpenAPI operationId values.
Handlers explicitly control HTTP response status codes to ensure runtime behavior matches the OpenAPI contract. Domain models defined using Pydantic are used for request and response payloads.
No routing decorators, path definitions, or implicit framework behavior appear in this module. All routing, HTTP methods, and schemas are defined in the OpenAPI specification.
"},{"location":"openapi_first/templates/model_app/routes/#openapi_first.templates.model_app.routes-functions","title":"Functions","text":""},{"location":"openapi_first/templates/model_app/routes/#openapi_first.templates.model_app.routes.create_item","title":"create_item","text":"create_item(payload: ItemCreate, response: Response)\n
Create a new item.
Implements the OpenAPI operation identified by operationId: create_item.
"},{"location":"openapi_first/templates/model_app/routes/#openapi_first.templates.model_app.routes.create_item--parameters","title":"Parameters","text":"payload : ItemCreate Request body describing the item to create. response : fastapi.Response Response object used to set the HTTP status code.
"},{"location":"openapi_first/templates/model_app/routes/#openapi_first.templates.model_app.routes.create_item--returns","title":"Returns","text":"Item The newly created item.
"},{"location":"openapi_first/templates/model_app/routes/#openapi_first.templates.model_app.routes.delete_item","title":"delete_item","text":"delete_item(item_id: int, response: Response)\n
Delete an existing item.
Implements the OpenAPI operation identified by operationId: delete_item.
"},{"location":"openapi_first/templates/model_app/routes/#openapi_first.templates.model_app.routes.delete_item--parameters","title":"Parameters","text":"item_id : int Identifier of the item to delete. response : fastapi.Response Response object used to set the HTTP status code.
"},{"location":"openapi_first/templates/model_app/routes/#openapi_first.templates.model_app.routes.delete_item--returns","title":"Returns","text":"None No content.
"},{"location":"openapi_first/templates/model_app/routes/#openapi_first.templates.model_app.routes.delete_item--raises","title":"Raises","text":"HTTPException 404 if the item does not exist.
"},{"location":"openapi_first/templates/model_app/routes/#openapi_first.templates.model_app.routes.get_item","title":"get_item","text":"get_item(item_id: int)\n
Retrieve a single item by ID.
Implements the OpenAPI operation identified by operationId: get_item.
"},{"location":"openapi_first/templates/model_app/routes/#openapi_first.templates.model_app.routes.get_item--parameters","title":"Parameters","text":"item_id : int Identifier of the item to retrieve.
"},{"location":"openapi_first/templates/model_app/routes/#openapi_first.templates.model_app.routes.get_item--returns","title":"Returns","text":"Item The requested item.
"},{"location":"openapi_first/templates/model_app/routes/#openapi_first.templates.model_app.routes.get_item--raises","title":"Raises","text":"HTTPException 404 if the item does not exist.
"},{"location":"openapi_first/templates/model_app/routes/#openapi_first.templates.model_app.routes.list_items","title":"list_items","text":"list_items()\n
List all items.
Implements the OpenAPI operation identified by operationId: list_items.
"},{"location":"openapi_first/templates/model_app/routes/#openapi_first.templates.model_app.routes.list_items--returns","title":"Returns","text":"list[Item] A list of item domain objects.
"},{"location":"openapi_first/templates/model_app/routes/#openapi_first.templates.model_app.routes.update_item","title":"update_item","text":"update_item(item_id: int, payload: ItemCreate)\n
Update an existing item.
Implements the OpenAPI operation identified by operationId: update_item.
"},{"location":"openapi_first/templates/model_app/routes/#openapi_first.templates.model_app.routes.update_item--parameters","title":"Parameters","text":"item_id : int Identifier of the item to update. payload : ItemCreate New item data.
"},{"location":"openapi_first/templates/model_app/routes/#openapi_first.templates.model_app.routes.update_item--returns","title":"Returns","text":"Item The updated item.
"},{"location":"openapi_first/templates/model_app/routes/#openapi_first.templates.model_app.routes.update_item--raises","title":"Raises","text":"HTTPException 404 if the item does not exist.
"},{"location":"openapi_first/templates/model_app/test_model_app/","title":"Test Model App","text":""},{"location":"openapi_first/templates/model_app/test_model_app/#openapi_first.templates.model_app.test_model_app","title":"openapi_first.templates.model_app.test_model_app","text":"End-to-end tests for the OpenAPI-first model CRUD example app.
These tests validate that all CRUD operations behave correctly against the in-memory mock data store using Pydantic models. - OpenAPI specification loading - OperationId-driven route binding on the server - OperationId-driven client invocation - Pydantic model-based request and response handling
All CRUD operations are exercised against an in-memory mock data store backed by Pydantic domain models.
The tests assume: - OpenAPI-first route binding - Pydantic model validation - In-memory storage (no persistence guarantees) - Deterministic behavior in a single process
"},{"location":"openapi_first/templates/model_app/test_model_app/#openapi_first.templates.model_app.test_model_app-classes","title":"Classes","text":""},{"location":"openapi_first/templates/model_app/test_model_app/#openapi_first.templates.model_app.test_model_app-functions","title":"Functions","text":""},{"location":"openapi_first/templates/model_app/test_model_app/#openapi_first.templates.model_app.test_model_app.test_create_item","title":"test_create_item","text":"test_create_item()\n
Creating a new item should return the created entity.
"},{"location":"openapi_first/templates/model_app/test_model_app/#openapi_first.templates.model_app.test_model_app.test_delete_item","title":"test_delete_item","text":"test_delete_item()\n
Deleting an item should remove it from the store.
"},{"location":"openapi_first/templates/model_app/test_model_app/#openapi_first.templates.model_app.test_model_app.test_get_item","title":"test_get_item","text":"test_get_item()\n
Existing item should be retrievable by ID.
"},{"location":"openapi_first/templates/model_app/test_model_app/#openapi_first.templates.model_app.test_model_app.test_list_items_initial","title":"test_list_items_initial","text":"test_list_items_initial()\n
Initial items should be present.
"},{"location":"openapi_first/templates/model_app/test_model_app/#openapi_first.templates.model_app.test_model_app.test_update_item","title":"test_update_item","text":"test_update_item()\n
Updating an item should replace its values.
"},{"location":"openapi_first/templates/vet_app/","title":"Vet App","text":" - Data
- Main
- Models
- Routes
- Sse
- Test Vet App
"},{"location":"openapi_first/templates/vet_app/#openapi_first.templates.vet_app","title":"openapi_first.templates.vet_app","text":"OpenAPI-first Veterinary Clinic application template.
This package contains a complete, runnable example of an OpenAPI-first veterinary clinic management service. It demonstrates all x- extension fields consumed by the react-openapi admin panel renderer.
The application manages five resources:
- Parents \u2014 pet owners with contact details
- Vets \u2014 veterinarians with specializations
- Treatments \u2014 medical procedure catalog
- Pets \u2014 animals with species, age, weight, and photos
- Appointments \u2014 scheduled visits linking pets, vets, and treatments
All HTTP routes, methods, schemas, and operation bindings are defined in the OpenAPI specification (openapi.yaml). Every operation has an explicit operationId that maps to a Python handler in routes.py.
This file is a copyable template. It is not part of the openapi_first library API surface.
"},{"location":"openapi_first/templates/vet_app/#openapi_first.templates.vet_app--openapi-x-extension-fields-demonstrated","title":"OpenAPI x- extension fields demonstrated","text":"Schema-level extensions (display metadata for resource endpoints):
x-primary-key (REQUIRED) Primary key property name x-display-format (REQUIRED) Human-readable label template x-list-columns (REQUIRED) Columns for the datatable
Property-level extensions (control UI rendering):
x-label (REQUIRED) Human-readable field label x-order (REQUIRED) Field ordering in forms/detail x-description (optional) Helper text below form fields x-hidden (optional) Visibility in form / list / detail x-filterable (optional) Allows column filtering x-sortable (optional) Allows column sorting x-fk (optional) Foreign key \u2014 renders as dropdown x-fk.resource (REQUIRED for FK) Target resource name x-fk.prefetch (optional) Preload all FK options on mount x-ui-type (optional) Custom UI type (e.g. image upload) x-upload-url (optional) Upload endpoint for binary fields
"},{"location":"openapi_first/templates/vet_app/#openapi_first.templates.vet_app--scaffolding-via-cli","title":"Scaffolding via CLI","text":"Create a new vet clinic service using the bundled template:
openapi-first vet_app\n
Create the service in a custom directory:
openapi-first vet_app my-vet-clinic\n
"},{"location":"openapi_first/templates/vet_app/#openapi_first.templates.vet_app--client-usage-example","title":"Client Usage Example","text":"from openapi_first.loader import load_openapi\nfrom openapi_first.client import OpenAPIClient\n\nspec = load_openapi(\"openapi.yaml\")\nclient = OpenAPIClient(spec)\n\n# List pets with pagination\nresponse = client.list_pets(query_params={\"limit\": 10, \"offset\": 0})\n\n# Create a pet with FK references\nresponse = client.create_pet(\n body={\"name\": \"Fido\", \"species\": \"dog\", \"parents\": [1, 2]}\n)\n\n# Upload a pet photo\nresponse = client.upload_pet_photo(\n path_params={\"id\": 1},\n body={\"file\": open(\"photo.jpg\", \"rb\")},\n)\n
"},{"location":"openapi_first/templates/vet_app/#openapi_first.templates.vet_app--non-goals","title":"Non-Goals","text":"This template is intentionally minimal and is NOT: - production-ready - persistent or concurrency-safe - a reference architecture for data storage
It exists solely as a copyable example for learning, testing, and bootstrapping OpenAPI-first services.
This package is not part of the openapi_first library API surface.
"},{"location":"openapi_first/templates/vet_app/data/","title":"Data","text":""},{"location":"openapi_first/templates/vet_app/data/#openapi_first.templates.vet_app.data","title":"openapi_first.templates.vet_app.data","text":"In-memory data store for the Veterinary Clinic example.
This module is NOT thread-safe and is intended for demos and scaffolds only.
It provides minimal, process-local data stores for the five veterinary clinic entities. Each store exposes standard CRUD operations backed by a simple dictionary.
This module intentionally avoids: - persistence - concurrency guarantees - transactional semantics - validation beyond what Pydantic provides
This module is not part of the openapi_first library API surface.
"},{"location":"openapi_first/templates/vet_app/main/","title":"Main","text":""},{"location":"openapi_first/templates/vet_app/main/#openapi_first.templates.vet_app.main","title":"openapi_first.templates.vet_app.main","text":"Application entry point for an OpenAPI-first Veterinary Clinic service.
This module constructs a FastAPI application exclusively from an OpenAPI specification and a handler namespace, without using decorator-driven routing.
All HTTP routes, methods, request/response schemas, and operation bindings are defined in the OpenAPI document referenced by openapi_path. Python callables defined in the routes module are bound to OpenAPI operations strictly via operationId.
This module contains no routing logic, persistence concerns, or framework configuration beyond application assembly.
Design guarantees: - OpenAPI is the single source of truth - No undocumented routes can exist - Every OpenAPI operationId must resolve to exactly one handler - All contract violations fail at application startup
This file is intended to be used as the ASGI entry point.
Example uvicorn main:app
"},{"location":"openapi_first/templates/vet_app/main/#openapi_first.templates.vet_app.main-classes","title":"Classes","text":""},{"location":"openapi_first/templates/vet_app/models/","title":"Models","text":""},{"location":"openapi_first/templates/vet_app/models/#openapi_first.templates.vet_app.models","title":"openapi_first.templates.vet_app.models","text":""},{"location":"openapi_first/templates/vet_app/routes/","title":"Routes","text":""},{"location":"openapi_first/templates/vet_app/routes/#openapi_first.templates.vet_app.routes","title":"openapi_first.templates.vet_app.routes","text":"Veterinary Clinic route handlers bound via OpenAPI operationId.
Handlers explicitly control HTTP response status codes to ensure runtime behavior matches the OpenAPI contract. Domain models defined using Pydantic are used for request and response payloads.
No routing decorators, path definitions, or implicit framework behavior appear in this module. All routing, HTTP methods, and schemas are defined in the OpenAPI specification.
"},{"location":"openapi_first/templates/vet_app/routes/#openapi_first.templates.vet_app.routes-functions","title":"Functions","text":""},{"location":"openapi_first/templates/vet_app/routes/#openapi_first.templates.vet_app.routes.create_appointment","title":"create_appointment","text":"create_appointment(\n payload: AppointmentCreate, response: Response\n)\n
Create an appointment.
"},{"location":"openapi_first/templates/vet_app/routes/#openapi_first.templates.vet_app.routes.create_parent","title":"create_parent","text":"create_parent(payload: ParentCreate, response: Response)\n
Create a parent.
"},{"location":"openapi_first/templates/vet_app/routes/#openapi_first.templates.vet_app.routes.create_parent--parameters","title":"Parameters","text":"payload : ParentCreate Parent data excluding the id field.
"},{"location":"openapi_first/templates/vet_app/routes/#openapi_first.templates.vet_app.routes.create_parent--returns","title":"Returns","text":"Parent The newly created parent.
"},{"location":"openapi_first/templates/vet_app/routes/#openapi_first.templates.vet_app.routes.create_pet","title":"create_pet","text":"create_pet(payload: PetCreate, response: Response)\n
Create a pet.
"},{"location":"openapi_first/templates/vet_app/routes/#openapi_first.templates.vet_app.routes.create_treatment","title":"create_treatment","text":"create_treatment(\n payload: TreatmentCreate, response: Response\n)\n
Add a treatment (admin only).
"},{"location":"openapi_first/templates/vet_app/routes/#openapi_first.templates.vet_app.routes.create_vet","title":"create_vet","text":"create_vet(payload: VetCreate, response: Response)\n
Create a vet.
"},{"location":"openapi_first/templates/vet_app/routes/#openapi_first.templates.vet_app.routes.delete_appointment","title":"delete_appointment","text":"delete_appointment(id: int, response: Response)\n
Delete an existing appointment.
"},{"location":"openapi_first/templates/vet_app/routes/#openapi_first.templates.vet_app.routes.delete_parent","title":"delete_parent","text":"delete_parent(id: int, response: Response)\n
Delete an existing parent.
"},{"location":"openapi_first/templates/vet_app/routes/#openapi_first.templates.vet_app.routes.delete_parent--parameters","title":"Parameters","text":"id : int Identifier of the parent.
"},{"location":"openapi_first/templates/vet_app/routes/#openapi_first.templates.vet_app.routes.delete_parent--raises","title":"Raises","text":"HTTPException 404 if the parent does not exist.
"},{"location":"openapi_first/templates/vet_app/routes/#openapi_first.templates.vet_app.routes.delete_pet","title":"delete_pet","text":"delete_pet(id: int, response: Response)\n
Delete an existing pet.
"},{"location":"openapi_first/templates/vet_app/routes/#openapi_first.templates.vet_app.routes.delete_treatment","title":"delete_treatment","text":"delete_treatment(id: int, response: Response)\n
Delete an existing treatment.
"},{"location":"openapi_first/templates/vet_app/routes/#openapi_first.templates.vet_app.routes.delete_vet","title":"delete_vet","text":"delete_vet(id: int, response: Response)\n
Delete an existing vet.
"},{"location":"openapi_first/templates/vet_app/routes/#openapi_first.templates.vet_app.routes.get_appointment","title":"get_appointment","text":"get_appointment(id: int)\n
Retrieve a single appointment by ID.
"},{"location":"openapi_first/templates/vet_app/routes/#openapi_first.templates.vet_app.routes.get_parent","title":"get_parent","text":"get_parent(id: int)\n
Retrieve a single parent by ID.
"},{"location":"openapi_first/templates/vet_app/routes/#openapi_first.templates.vet_app.routes.get_parent--parameters","title":"Parameters","text":"id : int Identifier of the parent.
"},{"location":"openapi_first/templates/vet_app/routes/#openapi_first.templates.vet_app.routes.get_parent--returns","title":"Returns","text":"Parent The requested parent.
"},{"location":"openapi_first/templates/vet_app/routes/#openapi_first.templates.vet_app.routes.get_parent--raises","title":"Raises","text":"HTTPException 404 if the parent does not exist.
"},{"location":"openapi_first/templates/vet_app/routes/#openapi_first.templates.vet_app.routes.get_pet","title":"get_pet","text":"get_pet(id: int)\n
Retrieve a single pet by ID.
"},{"location":"openapi_first/templates/vet_app/routes/#openapi_first.templates.vet_app.routes.get_treatment","title":"get_treatment","text":"get_treatment(id: int)\n
Retrieve a single treatment by ID.
"},{"location":"openapi_first/templates/vet_app/routes/#openapi_first.templates.vet_app.routes.get_vet","title":"get_vet","text":"get_vet(id: int)\n
Retrieve a single vet by ID.
"},{"location":"openapi_first/templates/vet_app/routes/#openapi_first.templates.vet_app.routes.list_appointments","title":"list_appointments","text":"list_appointments(\n limit: int = 20,\n offset: int = 0,\n date: str = None,\n vet: int = None,\n pet: int = None,\n)\n
List appointments (paginated, filterable).
"},{"location":"openapi_first/templates/vet_app/routes/#openapi_first.templates.vet_app.routes.list_parents","title":"list_parents","text":"list_parents(limit: int = 20, offset: int = 0)\n
List parents (paginated).
"},{"location":"openapi_first/templates/vet_app/routes/#openapi_first.templates.vet_app.routes.list_parents--parameters","title":"Parameters","text":"limit : int Maximum number of records to return. offset : int Number of records to skip.
"},{"location":"openapi_first/templates/vet_app/routes/#openapi_first.templates.vet_app.routes.list_parents--returns","title":"Returns","text":"dict Paginated response with total and items.
"},{"location":"openapi_first/templates/vet_app/routes/#openapi_first.templates.vet_app.routes.list_pets","title":"list_pets","text":"list_pets(limit: int = 20, offset: int = 0)\n
List pets (paginated).
"},{"location":"openapi_first/templates/vet_app/routes/#openapi_first.templates.vet_app.routes.list_treatments","title":"list_treatments","text":"list_treatments()\n
List treatments (catalogue).
"},{"location":"openapi_first/templates/vet_app/routes/#openapi_first.templates.vet_app.routes.list_treatments--returns","title":"Returns","text":"list[Treatment] A list of treatment domain objects.
"},{"location":"openapi_first/templates/vet_app/routes/#openapi_first.templates.vet_app.routes.list_vets","title":"list_vets","text":"list_vets(limit: int = 20, offset: int = 0)\n
List vets (paginated).
"},{"location":"openapi_first/templates/vet_app/routes/#openapi_first.templates.vet_app.routes.stream_actions","title":"stream_actions async","text":"stream_actions(id: int)\n
Stream animal actions via SSE, scoped to a pet's species.
"},{"location":"openapi_first/templates/vet_app/routes/#openapi_first.templates.vet_app.routes.update_appointment","title":"update_appointment","text":"update_appointment(id: int, payload: AppointmentCreate)\n
Update an existing appointment.
"},{"location":"openapi_first/templates/vet_app/routes/#openapi_first.templates.vet_app.routes.update_parent","title":"update_parent","text":"update_parent(id: int, payload: ParentCreate)\n
Update an existing parent.
"},{"location":"openapi_first/templates/vet_app/routes/#openapi_first.templates.vet_app.routes.update_parent--parameters","title":"Parameters","text":"id : int Identifier of the parent. payload : ParentCreate Updated parent data.
"},{"location":"openapi_first/templates/vet_app/routes/#openapi_first.templates.vet_app.routes.update_parent--returns","title":"Returns","text":"Parent The updated parent.
"},{"location":"openapi_first/templates/vet_app/routes/#openapi_first.templates.vet_app.routes.update_parent--raises","title":"Raises","text":"HTTPException 404 if the parent does not exist.
"},{"location":"openapi_first/templates/vet_app/routes/#openapi_first.templates.vet_app.routes.update_pet","title":"update_pet","text":"update_pet(id: int, payload: PetCreate)\n
Update an existing pet.
"},{"location":"openapi_first/templates/vet_app/routes/#openapi_first.templates.vet_app.routes.update_treatment","title":"update_treatment","text":"update_treatment(id: int, payload: TreatmentCreate)\n
Update an existing treatment.
"},{"location":"openapi_first/templates/vet_app/routes/#openapi_first.templates.vet_app.routes.update_vet","title":"update_vet","text":"update_vet(id: int, payload: VetCreate)\n
Update an existing vet.
"},{"location":"openapi_first/templates/vet_app/routes/#openapi_first.templates.vet_app.routes.upload_pet_photo","title":"upload_pet_photo","text":"upload_pet_photo(id: int, file: UploadFile)\n
Upload a pet photo.
"},{"location":"openapi_first/templates/vet_app/routes/#openapi_first.templates.vet_app.routes.upload_pet_photo--parameters","title":"Parameters","text":"id : int Identifier of the pet. file : UploadFile Image file to upload.
"},{"location":"openapi_first/templates/vet_app/routes/#openapi_first.templates.vet_app.routes.upload_pet_photo--returns","title":"Returns","text":"dict A confirmation with the pet ID.
"},{"location":"openapi_first/templates/vet_app/sse/","title":"Sse","text":""},{"location":"openapi_first/templates/vet_app/sse/#openapi_first.templates.vet_app.sse","title":"openapi_first.templates.vet_app.sse","text":""},{"location":"openapi_first/templates/vet_app/test_vet_app/","title":"Test Vet App","text":""},{"location":"openapi_first/templates/vet_app/test_vet_app/#openapi_first.templates.vet_app.test_vet_app","title":"openapi_first.templates.vet_app.test_vet_app","text":"End-to-end tests for the OpenAPI-first Veterinary Clinic example app.
These tests validate that all CRUD operations behave correctly against the in-memory mock data store using Pydantic models.
"},{"location":"openapi_first/templates/vet_app/test_vet_app/#openapi_first.templates.vet_app.test_vet_app-classes","title":"Classes","text":""},{"location":"openapi_first/templates/vet_app/test_vet_app/#openapi_first.templates.vet_app.test_vet_app-functions","title":"Functions","text":""},{"location":"openapi_first/templates/vet_app/test_vet_app/#openapi_first.templates.vet_app.test_vet_app.test_create_parent","title":"test_create_parent","text":"test_create_parent()\n
Creating a parent returns 201 with the created entity.
"},{"location":"openapi_first/templates/vet_app/test_vet_app/#openapi_first.templates.vet_app.test_vet_app.test_create_pet","title":"test_create_pet","text":"test_create_pet()\n
Creating a pet links FK references.
"},{"location":"openapi_first/templates/vet_app/test_vet_app/#openapi_first.templates.vet_app.test_vet_app.test_create_treatment","title":"test_create_treatment","text":"test_create_treatment()\n
Creating a treatment returns 201.
"},{"location":"openapi_first/templates/vet_app/test_vet_app/#openapi_first.templates.vet_app.test_vet_app.test_create_vet","title":"test_create_vet","text":"test_create_vet()\n
Creating a vet returns 201.
"},{"location":"openapi_first/templates/vet_app/test_vet_app/#openapi_first.templates.vet_app.test_vet_app.test_delete_parent","title":"test_delete_parent","text":"test_delete_parent()\n
Delete parent returns 204 and removes the entity.
"},{"location":"openapi_first/templates/vet_app/test_vet_app/#openapi_first.templates.vet_app.test_vet_app.test_full_appointment_lifecycle","title":"test_full_appointment_lifecycle","text":"test_full_appointment_lifecycle()\n
Create a parent, vet, treatment, pet, then an appointment.
"},{"location":"openapi_first/templates/vet_app/test_vet_app/#openapi_first.templates.vet_app.test_vet_app.test_get_parent","title":"test_get_parent","text":"test_get_parent()\n
Get parent by ID returns the entity.
"},{"location":"openapi_first/templates/vet_app/test_vet_app/#openapi_first.templates.vet_app.test_vet_app.test_list_appointments","title":"test_list_appointments","text":"test_list_appointments()\n
List appointments returns paginated response with filter params.
"},{"location":"openapi_first/templates/vet_app/test_vet_app/#openapi_first.templates.vet_app.test_vet_app.test_list_parents","title":"test_list_parents","text":"test_list_parents()\n
List parents returns paginated response.
"},{"location":"openapi_first/templates/vet_app/test_vet_app/#openapi_first.templates.vet_app.test_vet_app.test_list_treatments","title":"test_list_treatments","text":"test_list_treatments()\n
List treatments returns an array.
"},{"location":"openapi_first/templates/vet_app/test_vet_app/#openapi_first.templates.vet_app.test_vet_app.test_list_vets","title":"test_list_vets","text":"test_list_vets()\n
List vets returns paginated response.
"},{"location":"openapi_first/templates/vet_app/test_vet_app/#openapi_first.templates.vet_app.test_vet_app.test_update_parent","title":"test_update_parent","text":"test_update_parent()\n
Update parent replaces its values.
"},{"location":"openapi_first/templates/vet_app/test_vet_app/#openapi_first.templates.vet_app.test_vet_app.test_upload_pet_photo","title":"test_upload_pet_photo","text":"test_upload_pet_photo()\n
Upload pet photo returns 200.
"}]}
\ No newline at end of file