[Python-checkins] cpython (3.4): Issues #22989, #21228: Document HTTP response object for urlopen()

[martin.panter]

https://hg.python.org/cpython/rev/fa3c9faabfb0
changeset:   99370:fa3c9faabfb0
branch:      3.4
parent:      99366:0325eca1927e
user:        Martin Panter <vadmium+py at gmail.com>
date:        Thu Nov 26 11:01:58 2015 +0000
summary:
  Issues #22989, #21228: Document HTTP response object for urlopen()

Previous documentation was not clear if the geturl(), info() and getcode()
were valid for HTTP responses. The “msg” attribute is different to the usual
HTTPResponse.msg attribute. Based on patch by Evens Fortuné.

files:
  Doc/library/urllib.request.rst |  20 +++++++++++++-------
  Misc/ACKS                      |   1 +
  2 files changed, 14 insertions(+), 7 deletions(-)


diff --git a/Doc/library/urllib.request.rst b/Doc/library/urllib.request.rst
--- a/Doc/library/urllib.request.rst
+++ b/Doc/library/urllib.request.rst
@@ -59,13 +59,7 @@
 
    The *cadefault* parameter is ignored.
 
-   For http and https urls, this function returns a
-   :class:`http.client.HTTPResponse` object which has the following
-   :ref:`httpresponse-objects` methods.
-
-   For ftp, file, and data urls and requests explicitly handled by legacy
-   :class:`URLopener` and :class:`FancyURLopener` classes, this function
-   returns a :class:`urllib.response.addinfourl` object which can work as
+   This function always returns an object which can work as
    :term:`context manager` and has methods such as
 
    * :meth:`~urllib.response.addinfourl.geturl` --- return the URL of the resource retrieved,
@@ -77,6 +71,18 @@
 
    * :meth:`~urllib.response.addinfourl.getcode` -- return the HTTP status code of the response.
 
+   For http and https urls, this function returns a
+   :class:`http.client.HTTPResponse` object slightly modified. In addition
+   to the three new methods above, the msg attribute contains the
+   same information as the :attr:`~http.client.HTTPResponse.reason`
+   attribute --- the reason phrase returned by server --- instead of
+   the response headers as it is specified in the documentation for
+   :class:`~http.client.HTTPResponse`.
+
+   For ftp, file, and data urls and requests explicitly handled by legacy
+   :class:`URLopener` and :class:`FancyURLopener` classes, this function
+   returns a :class:`urllib.response.addinfourl` object.
+
    Raises :exc:`~urllib.error.URLError` on errors.
 
    Note that ``None`` may be returned if no handler handles the request (though
diff --git a/Misc/ACKS b/Misc/ACKS
--- a/Misc/ACKS
+++ b/Misc/ACKS
@@ -436,6 +436,7 @@
 Michael Foord
 Amaury Forgeot d'Arc
 Doug Fort
+Evens Fortuné
 Chris Foster
 John Fouhy
 Andrew Francis

-- 
Repository URL: https://hg.python.org/cpython