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 #92900 (comment)

Author: dlenski

Doc/library/email.header.rst

@@ -201,6 +201,11 @@ 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::
+
+       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=' ')
 
@@ -214,3 +219,8 @@ The :mod:`email.header` module also provides the following convenient functions.
    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.
+
+   .. note::
+
+       This function exists for for backwards compatibility only, and is
+       not recommended for use in new code.

Lib/email/header.py

@@ -72,6 +72,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 email.headerregistry.HeaderRegistry instead.
     """
     # If it is a Header object, we can just return the encoded chunks.
     if hasattr(header, '_chunks'):
@@ -164,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)

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.
+The inconsistent return types of :func:`email.header.decode_header` are now documented,
+and the use of :func:`email.header.decode_header` and :func:`email.header.make_header`
+are discouraged, with :class:`email.headerregistry.HeaderRegistry` recommended as a
+replacement.