email-forward-parser 0.1.3__tar.gz → 0.2.0__tar.gz

email_forward_parser-0.2.0/.github/workflows/ci.yml

@@ -0,0 +1,36 @@
+name: CI
+
+on:
+  pull_request:
+  push:
+
+permissions:
+  contents: read
+
+concurrency:
+  group: ci-${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  verify:
+    runs-on: ubuntu-latest
+    timeout-minutes: 30
+    steps:
+      - uses: actions/checkout@v7
+      - name: Install uv and Python
+        uses: astral-sh/setup-uv@v10.0.1
+        with:
+          python-version: "3.14"
+          enable-cache: true
+      - name: Install locked dependencies
+        run: uv sync --frozen
+      - name: Check formatting
+        run: |
+          uv run black --check .
+          uv run isort --check-only .
+      - name: Lint
+        run: uv run ruff check .
+      - name: Type check
+        run: uv run mypy
+      - name: Test with configured coverage gate
+        run: uv run pytest

{email_forward_parser-0.1.3 → email_forward_parser-0.2.0}/.github/workflows/workflow.yml

@@ -4,24 +4,44 @@ on:
   push:
     tags:
       - "v*"
-  workflow_dispatch:
 
 permissions:
   contents: read
 
 jobs:
+  verify:
+    name: Verify package
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v7
+      - uses: astral-sh/setup-uv@v10.0.1
+        with:
+          python-version: "3.14"
+          enable-cache: true
+      - run: uv sync --frozen
+      - name: Verify tag matches package version
+        run: |
+          PACKAGE_VERSION=$(python -c 'import tomllib; print(tomllib.load(open("pyproject.toml", "rb"))["project"]["version"])')
+          test "v${PACKAGE_VERSION}" = "${GITHUB_REF_NAME}"
+      - run: uv run black --check .
+      - run: uv run isort --check-only .
+      - run: uv run ruff check .
+      - run: uv run mypy
+      - run: uv run pytest
+
   build:
     name: Build distribution
+    needs: verify
     runs-on: ubuntu-latest
 
     steps:
       - name: Checkout
-        uses: actions/checkout@v6
+        uses: actions/checkout@v7
 
       - name: Set up Python
-        uses: actions/setup-python@v6
+        uses: actions/setup-python@v7
         with:
-          python-version: "3.12"
+          python-version: "3.14"
 
       - name: Install tools
         run: python -m pip install --upgrade build twine

{email_forward_parser-0.1.3 → email_forward_parser-0.2.0}/PKG-INFO

@@ -1,6 +1,6 @@
-Metadata-Version: 2.4
+Metadata-Version: 2.5
 Name: email-forward-parser
-Version: 0.1.3
+Version: 0.2.0
 Summary: Python Library to parse forwarded email messages
 Project-URL: Homepage, https://github.com/felipehertzer/email-forward-parser-py
 Project-URL: Repository, https://github.com/felipehertzer/email-forward-parser-py
@@ -212,22 +212,10 @@ Keywords: email,eml,forwarded-email,mime,parser
 Classifier: License :: OSI Approved :: Apache Software License
 Classifier: Operating System :: OS Independent
 Classifier: Programming Language :: Python :: 3
-Classifier: Programming Language :: Python :: 3.10
-Classifier: Programming Language :: Python :: 3.11
-Classifier: Programming Language :: Python :: 3.12
-Classifier: Programming Language :: Python :: 3.13
 Classifier: Programming Language :: Python :: 3.14
 Classifier: Topic :: Communications :: Email
 Classifier: Topic :: Text Processing
-Requires-Python: >=3.10
-Provides-Extra: dev
-Requires-Dist: black>=25; extra == 'dev'
-Requires-Dist: isort>=6; extra == 'dev'
-Requires-Dist: mypy>=1.19; extra == 'dev'
-Requires-Dist: ruff>=0.14; extra == 'dev'
-Provides-Extra: test
-Requires-Dist: pytest-cov>=5; extra == 'test'
-Requires-Dist: pytest>=8; extra == 'test'
+Requires-Python: >=3.14
 Description-Content-Type: text/markdown
 
 # email-forward-parser-py
@@ -250,7 +238,7 @@ need to recover the original sender, recipients, subject, sent date, and body.
   `.eml` attachments.
 - Rebuilds an `.eml` string for the original message when a forwarded email is
   detected.
-- Ships with a 100% statement coverage gate.
+- Ships with a 100% statement and branch coverage gate.
 
 ## Installation
 
@@ -258,7 +246,7 @@ need to recover the original sender, recipients, subject, sent date, and body.
 python -m pip install email-forward-parser
 ```
 
-Python 3.10 or newer is required.
+Python 3.14 or newer is required.
 
 The distribution name is `email-forward-parser`, but the import package is
 `emailforwardparser`:
@@ -536,7 +524,7 @@ python -m mypy
 python -m pytest
 ```
 
-`pytest` is configured to require 100% statement coverage.
+`pytest` is configured to require 100% statement and branch coverage.
 
 ## Release
 

{email_forward_parser-0.1.3 → email_forward_parser-0.2.0}/README.md

@@ -18,7 +18,7 @@ need to recover the original sender, recipients, subject, sent date, and body.
   `.eml` attachments.
 - Rebuilds an `.eml` string for the original message when a forwarded email is
   detected.
-- Ships with a 100% statement coverage gate.
+- Ships with a 100% statement and branch coverage gate.
 
 ## Installation
 
@@ -26,7 +26,7 @@ need to recover the original sender, recipients, subject, sent date, and body.
 python -m pip install email-forward-parser
 ```
 
-Python 3.10 or newer is required.
+Python 3.14 or newer is required.
 
 The distribution name is `email-forward-parser`, but the import package is
 `emailforwardparser`:
@@ -304,7 +304,7 @@ python -m mypy
 python -m pytest
 ```
 
-`pytest` is configured to require 100% statement coverage.
+`pytest` is configured to require 100% statement and branch coverage.
 
 ## Release
 

{email_forward_parser-0.1.3 → email_forward_parser-0.2.0}/emailforwardparser/client.py

@@ -1,6 +1,7 @@
 from __future__ import annotations
 
 import base64
+import binascii
 import logging
 from email import policy
 from email.message import EmailMessage, Message
@@ -8,11 +9,16 @@ from email.mime.multipart import MIMEMultipart
 from email.mime.text import MIMEText
 from email.parser import Parser
 from email.utils import formataddr, getaddresses
-from typing import Any
+from typing import TypedDict
 
 from emailforwardparser import forward_parser as fp
 
-log = logging.getLogger("emailforwardparser")
+ParsedEmail = TypedDict(
+    "ParsedEmail",
+    {"forward": bool, "eml": str, "Send-To": str},
+)
+
+LOGGER = logging.getLogger(__name__)
 
 
 class EmailParserClient:
@@ -20,7 +26,7 @@ class EmailParserClient:
     A client for parsing email messages, with support for detecting and handling forwarded emails.
     """
 
-    def get_original_eml(self, email: str) -> dict:
+    def get_original_eml(self, email: str) -> ParsedEmail:
         """
         Retrieve the original email message as a dict, including metadata and content.
 
@@ -41,7 +47,7 @@ class EmailParserClient:
             msg, original_metadata.email, original_metadata.forwarded, send_to=send_to
         )
 
