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?

(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.

> 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?

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.

> 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?

I suggest we move the discussion to #6490.