Re: [Python-Dev] [Python-checkins] cpython (3.3): Issue #17860: explicitly mention that std* streams are opened in binary mode by
On Sat, 06 Jul 2013 10:25:19 +0200, ronald.oussoren <python-checkins@python.org> wrote:
http://hg.python.org/cpython/rev/a2c2ffa1a41c changeset: 84453:a2c2ffa1a41c branch: 3.3 parent: 84449:df79735b21c1 user: Ronald Oussoren <ronaldoussoren@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. --David
On 6 Jul, 2013, at 13:59, R. David Murray <rdmurray@bitdance.com> wrote:
On Sat, 06 Jul 2013 10:25:19 +0200, ronald.oussoren <python-checkins@python.org> wrote:
http://hg.python.org/cpython/rev/a2c2ffa1a41c changeset: 84453:a2c2ffa1a41c branch: 3.3 parent: 84449:df79735b21c1 user: Ronald Oussoren <ronaldoussoren@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@python.org http://mail.python.org/mailman/listinfo/python-dev Unsubscribe: http://mail.python.org/mailman/options/python-dev/ronaldoussoren%40mac.com
On 6 Jul, 2013, at 14:09, Ronald Oussoren <ronaldoussoren@mac.com> wrote:
On 6 Jul, 2013, at 13:59, R. David Murray <rdmurray@bitdance.com> wrote:
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.
I didn't like the parenthentical after all. Would this work for you?: - If *universal_newlines* is ``True``, the file objects *stdin*, *stdout* and - *stderr* will be opened as text streams in :term:`universal newlines` mode + If *universal_newlines* is ``False`` the file objects *stdin*, *stdout* and + *stderr* will be opened as binary streams, and no line ending conversion is done. + + If *universal_newlines* is ``True``, these file objects + will be opened as text streams in :term:`universal newlines` mode using the encoding returned by :func:`locale.getpreferredencoding(False) - <locale.getpreferredencoding>`, otherwise these streams will be opened - as binary streams. For *stdin*, line ending characters + <locale.getpreferredencoding>`. 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 That is, a new paragraph is added before the existing one to explain the behavior of "not universal_newlines". Ronald
Ronald
--David _______________________________________________ Python-Dev mailing list Python-Dev@python.org http://mail.python.org/mailman/listinfo/python-dev Unsubscribe: http://mail.python.org/mailman/options/python-dev/ronaldoussoren%40mac.com
_______________________________________________ Python-Dev mailing list Python-Dev@python.org http://mail.python.org/mailman/listinfo/python-dev Unsubscribe: http://mail.python.org/mailman/options/python-dev/ronaldoussoren%40mac.com
Please update the docstring in subprocess.py with the wording improvements that you settle on while you're at it. On Sat, Jul 6, 2013 at 6:03 AM, Ronald Oussoren <ronaldoussoren@mac.com>wrote:
On 6 Jul, 2013, at 14:09, Ronald Oussoren <ronaldoussoren@mac.com> wrote:
On 6 Jul, 2013, at 13:59, R. David Murray <rdmurray@bitdance.com> wrote:
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.
I didn't like the parenthentical after all. Would this work for you?:
- If *universal_newlines* is ``True``, the file objects *stdin*, *stdout* and - *stderr* will be opened as text streams in :term:`universal newlines` mode + If *universal_newlines* is ``False`` the file objects *stdin*, *stdout* and + *stderr* will be opened as binary streams, and no line ending conversion is done. + + If *universal_newlines* is ``True``, these file objects + will be opened as text streams in :term:`universal newlines` mode using the encoding returned by :func:`locale.getpreferredencoding(False) - <locale.getpreferredencoding>`, otherwise these streams will be opened - as binary streams. For *stdin*, line ending characters + <locale.getpreferredencoding>`. 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
That is, a new paragraph is added before the existing one to explain the behavior of "not universal_newlines".
Ronald
Ronald
--David _______________________________________________ Python-Dev mailing list Python-Dev@python.org http://mail.python.org/mailman/listinfo/python-dev Unsubscribe:
http://mail.python.org/mailman/options/python-dev/ronaldoussoren%40mac.com
_______________________________________________ Python-Dev mailing list Python-Dev@python.org http://mail.python.org/mailman/listinfo/python-dev Unsubscribe:
http://mail.python.org/mailman/options/python-dev/ronaldoussoren%40mac.com
_______________________________________________ Python-Dev mailing list Python-Dev@python.org http://mail.python.org/mailman/listinfo/python-dev Unsubscribe: http://mail.python.org/mailman/options/python-dev/greg%40krypto.org
On Sat, 06 Jul 2013 08:14:26 -0700, "Gregory P. Smith" <greg@krypto.org> wrote:
Please update the docstring in subprocess.py with the wording improvements that you settle on while you're at it.
On Sat, Jul 6, 2013 at 6:03 AM, Ronald Oussoren <ronaldoussoren@mac.com>wrote:
I didn't like the parenthentical after all. Would this work for you?:
- If *universal_newlines* is ``True``, the file objects *stdin*, *stdout* and - *stderr* will be opened as text streams in :term:`universal newlines` mode + If *universal_newlines* is ``False`` the file objects *stdin*, *stdout* and + *stderr* will be opened as binary streams, and no line ending conversion is done. + + If *universal_newlines* is ``True``, these file objects + will be opened as text streams in :term:`universal newlines` mode using the encoding returned by :func:`locale.getpreferredencoding(False) - <locale.getpreferredencoding>`, otherwise these streams will be opened - as binary streams. For *stdin*, line ending characters + <locale.getpreferredencoding>`. 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
That is, a new paragraph is added before the existing one to explain the behavior of "not universal_newlines".
Looks good to me. --David
participants (3)
-
Gregory P. Smith -
R. David Murray -
Ronald Oussoren