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

[harjothkhara]

Under the compat32 policy, Message.items() yields a Header object (not a str) for any header carrying 8-bit data. You can assign that back with msg[name] = value, but msg.add_header(name, value) — documented as equivalent — raised TypeError: sequence item 0: expected str instance, Header found, because it always did SEMISPACE.join(parts). So the natural "copy every header" loop breaks:

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

Fix: when no extra parameters are passed, add_header() now stores the value the same way __setitem__ does, so a Header (or str) is stored unchanged — matching the documented equivalence. None still becomes ''. The parameterized branch is left as-is: it has to build a string, and silently stringifying an unknown-8bit Header would corrupt its bytes to U+FFFD, so it still raises there.

Added a regression test and a versionchanged note. ./python -m test test_email passes.

Disclosure: I used AI assistance writing this; I've reviewed the change and can explain it.

• 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

[harjothkhara]

@picnixz, small email-related fix in message.py. Since you've worked in this area recently, would you mind taking a quick look when you have a chance?

[harjothkhara]

@picnixz gentle follow-up — you triaged gh-151454 (added the email labels). This patch makes add_header accept a Header value by delegating to __setitem__ when there are no params, with a test and NEWS. Mind a quick review when you have time?

[picnixz]

Sorry, but no. I just added labels (which I can do easily) but reviewing takes time. I would suggest waiting for someone from the email to pick this up (but please be patient as it may require to wait more than just one or two weeks).

[picnixz]

Ok so I still took a bit of my time. I'm going to comment on the issue.