Document that on Unix, the 'cmd' argument to the os.popen2/3/4 and

popen2.popen2/3/4 functions can be a sequence. All texts are a variation on the
following:

On \UNIX, \var{cmd} may be a sequence, in which case arguments will be passed
directly to the program without shell intervention (as with
\function{os.spawnv()}). If \var{cmd} is a string it will be passed to the shell
(as with \function{os.system()}).

diff --git a/Doc/lib/libos.tex b/Doc/lib/libos.tex
index 510da178745421784ec84106b4ceb2684d1f1146..6ad5b3e590413415d60377755f19d59f0c35e437 100644 (file)
--- a/Doc/lib/libos.tex
+++ b/Doc/lib/libos.tex
@@ -361,6 +361,11 @@ specified, it specifies the buffer size for the I/O pipes.
 objects should be opened in binary or text mode.  The default value
 for \var{mode} is \code{'t'}.
 
+Also, for each of these variants, on \UNIX, \var{cmd} may be a sequence, in
+which case arguments will be passed directly to the program without shell
+intervention (as with \function{os.spawnv()}). If \var{cmd} is a string it will
+be passed to the shell (as with \function{os.system()}).
+
 These methods do not make it possible to retrieve the return code from
 the child processes.  The only way to control the input and output
 streams and also retrieve the return codes is to use the
@@ -389,15 +394,14 @@ Availability: \UNIX, Windows.
 \begin{funcdesc}{popen4}{cmd\optional{, mode\optional{, bufsize}}}
 Executes \var{cmd} as a sub-process.  Returns the file objects
 \code{(\var{child_stdin}, \var{child_stdout_and_stderr})}.
