[Python-checkins] cpython: #6490: Expand documentation for os.popen().

[andrew.kuchling]

http://hg.python.org/cpython/rev/3417a95df7e2
changeset:   90357:3417a95df7e2
user:        Andrew Kuchling <amk at amk.ca>
date:        Wed Apr 16 09:10:53 2014 -0400
summary:
  #6490: Expand documentation for os.popen().

Patch by Sam Kimbrel.

files:
  Doc/library/os.rst |  25 +++++++++++++++++++++----
  1 files changed, 21 insertions(+), 4 deletions(-)


diff --git a/Doc/library/os.rst b/Doc/library/os.rst
--- a/Doc/library/os.rst
+++ b/Doc/library/os.rst
@@ -2730,10 +2730,27 @@
    Availability: Unix.
 
 
-.. function:: popen(...)
-
-   Run child processes, returning opened pipes for communications.  These functions
-   are described in section :ref:`os-newstreams`.
+.. function:: popen(command, mode='r', buffering=-1)
+
+   Open a pipe to or from *command*.  The return value is an open file object
+   connected to the pipe, which can be read or written depending on whether *mode*
+   is ``'r'`` (default) or ``'w'``. The *buffering* argument has the same meaning as
+   the corresponding argument to the built-in :func:`open` function. The
+   returned file object reads or writes text strings rather than bytes.
+
+   The ``close`` method returns :const:`None` if the subprocess exited
+   successfully, or the subprocess's return code if there was an
+   error. On POSIX systems, if the return code is positive it
+   represents the return value of the process left-shifted by one
+   byte.  If the return code is negative, the process was terminated
+   by the signal given by the negated value of the return code.  (For
+   example, the return value might be ``- signal.SIGKILL`` if the
+   subprocess was killed.)  On Windows systems, the return value
+   contains the signed integer return code from the child process.
+
+   This is implemented using :class:`subprocess.Popen`; see that class's
+   documentation for more powerful ways to manage and communicate with
+   subprocesses.
 
 
 .. function:: spawnl(mode, path, ...)

-- 
Repository URL: http://hg.python.org/cpython