[issue15561] update subprocess docs to reference io.TextIOWrapper
New submission from Chris Jerdonek: This is an issue to update the subprocess module documentation after updates to io.TextIOWrapper's documentation here: http://hg.python.org/cpython/rev/f17a1410ebe5 This issue was discussed briefly on python-dev: http://mail.python.org/pipermail/python-dev/2012-August/121239.html Patch attached. ---------- assignee: docs@python components: Documentation files: issue-subprocess-docs-1.patch keywords: easy, patch messages: 167512 nosy: cjerdonek, docs@python, haypo priority: normal severity: normal stage: patch review status: open title: update subprocess docs to reference io.TextIOWrapper versions: Python 3.3 Added file: http://bugs.python.org/file26703/issue-subprocess-docs-1.patch _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue15561> _______________________________________
Chris Jerdonek added the comment: Victor, would you be able to take a look at this minor documentation patch? It incorporates the change that you suggested we make on python-dev. ---------- _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue15561> _______________________________________
Chris Jerdonek added the comment: io module experts: Can one of you review this minor change to the subprocess documentation to make it reference the newly added io.TextIOWrapper documentation changes? For background purposes, digging back, it looks like the original change to subprocess was made here: 9ce8fa0a0899 ---------- nosy: +benjamin.peterson, hynek, pitrou, stutzbach versions: +Python 3.2 _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue15561> _______________________________________
Changes by Andrew Svetlov <andrew.svetlov@gmail.com>: ---------- nosy: +asvetlov _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue15561> _______________________________________
Chris Jerdonek added the comment: In the process of working on issue 15595, I noticed that the documentation change will need to be slightly different for Python 3.2 than for 3.3. In 3.2, it is locale.getpreferredencoding() (which defaults to do_setlocale=True) instead of locale.getpreferredencoding(False). I will provide a patch adjusted for 3.2. ---------- _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue15561> _______________________________________
Andrew Svetlov added the comment: Please do. ---------- _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue15561> _______________________________________
Changes by Chris Jerdonek <chris.jerdonek@gmail.com>: Added file: http://bugs.python.org/file26747/issue-15561-2-branch-32.patch _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue15561> _______________________________________
Chris Jerdonek added the comment: I have uploaded updated patches for both 3.2 and the default branch. Thanks, Andrew. ---------- Added file: http://bugs.python.org/file26748/issue-15561-2-branch-default.patch _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue15561> _______________________________________
Andrew Svetlov added the comment: Hmm. As I can see in subprocess.py TextIOWrapper is applied to stdin also in non-buffered (write_through=True) mode. So input will be converted to use '\n' as well. Can you reflect this fact in your patches? ---------- _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue15561> _______________________________________
Chris Jerdonek added the comment:
Can you reflect this fact in your patches?
Sure. (Though for stdin '\n' is converted to os.linesep and no more.) Would you mind if I also updated the following part of the subprocess documentation to reference the part we are updating, so that the documentation is just in one place? "If universal_newlines is True, the file objects stdout and stderr are opened as text files, but lines may be terminated by any of '\n', the Unix end-of-line convention, '\r', the old Macintosh convention or '\r\n', the Windows convention. All of these external representations are seen as '\n' by the Python program." The part we're updating is in the "Frequently Used Arguments" section and so seems like the natural place for expanded details. ---------- _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue15561> _______________________________________
Andrew Svetlov added the comment: Do you mean to mention stdin as well as stdout/stderr? It will be nice. ---------- _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue15561> _______________________________________
Chris Jerdonek added the comment: Yes, that too. :) I am working on it. ---------- _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue15561> _______________________________________
Chris Jerdonek added the comment: For 3.2 to mention write_through, issue 15638 should probably be fixed first. I can create a patch for that first. ---------- dependencies: +incorrect version info for TextIOWrapper write_through docs _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue15561> _______________________________________
Chris Jerdonek added the comment:
As I can see in subprocess.py TextIOWrapper is applied to stdin also in non-buffered (write_through=True) mode.
In 3.2, I will not mention the write_through argument based on Antoine's response to issue 15638. ---------- _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue15561> _______________________________________
Chris Jerdonek added the comment: Andrew, here is the new patch for 3.2. 3.3 will come shortly after. ---------- Added file: http://bugs.python.org/file26783/issue-15561-3-branch-32.patch _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue15561> _______________________________________
Chris Jerdonek added the comment: Here is the patch for the default/3.3 branch, which for convenience is a diff for the branch *after the 3.2 patch has been forward-ported to 3.3*. I did not think it was necessary to mention write_through specifically since it seems more like an implementation detail (though stdin as a whole is now documented). ---------- Added file: http://bugs.python.org/file26784/issue-15561-3-branch-default-delta.patch _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue15561> _______________________________________
Roundup Robot added the comment: New changeset 381aaf79c254 by Andrew Svetlov in branch '3.2': Issue #15561: Update subprocess docs to reference io.TextIOWrapper. http://hg.python.org/cpython/rev/381aaf79c254 New changeset 0cd9423770fa by Andrew Svetlov in branch 'default': Issue #15561: Update subprocess docs to reference io.TextIOWrapper. http://hg.python.org/cpython/rev/0cd9423770fa ---------- nosy: +python-dev _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue15561> _______________________________________
Andrew Svetlov added the comment: Fixed. BTW I prefer to use «stream» as alias to file object it subprocess context. «file» can clash with «the real file in filesystem» for documentation reader. ---------- resolution: -> fixed stage: patch review -> committed/rejected status: open -> closed _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue15561> _______________________________________
Chris Jerdonek added the comment:
Fixed. BTW I prefer to use «stream» as alias to file object
Thanks a lot, Andrew. Yes, I agree and actually contemplated doing that myself. ---------- _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue15561> _______________________________________
Chris Jerdonek added the comment: Victor, would you be able to take a look at this minor documentation patch? It incorporates the change that you suggested we make on python-dev. ---------- _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue15561> _______________________________________
Chris Jerdonek added the comment: io module experts: Can one of you review this minor change to the subprocess documentation to make it reference the newly added io.TextIOWrapper documentation changes? For background purposes, digging back, it looks like the original change to subprocess was made here: 9ce8fa0a0899 ---------- nosy: +benjamin.peterson, hynek, pitrou, stutzbach versions: +Python 3.2 _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue15561> _______________________________________
Changes by Andrew Svetlov <andrew.svetlov@gmail.com>: ---------- nosy: +asvetlov _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue15561> _______________________________________
Chris Jerdonek added the comment: In the process of working on issue 15595, I noticed that the documentation change will need to be slightly different for Python 3.2 than for 3.3. In 3.2, it is locale.getpreferredencoding() (which defaults to do_setlocale=True) instead of locale.getpreferredencoding(False). I will provide a patch adjusted for 3.2. ---------- _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue15561> _______________________________________
Andrew Svetlov added the comment: Please do. ---------- _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue15561> _______________________________________
Changes by Chris Jerdonek <chris.jerdonek@gmail.com>: Added file: http://bugs.python.org/file26747/issue-15561-2-branch-32.patch _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue15561> _______________________________________
Chris Jerdonek added the comment: I have uploaded updated patches for both 3.2 and the default branch. Thanks, Andrew. ---------- Added file: http://bugs.python.org/file26748/issue-15561-2-branch-default.patch _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue15561> _______________________________________
Andrew Svetlov added the comment: Hmm. As I can see in subprocess.py TextIOWrapper is applied to stdin also in non-buffered (write_through=True) mode. So input will be converted to use '\n' as well. Can you reflect this fact in your patches? ---------- _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue15561> _______________________________________
Chris Jerdonek added the comment:
Can you reflect this fact in your patches?
Sure. (Though for stdin '\n' is converted to os.linesep and no more.) Would you mind if I also updated the following part of the subprocess documentation to reference the part we are updating, so that the documentation is just in one place? "If universal_newlines is True, the file objects stdout and stderr are opened as text files, but lines may be terminated by any of '\n', the Unix end-of-line convention, '\r', the old Macintosh convention or '\r\n', the Windows convention. All of these external representations are seen as '\n' by the Python program." The part we're updating is in the "Frequently Used Arguments" section and so seems like the natural place for expanded details. ---------- _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue15561> _______________________________________
Andrew Svetlov added the comment: Do you mean to mention stdin as well as stdout/stderr? It will be nice. ---------- _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue15561> _______________________________________
Chris Jerdonek added the comment: Yes, that too. :) I am working on it. ---------- _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue15561> _______________________________________
Chris Jerdonek added the comment: For 3.2 to mention write_through, issue 15638 should probably be fixed first. I can create a patch for that first. ---------- dependencies: +incorrect version info for TextIOWrapper write_through docs _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue15561> _______________________________________
Chris Jerdonek added the comment:
As I can see in subprocess.py TextIOWrapper is applied to stdin also in non-buffered (write_through=True) mode.
In 3.2, I will not mention the write_through argument based on Antoine's response to issue 15638. ---------- _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue15561> _______________________________________
Chris Jerdonek added the comment: Andrew, here is the new patch for 3.2. 3.3 will come shortly after. ---------- Added file: http://bugs.python.org/file26783/issue-15561-3-branch-32.patch _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue15561> _______________________________________
Chris Jerdonek added the comment: Here is the patch for the default/3.3 branch, which for convenience is a diff for the branch *after the 3.2 patch has been forward-ported to 3.3*. I did not think it was necessary to mention write_through specifically since it seems more like an implementation detail (though stdin as a whole is now documented). ---------- Added file: http://bugs.python.org/file26784/issue-15561-3-branch-default-delta.patch _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue15561> _______________________________________
Roundup Robot added the comment: New changeset 381aaf79c254 by Andrew Svetlov in branch '3.2': Issue #15561: Update subprocess docs to reference io.TextIOWrapper. http://hg.python.org/cpython/rev/381aaf79c254 New changeset 0cd9423770fa by Andrew Svetlov in branch 'default': Issue #15561: Update subprocess docs to reference io.TextIOWrapper. http://hg.python.org/cpython/rev/0cd9423770fa ---------- nosy: +python-dev _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue15561> _______________________________________
Andrew Svetlov added the comment: Fixed. BTW I prefer to use «stream» as alias to file object it subprocess context. «file» can clash with «the real file in filesystem» for documentation reader. ---------- resolution: -> fixed stage: patch review -> committed/rejected status: open -> closed _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue15561> _______________________________________
Chris Jerdonek added the comment:
Fixed. BTW I prefer to use «stream» as alias to file object
Thanks a lot, Andrew. Yes, I agree and actually contemplated doing that myself. ---------- _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue15561> _______________________________________
participants (3)
-
Andrew Svetlov -
Chris Jerdonek
-
Roundup Robot