mail-intake/mcp_docs/modules/mail_intake.parsers.json

{
  "module": "mail_intake.parsers",
  "content": {
    "path": "mail_intake.parsers",
    "docstring": "Message parsing utilities for Mail Intake.\n\nThis package contains **provider-aware but adapter-agnostic parsing helpers**\nused to extract and normalize structured information from raw mail payloads.\n\nParsers in this package are responsible for:\n- Interpreting provider-native message structures\n- Extracting meaningful fields such as headers, body text, and subjects\n- Normalizing data into consistent internal representations\n\nThis package does not:\n- Perform network or IO operations\n- Contain provider API logic\n- Construct domain models directly\n\nParsing functions are designed to be composable and are orchestrated by the\ningestion layer.",
    "objects": {
      "extract_body": {
        "name": "extract_body",
        "kind": "function",
        "path": "mail_intake.parsers.extract_body",
        "signature": "<bound method Alias.signature of Alias('extract_body', 'mail_intake.parsers.body.extract_body')>",
        "docstring": "Extract the best-effort message body from a Gmail payload.\n\nPriority:\n1. text/plain\n2. text/html (stripped to text)\n3. Single-part body\n4. empty string (if nothing usable found)\n\nArgs:\n    payload: Provider-native message payload dictionary.\n\nReturns:\n    Extracted plain-text message body."
      },
      "parse_headers": {
        "name": "parse_headers",
        "kind": "function",
        "path": "mail_intake.parsers.parse_headers",
        "signature": "<bound method Alias.signature of Alias('parse_headers', 'mail_intake.parsers.headers.parse_headers')>",
        "docstring": "Convert a list of Gmail-style headers into a normalized dict.\n\nProvider payloads (such as Gmail) typically represent headers as a list\nof name/value mappings. This function normalizes them into a\ncase-insensitive dictionary keyed by lowercase header names.\n\nArgs:\n    raw_headers: List of header dictionaries, each containing\n        ``name`` and ``value`` keys.\n\nReturns:\n    Dictionary mapping lowercase header names to stripped values.\n\nExample:\n    Input:\n        [\n            {\"name\": \"From\", \"value\": \"John Doe <john@example.com>\"},\n            {\"name\": \"Subject\", \"value\": \"Re: Interview Update\"},\n        ]\n\n    Output:\n        {\n            \"from\": \"John Doe <john@example.com>\",\n            \"subject\": \"Re: Interview Update\",\n        }"
      },
      "extract_sender": {
        "name": "extract_sender",
        "kind": "function",
        "path": "mail_intake.parsers.extract_sender",
        "signature": "<bound method Alias.signature of Alias('extract_sender', 'mail_intake.parsers.headers.extract_sender')>",
        "docstring": "Extract sender email and optional display name from headers.\n\nThis function parses the ``From`` header and attempts to extract:\n- Sender email address\n- Optional human-readable display name\n\nArgs:\n    headers: Normalized header dictionary as returned by\n        :func:`parse_headers`.\n\nReturns:\n    A tuple ``(email, name)`` where:\n    - ``email`` is the sender email address\n    - ``name`` is the display name, or ``None`` if unavailable\n\nExamples:\n    ``\"John Doe <john@example.com>\"`` → ``(\"john@example.com\", \"John Doe\")``\n    ``\"john@example.com\"`` → ``(\"john@example.com\", None)``"
      },
      "normalize_subject": {
        "name": "normalize_subject",
        "kind": "function",
        "path": "mail_intake.parsers.normalize_subject",
        "signature": "<bound method Alias.signature of Alias('normalize_subject', 'mail_intake.parsers.subject.normalize_subject')>",
        "docstring": "Normalize an email subject for thread-level comparison.\n\nOperations:\n- Strips common prefixes such as ``Re:``, ``Fwd:``, and ``FW:``\n- Repeats prefix stripping to handle stacked prefixes\n- Collapses excessive whitespace\n- Preserves original casing (no lowercasing)\n\nThis function is intentionally conservative and avoids aggressive\ntransformations that could alter the semantic meaning of the subject.\n\nArgs:\n    subject: Raw subject line from a message header.\n\nReturns:\n    Normalized subject string suitable for thread grouping."
      },
      "body": {
        "name": "body",
        "kind": "module",
        "path": "mail_intake.parsers.body",
        "signature": null,
        "docstring": "Message body extraction utilities for Mail Intake.\n\nThis module contains helper functions for extracting a best-effort\nplain-text body from provider-native message payloads.\n\nThe logic is intentionally tolerant of malformed or partial data and\nprefers human-readable text over fidelity to original formatting.",
        "members": {
          "base64": {
            "name": "base64",
            "kind": "alias",
            "path": "mail_intake.parsers.body.base64",
            "signature": "<bound method Alias.signature of Alias('base64', 'base64')>",
            "docstring": null
          },
          "Dict": {
            "name": "Dict",
            "kind": "alias",
            "path": "mail_intake.parsers.body.Dict",
            "signature": "<bound method Alias.signature of Alias('Dict', 'typing.Dict')>",
            "docstring": null
          },
          "Any": {
            "name": "Any",
            "kind": "alias",
            "path": "mail_intake.parsers.body.Any",
            "signature": "<bound method Alias.signature of Alias('Any', 'typing.Any')>",
            "docstring": null
          },
          "Optional": {
            "name": "Optional",
            "kind": "alias",
            "path": "mail_intake.parsers.body.Optional",
            "signature": "<bound method Alias.signature of Alias('Optional', 'typing.Optional')>",
            "docstring": null
          },
          "BeautifulSoup": {
            "name": "BeautifulSoup",
            "kind": "alias",
            "path": "mail_intake.parsers.body.BeautifulSoup",
            "signature": "<bound method Alias.signature of Alias('BeautifulSoup', 'bs4.BeautifulSoup')>",
            "docstring": null
          },
          "MailIntakeParsingError": {
            "name": "MailIntakeParsingError",
            "kind": "class",
            "path": "mail_intake.parsers.body.MailIntakeParsingError",
            "signature": "<bound method Alias.signature of Alias('MailIntakeParsingError', 'mail_intake.exceptions.MailIntakeParsingError')>",
            "docstring": "Errors encountered while parsing message content.\n\nRaised when raw provider payloads cannot be interpreted\nor normalized into internal domain models."
          },
          "extract_body": {
            "name": "extract_body",
            "kind": "function",
            "path": "mail_intake.parsers.body.extract_body",
            "signature": "<bound method Function.signature of Function('extract_body', 77, 122)>",
            "docstring": "Extract the best-effort message body from a Gmail payload.\n\nPriority:\n1. text/plain\n2. text/html (stripped to text)\n3. Single-part body\n4. empty string (if nothing usable found)\n\nArgs:\n    payload: Provider-native message payload dictionary.\n\nReturns:\n    Extracted plain-text message body."
          }
        }
      },
      "headers": {
        "name": "headers",
        "kind": "module",
        "path": "mail_intake.parsers.headers",
        "signature": null,
        "docstring": "Message header parsing utilities for Mail Intake.\n\nThis module provides helper functions for normalizing and extracting\nuseful information from provider-native message headers.\n\nThe functions here are intentionally simple and tolerant of malformed\nor incomplete header data.",
        "members": {
          "Dict": {
            "name": "Dict",
            "kind": "alias",
            "path": "mail_intake.parsers.headers.Dict",
            "signature": "<bound method Alias.signature of Alias('Dict', 'typing.Dict')>",
            "docstring": null
          },
          "List": {
            "name": "List",
            "kind": "alias",
            "path": "mail_intake.parsers.headers.List",
            "signature": "<bound method Alias.signature of Alias('List', 'typing.List')>",
            "docstring": null
          },
          "Tuple": {
            "name": "Tuple",
            "kind": "alias",
            "path": "mail_intake.parsers.headers.Tuple",
            "signature": "<bound method Alias.signature of Alias('Tuple', 'typing.Tuple')>",
            "docstring": null
          },
          "Optional": {
            "name": "Optional",
            "kind": "alias",
            "path": "mail_intake.parsers.headers.Optional",
            "signature": "<bound method Alias.signature of Alias('Optional', 'typing.Optional')>",
            "docstring": null
          },
          "parse_headers": {
            "name": "parse_headers",
            "kind": "function",
            "path": "mail_intake.parsers.headers.parse_headers",
            "signature": "<bound method Function.signature of Function('parse_headers', 14, 53)>",
            "docstring": "Convert a list of Gmail-style headers into a normalized dict.\n\nProvider payloads (such as Gmail) typically represent headers as a list\nof name/value mappings. This function normalizes them into a\ncase-insensitive dictionary keyed by lowercase header names.\n\nArgs:\n    raw_headers: List of header dictionaries, each containing\n        ``name`` and ``value`` keys.\n\nReturns:\n    Dictionary mapping lowercase header names to stripped values.\n\nExample:\n    Input:\n        [\n            {\"name\": \"From\", \"value\": \"John Doe <john@example.com>\"},\n            {\"name\": \"Subject\", \"value\": \"Re: Interview Update\"},\n        ]\n\n    Output:\n        {\n            \"from\": \"John Doe <john@example.com>\",\n            \"subject\": \"Re: Interview Update\",\n        }"
          },
          "extract_sender": {
            "name": "extract_sender",
            "kind": "function",
            "path": "mail_intake.parsers.headers.extract_sender",
            "signature": "<bound method Function.signature of Function('extract_sender', 56, 87)>",
            "docstring": "Extract sender email and optional display name from headers.\n\nThis function parses the ``From`` header and attempts to extract:\n- Sender email address\n- Optional human-readable display name\n\nArgs:\n    headers: Normalized header dictionary as returned by\n        :func:`parse_headers`.\n\nReturns:\n    A tuple ``(email, name)`` where:\n    - ``email`` is the sender email address\n    - ``name`` is the display name, or ``None`` if unavailable\n\nExamples:\n    ``\"John Doe <john@example.com>\"`` → ``(\"john@example.com\", \"John Doe\")``\n    ``\"john@example.com\"`` → ``(\"john@example.com\", None)``"
          }
        }
      },
      "subject": {
        "name": "subject",
        "kind": "module",
        "path": "mail_intake.parsers.subject",
        "signature": null,
        "docstring": "Subject line normalization utilities for Mail Intake.\n\nThis module provides helper functions for normalizing email subject lines\nto enable reliable thread-level comparison and grouping.\n\nNormalization is intentionally conservative to avoid altering semantic\nmeaning while removing common reply and forward prefixes.",
        "members": {
          "re": {
            "name": "re",
            "kind": "alias",
            "path": "mail_intake.parsers.subject.re",
            "signature": "<bound method Alias.signature of Alias('re', 're')>",
            "docstring": null
          },
          "normalize_subject": {
            "name": "normalize_subject",
            "kind": "function",
            "path": "mail_intake.parsers.subject.normalize_subject",
            "signature": "<bound method Function.signature of Function('normalize_subject', 18, 52)>",
            "docstring": "Normalize an email subject for thread-level comparison.\n\nOperations:\n- Strips common prefixes such as ``Re:``, ``Fwd:``, and ``FW:``\n- Repeats prefix stripping to handle stacked prefixes\n- Collapses excessive whitespace\n- Preserves original casing (no lowercasing)\n\nThis function is intentionally conservative and avoids aggressive\ntransformations that could alter the semantic meaning of the subject.\n\nArgs:\n    subject: Raw subject line from a message header.\n\nReturns:\n    Normalized subject string suitable for thread grouping."
          }
        }
      }
    }
  }
}