gh-151454: Accept Header values in email.message.Message.add_header

[harjothkhara]

email.message.Message.items() returns (name, Header) pairs under the
compat32 policy when a header carries 8-bit data (for example a multi-line
SpamAssassin X-Ham-Report). Assigning such a value back with
msg[name] = value works, but the documented-as-equivalent
msg.add_header(name, value) raised:

TypeError: sequence item 0: expected str instance, Header found

add_header() always assembled the header with SEMISPACE.join(parts), and
str.join rejects a non-str element such as a Header. So the common
"copy every header into a new message" loop from the bug report broke on any
message carrying a Header-typed value:

for h, v in oldmsg.items():
    newmsg.add_header(h, v)   # TypeError on a Header value

Fix

When no extra parameters are given, add_header() now stores the value the
same way __setitem__ does, so a Header (or str) is stored unmodified —
matching the documented equivalence with msg[name] = value. None is still
coerced to '' to preserve add_header()'s historical behavior.

The parameterized branch is intentionally left unchanged: it must assemble the
header as a string, so it continues to require a str value. (Passing a
Header there still raises, as before — and stringifying an unknown-8bit
Header would silently corrupt its bytes to U+FFFD, so quietly accepting it
would be worse than the existing error.)

Verification

$ ./python -m test test_email
== Tests result: SUCCESS ==
Total tests: run=1,814 skipped=2
Result: SUCCESS

New regression test test_add_header_copies_Header_returned_by_items
reproduces the bug from the real email.message_from_bytes(...).items()
producer path, and asserts the Header is stored unmodified (raw_items()
identity) and that add_header matches the __setitem__ path byte-for-byte
(as_bytes()). The add_header docs gain a note and a .. versionchanged::
describing the no-parameter Header acceptance, as the issue requested.

Real behavior proof

Behavior addressed: Message.add_header(name, value) raised
TypeError: sequence item 0: expected str instance, Header found when value
was an email.header.Header — the type Message.items() yields under the
compat32 policy for 8-bit headers — whereas the documented-equivalent
msg[name] = value accepted it.

Real environment tested: locally-built CPython main (Python 3.16.0a0),
arm64 macOS, run via ./python.exe. The same interpreter binary is used for
both BEFORE and AFTER; only Lib/email/message.py is swapped (origin/main vs.
this PR), since the change is pure Python and loaded at runtime.

Exact steps or command run after this patch:

# repro: faithfully reproduces the reporter's loop on a message whose
# multi-line X-Ham-Report header carries an 8-bit byte (0xe9), which makes
# items() yield a Header under compat32.
$ git checkout origin/main -- Lib/email/message.py   # BEFORE
$ ./python.exe /tmp/repro_151454.py
$ git checkout HEAD -- Lib/email/message.py          # AFTER (this PR)
$ ./python.exe /tmp/repro_151454.py

Evidence after fix:

########## BEFORE (unpatched origin/main) ##########
items() yields X-Ham-Report as: Header
Traceback (most recent call last):
  File "/tmp/repro_151454.py", line 18, in <module>
    newmsg.add_header(h, v)
  File ".../Lib/email/message.py", line 587, in add_header
    self[_name] = SEMISPACE.join(parts)
TypeError: sequence item 0: expected str instance, Header found
[exit 1]

########## AFTER (this PR) ##########
items() yields X-Ham-Report as: Header
copy loop completed OK
X-Ham-Report preserved as: Header
add_header matches msg[h]=v byte-for-byte: True
[exit 0]

Observed result after fix: the reporter's copy loop completes without
error, the X-Ham-Report value is preserved as a Header (not stringified),
and the resulting message serializes byte-for-byte identically to the
msg[h] = v workaround.

What was not tested:

• The parameterized form add_header(name, Header(...), **params) — left
  unchanged on purpose; it still raises TypeError as on main.
• Non-compat32 policies (email.policy.default / EmailMessage): there
  msg[name] = Header(...) itself raises, and add_header now delegates to
  the same __setitem__, so behavior is unchanged and consistent.
• The ssl module is not built in this environment (no OpenSSL); unrelated to
  email and does not affect test_email.

• Issue: email.message.Message.add_header behavior differs from Message[header]=v #151454

[read-the-docs-community]

Documentation build overview

📚 cpython-previews | 🛠️ Build #33128551 | 📁 Comparing dcb7d25 against main (9ad6ba0)

  🔍 Preview build  

2 files changed

± library/email.compat32-message.html
± whatsnew/changelog.html