From f5a429295d855267c33c5ef110fbf05ee7a3013e Mon Sep 17 00:00:00 2001 From: Andrew Kuchling Date: Wed, 16 Apr 2014 09:10:53 -0400 Subject: #6490: Expand documentation for os.popen(). Patch by Sam Kimbrel. --- Doc/library/os.rst | 25 +++++++++++++++++++++---- 1 file changed, 21 insertions(+), 4 deletions(-) diff --git a/Doc/library/os.rst b/Doc/library/os.rst index 3d492ba..b7887f9 100644 --- a/Doc/library/os.rst +++ b/Doc/library/os.rst @@ -2730,10 +2730,27 @@ written in Python, such as a mail server's external command delivery program. 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, ...) -- cgit v0.12