diff --git a/Doc/library/email.header.rst b/Doc/library/email.header.rst index 65e2d0367fd7684..66e63560bb8dbb5 100644 --- a/Doc/library/email.header.rst +++ b/Doc/library/email.header.rst @@ -155,6 +155,19 @@ 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é' + + Alternatively, messages parsed with the :data:`email.policy.default` + policy decode their headers automatically. + .. 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.