[issue26001] Tutorial: write() does not expect string in binary mode
New submission from Dimitri Papadopoulos Orfanos: About section "7.2.1. Methods of File Objects" of the tutorial: 1. Method read() is documented as follows: reads some quantity of data and returns it as a string or bytes object. Indeed read() returns a string in text mode and bytes in binary mode. For the sake of clarity, I suggest changing to: reads some quantity of data and returns it as a string (in text mode) or bytes object (in binary mode). This might seem long-winded but I believe it would help those moving from Python 2 to Python 3. 2. Method write() is documented as follows: To write something other than a string, it needs to be converted to a string first While this is correct in text mode, it is wrong in binary mode. May I suggest: To write something other than a string (in text mode) or bytes object (in binary mode), it needs to be converted first ---------- assignee: docs@python components: Documentation messages: 257418 nosy: Dimitri Papadopoulos Orfanos, docs@python priority: normal severity: normal status: open title: Tutorial: write() does not expect string in binary mode versions: Python 3.5 _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue26001> _______________________________________
Upendra Kumar added the comment: I also think that for better clarification, binary mode and text mode should be specified clearly for both methods read() and write(). For read(), I have changed it to: ' some quantity of data and returns it as a string (in text mode) or bytes object (in binary mode).' For write(), I have changed it to: ' To write something other than a string (in text mode) or bytes object (in binary mode), it needs to be converted first to string or bytes object respectively. ' Please if someone could review it, as I have not submitted a patch related to docs before. And I am not sure, if I have made correct changes at right place. ---------- keywords: +patch nosy: +upendra-k14 Added file: http://bugs.python.org/file41486/fileiotutorial.patch _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue26001> _______________________________________
Changes by Ezio Melotti <ezio.melotti@gmail.com>: ---------- stage: -> patch review type: -> enhancement versions: +Python 3.6 _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue26001> _______________________________________
Terry J. Reedy added the comment: Lines should be kept to about 80 chars. Both chunks needs a newline added. I think it okay to create short lines rather than re-wrapping the whole paragraph. ---------- nosy: +terry.reedy _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue26001> _______________________________________
Elena Oat added the comment: Wrapped the lines to 80 chars. ---------- nosy: +Elena.Oat Added file: http://bugs.python.org/file41556/issue26001.diff _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue26001> _______________________________________
Roundup Robot added the comment: New changeset 5a2692911a43 by Ezio Melotti in branch '3.5': #26001: mention in the tutorial that files in binary mode expect bytes, not str. https://hg.python.org/cpython/rev/5a2692911a43 New changeset 4b434a4770a9 by Ezio Melotti in branch 'default': #26001: merge with 3.5. https://hg.python.org/cpython/rev/4b434a4770a9 ---------- nosy: +python-dev _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue26001> _______________________________________
Ezio Melotti added the comment: Fixed, thanks Dimistri for the report, Upendra for the patch, Terry for the review, and Elena for the rewrapping! I also rephrased the last sentence a bit to make it more readable. ---------- assignee: docs@python -> ezio.melotti nosy: +ezio.melotti resolution: -> fixed stage: patch review -> resolved status: open -> closed _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue26001> _______________________________________
participants (6)
-
Dimitri Papadopoulos Orfanos -
Elena Oat
-
Ezio Melotti
-
Roundup Robot
-
Terry J. Reedy
-
Upendra Kumar