[issue9382] os.popen referenced but not documented in Python 3.x

New submission from Chris Rebert <pybugs@rebertia.com>: 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? ---------- assignee: docs@python components: Documentation messages: 111597 nosy: cvrebert, docs@python priority: normal severity: normal status: open title: os.popen referenced but not documented in Python 3.x versions: Python 3.1 _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue9382> _______________________________________

R. David Murray <rdmurray@bitdance.com> added the comment: (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. ---------- nosy: +r.david.murray _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue9382> _______________________________________

STINNER Victor <victor.stinner@haypocalc.com> added the comment:
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? ---------- nosy: +haypo _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue9382> _______________________________________

Eli Bendersky <eliben@gmail.com> added the comment: 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. ---------- nosy: +eli.bendersky _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue9382> _______________________________________

Changes by Ezio Melotti <ezio.melotti@gmail.com>: ---------- nosy: +ezio.melotti _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue9382> _______________________________________

STINNER Victor <victor.stinner@haypocalc.com> added the comment:
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? ---------- _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue9382> _______________________________________

Éric Araujo <merwok@netwok.org> added the comment: I suggest we move the discussion to #6490. ---------- nosy: +eric.araujo resolution: -> duplicate stage: -> committed/rejected status: open -> closed superseder: -> os.popen documentation in 2.6 is probably wrong _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue9382> _______________________________________
participants (6)
-
Chris Rebert
-
Eli Bendersky
-
Ezio Melotti
-
R. David Murray
-
STINNER Victor
-
Éric Araujo