mirror of
https://github.com/python/cpython.git
synced 2025-11-02 22:51:25 +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
|
||
|---|---|---|
| .. | ||
| data | ||
| __init__.py | ||
| __main__.py | ||
| test__encoded_words.py | ||
| test__header_value_parser.py | ||
| test_asian_codecs.py | ||
| test_contentmanager.py | ||
| test_defect_handling.py | ||
| test_email.py | ||
| test_generator.py | ||
| test_headerregistry.py | ||
| test_inversion.py | ||
| test_message.py | ||
| test_parser.py | ||
| test_pickleable.py | ||
| test_policy.py | ||
| test_utils.py | ||
| torture_test.py | ||