gh-153648: Deprecate http.client.HTTPMessage.getallmatchingheaders()

getallmatchingheaders() has returned an empty list for every input since
Python 3.0 -- it compares keys() entries, which are bare header names,
against "name:".  Its only user was the CGI handler, removed in 3.15, and
run_cgi() had already stopped calling it in 3.10.

Deprecate it, with removal in 3.18.  Use email.message.Message.get_all()
instead.

Author: soreavis

Doc/deprecations/pending-removal-in-3.18.rst

@@ -16,3 +16,10 @@ Pending removal in Python 3.18
   * ``import`` lines in :file:`{name}.pth` files are silently ignored.
 
   (Contributed by Barry Warsaw in :gh:`148641`.)
+
+* :mod:`http.client`:
+
+  * :meth:`!http.client.HTTPMessage.getallmatchingheaders` has been deprecated
+    since Python 3.16.  It has returned an empty list for every input since
+    Python 3.0; use :meth:`email.message.Message.get_all` instead.
+    (Contributed by Julian Soreavis in :gh:`153648`.)

Doc/whatsnew/3.16.rst

@@ -657,6 +657,15 @@ New deprecations
     3.9, now issues a deprecation warning on use. This property is slated for
     removal in 3.21. Use ``ast.Tuple.elts`` instead.
 
+* :mod:`http.client`:
+
+  * :meth:`!http.client.HTTPMessage.getallmatchingheaders` is now deprecated
+    and will be removed in Python 3.18.  It has returned an empty list for
+    every input since Python 3.0, and its only user, the CGI handler, was
+    removed in Python 3.15.  Use :meth:`email.message.Message.get_all`
+    instead.
+    (Contributed by Julian Soreavis in :gh:`153648`.)
+
 * :mod:`struct`:
 
   * Soft-deprecated since Python 3.15, using ``'F'`` and ``'D'`` type codes are now

Lib/http/client.py

@@ -195,8 +195,8 @@ def _strip_ipv6_iface(enc_name: bytes) -> bytes:
 class HTTPMessage(email.message.Message):
 
     # The getallmatchingheaders() method was only used by the CGI handler
-    # that was removed in Python 3.15. However, since the public API was not
-    # properly defined, it will be kept for backwards compatibility reasons.
+    # that was removed in Python 3.15. It has returned an empty list for every
+    # input since Python 3.0.
 
     def getallmatchingheaders(self, name):
         """Find all header lines matching a given header name.
@@ -208,6 +208,11 @@ def getallmatchingheaders(self, name):
         occurrences are returned.  Case is not important in the header name.
 
         """
+        import warnings
+        warnings._deprecated(
+            "http.client.HTTPMessage.getallmatchingheaders",
+            remove=(3, 18),
+        )
         name = name.lower() + ':'
         n = len(name)
         lst = []

Lib/test/test_httplib.py

@@ -507,6 +507,12 @@ def test_max_connection_trailers(self):
             response = conn.getresponse()
             self.assertEqual(response.read(), chunked_expected)
 
+    def test_getallmatchingheaders_deprecated(self):
+        message = client.parse_headers(io.BytesIO(b"Set-Cookie: a=1\r\n\r\n"))
+        with self.assertWarns(DeprecationWarning):
+            message.getallmatchingheaders("Set-Cookie")
+
+
 class HttpMethodTests(TestCase):
     def test_invalid_method_names(self):
         methods = (

Misc/NEWS.d/next/Library/2026-07-13-08-20-16.gh-issue-153648.0L8KTV.rst

@@ -0,0 +1,4 @@
+Deprecate :meth:`!http.client.HTTPMessage.getallmatchingheaders`, to be
+removed in Python 3.18.  It has returned an empty list for every input since
+Python 3.0, and its only user, the CGI handler, was removed in Python 3.15.
+Use :meth:`email.message.Message.get_all` instead.  Patch by Julian Soreavis.