[Python-checkins] [Python-Dev] cpython (3.3): Issue #17860: explicitly mention that std* streams are opened in binary mode by

[Ronald Oussoren]

On 6 Jul, 2013, at 13:59, R. David Murray <rdmurray at bitdance.com> wrote:

> On Sat, 06 Jul 2013 10:25:19 +0200, ronald.oussoren <python-checkins at python.org> wrote:
>> http://hg.python.org/cpython/rev/a2c2ffa1a41c
>> changeset:   84453:a2c2ffa1a41c
>> branch:      3.3
>> parent:      84449:df79735b21c1
>> user:        Ronald Oussoren <ronaldoussoren at mac.com>
>> date:        Sat Jul 06 10:23:59 2013 +0200
>> summary:
>>  Issue #17860: explicitly mention that std* streams are opened in binary mode by default.
>> 
>> The documentation does mention that the streams are opened in text mode
>> when univeral_newlines is true, but not that that they are opened in
>> binary mode when that argument is false and that seems to confuse at
>> least some users.
>> 
>> files:
>>  Doc/library/subprocess.rst |  6 ++++--
>>  1 files changed, 4 insertions(+), 2 deletions(-)
>> 
>> 
>> diff --git a/Doc/library/subprocess.rst b/Doc/library/subprocess.rst
>> --- a/Doc/library/subprocess.rst
>> +++ b/Doc/library/subprocess.rst
>> @@ -293,7 +293,8 @@
>>    If *universal_newlines* is ``True``, the file objects *stdin*, *stdout* and
>>    *stderr* will be opened as text streams in :term:`universal newlines` mode
>>    using the encoding returned by :func:`locale.getpreferredencoding(False)
>> -   <locale.getpreferredencoding>`.  For *stdin*, line ending characters
>> +   <locale.getpreferredencoding>`, otherwise these streams will be opened
>> +   as binary streams.  For *stdin*, line ending characters
>>    ``'\n'`` in the input will be converted to the default line separator
>>    :data:`os.linesep`.  For *stdout* and *stderr*, all line endings in the
>>    output will be converted to ``'\n'``.  For more information see the
> 
> IMO, either the default should be mentioned first, or the default
> should be mentioned in a parenthetical.  Otherwise it sounds like
> newline translation is being done in both modes.  Logically that makes
> no sense, so the above construction will likely lead to, at a minimum,
> an interruption in the flow for the reader, and at worse even more
> confusion than not mentioning it at all.

You've got a point there. Converting the next text (", otherwise ...") to a parententical
seems to be the cleanest fix, creating a separate sentence for the ``False`` case introduces
duplication unless I restructure the text.

Ronald

> 
> --David
> _______________________________________________
> Python-Dev mailing list
> Python-Dev at python.org
> http://mail.python.org/mailman/listinfo/python-dev
> Unsubscribe: http://mail.python.org/mailman/options/python-dev/ronaldoussoren%40mac.com