This issue tracker has been migrated to GitHub, and is currently read-only.
For more information, see the GitHub FAQs in the Python's Developer Guide.

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

Created on 2008-09-12 19:05 by raz, last changed 2022-04-11 14:56 by admin. This issue is now closed.

Messages (4)
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...."
msg391957 - (view) Author: Irit Katriel (iritkatriel) * (Python committer) Date: 2021-04-26 17:46
This caveat no longer appear in the doc, and I could not find anything similar, so I am concluding this is no longer relevant.
Date User Action Args
2022-04-11 14:56:39adminsetgithub: 48099
2021-04-26 17:46:15iritkatrielsetstatus: open -> closed

nosy: + iritkatriel
messages: + msg391957

resolution: out of date
stage: needs patch -> resolved
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