Thanks to visit codestin.com
Credit goes to github.com

Skip to content

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

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 1 commit into from
Jun 15, 2025
Merged

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

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
34 changes: 29 additions & 5 deletions Doc/library/email.header.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -178,16 +178,36 @@ The :mod:`email.header` module also provides the following convenient functions.
Decode a message header value without converting the character set. The header
value is in *header*.

This function returns a list of ``(decoded_string, charset)`` pairs containing
each of the decoded parts of the header. *charset* is ``None`` for non-encoded
parts of the header, otherwise a lower case string containing the name of the
character set specified in the encoded string.
For historical reasons, this function may return either:

Here's an example::
1. A list of pairs containing each of the decoded parts of the header,
``(decoded_bytes, charset)``, where *decoded_bytes* is always an instance of
:class:`bytes`, and *charset* is either:

- A lower case string containing the name of the character set specified.

- ``None`` for non-encoded parts of the header.

2. A list of length 1 containing a pair ``(string, None)``, where
*string* is always an instance of :class:`str`.

An :exc:`email.errors.HeaderParseError` may be raised when certain decoding
errors occur (e.g. a base64 decoding exception).

Here are examples:

>>> from email.header import decode_header
>>> decode_header('=?iso-8859-1?q?p=F6stal?=')
[(b'p\xf6stal', 'iso-8859-1')]
>>> decode_header('unencoded_string')
[('unencoded_string', None)]
>>> decode_header('bar =?utf-8?B?ZsOzbw==?=')
[(b'bar ', None), (b'f\xc3\xb3o', 'utf-8')]

.. note::

This function exists for for backwards compatibility only. For
new code, we recommend using :class:`email.headerregistry.HeaderRegistry`.


.. function:: make_header(decoded_seq, maxlinelen=None, header_name=None, continuation_ws=' ')
Expand All @@ -203,3 +223,7 @@ The :mod:`email.header` module also provides the following convenient functions.
:class:`Header` instance. Optional *maxlinelen*, *header_name*, and
*continuation_ws* are as in the :class:`Header` constructor.

.. note::

This function exists for for backwards compatibility only, and is
not recommended for use in new code.
17 changes: 13 additions & 4 deletions Lib/email/header.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -59,16 +59,22 @@
def decode_header(header):
"""Decode a message header value without converting charset.

Returns a list of (string, charset) pairs containing each of the decoded
parts of the header. Charset is None for non-encoded parts of the header,
otherwise a lower-case string containing the name of the character set
specified in the encoded string.
For historical reasons, this function may return either:

1. A list of length 1 containing a pair (str, None).
2. A list of (bytes, charset) pairs containing each of the decoded
parts of the header. Charset is None for non-encoded parts of the header,
otherwise a lower-case string containing the name of the character set
specified in the encoded string.

header may be a string that may or may not contain RFC2047 encoded words,
or it may be a Header object.

An email.errors.HeaderParseError may be raised when certain decoding error
occurs (e.g. a base64 decoding exception).

This function exists for backwards compatibility only. For new code, we
recommend using email.headerregistry.HeaderRegistry instead.
"""
# If it is a Header object, we can just return the encoded chunks.
if hasattr(header, '_chunks'):
Expand Down Expand Up @@ -161,6 +167,9 @@ def make_header(decoded_seq, maxlinelen=None, header_name=None,
This function takes one of those sequence of pairs and returns a Header
instance. Optional maxlinelen, header_name, and continuation_ws are as in
the Header constructor.

This function exists for backwards compatibility only, and is not
recommended for use in new code.
"""
h = Header(maxlinelen=maxlinelen, header_name=header_name,
continuation_ws=continuation_ws)
Expand Down
12 changes: 12 additions & 0 deletions Lib/test/test_email/test_email.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2543,6 +2543,18 @@ def test_multiline_header(self):
self.assertEqual(str(make_header(decode_header(s))),
'"Müller T" <[email protected]>')

def test_unencoded_ascii(self):
# bpo-22833/gh-67022: returns [(str, None)] rather than [(bytes, None)]
s = 'header without encoded words'
self.assertEqual(decode_header(s),
[('header without encoded words', None)])

def test_unencoded_utf8(self):
# bpo-22833/gh-67022: returns [(str, None)] rather than [(bytes, None)]
s = 'header with unexpected non ASCII caract\xe8res'
self.assertEqual(decode_header(s),
[('header with unexpected non ASCII caract\xe8res', None)])


# Test the MIMEMessage class
class TestMIMEMessage(TestEmailBase):
Expand Down
Loading