Repository navigation
os.popen documentation is probably wrong #50739
Description
| BPO | 6490 |
|---|---|
| Nosy | @malemburg, @gvanrossum, @akuchling, @birkenfeld, @amauryfa, @vstinner, @benjaminp, @ezio-melotti, @merwok, @bitdancer, @vadmium |
| Files |
Note: these values reflect the state of the issue at the time it was migrated and might not reflect the current state.
Show more details
GitHub fields:
assignee = 'https://github.com/merwok'
closed_at = <Date 2014-04-16.13:11:39.209>
created_at = <Date 2009-07-15.08:35:38.269>
labels = ['type-bug', 'docs']
title = 'os.popen documentation is probably wrong'
updated_at = <Date 2014-04-16.13:11:39.208>
user = 'https://bugs.python.org/krawyoti'bugs.python.org fields:
activity = <Date 2014-04-16.13:11:39.208>
actor = 'akuchling'
assignee = 'eric.araujo'
closed = True
closed_date = <Date 2014-04-16.13:11:39.209>
closer = 'akuchling'
components = ['Documentation']
creation = <Date 2009-07-15.08:35:38.269>
creator = 'krawyoti'
dependencies = []
files = ['14509', '19674', '22188', '34896', '34902']
hgrepos = []
issue_num = 6490
keywords = ['patch']
message_count = 25.0
messages = ['90532', '90558', '90569', '90572', '90573', '90586', '90589', '98498', '121660', '123429', '129958', '129959', '130448', '137255', '137256', '137297', '137299', '137302', '203483', '203557', '216384', '216424', '216426', '216461', '216462']
nosy_count = 16.0
nosy_names = ['lemburg', 'gvanrossum', 'akuchling', 'georg.brandl', 'amaury.forgeotdarc', 'vstinner', 'benjamin.peterson', 'ezio.melotti', 'Neil Muller', 'eric.araujo', 'r.david.murray', 'cvrebert', 'krawyoti', 'python-dev', 'martin.panter', 'sam.kimbrel']
pr_nums = []
priority = 'normal'
resolution = 'fixed'
stage = 'resolved'
status = 'closed'
superseder = None
type = 'behavior'
url = 'https://bugs.python.org/issue6490'
versions = ['Python 3.1', 'Python 2.7', 'Python 3.2', 'Python 3.3', 'Python 3.4']
Activity
krawyoti commentedon Jul 15, 2009
The documentation in Python 2.6 claims os.popen is deprecated [1]. This
is probably a false claim. I think that at some point os.popen got
confused with os.popen2, os.popen3, os.popen4 and the popen2 module, all
of which are correctly deprecated.
I bring three forward three pieces of evidence that os.popen is *not*
deprecated:
i) In Python 3.1, unlike the others, os.popen is still present and is
not even deprecated. [2]
ii) Unlike the others, using os.popen does not raise a DeprecationWarning;
iii) Unlike the others, its implementation is lifted straight from the
posix module.
--
[1] http://docs.python.org/2.6/library/os.html#os.popen
[2] http://docs.python.org/3.1/library/os.html#os.plock
birkenfeld commentedon Jul 16, 2009
Actually popen() isn't documented anymore in the 3.1 docs. However, I
don't know about the "real" deprecation status. Benjamin?
benjaminp commentedon Jul 16, 2009
I have no idea either. It seems os.popen is now a hacked up to use
subprocess, so it seems intentional to keep it. Guido, you made this
change; is os.peopen supposed to be gone in 3.x?
gvanrossum commentedon Jul 16, 2009
I am guessing the reason to keep os.popen() (albeit now reimplemented
using subprocess) is that it is a convenient wrapper for a common use case
and also familiar. I see no problem with this. (Indeed the big problem
was with the proliferation of popenN with confusing signatures.) So I
guess it ought to be documented and removed from the list of deprecations
in 2.6.
amauryfa commentedon Jul 16, 2009
By the way, shouldn't the various posix.spawnv* functions be officiall
deprecated as well?
krawyoti commentedon Jul 16, 2009
Georg, please note that os.popen *is* documented in 3.1. See attached
screen shot.
birkenfeld commentedon Jul 16, 2009
That is not really a documentation for the function, but a pointer to a
section in which there is no documentation for popen.
ezio-melotti commentedon Jan 29, 2010
The function is still marked as deprecated in the 2.x doc and undocumented in 3.x (the function is there, but the description points somewhere else).
NeilMuller commentedon Nov 20, 2010
The attached patch grabs the os.popen documentation from python 2.7, throws away the deprecation notes, and adds a pointer to subprocess.Popen for more details.
merwok commentedon Dec 5, 2010
I will refresh the patch, update it to recommend use as a context manager, and submit the patch here for review before committing. It’s too late for 2.6, though.
Benjamin, I hope you won’t mind me taking the assignment from you.
6 remaining items
malemburg commentedon May 30, 2011
Chris Rebert wrote:
Thanks, but I still don't understand why os.popen() wasn't removed
from the list of deprecated APIs as per Guido's message further up
on the ticket.
If you look at the amount of code you need to add in order
to support the os.popen() functionality directly using
subprocess instead of going the indirect way via the existing
os.popen() wrapper around the subprocess functionality, I think
this shows that the wrapper is indeed a good thing to have
and something you'd otherwise implement anyway as part of
standard code refactoring.
So instead of applying such a patch, I think we should add back
the documentation for os.popen() and remove the deprecation
notices.
The deprecations for os.popenN() are still fine, since those
APIs are not used all that much, and I'm sure that no one can
really remember what all the different versions do anyway :-)
os.popen() OTOH is often used and implements a very common
use: running an external command and getting the stdout
results back for further processing.
bitdancer commentedon May 30, 2011
That's good, because those functions are already gone in Python3 :)
Victor: did you notice that getoutput and friends call os.popen?
The one argument I can see for actually deprecating os.popen is that in general the os module functions are thin wrappers around the corresponding posix functions. But that is only true in general, and os.popen was never a "thin" wrapper, at least on most platforms.
vstinner commentedon May 30, 2011
Yes, because I wrote a patch to call directly subprocess :-) => see the issue
bpo-10197. I don't want to remove os.popen() anymore, it's too much work for a
minor gain (we will remove it in Python 4). But we can add a note in its
documentation saying that the subprocess should be prefered.
os.popen() was a thin wrapper in Python 2.x: posix.popen() was a wrapper of
the popen() C function.
bitdancer commentedon May 30, 2011
There were an awfully large number of pages of code for a thin wrapper. Granted, half of that was probably os/2 support...
[-]os.popen documentation in 2.6 is probably wrong[/-][+]os.popen documentation is probably wrong[/+]vadmium commentedon Nov 20, 2013
Please apply Neil Muller’s documentation patch. It is certainly better than the current state.
If you want to improve it further, maybe get rid of the trailing comma, and mention that the close() method returns the exit status encoded like the wait() function.
vadmium commentedon Nov 21, 2013
Also it would be good to document that it returns a text stream, not a binary stream.
samkimbrel commentedon Apr 15, 2014
Updated the patch as per Martin's notes in msg203483.
akuchling commentedon Apr 16, 2014
I thought the discussion of the return code was rather complicated and tried rewriting it; new patch attached. Is it an improvement? The new version also specifies the function's parameters.
samkimbrel commentedon Apr 16, 2014
Yes, I think that wording works a lot better. Thanks for the touch-up.
python-dev commentedon Apr 16, 2014
New changeset 3417a95df7e2 by Andrew Kuchling in branch 'default':
bpo-6490: Expand documentation for os.popen().
http://hg.python.org/cpython/rev/3417a95df7e2
akuchling commentedon Apr 16, 2014
Thanks for your patch!
[-]os.popen documentation is probably wrong[/-][+]os.popen documentation is probably wrong[/+]