Repository: twisted/twisted

Issue:
Deprecate t.w.h.HTTPClient
**Is your feature request related to a problem? Please describe.**

I think this speaks for itself:

https://github.com/twisted/twisted/blob/dd3b1f38a60f960efeda1388536ff50512878591/src/twisted/web/http.py#L626-L628

It looks like we forgot to deprecate and remove this along with `getPage` and friends (in #10295).

**Describe the solution you'd like**

Deprecate it, and file a ticket to remove it per policy.

**Describe alternatives you've considered**

Leave it sitting there like a footgun. :man_shrugging: 

**Additional context**

See https://github.com/twisted/twisted/pull/735#discussion_r1588776725 and note #12159.

Discussion:

Patch:
diff --git a/src/twisted/web/http.py b/src/twisted/web/http.py
index 0beb327669..b08ee9121c 100644
--- a/src/twisted/web/http.py
+++ b/src/twisted/web/http.py
@@ -31,6 +31,7 @@ also useful for HTTP clients (such as the chunked encoding parser).
     it, as in the HTTP 1.1 chunked I{Transfer-Encoding} (RFC 7230 section 4.1).
     This limits how much data may be buffered when decoding the line.
 """
+
 from __future__ import annotations
 
 __all__ = [
@@ -140,7 +141,7 @@ from twisted.protocols import basic, policies
 from twisted.python import log
 from twisted.python.compat import nativeString, networkString
 from twisted.python.components import proxyForInterface
-from twisted.python.deprecate import deprecated
+from twisted.python.deprecate import deprecated, deprecatedModuleAttribute
 from twisted.python.failure import Failure
 from twisted.web._responses import (
     ACCEPTED,
@@ -780,6 +781,14 @@ class HTTPClient(basic.LineReceiver):
             self.setLineMode(rest)
 
 
+deprecatedModuleAttribute(
+    Version("Twisted", "NEXT", 0, 0),
+    "Use twisted.web.client.Agent instead.",
+    __name__,
+    HTTPClient.__name__,
+)
+
+
 # response codes that must have empty bodies
 NO_BODY_CODES = (204, 304)
 
diff --git a/src/twisted/web/iweb.py b/src/twisted/web/iweb.py
index 1aeb152fd9..040b916c73 100644
--- a/src/twisted/web/iweb.py
+++ b/src/twisted/web/iweb.py
@@ -9,6 +9,7 @@ Interface definitions for L{twisted.web}.
     L{IBodyProducer.length} to indicate that the length of the entity
     body is not known in advance.
 """
+
 from typing import TYPE_CHECKING, Callable, List, Optional
 
 from zope.interface import Attribute, Interface
@@ -595,15 +596,15 @@ class IResponse(Interface):
         L{IPushProducer}.  The protocol's C{connectionLost} method will be
         called with:
 
-            - ResponseDone, which indicates that all bytes from the response
+            - L{ResponseDone}, which indicates that all bytes from the response
               have been successfully delivered.
 
-            - PotentialDataLoss, which indicates that it cannot be determined
+            - L{PotentialDataLoss}, which indicates that it cannot be determined
               if the entire response body has been delivered.  This only occurs
               when making requests to HTTP servers which do not set
               I{Content-Length} or a I{Transfer-Encoding} in the response.
 
-            - ResponseFailed, which indicates that some bytes from the response
+            - L{ResponseFailed}, which indicates that some bytes from the response
               were lost.  The C{reasons} attribute of the exception may provide
               more specific indications as to why.
         """
diff --git a/src/twisted/web/newsfragments/12158.removal b/src/twisted/web/newsfragments/12158.removal
new file mode 100644
index 0000000000..94bc3acb08
--- /dev/null
+++ b/src/twisted/web/newsfragments/12158.removal
@@ -0,0 +1,1 @@
+twisted.web.http.HTTPClient is now deprecated in favor of twisted.web.client.Agent


Test patch:
diff --git a/src/twisted/web/test/test_http.py b/src/twisted/web/test/test_http.py
index 91e382f9a0..b88d7c474b 100644
--- a/src/twisted/web/test/test_http.py
+++ b/src/twisted/web/test/test_http.py
@@ -5,7 +5,6 @@
 Test HTTP support.
 """
 
-
 import base64
 import calendar
 import random
@@ -20,6 +19,7 @@ from zope.interface import directlyProvides, providedBy, provider
 from zope.interface.verify import verifyObject
 
 import hamcrest
+from incremental import Version
 
 from twisted.internet import address
 from twisted.internet.error import ConnectionDone, ConnectionLost
@@ -4442,6 +4442,22 @@ class HTTPChannelSanitizationTests(unittest.SynchronousTestCase):
             )
 
 
+class HTTPClientDeprecationTests(unittest.SynchronousTestCase):
+    """
+    Test that L{http.HTTPClient} is deprecated.
+    """
+
+    def test_deprecated(self):
+        """
+        Accessing L{http.HTTPClient} produces a deprecation warning.
+        """
+        self.getDeprecatedModuleAttribute(
+            "twisted.web.http",
+            "HTTPClient",
+            Version("Twisted", "NEXT", 0, 0),
+        )
+
+
 class HTTPClientSanitizationTests(unittest.SynchronousTestCase):
     """
     Test that L{http.HTTPClient} sanitizes its output.