classification
Title: FUD in documentation for urllib.urlopen()
Type: behavior Stage: needs patch
Components: Documentation Versions: Python 2.7
process
Status: open Resolution:
Dependencies: Superseder:
Assigned To: docs@python Nosy List: benjamin.peterson, chris.jerdonek, docs@python, dstanek, georg.brandl, mvolz, orsenthil, raz, xcombelle
Priority: normal Keywords:

Created on 2008-09-12 19:05 by raz, last changed 2014-03-11 18:04 by xcombelle.

Messages (3)
msg73122 - (view) Author: raz (raz) Date: 2008-09-12 19:05
The documentation for urllib.urlopen() states:

"One caveat: the read() method, if the size argument is omitted or
negative, may not read until the end of the data stream; there is no
good way to determine that the entire stream from a socket has been read
in the general case."

To an innocent reader this effectively translates to:
"The read() method may silently truncate your data but we won't tell you
any details about it."

The paragraph should be clarified as follows:

- Under what circumstances can truncation happen (which protocols are
affected, under which conditions?)
- What are safe use-cases where truncation can not happen (e.g. the
common case of a simple HTTP-GET)
msg73139 - (view) Author: Benjamin Peterson (benjamin.peterson) * (Python committer) Date: 2008-09-12 20:35
Would you be interested in working on a patch?
msg171798 - (view) Author: Chris Jerdonek (chris.jerdonek) * (Python committer) Date: 2012-10-02 13:12
The section of the Dev Guide on "affirmative tone" should also be applied:

"The documentation focuses on affirmatively stating what the language does and how to use it effectively...."

http://docs.python.org/devguide/documenting.html#affirmative-tone
History
Date User Action Args
2014-03-11 18:04:54xcombellesetnosy: + xcombelle
2014-03-09 23:31:39mvolzsetnosy: + mvolz
2013-11-06 19:16:20akuchlingsetkeywords: - easy
2012-10-02 13:12:47chris.jerdoneksetnosy: + chris.jerdonek
messages: + msg171798
2012-10-02 06:18:31ezio.melottisetkeywords: + easy
versions: + Python 2.7, - Python 2.6, Python 3.0
2011-11-12 05:05:29eli.benderskysetnosy: - eli.bendersky
2011-01-27 03:56:49eli.benderskysetnosy: + eli.bendersky
2011-01-26 17:54:40dstaneksetnosy: + dstanek
2010-08-02 19:29:00georg.brandlsetassignee: georg.brandl -> docs@python

nosy: + docs@python
2009-02-12 18:53:13ajaksu2setnosy: + orsenthil
stage: needs patch
versions: + Python 2.6, Python 3.0, - Python 2.5, Python 2.4
2008-09-12 20:35:47benjamin.petersonsetnosy: + benjamin.peterson
messages: + msg73139
2008-09-12 19:05:42razcreate