[New-bugs-announce] [issue15624] clarify io.TextIOWrapper newline documentation

[Chris Jerdonek]

New submission from Chris Jerdonek:

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.

----------
assignee: docs at python
components: Documentation
keywords: easy
messages: 167995
nosy: cjerdonek, docs at python
priority: normal
severity: normal
status: open
title: clarify io.TextIOWrapper newline documentation

_______________________________________
Python tracker <report at bugs.python.org>
<http://bugs.python.org/issue15624>
_______________________________________