[3.14] gh-67022: Document bytes/str inconsistency in email.header.decode_header() and suggest email.headerregistry.HeaderRegistry as a sane alternative (GH-92900)

[miss-islington]

• The decode_header() function decodes raw part to bytes or str, depending on encoded part #67022: Document bytes/str inconsistency in email.header.decode_header()

This function's possible return types have been surprising and error-prone
for the entirety of its Python 3.x history. It can return either:

1. typing.List[typing.Tuple[bytes, typing.Optional[str]]] of length >1
2. or typing.List[typing.Tuple[str, None]], of length exactly 1

This means that any user of this function must be prepared to accept either
bytes or str for the first member of the 2-tuples it returns, which is a
very surprising behavior in Python 3.x, particularly given that the second
member of the tuple is supposed to represent the charset/encoding of the
first member.

This patch documents the behavior of this function, and adds test cases
to demonstrate it.

As discussed in bpo-22833, this cannot be changed in a backwards-compatible
way, and some users of this function depend precisely on the existing
behavior.

Add warnings about obsolescence of 'email.header.decode_header' and 'email.header.make_header' functions.

Recommend use of email.headerregistry.HeaderRegistry instead, as suggested
in #92900 (comment)
(cherry picked from commit 60181f4)

Co-authored-by: Dan Lenski [email protected]

---

📚 Documentation preview 📚: https://cpython-previews--135548.org.readthedocs.build/