classification
Title: Deprecate addinfourl getters
Type: enhancement Stage: patch review
Components: Library (Lib) Versions: Python 3.3, Python 3.4, Python 2.7
process
Status: open Resolution:
Dependencies: Superseder:
Assigned To: orsenthil Nosy List: berker.peksag, eric.araujo, ezio.melotti, martin.panter, nadeem.vawda, orsenthil, petri.lehtinen, sandro.tosi
Priority: normal Keywords: easy, patch, patch, patch, patch

Created on 2011-08-07 23:46 by ezio.melotti, last changed 2019-01-06 19:37 by epicfaace.

Pull Requests
URL Status Linked Edit
PR 11447 open epicfaace, 2019-01-06 19:37
PR 11447 open epicfaace, 2019-01-06 19:37
PR 11447 open epicfaace, 2019-01-06 19:37
PR 11447 open epicfaace, 2019-01-06 19:37
Messages (12)
msg141756 - (view) Author: Ezio Melotti (ezio.melotti) * (Python committer) Date: 2011-08-07 23:46
The documentation for urllib.request.urlopen [0] says that:
"""
This function returns a file-like object [addinfourl] with two additional methods from the urllib.response module
    geturl() — return the URL of the resource retrieved, [...]
    info() — return the meta-information of the page, [...]
"""

There's also a third undocumented method: getcode().  Looking at the code[1] ISTM that the 3 getters (geturl(), info(), and getcode()):
  1) have an inconsistent interface (why not getinfo() or getheaders()?);
  2) they just return the url, headers, and code attributes;

For these two reasons I propose to:
  * document the 3 attributes as the suggested way to access this information;
  * deprecate the 3 getters;
  * avoid to document the now undocumented getcode();


[0]: http://docs.python.org/py3k/library/urllib.request.html
[1]: Lib/urllib/response.py:83
msg141757 - (view) Author: Ezio Melotti (ezio.melotti) * (Python committer) Date: 2011-08-08 00:26
Another possible improvement that can be done is providing a proper Response object instead of addbase, addinfo, addinfourl (yes, those are oddly-named classes, not functions [0]).
The Response object could be like 'addbase', but with this signature:

class Response:
    def __init__(self, fp, headers=None, url=None, code=None):
        ...
and without additional getters.

The addclosehook class could be provided via an alternative constructor:

    @classmethod
    def with_close_hook(cls, fp, hook, *hookargs):
        ...

[0]: Lib/urllib/response.py
msg142424 - (view) Author: Éric Araujo (eric.araujo) * (Python committer) Date: 2011-08-19 12:04
> For these two reasons I propose to:
>  * document the 3 attributes as the suggested way to access this
>    information;
>  * deprecate the 3 getters;
>  * avoid to document the now undocumented getcode();
+1

> The addclosehook class could be provided via an alternative constructor
I can’t say why, but I don’t like that.
msg142438 - (view) Author: Ezio Melotti (ezio.melotti) * (Python committer) Date: 2011-08-19 12:50
I thought about having another class, but I couldn't come up with a decent name for it (ResponseWithCloseHook?).  After all it's still a Response and unless you need a way to distinguish responses with and without close hooks, I think it might be better to have a single class for both.
msg147983 - (view) Author: Éric Araujo (eric.araujo) * (Python committer) Date: 2011-11-20 12:02
> I thought about having another class, but I couldn't come up with a
> decent name for it (ResponseWithCloseHook?).

If it’s used together with the base Response class (I don’t have the details in memory anymore), you could try ClosingMixin or FileLikeMixin.
msg180901 - (view) Author: Petri Lehtinen (petri.lehtinen) * (Python committer) Date: 2013-01-29 11:31
+1 for the documentation changes, which should be applied to 2.7 as well. The deprecation is the only thing to go to 3.4 only, if it's done at all.
msg180902 - (view) Author: Petri Lehtinen (petri.lehtinen) * (Python committer) Date: 2013-01-29 11:43
Also note that getcode() is already documented in urllib (not urllib2) documentation:

    http://docs.python.org/2/library/urllib.html#urllib.urlopen
