Add email.header.decode_header_to_string() convenience function

This function takes an email header, possibly with portions encoded
according to RFC2047, and converts it to a standard Python string.

It is intended to provide a sane, Pythonic replacement for
`email.header.decode_header()`, which has two major problems:

1. May return either bytes or str (bpo-22833/gh-67022), an
   inconsistent and error-prone interface
2. Exposes details of an email header value's encoding which
   most users will not care about or want to deal with. Many users
   likely just want to decode an email header value to a Python
   string.

It turns out that `email.header` already contained most of the code
necessary to do this, and providing `decode_header_to_string` as a
documented wrapper function points users in the right direction.

Author: dlenski

Doc/library/email.header.rst

@@ -173,6 +173,38 @@ Here is the :class:`Header` class description:
 The :mod:`email.header` module also provides the following convenient functions.
 
 
+.. function:: decode_header_to_string(header)
+
+   Decode a message header value to a Unicode string, including handling
+   portions encoded according to :rfc:`2047`.
+
+   An :exc:`classemail.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_to_string
+      >>> decode_header_to_string('=?iso-8859-1?q?p=F6stal?=')
+      'p\xf6stal'
+      >>> decode_header_to_string('unencoded_string')
+      'unencoded_string'
+      >>> decode_header_to_string('bar =?utf-8?B?ZsOzbw==?=')
+      'bar f\xf3o'
+
+
+.. function:: make_header(decoded_seq, maxlinelen=None, header_name=None, continuation_ws=' ')
+
+   Create a :class:`Header` instance from a sequence of pairs as returned by
+   :func:`decode_header`.
+
+   :func:`decode_header` takes a header value string and returns a sequence of
+   pairs of the format ``(decoded_string, charset)`` where *charset* is the name of
+   the character set.
+
+   This function takes one of those sequence of pairs and returns a
+   :class:`Header` instance.  Optional *maxlinelen*, *header_name*, and
+   *continuation_ws* are as in the :class:`Header` constructor.
+
 
 .. function:: decode_header(header)
 
@@ -202,16 +234,7 @@ The :mod:`email.header` module also provides the following convenient functions.
       >>> decode_header('bar =?utf-8?B?ZsOzbw==?=')
       [(b'bar ', None), (b'f\xc3\xb3o', 'utf-8')]
 
+   .. note::
 
-.. function:: make_header(decoded_seq, maxlinelen=None, header_name=None, continuation_ws=' ')
-
-   Create a :class:`Header` instance from a sequence of pairs as returned by
-   :func:`decode_header`.
-
-   :func:`decode_header` takes a header value string and returns a sequence of
-   pairs of the format ``(decoded_string, charset)`` where *charset* is the name of
-   the character set.
-
-   This function takes one of those sequence of pairs and returns a
-   :class:`Header` instance.  Optional *maxlinelen*, *header_name*, and
-   *continuation_ws* are as in the :class:`Header` constructor.
+      This function exists for for backwards compatibility only. For
+      new code we recommend using :mod:`email.header.decode_header_to_string`.

Lib/email/header.py

@@ -74,6 +74,9 @@ def decode_header(header):
 
     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 decode_header_to_string instead.
     """
     # If it is a Header object, we can just return the encoded chunks.
     if hasattr(header, '_chunks'):
@@ -155,6 +158,23 @@ def decode_header(header):
     return collapsed
 
 
+
+def decode_header_to_string(header):
+    """Decode a message header into a string.
+
+    header may be a string that may or may not contain RFC2047 encoded words,
+    or it may be a Header object; in the latter case, this is equivalent to
+    str(header).
+
+    An email.errors.HeaderParseError may be raised when certain decoding error
+    occurs (e.g. a base64 decoding exception).
+    """
+
+    if not isinstance(header, Header):
+        header = make_header(decode_header(header))
+    return str(header)
+
+
 
 def make_header(decoded_seq, maxlinelen=None, header_name=None,
                 continuation_ws=' '):

Lib/test/test_email/test_email.py

@@ -19,7 +19,7 @@
 import email.policy
 
 from email.charset import Charset
-from email.header import Header, decode_header, make_header
+from email.header import Header, decode_header, decode_header_to_string, make_header
 from email.parser import Parser, HeaderParser
 from email.generator import Generator, DecodedGenerator, BytesGenerator
 from email.message import Message
@@ -2476,6 +2476,17 @@ def test_unencoded_utf8(self):
         self.assertEqual(decode_header(s),
             [('header with unexpected non ASCII caract\xe8res', None)])
 
+    def test_decode_header_to_string_from_string(self):
+        s = '=?windows-1252?q?=22M=FCller_T=22?=\r\n <[email protected]>'
+        self.assertEqual(str(make_header(decode_header(s))),
+            decode_header_to_string(s))
+
+    def test_decode_header_to_string_from_header_obj(self):
+        s = '\xeatre'
+        h = Header(s)
+        self.assertEqual(str(h),
+            decode_header_to_string(h))
+
 
 # Test the MIMEMessage class
 class TestMIMEMessage(TestEmailBase):

Misc/NEWS.d/next/Library/2022-01-11-21-40-14.bpo-22833.WB-JWw.rst

@@ -1 +1,4 @@
 The inconsistent return types of :func:`email.header.decode_header` are now documented.
+
+:func:`email.header.decode_header_to_string` is provided as a less error-prone and
+more straightforward alternative for it.