classification
Title: Tutorial: write() does not expect string in binary mode
Type: enhancement Stage: resolved
Components: Documentation Versions: Python 3.6, Python 3.5
process
Status: closed Resolution: fixed
Dependencies: Superseder:
Assigned To: ezio.melotti Nosy List: Dimitri Papadopoulos Orfanos, Elena.Oat, docs@python, ezio.melotti, python-dev, terry.reedy, upendra-k14
Priority: normal Keywords: patch

Created on 2016-01-03 13:56 by Dimitri Papadopoulos Orfanos, last changed 2016-01-12 09:30 by ezio.melotti. This issue is now closed.

Files
File name Uploaded Description Edit
fileiotutorial.patch upendra-k14, 2016-01-04 02:13 Update in tutorial/inputoutput.rst related to read() and write() methods
issue26001.diff Elena.Oat, 2016-01-09 14:58 review
Messages (6)
msg257418 - (view) Author: Dimitri Papadopoulos Orfanos (Dimitri Papadopoulos Orfanos) Date: 2016-01-03 13:56
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
msg257436 - (view) Author: Upendra Kumar (upendra-k14) * Date: 2016-01-04 02:13
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.
msg257771 - (view) Author: Terry J. Reedy (terry.reedy) * (Python committer) Date: 2016-01-08 18:11
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.
msg257840 - (view) Author: Elena Oat (Elena.Oat) * Date: 2016-01-09 14:58
Wrapped the lines to 80 chars.
msg258087 - (view) Author: Roundup Robot (python-dev) (Python triager) Date: 2016-01-12 09:28
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
msg258088 - (view) Author: Ezio Melotti (ezio.melotti) * (Python committer) Date: 2016-01-12 09:30
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.
History
Date User Action Args
2016-01-12 09:30:02ezio.melottisetstatus: open -> closed

assignee: docs@python -> ezio.melotti

nosy: + ezio.melotti
messages: + msg258088
resolution: fixed
stage: patch review -> resolved
2016-01-12 09:28:11python-devsetnosy: + python-dev
messages: + msg258087
2016-01-09 14:58:56Elena.Oatsetfiles: + issue26001.diff
nosy: + Elena.Oat
messages: + msg257840

2016-01-08 18:11:10terry.reedysetnosy: + terry.reedy
messages: + msg257771
2016-01-08 17:48:34ezio.melottisetstage: patch review
type: enhancement
versions: + Python 3.6
2016-01-04 02:13:59upendra-k14setfiles: + fileiotutorial.patch

nosy: + upendra-k14
messages: + msg257436

keywords: + patch
2016-01-03 13:56:15Dimitri Papadopoulos Orfanoscreate