classification
Title: docs: note that subprocess doesn't replace os.exec*
Type: enhancement Stage: resolved
Components: Documentation Versions: Python 3.3, Python 3.4, Python 2.7
process
Status: closed Resolution: fixed
Dependencies: Superseder:
Assigned To: docs@python Nosy List: Anastasia.Filatova, docs@python, ezio.melotti, loewis, python-dev, r.david.murray, techtonik, terry.reedy
Priority: normal Keywords: easy, patch

Created on 2013-09-21 07:29 by techtonik, last changed 2014-03-17 06:31 by python-dev. This issue is now closed.

Files
File name Uploaded Description Edit
Issue19060.patch Anastasia.Filatova, 2014-03-11 21:55 review
Issue19060_py33.patch Anastasia.Filatova, 2014-03-12 11:54 review
Issue19060_py34.patch Anastasia.Filatova, 2014-03-12 11:55 review
Issue19060_py27.patch Anastasia.Filatova, 2014-03-12 11:55 review
Messages (12)
msg198188 - (view) Author: anatoly techtonik (techtonik) Date: 2013-09-21 07:29
I always thought that subprocess is replacing all other methods of executing external programs from Python and it is a preferred way. Perhaps I was not attentive that people isolate:
  os.system
  os.spawn*
  os.popen*
and
  os.exec*

While subprocess replaces three first, it doesn't do this with the last one. The documentation should mention this in the header block. Proposed edit:

  ...
  replace several other, older modules and functions, such as:

     os.system
     os.spawn*
     os.popen*
     popen2.*
     commands.*

+ Note that it doesn't replace other ways of executing external
+ processes from Python, such as:
+
+    os.exec*

  Information about how the subprocess module can be used
  ...
msg198189 - (view) Author: anatoly techtonik (techtonik) Date: 2013-09-21 07:30
tag:easy (meaning, please mark it as easy for OpenHatch robots)
msg198545 - (view) Author: Terry J. Reedy (terry.reedy) * (Python committer) Date: 2013-09-28 19:30
The problem with the current text is 'such as', implying that there are other unlisted items that could have (should have?) been added to make the list complete. If the list is complete, 'such as' could just be removed. If a sentence were added, I would simplify it to
"It does not replace os.exec*." or perhaps "os.fork and os.exec*.".
msg198572 - (view) Author: anatoly techtonik (techtonik) Date: 2013-09-29 09:29
I would like to know if the list is complete too. It would be
extremely awesome if it was complete.

This raises a side issue that there seems no guideline to write
unambiguous and complete documentation. I spammed the tracker with
this stuff in issue19121.
msg198573 - (view) Author: anatoly techtonik (techtonik) Date: 2013-09-29 09:32
On Sat, Sep 28, 2013 at 10:30 PM, Terry J. Reedy <report@bugs.python.org> wrote:
>
> If a sentence were added, I would simplify it to
> "It does not replace os.exec*." or perhaps "os.fork and os.exec*.".

I prefer list. It is easier to scan:
http://www.nngroup.com/articles/how-users-read-on-the-web/
msg213178 - (view) Author: (Anastasia.Filatova) * Date: 2014-03-11 21:55
Hello,
I've made patch which address this issue. Could you please review it?
msg213185 - (view) Author: R. David Murray (r.david.murray) * (Python committer) Date: 2014-03-11 23:19
Anastasia, thanks for the patch, but the change being suggested here is just the adding of the note that it does not replace os.exec or os.fork.  The listing of what things it does replace is already correct (it differs between python2 and python3, which is why Anatoly's list has things in it that aren't in the python3 doc).

Personally I don't think that adding the note is useful.  The list of things subprocess doesn't replace is much less well defined than what it does replace.  I think we should just list the former, as we do.

So, I prefer going with removing 'such as', and treating it as a bug if there is something in the stdlib that subprocess should (normally) be used in place of that is not included in this list.
msg213195 - (view) Author: Terry J. Reedy (terry.reedy) * (Python committer) Date: 2014-03-12 02:44
I agree with David about not adding the note. Simplify "This module intends to replace several other, older modules and functions, such as:" to "This module replaces several older modules and functions:".

