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

email_forward_parser-0.2.1/.githooks/pre-push

@@ -0,0 +1,93 @@
+#!/bin/sh
+# Style and type checks on the commits being pushed; GitHub Actions runs the tests.
+# Turn it on once per clone: git config core.hooksPath .githooks
+
+fix='uv run black . && uv run isort . && uv run ruff check --fix .'
+
+# The same install as CI's "Install locked dependencies".
+setup() {
+    uv sync --frozen || return
+}
+
+checks() {
+    check uv run black --check .
+    check uv run isort --check-only .
+    check uv run ruff check .
+    check uv run mypy
+}
+
+# --- the same in every repo from here ---
+
+set -u
+unset GIT_DIR GIT_WORK_TREE GIT_INDEX_FILE
+common=$(cd "$(git rev-parse --git-common-dir)" && pwd)
+checked="$common/pre-push-checked"
+# A commit passes for this version of the hook: changing the checks checks it again.
+version=$(cksum <"$0" | cut -d' ' -f1)
+# One checkout per clone, kept between pushes so its dependencies and tool caches stay installed.
+cache="${XDG_CACHE_HOME:-$HOME/.cache}/pre-push"
+dir="$cache/$(basename "$(dirname "$common")")-$(printf %s "$common" | cksum | cut -d' ' -f1)"
+lock="$dir.lock"
+
+# Run one check and carry on, so a push shows every failure at once.
+check() {
+    "$@" || failed=1
+}
+
+# Another push in this clone may be using the checkout: wait for it, or take over a lock its push left behind.
+take_lock() {
+    mkdir -p "$cache"
+    until mkdir "$lock" 2>/dev/null; do
+        owner=$(cat "$lock/pid" 2>/dev/null)
+        if [ -n "$owner" ] && ! kill -0 "$owner" 2>/dev/null; then
+            rm -rf "$lock"
+            continue
+        fi
+        echo "pre-push: waiting for another push's checks to finish" >&2
+        sleep 5
+    done
+    echo $$ >"$lock/pid"
+}
+trap '[ "$(cat "$lock/pid" 2>/dev/null)" = $$ ] && rm -rf "$lock"' EXIT
+trap 'exit 1' INT TERM
+
+# Check out the commit itself, not the working tree: uncommitted files don't go out.
+checkout() {
+    if [ -f "$dir/.git" ] && git -C "$dir" checkout --quiet --force --detach "$1" 2>/dev/null; then
+        git -C "$dir" clean -fdq
+        return
+    fi
+    # First push, or the folder or its registration went missing: start it again.
+    rm -rf "$dir"
+    git worktree add --quiet --force --detach "$dir" "$1"
+}
+
+status=0
+while read -r _ sha _ _; do
+    # A deleted ref sends all zeros, which isn't a commit.
+    commit=$(git rev-parse --verify --quiet "$sha^{commit}") || continue
+    # Pushing the same commit to the next remote doesn't check it again.
+    grep -qsx "$commit $version" "$checked" && continue
+
+    [ -d "$lock" ] && [ "$(cat "$lock/pid" 2>/dev/null)" = $$ ] || take_lock
+    short=$(git rev-parse --short "$commit")
+    if ! checkout "$commit"; then
+        echo "pre-push: couldn't check out $short in $dir" >&2
+        status=1
+        continue
+    fi
+    if ! (cd "$dir" && setup) </dev/null >&2; then
+        echo "pre-push: installing the dependencies of $short failed" >&2
+        status=1
+        continue
+    fi
+    if (cd "$dir" && failed=0 && checks && exit $failed) </dev/null; then
+        echo "$commit $version" >>"$checked"
+    else
+        echo >&2
+        echo "pre-push: checks failed on $short. Style fixes itself with: $fix" >&2
+        echo "pre-push: type errors need a code change. Commit the fix and push again (git push --no-verify skips the checks)." >&2
+        status=1
+    fi
+done
+exit $status

{email_forward_parser-0.1.3 → email_forward_parser-0.2.1}/.github/dependabot.yml

@@ -12,8 +12,14 @@ updates:
       - "dependencies"
       - "python"
 
