From 3c526b41f3d85641d9aa89ec40533e45cab85bcd Mon Sep 17 00:00:00 2001 From: ArtyomSimitian Date: Tue, 3 Nov 2026 12:00:58 -0800 Subject: [PATCH 1/3] gh-61707: Clarify that Header.__str__() does not decode RFC 2047 encoded words --- Doc/library/email.header.rst | 10 ++++++++++ .../2026-11-03-20-00-00.gh-issue-61707.Hd5rSt.rst | 3 +++ 2 files changed, 13 insertions(+) create mode 100644 Misc/NEWS.d/next/Documentation/2026-11-03-20-00-00.gh-issue-61707.Hd5rSt.rst diff --git a/Doc/library/email.header.rst b/Doc/library/email.header.rst index 65e2d0367fd7684..afb2c21ab5dd872 100644 --- a/Doc/library/email.header.rst +++ b/Doc/library/email.header.rst @@ -155,6 +155,16 @@ Here is the :class:`Header` class description: charset of ``'unknown-8bit'`` are decoded as ASCII using the ``'replace'`` error handler. + This does not decode :rfc:`2047` encoded words that appear in the header + value itself. For example, + ``str(Header('=?utf-8?q?Caf=C3=A9?='))`` returns the string unchanged. + To decode a raw header string, use :func:`decode_header` and + :func:`make_header`:: + + >>> from email.header import decode_header, make_header + >>> str(make_header(decode_header('=?utf-8?q?Caf=C3=A9?='))) + 'Café' + .. versionchanged:: 3.2 Added handling for the ``'unknown-8bit'`` charset. diff --git a/Misc/NEWS.d/next/Documentation/2026-11-03-20-00-00.gh-issue-61707.Hd5rSt.rst b/Misc/NEWS.d/next/Documentation/2026-11-03-20-00-00.gh-issue-61707.Hd5rSt.rst new file mode 100644 index 000000000000000..2dad88cc5a0c588 --- /dev/null +++ b/Misc/NEWS.d/next/Documentation/2026-11-03-20-00-00.gh-issue-61707.Hd5rSt.rst @@ -0,0 +1,3 @@ +Clarify that :meth:`email.header.Header.__str__` does not decode :rfc:`2047` +encoded words, and point to :func:`email.header.decode_header` and +:func:`email.header.make_header` for decoding raw header strings. From f3e7e861c6729548fac1b3a8a0101bd883ec3122 Mon Sep 17 00:00:00 2001 From: ArtyomSimitian Date: Tue, 3 Nov 2026 12:14:56 -0800 Subject: [PATCH 2/3] Mention email.policy.default as the modern alternative --- Doc/library/email.header.rst | 3 +++ 1 file changed, 3 insertions(+) diff --git a/Doc/library/email.header.rst b/Doc/library/email.header.rst index afb2c21ab5dd872..2fe71f001c68277 100644 --- a/Doc/library/email.header.rst +++ b/Doc/library/email.header.rst @@ -164,6 +164,9 @@ Here is the :class:`Header` class description: >>> from email.header import decode_header, make_header >>> str(make_header(decode_header('=?utf-8?q?Caf=C3=A9?='))) 'Café' + + Alternatively, messages parsed with the :data:`email.policy.default` + policy decode their headers automatically. .. versionchanged:: 3.2 Added handling for the ``'unknown-8bit'`` charset. From bb7f8a3e5c542b9531f5252525f0b0f48a452a61 Mon Sep 17 00:00:00 2001 From: ArtyomSimitian Date: Tue, 3 Nov 2026 12:34:02 -0800 Subject: [PATCH 3/3] Fix indentation and trailing whitespace --- Doc/library/email.header.rst | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/Doc/library/email.header.rst b/Doc/library/email.header.rst index 2fe71f001c68277..66e63560bb8dbb5 100644 --- a/Doc/library/email.header.rst +++ b/Doc/library/email.header.rst @@ -164,9 +164,9 @@ Here is the :class:`Header` class description: >>> from email.header import decode_header, make_header >>> str(make_header(decode_header('=?utf-8?q?Caf=C3=A9?='))) 'Café' - - Alternatively, messages parsed with the :data:`email.policy.default` - policy decode their headers automatically. + + Alternatively, messages parsed with the :data:`email.policy.default` + policy decode their headers automatically. .. versionchanged:: 3.2 Added handling for the ``'unknown-8bit'`` charset.