bpo-12707: deprecate info(), geturl(), getcode() methods in favor of headers, url, and status properties for HTTPResponse and addinfourl (GH-11447)

Co-Authored-By: epicfaace <[email protected]>

Author: epicfaace

Doc/library/http.client.rst

@@ -484,6 +484,14 @@ statement.
 
    HTTP protocol version used by server.  10 for HTTP/1.0, 11 for HTTP/1.1.
 
+.. attribute:: HTTPResponse.url
+
+   URL of the resource retrieved, commonly used to determine if a redirect was followed.
+
+.. attribute:: HTTPResponse.headers
+
+   Headers of the response in the form of an :class:`email.message.EmailMessage` instance.
+
 .. attribute:: HTTPResponse.status
 
    Status code returned by server.
@@ -501,6 +509,21 @@ statement.
 
    Is ``True`` if the stream is closed.
 
+.. method:: HTTPResponse.geturl()
+
+   .. deprecated:: 3.9
+      Deprecated in favor of :attr:`~HTTPResponse.url`.
+
+.. method:: HTTPResponse.info()
+
+   .. deprecated:: 3.9
+      Deprecated in favor of :attr:`~HTTPResponse.headers`.
+
+.. method:: HTTPResponse.getstatus()
+
+   .. deprecated:: 3.9
+      Deprecated in favor of :attr:`~HTTPResponse.status`.
+
 Examples
 --------
 

Doc/library/urllib.request.rst

@@ -55,16 +55,8 @@ The :mod:`urllib.request` module defines the following functions:
    The *cadefault* parameter is ignored.
 
    This function always returns an object which can work as a
-   :term:`context manager` and has methods such as
-
-   * :meth:`~urllib.response.addinfourl.geturl` --- return the URL of the resource retrieved,
-     commonly used to determine if a redirect was followed
-
-   * :meth:`~urllib.response.addinfourl.info` --- return the meta-information of the page, such as headers,
-     in the form of an :func:`email.message_from_string` instance (see
-     `Quick Reference to HTTP Headers <http://jkorpela.fi/http.html>`_)
-
-   * :meth:`~urllib.response.addinfourl.getcode` -- return the HTTP status code of the response.
+   :term:`context manager` and has the properties *url*, *headers*, and *status*.
+   See :class:`urllib.response.addinfourl` for more detail on these properties.
 
    For HTTP and HTTPS URLs, this function returns a
    :class:`http.client.HTTPResponse` object slightly modified. In addition
@@ -1585,9 +1577,42 @@ some point in the future.
    :synopsis: Response classes used by urllib.
 
 The :mod:`urllib.response` module defines functions and classes which define a
-minimal file like interface, including ``read()`` and ``readline()``. The
-typical response object is an addinfourl instance, which defines an ``info()``
-method and that returns headers and a ``geturl()`` method that returns the url.
-Functions defined by this module are used internally by the
-:mod:`urllib.request` module.
+minimal file-like interface, including ``read()`` and ``readline()``.
+Functions defined by this module are used internally by the :mod:`urllib.request` module.
+The typical response object is a :class:`urllib.response.addinfourl` instance:
+
+.. class:: addinfourl
+
+   .. attribute:: url
+
+      URL of the resource retrieved, commonly used to determine if a redirect was followed.
+
+   .. attribute:: headers
+
+      Returns the headers of the response in the form of an :class:`~email.message.EmailMessage` instance.
+
+   .. attribute:: status
+
+      .. versionadded:: 3.9
+
+      Status code returned by server.
+
+   .. method:: geturl()
+
+      .. deprecated:: 3.9
+         Deprecated in favor of :attr:`~addinfourl.url`.
+
+   .. method:: info()
+
+      .. deprecated:: 3.9
+         Deprecated in favor of :attr:`~addinfourl.headers`.
+
+   .. attribute:: code
+
+      .. deprecated:: 3.9
+         Deprecated in favor of :attr:`~addinfourl.status`.
+
+   .. method:: getstatus()
 
+      .. deprecated:: 3.9
+         Deprecated in favor of :attr:`~addinfourl.status`.

Lib/test/test_urllib.py

@@ -194,6 +194,15 @@ def test_close(self):
         # by the tearDown() method for the test
         self.returned_obj.close()
 
+    def test_headers(self):
+        self.assertIsInstance(self.returned_obj.headers, email.message.Message)
+
+    def test_url(self):
+        self.assertEqual(self.returned_obj.url, self.pathname)
+
+    def test_status(self):
+        self.assertIsNone(self.returned_obj.status)
+
     def test_info(self):
         self.assertIsInstance(self.returned_obj.info(), email.message.Message)
 

Lib/test/test_urllib_response.py

@@ -42,6 +42,7 @@ def closehook():
     def test_addinfo(self):
         info = urllib.response.addinfo(self.fp, self.test_headers)
         self.assertEqual(info.info(), self.test_headers)
+        self.assertEqual(info.headers, self.test_headers)
 
     def test_addinfourl(self):
         url = "http://www.python.org"
@@ -51,6 +52,9 @@ def test_addinfourl(self):
         self.assertEqual(infourl.info(), self.test_headers)
         self.assertEqual(infourl.geturl(), url)
         self.assertEqual(infourl.getcode(), code)
+        self.assertEqual(infourl.headers, self.test_headers)
+        self.assertEqual(infourl.url, url)
+        self.assertEqual(infourl.status, code)
 
     def tearDown(self):
         self.sock.close()

Lib/urllib/request.py

@@ -163,18 +163,10 @@ def urlopen(url, data=None, timeout=socket._GLOBAL_DEFAULT_TIMEOUT,
 
     The *cadefault* parameter is ignored.
 
-    This function always returns an object which can work as a context
-    manager and has methods such as
 
-    * geturl() - return the URL of the resource retrieved, commonly used to
-      determine if a redirect was followed
-
-    * info() - return the meta-information of the page, such as headers, in the
-      form of an email.message_from_string() instance (see Quick Reference to
-      HTTP Headers)
-
-    * getcode() - return the HTTP status code of the response.  Raises URLError
-      on errors.
+    This function always returns an object which can work as a
+    context manager and has the properties url, headers, and status.
+    See urllib.response.addinfourl for more detail on these properties.
 
     For HTTP and HTTPS URLs, this function returns a http.client.HTTPResponse
     object slightly modified. In addition to the three new methods above, the

Lib/urllib/response.py

@@ -73,6 +73,10 @@ def __init__(self, fp, headers, url, code=None):
         self.url = url
         self.code = code
 
+    @property
+    def status(self):
+        return self.code
+
     def getcode(self):
         return self.code
 

Misc/NEWS.d/next/Documentation/2019-08-27-01-14-59.bpo-12707.Yj3_7_.rst

@@ -0,0 +1 @@
+Deprecate info(), geturl(), getcode() methods in favor of the headers, url, and status properties, respectively, for HTTPResponse and addinfourl. Also deprecate the code attribute of addinfourl in favor of the status attribute. Patch by Ashwin Ramaswami