mirror of
https://github.com/python/cpython.git
synced 2025-07-07 19:35:27 +00:00
1c4f01a160
gh-67022: Document bytes/str inconsistency in email.header.decode_header() and suggest email.headerregistry.HeaderRegistry as a sane alternative (GH-92900)
* gh-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 https://github.com/python/cpython/pull/92900#discussion_r1112472177
(cherry picked from commit
|
||
|---|---|---|
| .. | ||
| mime | ||
| __init__.py | ||
| _encoded_words.py | ||
| _header_value_parser.py | ||
| _parseaddr.py | ||
| _policybase.py | ||
| architecture.rst | ||
| base64mime.py | ||
| charset.py | ||
| contentmanager.py | ||
| encoders.py | ||
| errors.py | ||
| feedparser.py | ||
| generator.py | ||
| header.py | ||
| headerregistry.py | ||
| iterators.py | ||
| message.py | ||
| parser.py | ||
| policy.py | ||
| quoprimime.py | ||
| utils.py | ||