clarify newline documentation for open and io.TextIOWrapper.

[cjerdonek]

BPO	15624
Nosy	@asvetlov, @cjerdonek

^{Note: these values reflect the state of the issue at the time it was migrated and might not reflect the current state.}

Show more details

GitHub fields:

assignee = None
closed_at = <Date 2012-08-13.10:00:56.820>
created_at = <Date 2012-08-11.19:14:23.799>
labels = ['easy', 'docs']
title = 'clarify newline documentation for open and io.TextIOWrapper.'
updated_at = <Date 2012-08-13.11:29:26.652>
user = 'https://github.com/cjerdonek'

bugs.python.org fields:

activity = <Date 2012-08-13.11:29:26.652>
actor = 'chris.jerdonek'
assignee = 'docs@python'
closed = True
closed_date = <Date 2012-08-13.10:00:56.820>
closer = 'asvetlov'
components = ['Documentation']
creation = <Date 2012-08-11.19:14:23.799>
creator = 'chris.jerdonek'
dependencies = []
files = []
hgrepos = []
issue_num = 15624
keywords = ['easy']
message_count = 6.0
messages = ['167995', '167996', '168074', '168075', '168076', '168079']
nosy_count = 4.0
nosy_names = ['asvetlov', 'chris.jerdonek', 'docs@python', 'python-dev']
pr_nums = []
priority = 'normal'
resolution = 'fixed'
stage = 'resolved'
status = 'closed'
superseder = None
type = None
url = 'https://bugs.python.org/issue15624'
versions = ['Python 3.2', 'Python 3.3']

[cjerdonek]

The documentation of io.TextIOWrapper's newline argument is somewhat confusing and perhaps reversed from what was intended. (For example, the subprocess module uses the reverse terminology.) Either way, it can be improved somewhat. Currently, it says--

"* On input, if newline is None,... Lines in the input can end in '\n', '\r', or '\r\n', and these are translated into '\n' before being returned to the caller...

• On output, if newline is None, any '\n' characters written are translated to the system default line separator, os.linesep..."

(from http://docs.python.org/dev/library/io.html#io.TextIOWrapper )

It is somewhat confusing because "On input" does not mean "On input to the buffer," and "On output" does not mean "On output from the buffer." It is the reverse.

A minimal change to address this would be something along the lines of--

"On input" -> "When reading input from the buffer"
"On output" -> "When writing output to the buffer

The same change could also be made to the open() documentation:

http://docs.python.org/dev/library/functions.html#open

I can prepare a patch for affected versions.

[cjerdonek]

Andrew, I'm adding you because this is the documentation that the subprocess module will point to after bpo-15561.

[asvetlov]

For me input means «reading from» and output — «writing to».

Nevertheless I'm ok with you suggestion.

[python-dev]

New changeset 5b629e9fde61 by Andrew Svetlov in branch '3.2':
Issue bpo-15624: clarify newline documentation for open and io.TextIOWrapper
http://hg.python.org/cpython/rev/5b629e9fde61

New changeset 9e098890ea2c by Andrew Svetlov in branch 'default':
Issue bpo-15624: clarify newline documentation for open and io.TextIOWrapper
http://hg.python.org/cpython/rev/9e098890ea2c

[asvetlov]

Close as fixed. Thanks.

[cjerdonek]

Thanks a lot, Andrew.