Add warnings about obsolescence of 'email.header.decode_header' and 'email.header.make_header' functions.

dlenski · dlenski · commit 90db289c5e76 · 2025-06-11T13:27:37.000-07:00
Recommend use of `email.headerregistry.HeaderRegistry` instead, as suggested in #92900 (comment)
diff --git a/Doc/library/email.header.rst b/Doc/library/email.header.rst
@@ -202,6 +202,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=' ')
 
@@ -215,3 +220,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.
diff --git a/Lib/email/header.py b/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 email.headerregistry.HeaderRegistry instead.
     """
     # If it is a Header object, we can just return the encoded chunks.
     if hasattr(header, '_chunks'):
@@ -167,6 +170,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)
