[Python-checkins] r52473 - python/trunk/Doc/lib/libcommands.tex python/trunk/Doc/lib/libos.tex python/trunk/Doc/lib/libpopen2.tex python/trunk/Doc/lib/libsubprocess.tex
andrew.kuchling
python-checkins at python.org
Fri Oct 27 16:53:42 CEST 2006
Author: andrew.kuchling
Date: Fri Oct 27 16:53:41 2006
New Revision: 52473
Modified:
python/trunk/Doc/lib/libcommands.tex
python/trunk/Doc/lib/libos.tex
python/trunk/Doc/lib/libpopen2.tex
python/trunk/Doc/lib/libsubprocess.tex
Log:
Point users to the subprocess module in the docs for os.system, os.spawn*, os.popen2, and the popen2 and commands modules
Modified: python/trunk/Doc/lib/libcommands.tex
==============================================================================
--- python/trunk/Doc/lib/libcommands.tex (original)
+++ python/trunk/Doc/lib/libcommands.tex Fri Oct 27 16:53:41 2006
@@ -12,6 +12,11 @@
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 @@
>>> 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}
Modified: python/trunk/Doc/lib/libos.tex
==============================================================================
--- python/trunk/Doc/lib/libos.tex (original)
+++ python/trunk/Doc/lib/libos.tex Fri Oct 27 16:53:41 2006
@@ -361,6 +361,10 @@
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 @@
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 @@
\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 @@
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}{}
Modified: python/trunk/Doc/lib/libpopen2.tex
==============================================================================
--- python/trunk/Doc/lib/libpopen2.tex (original)
+++ python/trunk/Doc/lib/libpopen2.tex Fri Oct 27 16:53:41 2006
@@ -11,10 +11,10 @@
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 @@
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}
Modified: python/trunk/Doc/lib/libsubprocess.tex
==============================================================================
--- python/trunk/Doc/lib/libsubprocess.tex (original)
+++ python/trunk/Doc/lib/libsubprocess.tex Fri Oct 27 16:53:41 2006
@@ -12,9 +12,6 @@
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*
More information about the Python-checkins
mailing list