msg184552 - (view) Author: Senthil Kumaran (orsenthil) * (Python committer) Date: 2013-03-18 23:22
And getcode is documented all 3.x documentation now.

URLOpener (and by inheritance) raise DeprecationWarning since 3.3. I believe, when class becomes deprecated and removed, their methods go away too? For the URLOpener, I would like that to happen as it will present a much cleaner newer way for further enhancement.
msg184553 - (view) Author: Senthil Kumaran (orsenthil) * (Python committer) Date: 2013-03-18 23:23
URLOpener (and by inheritance *FancyURLOpener*)
msg184567 - (view) Author: Senthil Kumaran (orsenthil) * (Python committer) Date: 2013-03-19 00:34
This commit by Ezio in the tests is related (1bcddc0a3765)
msg234945 - (view) Author: Martin Panter (martin.panter) * (Python committer) Date: 2015-01-29 04:44
I think it would be okay to deprecate the methods in the documentation, but they should not be removed nor trigger warnings any time soon.

Currently the following related methods and attributes are documented:

* addinfourl.getcode() == HTTPResponse.status == HTTPError.code
* HTTPResponse.reason == HTTPError.reason (HTTPError documentation is vague on this.)
* addinfourl.geturl()
* addinfourl.info() == HTTPResponse.msg == HTTPError.headers (But see Issue 22989 and patch in Issue 21228 for a quirk with HTTPResponse.)

It would be nice to ensure these three classes all implement the same “Response” interface, except that geturl() and “url” may not be appropriate for HTTPResponse. The “code” and “headers” attributes should definitely be documented for consistency. I propose also adding and documenting “reason”.
msg234947 - (view) Author: Martin Panter (martin.panter) * (Python committer) Date: 2015-01-29 05:06
Blessing a geturl() method or “url” attribute on HTTPError might require Issue 13567 to be fixed
History
Date User Action Args
2019-01-06 19:37:53epicfaacesetkeywords: + patch
stage: needs patch -> patch review
pull_requests: + pull_request10907
2019-01-06 19:37:40epicfaacesetkeywords: + patch
stage: needs patch -> needs patch
pull_requests: + pull_request10908
2019-01-06 19:37:26epicfaacesetkeywords: + patch
stage: needs patch -> needs patch
pull_requests: + pull_request10906
2019-01-06 19:37:13epicfaacesetkeywords: + patch
stage: needs patch -> needs patch
pull_requests: + pull_request10905
2015-01-29 05:30:23berker.peksagsetnosy: + berker.peksag
2015-01-29 05:06:51martin.pantersetmessages: + msg234947
2015-01-29 04:44:46martin.pantersetmessages: + msg234945
2014-09-01 01:18:05martin.pantersetnosy: + martin.panter
2013-03-19 00:34:14orsenthilsetmessages: + msg184567
2013-03-18 23:27:55orsenthilsetassignee: orsenthil
2013-03-18 23:23:35orsenthilsetmessages: + msg184553
2013-03-18 23:22:39orsenthilsetmessages: + msg184552
2013-01-29 11:43:40petri.lehtinensetmessages: + msg180902
2013-01-29 11:31:35petri.lehtinensetnosy: + petri.lehtinen

messages: + msg180901
versions: + Python 2.7, Python 3.3
2012-09-26 16:50:16ezio.melottisettype: enhancement
versions: + Python 3.4, - Python 3.3
2011-11-20 12:02:07eric.araujosetmessages: + msg147983
2011-08-19 12:50:57ezio.melottisetmessages: + msg142438
2011-08-19 12:04:56eric.araujosetnosy: + eric.araujo
messages: + msg142424
2011-08-08 06:08:04nadeem.vawdasetnosy: + nadeem.vawda
2011-08-08 00:26:11ezio.melottisetmessages: + msg141757
2011-08-07 23:46:10ezio.melotticreate