classification
Title: httplib.HTTPResponse documentations inconsistent
Type: Stage: needs patch
Components: Documentation Versions: Python 3.3, Python 3.4, Python 2.7
process
Status: open Resolution:
Dependencies: 19154 Superseder:
Assigned To: orsenthil Nosy List: ThomasH, demian.brecht, eric.araujo, ezio.melotti, mvolz, orsenthil, terry.reedy
Priority: normal Keywords:

Created on 2008-07-22 17:31 by ThomasH, last changed 2014-06-17 05:49 by demian.brecht.

Messages (5)
msg70158 - (view) Author: (ThomasH) Date: 2008-07-22 17:31
The library reference documentation of httplib.HTTPResponse does not
match up with the online help documentation, or with the dir()
information of a particular instance.

E.g. the list of public features in the library reference
(http://docs.python.org/lib/httpresponse-objects.html) is:
- read
- getheader
- getheaders
- msg
- version
- status
- reason

From the online documentation (with 'help(httplib.HTTPResponse)'):
- begin
- close
- getheader
- getheaders
- isclosed
- read

And from a class instance (via 'dir(httpResponseInstance)'):
- 'begin',
- 'chunk_left',
- 'chunked',
- 'close',
- 'debuglevel',
- 'fp',
- 'getheader',
- 'getheaders',
- 'isclosed',
- 'length',
- 'msg',
- 'read',
- 'reason',
- 'status',
- 'strict',
- 'version',
- 'will_close'
msg107442 - (view) Author: Terry J. Reedy (terry.reedy) * (Python committer) Date: 2010-06-09 23:45
Docs have been considerably updated since 2.5. Please check if this still applies to the 2.7 docs
msg108857 - (view) Author: (ThomasH) Date: 2010-06-28 20:24
Still applies. Neither the 2.7 documentation has changed (judging from the current online dev docs), nor the implementation (judging from current svn). So my first two lists are still valid. I cannot comment on the third, as I don't have a 2.7 installation at hand, or will have any time soon.
msg108861 - (view) Author: Senthil Kumaran (orsenthil) * (Python committer) Date: 2010-06-28 20:42
Yes, I know httplib documentation needs improvement. There is a great deal of documentation in the module itself. A lot can be .rst'ifed.
msg199158 - (view) Author: Terry J. Reedy (terry.reedy) * (Python committer) Date: 2013-10-07 20:13
Docs are still as deficient in 3.3, and so I presume in 3.4.

Part of the discrepancy between the first two lists is that data attributes msg, version, status, and reason are instance-only attributes.

#19154 is (now) about improving fileno doc. That, some other methods, are missing doctrings, making help(method) useless.

A big change in 3.x is that HTTPResponse now subclasses io.RawIOBase and hence inherits or implements even more (undocumented) methods than listed here. I suppose they could be documented by reference to the base class, if that is the normal procedure when subclassing.
History
Date User Action Args
2014-06-17 05:49:13demian.brechtsetnosy: + demian.brecht
2014-03-09 23:28:13mvolzsetnosy: + mvolz
2013-10-07 20:13:19terry.reedysetversions: + Python 3.4, - Python 3.2
nosy: - georg.brandl

messages: + msg199158

dependencies: + AttributeError: 'NoneType' in http/client.py when using select when file descriptor is closed.
2011-11-20 12:00:17eric.araujosetnosy: + eric.araujo
2011-11-18 16:27:17ezio.melottisetnosy: + ezio.melotti

resolution: accepted ->
versions: + Python 3.3, - Python 2.6, Python 3.1
2010-06-28 20:42:40orsenthilsetassignee: georg.brandl -> orsenthil
versions: + Python 2.6, Python 3.1, Python 2.7, Python 3.2, - Python 2.5
nosy: + orsenthil

messages: + msg108861
resolution: accepted
stage: needs patch
2010-06-28 20:24:30ThomasHsetstatus: pending -> open

messages: + msg108857
2010-06-09 23:45:28terry.reedysetstatus: open -> pending
nosy: + terry.reedy
messages: + msg107442

2008-07-22 17:31:20ThomasHcreate