classification
Title: os.popen referenced but not documented in Python 3.x
Type: Stage: resolved
Components: Documentation Versions: Python 3.1
process
Status: closed Resolution: duplicate
Dependencies: Superseder: os.popen documentation is probably wrong
View: 6490
Assigned To: docs@python Nosy List: cvrebert, docs@python, eli.bendersky, eric.araujo, ezio.melotti, r.david.murray, vstinner
Priority: normal Keywords:

Created on 2010-07-26 05:24 by cvrebert, last changed 2011-05-30 15:29 by eric.araujo. This issue is now closed.

Messages (6)
msg111597 - (view) Author: Chris Rebert (cvrebert) * Date: 2010-07-26 05:24
http://docs.python.org/py3k/library/os.html  currently mentions os.popen() in several places. The docs for os.popen() itself say:
'These functions are described in section "File Object Creation"'

However, unlike the 2.x version of that section ( http://docs.python.org/library/os.html#file-object-creation ), the os.popen*() family is not documented there [or indeed anywhere] anymore ( http://docs.python.org/py3k/library/os.html#os-newstreams ); the entire section now only documents os.fdopen().

The 2.7 docs say that the os.popen*() family are deprecated, and indeed, of the family, only os.popen() seems to still exist in Python 3.x (at least based on my testing via ideone.com).

Thus, from what I can see, one of the following is the case:
(A) The entire os.popen*() family is supposed be gone in Python 3.x, so os.popen() should be removed entirely from both the code and the docs.
(B) os.popen() is the sole legitimate survivor of its family, and should be properly documented again.
(C) os.popen() was left in as a kludge, shouldn't be mentioned in the docs, and possibly should be renamed os._popen() to reflect its status.

So, which one of these is it?
msg111601 - (view) Author: R. David Murray (r.david.murray) * (Python committer) Date: 2010-07-26 11:31
(D) in python 3, os.popen has been reimplemented using subprocess.Popen.
So the other mentions of os.popen should probably be replaced with mentions of subprocess.Popen.

Your (C) is close...the continued existence of os.popen in Python3 is, I think, a bit of a kludge (I wasn't around for the discussion), but a backward compatibility one.  I don't know if there is a plan to deprecate it, but I suspect not.  On the other hand I certainly wouldn't recommend using it, since it does an import inside the function, which can get one into trouble if one uses threads.
msg136808 - (view) Author: STINNER Victor (vstinner) * (Python committer) Date: 2011-05-24 23:30
> The entire os.popen*() family is supposed be gone in Python 3.x

os.popen2(), os.popen3() and os.popen4() were removed in Python 3.0, but os.popen() was kept. Guido wants to keep it because it has a nicer API than subprocess.Popen. I'm too lazy to replace all calls to os.popen() by subprocess.Popen in the Python code base: it's still widely used. Hum, I'm unable to find the issue giving more details about this choice (keep os.popen).

The os.popen() doc should be restored. Can you work on a patch?
msg136823 - (view) Author: Eli Bendersky (eli.bendersky) * (Python committer) Date: 2011-05-25 03:21
os.popen() is certainly deprecated. Its documentation in both 2.6 and 2.7 notes:

  Deprecated since version 2.6: This function is obsolete. Use the subprocess module.

Indeed, the Python 3.x library/os.rst doc mentions it several times, but the documentation was removed. I don't think this is following the rules of deprecation.

If it was decided to keep os.popen alive, it *should* be documented in 3.x, possibly retaining the deprecation notice.
msg137293 - (view) Author: STINNER Victor (vstinner) * (Python committer) Date: 2011-05-30 15:22
> Its documentation in both 2.6 and 2.7 notes:
>
> Deprecated since version 2.6: This function is obsolete. 
> Use the subprocess module.

The deprecation should be removed from Python 2.7: os.popen() will not be removed from Python 2 because 2.7 is the last major version of the 2.x branch. And os.popen() will stay in Python 3: see #6490 and the Guido's message
http://bugs.python.org/issue6490#msg90572

> If it was decided to keep os.popen alive, it *should* be 
> documented in 3.x

Yes, os.popen() must be documented in Python 3. Do you want to write a patch to restore the doc?
msg137295 - (view) Author: √Čric Araujo (eric.araujo) * (Python committer) Date: 2011-05-30 15:29
I suggest we move the discussion to #6490.
History
Date User Action Args
2011-05-30 15:29:52eric.araujosetstatus: open -> closed

superseder: os.popen documentation is probably wrong

nosy: + eric.araujo
messages: + msg137295
resolution: duplicate
stage: resolved
2011-05-30 15:22:15vstinnersetmessages: + msg137293
2011-05-28 10:01:20ezio.melottisetnosy: + ezio.melotti
2011-05-25 03:21:28eli.benderskysetnosy: + eli.bendersky
messages: + msg136823
2011-05-24 23:30:38vstinnersetnosy: + vstinner
messages: + msg136808
2010-07-26 11:31:33r.david.murraysetnosy: + r.david.murray
messages: + msg111601
2010-07-26 05:24:07cvrebertcreate