The 2.7 list has 'popen*', which would include 'popen', which exists in 3.x but is not in the 3.x list. The 2.7 docs mark 'popen' as deprecated and replaced by subprocess, the same as for popen2,3,4. The 3.3 docs no longer mark popen as deprecated. Did it become undeprecated? Should the 2.7 'popen*' be changed to 'popen[2-4]'?
msg213252 - (view) Author: (Anastasia.Filatova) * Date: 2014-03-12 11:54
David, Terry, thank you for my patch review. I took into consideration your comments and corrected text for specified versions as you said. I decided don't change 'popen*' to 'popen[2-4]' to keep text in one format but the final decision is up to you.
msg213259 - (view) Author: R. David Murray (r.david.murray) * (Python committer) Date: 2014-03-12 14:20
Terry: good point.  popen did become undeprecated, however, its implementation was replaced by calls to subprocess.  The reason it is kept is that it is an easy shorthand for various common operations...that is, it is a convenience function, even though it lives in the os module for historical reasons.

So, the 2.7 list is correct (popen still uses the syscall there), and the python3 list is correct (popen is fine to use in python3).  It is perhaps worth mentioning that os.popen is a convenience function in the subprocess docs, but I'm not sure where to put it.  (I see that the popen docs also need updating, but that should be a separate issue, if someone wants to create it.)

Anastasia: thanks, that patch looks good to me.
msg213347 - (view) Author: Roundup Robot (python-dev) (Python triager) Date: 2014-03-13 02:42
New changeset 1d31060f8a5c by Benjamin Peterson in branch '2.7':
remove unnecessary word (closes #19060)
http://hg.python.org/cpython/rev/1d31060f8a5c

New changeset 4d8a9d12edfa by Benjamin Peterson in branch '3.3':
remove unnecessary word (closes #19060)
http://hg.python.org/cpython/rev/4d8a9d12edfa

New changeset 6f93ab911d5d by Benjamin Peterson in branch 'default':
merge 3.3 (#19060)
http://hg.python.org/cpython/rev/6f93ab911d5d
msg213833 - (view) Author: Roundup Robot (python-dev) (Python triager) Date: 2014-03-17 06:31
New changeset d2ad2e04dc9d by Benjamin Peterson in branch '3.4':
merge 3.3 (#19060)
http://hg.python.org/cpython/rev/d2ad2e04dc9d
History
Date User Action Args
2014-03-17 06:31:11python-devsetmessages: + msg213833
2014-03-13 02:42:20python-devsetstatus: open -> closed

nosy: + python-dev
messages: + msg213347

resolution: fixed
stage: needs patch -> resolved
2014-03-12 14:20:19r.david.murraysetmessages: + msg213259
2014-03-12 11:55:17Anastasia.Filatovasetfiles: + Issue19060_py27.patch
2014-03-12 11:55:03Anastasia.Filatovasetfiles: + Issue19060_py34.patch
2014-03-12 11:54:49Anastasia.Filatovasetfiles: + Issue19060_py33.patch

messages: + msg213252
2014-03-12 02:44:07terry.reedysetmessages: + msg213195
2014-03-11 23:19:50r.david.murraysetmessages: - msg213184
2014-03-11 23:19:41r.david.murraysetmessages: + msg213185
2014-03-11 23:17:57r.david.murraysetnosy: + r.david.murray
messages: + msg213184
2014-03-11 21:55:01Anastasia.Filatovasetfiles: + Issue19060.patch

nosy: + Anastasia.Filatova
messages: + msg213178

keywords: + patch
2013-10-05 21:21:32ezio.melottisetnosy: + ezio.melotti

type: enhancement
stage: needs patch
2013-09-29 09:32:41techtoniksetmessages: + msg198573
2013-09-29 09:29:56techtoniksetmessages: + msg198572
2013-09-28 19:30:42terry.reedysetversions: - Python 2.6, Python 3.1, Python 3.2, Python 3.5
nosy: + loewis, terry.reedy

messages: + msg198545

keywords: + easy
2013-09-21 07:30:46techtoniksetmessages: + msg198189
2013-09-21 07:29:55techtonikcreate