This issue tracker has been migrated to GitHub, and is currently read-only.
For more information, see the GitHub FAQs in the Python's Developer Guide.

classification
Title: update subprocess docs to reference io.TextIOWrapper
Type: Stage: resolved
Components: Documentation Versions: Python 3.2, Python 3.3
process
Status: closed Resolution: fixed
Dependencies: 15638 Superseder:
Assigned To: docs@python Nosy List: asvetlov, benjamin.peterson, chris.jerdonek, docs@python, hynek, pitrou, python-dev, stutzbach, vstinner
Priority: normal Keywords: easy, patch

Created on 2012-08-05 19:51 by chris.jerdonek, last changed 2022-04-11 14:57 by admin. This issue is now closed.

Files
File name Uploaded Description Edit
issue-subprocess-docs-1.patch chris.jerdonek, 2012-08-05 19:51 review
issue-15561-2-branch-32.patch chris.jerdonek, 2012-08-09 19:37
issue-15561-2-branch-default.patch chris.jerdonek, 2012-08-09 19:38
issue-15561-3-branch-32.patch chris.jerdonek, 2012-08-13 15:33
issue-15561-3-branch-default-delta.patch chris.jerdonek, 2012-08-13 15:39
Messages (17)
msg167512 - (view) Author: Chris Jerdonek (chris.jerdonek) * (Python committer) Date: 2012-08-05 19:51
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.
msg167584 - (view) Author: Chris Jerdonek (chris.jerdonek) * (Python committer) Date: 2012-08-06 21:17
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.
msg167658 - (view) Author: Chris Jerdonek (chris.jerdonek) * (Python committer) Date: 2012-08-08 04:30
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
msg167790 - (view) Author: Chris Jerdonek (chris.jerdonek) * (Python committer) Date: 2012-08-09 15:32
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.
msg167791 - (view) Author: Andrew Svetlov (asvetlov) * (Python committer) Date: 2012-08-09 15:35
Please do.
msg167823 - (view) Author: Chris Jerdonek (chris.jerdonek) * (Python committer) Date: 2012-08-09 19:38
I have uploaded updated patches for both 3.2 and the default branch.  Thanks, Andrew.
msg167976 - (view) Author: Andrew Svetlov (asvetlov) * (Python committer) Date: 2012-08-11 15:47
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?
msg167992 - (view) Author: Chris Jerdonek (chris.jerdonek) * (Python committer) Date: 2012-08-11 19:08
> 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.
msg168081 - (view) Author: Andrew Svetlov (asvetlov) * (Python committer) Date: 2012-08-13 12:04
Do you mean to mention stdin as well as stdout/stderr? It will be nice.
msg168085 - (view) Author: Chris Jerdonek (chris.jerdonek) * (Python committer) Date: 2012-08-13 12:15
Yes, that too. :) I am working on it.
msg168094 - (view) Author: Chris Jerdonek (chris.jerdonek) * (Python committer) Date: 2012-08-13 12:40
For 3.2 to mention write_through, issue 15638 should probably be fixed first.  I can create a patch for that first.
msg168106 - (view) Author: Chris Jerdonek (chris.jerdonek) * (Python committer) Date: 2012-08-13 13:18
> 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.
msg168119 - (view) Author: Chris Jerdonek (chris.jerdonek) * (Python committer) Date: 2012-08-13 15:33
Andrew, here is the new patch for 3.2.  3.3 will come shortly after.
msg168121 - (view) Author: Chris Jerdonek (chris.jerdonek) * (Python committer) Date: 2012-08-13 15:39
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).
msg168134 - (view) Author: Roundup Robot (python-dev) (Python triager) Date: 2012-08-13 19:11
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
msg168135 - (view) Author: Andrew Svetlov (asvetlov) * (Python committer) Date: 2012-08-13 19:16
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.
msg168136 - (view) Author: Chris Jerdonek (chris.jerdonek) * (Python committer) Date: 2012-08-13 19:19
> 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.
History
Date User Action Args
2022-04-11 14:57:33adminsetgithub: 59766
2012-08-13 19:19:58chris.jerdoneksetmessages: + msg168136
2012-08-13 19:16:02asvetlovsetstatus: open -> closed
resolution: fixed
messages: + msg168135

stage: patch review -> resolved
2012-08-13 19:11:26python-devsetnosy: + python-dev
messages: + msg168134
2012-08-13 15:39:05chris.jerdoneksetfiles: + issue-15561-3-branch-default-delta.patch

messages: + msg168121
2012-08-13 15:33:31chris.jerdoneksetfiles: + issue-15561-3-branch-32.patch

messages: + msg168119
2012-08-13 13:18:18chris.jerdoneksetmessages: + msg168106
2012-08-13 12:40:35chris.jerdoneksetdependencies: + incorrect version info for TextIOWrapper write_through docs
messages: + msg168094
2012-08-13 12:15:12chris.jerdoneksetmessages: + msg168085
2012-08-13 12:04:58asvetlovsetmessages: + msg168081
2012-08-11 19:08:16chris.jerdoneksetmessages: + msg167992
2012-08-11 15:47:26asvetlovsetmessages: + msg167976
2012-08-09 19:38:43chris.jerdoneksetfiles: + issue-15561-2-branch-default.patch

messages: + msg167823
2012-08-09 19:37:19chris.jerdoneksetfiles: + issue-15561-2-branch-32.patch
2012-08-09 15:35:47asvetlovsetmessages: + msg167791
2012-08-09 15:32:21chris.jerdoneksetmessages: + msg167790
2012-08-09 13:26:59asvetlovsetnosy: + asvetlov
2012-08-08 04:30:40chris.jerdoneksetnosy: + pitrou, benjamin.peterson, stutzbach, hynek

messages: + msg167658
versions: + Python 3.2
2012-08-06 21:17:57chris.jerdoneksetmessages: + msg167584
2012-08-05 19:51:57chris.jerdonekcreate