+  # The actions in .github/workflows are pinned to commit SHAs; this keeps the SHAs and their version comments
+  # current, in one pull request a week.
   - package-ecosystem: "github-actions"
     directory: "/"
+    groups:
+      github-actions:
+        patterns:
+          - "*"
     schedule:
       interval: "weekly"
       day: "monday"

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

@@ -0,0 +1,31 @@
+name: CI
+
+on:
+  pull_request:
+  push:
+
+permissions:
+  contents: read
+
+concurrency:
+  group: ci-${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+# Style and type checks run before each push, in .githooks/pre-push; this workflow runs the rest.
+# Runners are pinned to ubuntu-24.04 (ubuntu-latest moves to Ubuntu 26 from 2026-10-19) and actions to commit
+# SHAs, which Dependabot keeps current.
+jobs:
+  verify:
+    runs-on: ubuntu-24.04
+    timeout-minutes: 30
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+      - name: Install uv and Python
+        uses: astral-sh/setup-uv@1c37ad07a6a961277cf70c0d37d6f313000f5884 # v10.3.0
+        with:
+          python-version: "3.14"
+          enable-cache: true
+      - name: Install locked dependencies
+        run: uv sync --frozen
+      - name: Test with configured coverage gate
+        run: uv run pytest

email_forward_parser-0.2.1/.github/workflows/workflow.yml

@@ -0,0 +1,104 @@
+name: Publish to PyPI
+
+on:
+  push:
+    tags:
+      - "v*"
+
+permissions:
+  contents: read
+
+jobs:
+  verify:
+    name: Verify package
+    runs-on: ubuntu-24.04
+    timeout-minutes: 30
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+      - name: Install uv and Python
+        uses: astral-sh/setup-uv@1c37ad07a6a961277cf70c0d37d6f313000f5884 # v10.3.0
+        with:
+          python-version: "3.14"
+          enable-cache: true
+      - name: Install locked dependencies
+        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}"
+      - name: Test with configured coverage gate
+        run: uv run pytest
+
+  build:
+    name: Build distribution
+    needs: verify
+    runs-on: ubuntu-24.04
+    timeout-minutes: 10
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+
+      - name: Set up Python
+        uses: actions/setup-python@5fda3b95a4ea91299a34e894583c3862153e4b97 # v7.0.0
+        with:
+          python-version: "3.14"
+
+      - name: Install tools
+        run: python -m pip install --upgrade build twine
+
+      - name: Build package
+        run: python -m build
+
+      - name: Check package metadata
+        run: python -m twine check dist/*
+
+      - name: Upload distribution artifacts
+        uses: actions/upload-artifact@cf430e030ddbb5b0abf93d22962f4752f3646cd9 # v7.0.2
+        with:
+          name: python-package-distributions
+          path: dist/
+
+  publish:
+    name: Publish distribution to PyPI
+    needs: build
+    runs-on: ubuntu-24.04
+    timeout-minutes: 10
+    environment: pypi
+
+    permissions:
+      contents: read
+      id-token: write
+
+    steps:
+      - name: Download distribution artifacts
+        uses: actions/download-artifact@9000827ccba6bdab643e8b6fd33ac0654aef8333 # v8.0.2
+        with:
+          name: python-package-distributions
+          path: dist/
+
+      - name: Publish package
+        uses: pypa/gh-action-pypi-publish@dc37677b2e1c63e2034f94d8a5b11f265b73ba33 # v1.14.2
+
+  release:
+    name: Publish GitHub release
+    needs: publish
+    if: startsWith(github.ref, 'refs/tags/')
+    runs-on: ubuntu-24.04
+    timeout-minutes: 10
+
+    permissions:
+      contents: write
+
+    steps:
+      - name: Download distribution artifacts
+        uses: actions/download-artifact@9000827ccba6bdab643e8b6fd33ac0654aef8333 # v8.0.2
+        with:
+          name: python-package-distributions
+          path: dist/
+
+      - name: Publish release
+        uses: softprops/action-gh-release@efb35369e0ad2afab669f228072c1b0d510eae64 # v3.0.3
+        with:
+          files: dist/*
+          generate_release_notes: true

{email_forward_parser-0.1.3 → email_forward_parser-0.2.1}/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.1
 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.1}/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.1}/emailforwardparser/client.py

@@ -1,18 +1,26 @@
 from __future__ import annotations
 
 import base64
+import binascii
 import logging
 from email import policy
+from email.errors import HeaderParseError
+from email.header import decode_header, make_header
 from email.message import EmailMessage, Message
 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 +28,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.
 
@@ -32,7 +40,7 @@ class EmailParserClient:
         :rtype: dict
         """
         msg = self._parse_message(email)
-        send_to = self._first_header_address(msg.get("From", ""))
+        send_to = self._first_header_address(self._header(msg, "From"))
         eml = self._get_eml_attachment(msg)
         if eml:
             return self._get_dict(eml, fp.OriginalMetadata(), False, send_to=send_to)
@@ -41,7 +49,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 +102,26 @@ 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 = self._as_string(message) if isinstance(message, Message) else message
+        return {"forward": forwarded, "eml": eml, "Send-To": send_to}
+
+    @staticmethod
+    def _as_string(message: Message) -> str:
+        """The message as text. A header longer than a line is folded again as it is written,
+        which builds its mailboxes again and refuses (ValueError) one whose encoded-word name
+        decodes to a line break: the message is then written with its headers as they came.
+        """
+        try:
+            return message.as_string()
+        except ValueError:
+            return message.as_string(policy=policy.default.clone(refold_source="none"))
 
     def _build_original_email(
         self, metadata: fp.OriginalMetadata, message: Message
@@ -124,16 +137,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 +159,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 = []
@@ -167,8 +189,7 @@ class EmailParserClient:
 
     def _get_forwarded_metadata(self, message: Message) -> fp.ForwardMetadata:
         body = self._get_body(message)
-        subject = message.get("Subject")
-        subject = str(subject) if subject is not None else ""
+        subject = self._header(message, "Subject")
         if subject:
             return fp.get_forwarded_metadata(body.strip(), subject.strip())
         return fp.get_forwarded_metadata(body.strip())
@@ -189,7 +210,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 +224,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,23 +238,46 @@ 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:
         return Parser(policy=policy.default).parsestr(email)
 
     def _get_message_metadata(self, message: Message) -> fp.OriginalMetadata:
-        from_mailboxes = self._mailboxes_from_header(message.get("From", ""))
+        from_mailboxes = self._mailboxes_from_header(self._header(message, "From"))
         return fp.OriginalMetadata(
-            date=str(message.get("Date", "")).strip(),
-            subject=str(message.get("Subject", "")).strip(),
+            date=self._header(message, "Date").strip(),
+            subject=self._header(message, "Subject").strip(),
             body=self._get_body(message).strip(),
             from_=from_mailboxes[0] if from_mailboxes else fp.MailboxResult(),
-            to=self._mailboxes_from_header(message.get("To", "")),
-            cc=self._mailboxes_from_header(message.get("Cc", "")),
+            to=self._mailboxes_from_header(self._header(message, "To")),
+            cc=self._mailboxes_from_header(self._header(message, "Cc")),
         )
 
+    @staticmethod
+    def _header(message: Message, name: str) -> str:
+        """The header's decoded value, or "" when the message has none.
+
+        The email package builds an address header's mailboxes as it reads it, and refuses
+        (ValueError) one whose encoded-word name decodes to a line break, so reading such a
+        From raised out of the parser. Its mailboxes are read from the raw value instead,
+        each name decoded with its line breaks as spaces.
+        """
+        try:
+            value = message.get(name)
+        except ValueError:
+            raw = next(str(raw) for key, raw in message.raw_items() if key.lower() == name.lower())
+            mailboxes = []
+            for encoded_name, address in getaddresses([raw]):
+                try:
+                    decoded = str(make_header(decode_header(encoded_name)))
+                except HeaderParseError, LookupError, UnicodeError:
+                    decoded = encoded_name
+                mailboxes.append(formataddr((" ".join(decoded.split()), address)))
+            return ", ".join(mailboxes)
+        return str(value) if value is not None else ""
+
     def _first_header_address(self, header: object) -> str:
         mailboxes = self._mailboxes_from_header(header)
         if not mailboxes:
@@ -258,8 +302,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 +315,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