+Availability: \UNIX, Windows.
+\versionadded{2.0}
+\end{funcdesc}
 
 (Note that \code{\var{child_stdin}, \var{child_stdout}, and
 \var{child_stderr}} are named from the point of view of the child
 process, i.e. \var{child_stdin} is the child's standard input.)
 
-Availability: \UNIX, Windows.
-\versionadded{2.0}
-\end{funcdesc}
-
 This functionality is also available in the \refmodule{popen2} module
 using functions of the same names, but the return values of those
 functions have a different order.

diff --git a/Doc/lib/libpopen2.tex b/Doc/lib/libpopen2.tex
index 70a68c28ff4a65c7fda1b571fd67775ddcc701e2..985f580451bf2b8d32951da3a3d88e453d2da329 100644 (file)
--- a/Doc/lib/libpopen2.tex
+++ b/Doc/lib/libpopen2.tex
@@ -24,6 +24,11 @@ this is needed to determine whether the file objects should be opened
 in binary or text mode.  The default value for \var{mode} is
 \code{'t'}.
 
+On \UNIX, \var{cmd} may be a sequence, in which case arguments will be passed
+directly to the program without shell intervention (as with
+\function{os.spawnv()}). If \var{cmd} is a string it will be passed to the
+shell (as with \function{os.system()}).
+
 The only way to retrieve the return codes for the child processes is
 by using the \method{poll()} or \method{wait()} methods on the
 \class{Popen3} and \class{Popen4} classes; these are only available on
@@ -75,7 +80,6 @@ using \function{popen4()}.
 \versionadded{2.0}
 \end{classdesc}
 
-
 \subsection{Popen3 and Popen4 Objects \label{popen3-objects}}
 
 Instances of the \class{Popen3} and \class{Popen4} classes have the

diff --git a/Lib/os.py b/Lib/os.py
index 8839c109596d1b644583459726e514ba855e26d5..65b1830f8b9afc1eaab8b5903decc687fbcdf8fc 100644 (file)
--- a/Lib/os.py
+++ b/Lib/os.py
@@ -611,6 +611,12 @@ otherwise return -SIG, where SIG is the signal that killed it. """
 if _exists("fork"):
     if not _exists("popen2"):
         def popen2(cmd, mode="t", bufsize=-1):
+            """Execute the shell command 'cmd' in a sub-process.  On UNIX, 'cmd'
+            may be a sequence, in which case arguments will be passed directly to
+            the program without shell intervention (as with os.spawnv()).  If 'cmd'
+            is a string it will be passed to the shell (as with os.system()). If
+            'bufsize' is specified, it sets the buffer size for the I/O pipes.  The
+            file objects (child_stdin, child_stdout) are returned."""
             import popen2
             stdout, stdin = popen2.popen2(cmd, bufsize)
             return stdin, stdout
@@ -618,6 +624,12 @@ if _exists("fork"):
 
     if not _exists("popen3"):
         def popen3(cmd, mode="t", bufsize=-1):
+            """Execute the shell command 'cmd' in a sub-process.  On UNIX, 'cmd'
+            may be a sequence, in which case arguments will be passed directly to
+            the program without shell intervention (as with os.spawnv()).  If 'cmd'
+            is a string it will be passed to the shell (as with os.system()). If
+            'bufsize' is specified, it sets the buffer size for the I/O pipes.  The
+            file objects (child_stdin, child_stdout, child_stderr) are returned."""
             import popen2
             stdout, stdin, stderr = popen2.popen3(cmd, bufsize)
             return stdin, stdout, stderr
@@ -625,6 +637,12 @@ if _exists("fork"):
 
     if not _exists("popen4"):
         def popen4(cmd, mode="t", bufsize=-1):
+            """Execute the shell command 'cmd' in a sub-process.  On UNIX, 'cmd'
+            may be a sequence, in which case arguments will be passed directly to
+            the program without shell intervention (as with os.spawnv()).  If 'cmd'
+            is a string it will be passed to the shell (as with os.system()). If
+            'bufsize' is specified, it sets the buffer size for the I/O pipes.  The
+            file objects (child_stdin, child_stdout_stderr) are returned."""
             import popen2
             stdout, stdin = popen2.popen4(cmd, bufsize)
             return stdin, stdout

diff --git a/Lib/popen2.py b/Lib/popen2.py
index acba60258b46f7c5c7d368932aebd33b4d71809c..3f84bf9e852695d1e70c8d16fb66efc551a99316 100644 (file)
--- a/Lib/popen2.py
+++ b/Lib/popen2.py
@@ -30,10 +30,14 @@ class Popen3:
 
     def __init__(self, cmd, capturestderr=False, bufsize=-1):
         """The parameter 'cmd' is the shell command to execute in a
-        sub-process.  The 'capturestderr' flag, if true, specifies that
-        the object should capture standard error output of the child process.
-        The default is false.  If the 'bufsize' parameter is specified, it
-        specifies the size of the I/O buffers to/from the child process."""
+        sub-process.  On UNIX, 'cmd' may be a sequence, in which case arguments
+        will be passed directly to the program without shell intervention (as
+        with os.spawnv()).  If 'cmd' is a string it will be passed to the shell
+        (as with os.system()).   The 'capturestderr' flag, if true, specifies
+        that the object should capture standard error output of the child
+        process.  The default is false.  If the 'bufsize' parameter is
+        specified, it specifies the size of the I/O buffers to/from the child
+        process."""
         _cleanup()
         p2cread, p2cwrite = os.pipe()
         c2pread, c2pwrite = os.pipe()
@@ -120,44 +124,62 @@ if sys.platform[:3] == "win" or sys.platform == "os2emx":
     del Popen3, Popen4
 
     def popen2(cmd, bufsize=-1, mode='t'):
-        """Execute the shell command 'cmd' in a sub-process.  If 'bufsize' is
-        specified, it sets the buffer size for the I/O pipes.  The file objects
-        (child_stdout, child_stdin) are returned."""
+        """Execute the shell command 'cmd' in a sub-process. On UNIX, 'cmd' may
+        be a sequence, in which case arguments will be passed directly to the
+        program without shell intervention (as with os.spawnv()). If 'cmd' is a
+        string it will be passed to the shell (as with os.system()). If
+        'bufsize' is specified, it sets the buffer size for the I/O pipes. The
+        file objects (child_stdout, child_stdin) are returned."""
         w, r = os.popen2(cmd, mode, bufsize)
         return r, w
 
     def popen3(cmd, bufsize=-1, mode='t'):
-        """Execute the shell command 'cmd' in a sub-process.  If 'bufsize' is
-        specified, it sets the buffer size for the I/O pipes.  The file objects
-        (child_stdout, child_stdin, child_stderr) are returned."""
+        """Execute the shell command 'cmd' in a sub-process. On UNIX, 'cmd' may
+        be a sequence, in which case arguments will be passed directly to the
+        program without shell intervention (as with os.spawnv()). If 'cmd' is a
+        string it will be passed to the shell (as with os.system()). If
+        'bufsize' is specified, it sets the buffer size for the I/O pipes. The
+        file objects (child_stdout, child_stdin, child_stderr) are returned."""
         w, r, e = os.popen3(cmd, mode, bufsize)
         return r, w, e
 
     def popen4(cmd, bufsize=-1, mode='t'):
-        """Execute the shell command 'cmd' in a sub-process.  If 'bufsize' is
-        specified, it sets the buffer size for the I/O pipes.  The file objects
-        (child_stdout_stderr, child_stdin) are returned."""
+        """Execute the shell command 'cmd' in a sub-process. On UNIX, 'cmd' may
+        be a sequence, in which case arguments will be passed directly to the
+        program without shell intervention (as with os.spawnv()). If 'cmd' is a
+        string it will be passed to the shell (as with os.system()). If
+        'bufsize' is specified, it sets the buffer size for the I/O pipes. The
+        file objects (child_stdout_stderr, child_stdin) are returned."""
         w, r = os.popen4(cmd, mode, bufsize)
         return r, w
 else:
     def popen2(cmd, bufsize=-1, mode='t'):
-        """Execute the shell command 'cmd' in a sub-process.  If 'bufsize' is
-        specified, it sets the buffer size for the I/O pipes.  The file objects
-        (child_stdout, child_stdin) are returned."""
+        """Execute the shell command 'cmd' in a sub-process. On UNIX, 'cmd' may
+        be a sequence, in which case arguments will be passed directly to the
+        program without shell intervention (as with os.spawnv()). If 'cmd' is a
+        string it will be passed to the shell (as with os.system()). If
+        'bufsize' is specified, it sets the buffer size for the I/O pipes. The
+        file objects (child_stdout, child_stdin) are returned."""
         inst = Popen3(cmd, False, bufsize)
         return inst.fromchild, inst.tochild
 
     def popen3(cmd, bufsize=-1, mode='t'):
-        """Execute the shell command 'cmd' in a sub-process.  If 'bufsize' is
-        specified, it sets the buffer size for the I/O pipes.  The file objects
-        (child_stdout, child_stdin, child_stderr) are returned."""
+        """Execute the shell command 'cmd' in a sub-process. On UNIX, 'cmd' may
+        be a sequence, in which case arguments will be passed directly to the
+        program without shell intervention (as with os.spawnv()). If 'cmd' is a
+        string it will be passed to the shell (as with os.system()). If
+        'bufsize' is specified, it sets the buffer size for the I/O pipes. The
+        file objects (child_stdout, child_stdin, child_stderr) are returned."""
         inst = Popen3(cmd, True, bufsize)
         return inst.fromchild, inst.tochild, inst.childerr
 
     def popen4(cmd, bufsize=-1, mode='t'):
-        """Execute the shell command 'cmd' in a sub-process.  If 'bufsize' is
-        specified, it sets the buffer size for the I/O pipes.  The file objects
-        (child_stdout_stderr, child_stdin) are returned."""
+        """Execute the shell command 'cmd' in a sub-process. On UNIX, 'cmd' may
+        be a sequence, in which case arguments will be passed directly to the
+        program without shell intervention (as with os.spawnv()). If 'cmd' is a
+        string it will be passed to the shell (as with os.system()). If
+        'bufsize' is specified, it sets the buffer size for the I/O pipes. The
+        file objects (child_stdout_stderr, child_stdin) are returned."""
         inst = Popen4(cmd, bufsize)
         return inst.fromchild, inst.tochild