-    def get_original_eml_from_file(self, file_path: str) -> dict:
+    def get_original_eml_from_file(self, file_path: str) -> ParsedEmail:
         """
         Retrieve the original email message, including metadata and content.
 
@@ -94,21 +100,15 @@ class EmailParserClient:
 
     def _get_dict(
         self, message: Message | str, email: fp.OriginalMetadata, forwarded: bool, send_to: str = ""
-    ) -> dict:
-        result: dict[str, Any] = {}
-        result["forward"] = forwarded
+    ) -> ParsedEmail:
         if forwarded:
             source_message = (
                 message if isinstance(message, Message) else self._parse_message(message)
             )
-            result["eml"] = self._build_original_email(email, source_message).as_string()
+            eml = self._build_original_email(email, source_message).as_string()
         else:
-            if isinstance(message, Message):
-                result["eml"] = message.as_string()
-            else:
-                result["eml"] = message
-        result["Send-To"] = send_to
-        return result
+            eml = message.as_string() if isinstance(message, Message) else message
+        return {"forward": forwarded, "eml": eml, "Send-To": send_to}
 
     def _build_original_email(
         self, metadata: fp.OriginalMetadata, message: Message
@@ -124,16 +124,20 @@ class EmailParserClient:
 
         mt = MIMEText(metadata.body or "", _subtype="plain", _charset="utf-8")
         result.attach(mt)
-        payload = message.get_payload()
-        if isinstance(payload, list):
-            for part in payload:
+        raw_payload = message.get_payload()
+        if isinstance(raw_payload, list):
+            pending = list(raw_payload)
+            while pending:
+                part = pending.pop(0)
                 if isinstance(part, str) or (
                     part.get_content_type() == "text/plain"
                     and "attachment" not in str(part.get("Content-Disposition"))
                 ):
                     continue
                 if part.get_content_subtype() in ["related", "alternative"]:
-                    payload.extend(part.get_payload())
+                    nested_payload = part.get_payload()
+                    if isinstance(nested_payload, list):
+                        pending.extend(nested_payload)
                     continue
                 if part.get_content_type() == "text/html":
                     part.set_payload(part.get_payload())
@@ -142,17 +146,22 @@ class EmailParserClient:
 
     def _set_headers(self, metadata: fp.OriginalMetadata, result: EmailMessage | Message) -> None:
         if metadata.date:
-            result["Date"] = metadata.date
+            result["Date"] = self._header_value(metadata.date)
         from_header = self._format_addresses([metadata.from_])
         if from_header:
-            result["From"] = from_header
+            result["From"] = self._header_value(from_header)
         if metadata.subject:
-            result["Subject"] = metadata.subject
+            result["Subject"] = self._header_value(metadata.subject)
         to_header = self._format_addresses(metadata.to)
         if to_header:
-            result["To"] = to_header
+            result["To"] = self._header_value(to_header)
         if metadata.cc:
-            result["CC"] = self._format_addresses(metadata.cc)
+            result["CC"] = self._header_value(self._format_addresses(metadata.cc))
+
+    def _header_value(self, value: str) -> str:
+        # Parsed values come from message text, which may hold any Unicode line
+        # break (for example U+2028); a header value must be a single line.
+        return " ".join(value.splitlines())
 
     def _format_addresses(self, contacts: list[fp.MailboxResult]) -> str:
         addresses = []
@@ -189,7 +198,7 @@ class EmailParserClient:
     def _get_eml_attachment(self, message: Message) -> str:
         for part in message.walk():
             content_type = part.get_content_type()
-            if content_type is not None and content_type == "message/rfc822":
+            if content_type == "message/rfc822":
                 try:
                     payload = part.get_payload()
                     if isinstance(payload, list) and payload:
@@ -203,10 +212,10 @@ class EmailParserClient:
                         content = get_content()
                         if isinstance(content, Message):
                             return content.as_string()
-                except Exception:
-                    log.warning("failed to get attached eml, looking for others")
+                except LookupError, TypeError, ValueError:
+                    LOGGER.warning("attached_eml_decode_failed")
                     continue
-            if content_type is not None and content_type == "application/octet-stream":
+            if content_type == "application/octet-stream":
                 file_name = part.get_filename()
                 if file_name and file_name.lower().endswith(".eml"):
                     payload = part.get_payload(decode=True)
@@ -217,7 +226,7 @@ class EmailParserClient:
         return ""
 
     def _get_file_content(self, file_path: str) -> str:
-        with open(file_path, "r", encoding="utf8") as file:
+        with open(file_path, encoding="utf8") as file:
             return file.read()
 
     def _parse_message(self, email: str) -> Message:
@@ -258,8 +267,8 @@ class EmailParserClient:
                     return content
                 if isinstance(content, bytes):
                     return self._decode_bytes(content, part.get_content_charset())
-            except Exception:
-                log.warning("failed to decode message part with email policy", exc_info=True)
+            except LookupError, TypeError, ValueError:
+                LOGGER.warning("message_part_decode_failed", exc_info=True)
 
         payload = part.get_payload(decode=True)
         if isinstance(payload, bytes):
@@ -271,20 +280,20 @@ class EmailParserClient:
         return payload if isinstance(payload, str) else ""
 
     def _decode_bytes(self, payload: bytes, charset: str | None = None) -> str:
-        return payload.decode(charset or "utf-8", errors="replace")
+        try:
+            return payload.decode(charset or "utf-8", errors="replace")
+        except LookupError, UnicodeError:
+            # The sender declared a charset Python does not know (for example
+            # "unknown-8bit") or a codec that is not a text encoding.
+            return payload.decode("utf-8", errors="replace")
 
     def get_decoded_str(self, s: str | bytes | None, charset: str | None = None) -> str:
         if s is None:
             return ""
         if isinstance(s, bytes):
             return self._decode_bytes(s, charset)
-        if not isinstance(s, str):
-            return ""
-
         compact = "".join(s.split())
         try:
-            return base64.b64decode(compact, validate=True).decode(
-                charset or "utf-8", errors="replace"
-            )
-        except Exception:
+            return self._decode_bytes(base64.b64decode(compact, validate=True), charset)
+        except binascii.Error, ValueError:
             return s

{email_forward_parser-0.1.3 → email_forward_parser-0.2.0}/emailforwardparser/forward_parser.py

@@ -6,7 +6,7 @@ from re import Pattern
 from emailforwardparser import loop, regexs, utils
 
 
-@dataclass
+@dataclass(slots=True)
 class MailboxResult:
     """Class storing the name and address of a mailbox."""
 
@@ -14,7 +14,7 @@ class MailboxResult:
     address: str = ""
 
 
-@dataclass
+@dataclass(slots=True)
 class ParseBodyResult:
     """Class storing metadata of parsed forwarded email."""
 
@@ -23,7 +23,7 @@ class ParseBodyResult:
     email: str = ""
 
 
-@dataclass
+@dataclass(slots=True)
 class OriginalMetadata:
     """Class storing metadata of original content in forwarded message."""
 
@@ -35,7 +35,7 @@ class OriginalMetadata:
     cc: list[MailboxResult] = field(default_factory=list)
 
 
-@dataclass
+@dataclass(slots=True)
 class ForwardMetadata:
     """Result object storing forwarded email metadata."""
 
@@ -67,7 +67,10 @@ def parse_body(body: str, forwarded: bool) -> ParseBodyResult:
     if forwarded:
         match = loop.loop_regexes_split(regexs.ORIGINAL_FROM, body, True)
         if len(match) > 2:
-            email = "".join(match[i] for i in [1, 3])
+            # match[1] is the whole From line and match[3] the text after it. The
+            # split omits an empty trailing piece, so a body that ends on the From
+            # line has no match[3].
+            email = match[1] + (match[3] if len(match) > 3 else "")
             return ParseBodyResult(body=body, message=match[0].strip(), email=email.strip())
     return ParseBodyResult()
 
@@ -82,7 +85,10 @@ def parse_original_body(text: str) -> str:
 
     for regex in regexes:
         match = loop.loop_regexes_split(regex, text, True)
-        if len(match) > 3 and match[3].startswith("\n\n"):
+        # match[3] is the text after the header line, or, when the header occurs
+        # again (len(match) > 4), the gap before that next occurrence. Blank lines
+        # alone between two occurrences are not a body.
+        if len(match) > 3 and match[3].startswith("\n\n") and (len(match) == 4 or match[3].strip()):
             body = match[3]
             return body.strip()
     match = loop.loop_regexes_split(
@@ -122,8 +128,20 @@ def parse_original_from(text: str, body: str) -> MailboxResult:
 
     if authors:
         author = authors[0]
-        if author.name or author.address:
+        if author.address:
             return author
+        if author.name:
+            # Some clients (e.g. Gmail) wrap a long "From:" line right after the "<",
+            # leaving the address on the next line. Rejoin such lines and retry before
+            # settling for a name without an address.
+            for candidate in (text, body):
+                joined = regexs.WRAPPED_ADDRESS_BRACKET.sub(r"\1", candidate)
+                if joined == candidate:
+                    continue
+                retry = parse_mailbox(regexs.ORIGINAL_FROM, joined)
+                if retry and retry[0].address:
+                    return retry[0]
+            return MailboxResult(author.name.rstrip("<[ ").strip(), "")
 
     match, pattern = loop.loop_regexes_match(regexs.SEPARATOR_WITH_INFORMATION, body)
     if len(match) == 4 and pattern is not None:
@@ -201,7 +219,7 @@ def parse_original_date(text: str, body: str) -> str:
     return ""
 
 
-def parse_mailbox(regexes: list[Pattern], text: str) -> list[MailboxResult]:
+def parse_mailbox(regexes: list[Pattern[str]], text: str) -> list[MailboxResult]:
     match, _ = loop.loop_regexes_match(regexes, text)
     if match:
         mailboxes_line = match[-1].strip()

{email_forward_parser-0.1.3 → email_forward_parser-0.2.0}/emailforwardparser/loop.py

@@ -1,5 +1,5 @@
+from collections.abc import Sequence
 from re import Match, Pattern
-from typing import Sequence
 
 from .utils import split_with_regexp
 
@@ -48,9 +48,11 @@ def loop_regexes_match(
             match = current_match
             match_index = current_match_index
             regex_matched = regex
+            if match_index == 0:
+                # No later regex can match earlier, and ties keep the first one.
+                break
 
     # Convert match from None to an empty list if no match is found
     if match is None:
         return [], regex_matched
-    else:
-        return [match.group(0), *[group or "" for group in match.groups()]], regex_matched
+    return [match.group(0), *[group or "" for group in match.groups()]], regex_matched