diff options
Diffstat (limited to 'Doc')
| -rw-r--r-- | Doc/lib/libcommands.tex | 9 | ||||
| -rw-r--r-- | Doc/lib/libos.tex | 23 | ||||
| -rw-r--r-- | Doc/lib/libpopen2.tex | 12 | ||||
| -rw-r--r-- | Doc/lib/libsubprocess.tex | 3 |
4 files changed, 38 insertions, 9 deletions
diff --git a/Doc/lib/libcommands.tex b/Doc/lib/libcommands.tex index 74e7023..53b8a20 100644 --- a/Doc/lib/libcommands.tex +++ b/Doc/lib/libcommands.tex @@ -12,6 +12,11 @@ The \module{commands} module contains wrapper functions for return any output generated by the command and, optionally, the exit status. +The \module{subprocess} module provides more powerful facilities for +spawning new processes and retrieving their results. Using the +\module{subprocess} module is preferable to using the \module{commands} +module. + The \module{commands} module defines the following functions: @@ -51,3 +56,7 @@ Example: >>> commands.getstatus('/bin/ls') '-rwxr-xr-x 1 root 13352 Oct 14 1994 /bin/ls' \end{verbatim} + +\begin{seealso} + \seemodule{subprocess}{Module for spawning and managing subprocesses.} +\end{seealso} diff --git a/Doc/lib/libos.tex b/Doc/lib/libos.tex index beb6eff..355d8fa 100644 --- a/Doc/lib/libos.tex +++ b/Doc/lib/libos.tex @@ -361,6 +361,10 @@ object, except that when the exit status is zero (termination without errors), \code{None} is returned. Availability: Macintosh, \UNIX, Windows. +The \module{subprocess} module provides more powerful facilities for +spawning new processes and retrieving their results; using that module +is preferable to using this function. + \versionchanged[This function worked unreliably under Windows in earlier versions of Python. This was due to the use of the \cfunction{_popen()} function from the libraries provided with @@ -375,8 +379,13 @@ deleted once there are no file descriptors for the file. Availability: Macintosh, \UNIX, Windows. \end{funcdesc} +There are a number of different \function{popen*()} functions that +provide slightly different ways to create subprocesses. Note that the +\module{subprocess} module is easier to use and more powerful; +consider using that module before writing code using the +lower-level \function{popen*()} functions. -For each of the following \function{popen()} variants, if \var{bufsize} is +For each of the \function{popen*()} variants, if \var{bufsize} is specified, it specifies the buffer size for the I/O pipes. \var{mode}, if provided, should be the string \code{'b'} or \code{'t'}; on Windows this is needed to determine whether the file @@ -1547,7 +1556,13 @@ functions are described in section \ref{os-newstreams}. \funcline{spawnve}{mode, path, args, env} \funcline{spawnvp}{mode, file, args} \funcline{spawnvpe}{mode, file, args, env} -Execute the program \var{path} in a new process. If \var{mode} is +Execute the program \var{path} in a new process. + +(Note that the \module{subprocess} module provides more powerful +facilities for spawning new processes and retrieving their results; +using that module is preferable to using these functions.) + +If \var{mode} is \constant{P_NOWAIT}, this function returns the process ID of the new process; if \var{mode} is \constant{P_WAIT}, returns the process's exit code if it exits normally, or \code{-\var{signal}}, where @@ -1684,6 +1699,10 @@ and XP) this is the exit status of the command run; on systems using a non-native shell, consult your shell documentation. Availability: Macintosh, \UNIX, Windows. + +The \module{subprocess} module provides more powerful facilities for +spawning new processes and retrieving their results; using that module +is preferable to using this function. \end{funcdesc} \begin{funcdesc}{times}{} diff --git a/Doc/lib/libpopen2.tex b/Doc/lib/libpopen2.tex index 985f580..fa0c1a6 100644 --- a/Doc/lib/libpopen2.tex +++ b/Doc/lib/libpopen2.tex @@ -11,10 +11,10 @@ This module allows you to spawn processes and connect to their input/output/error pipes and obtain their return codes under \UNIX{} and Windows. -Note that starting with Python 2.0, this functionality is available -using functions from the \refmodule{os} module which have the same -names as the factory functions here, but the order of the return -values is more intuitive in the \refmodule{os} module variants. +The \module{subprocess} module provides more powerful facilities for +spawning new processes and retrieving their results. Using the +\module{subprocess} module is preferable to using the \module{popen2} +module. The primary interface offered by this module is a trio of factory functions. For each of these, if \var{bufsize} is specified, @@ -184,3 +184,7 @@ integrate I/O over pipes with their \function{select()} loops, or use separate threads to read each of the individual files provided by whichever \function{popen*()} function or \class{Popen*} class was used. + +\begin{seealso} + \seemodule{subprocess}{Module for spawning and managing subprocesses.} +\end{seealso} diff --git a/Doc/lib/libsubprocess.tex b/Doc/lib/libsubprocess.tex index 03072f7..f639710 100644 --- a/Doc/lib/libsubprocess.tex +++ b/Doc/lib/libsubprocess.tex @@ -12,9 +12,6 @@ connect to their input/output/error pipes, and obtain their return codes. This module intends to replace several other, older modules and functions, such as: -% XXX Should add pointers to this module to at least the popen2 -% and commands sections. - \begin{verbatim} os.system os.spawn* |