Documentation for Lib/commands.py, from Sue Williams.

4 files changed, 100 insertions, 2 deletions

diff --git a/Doc/lib.tex b/Doc/lib.tex
index 0e70deb..6198445 100644
--- a/Doc/lib.tex
+++ b/Doc/lib.tex
@@ -1,4 +1,4 @@
-\documentstyle[twoside,11pt,myformat]{report}
+\documentstyle[twoside,openright,10pt,myformat]{report}
 
 % NOTE: this file controls which chapters/sections of the library
 % manual are actually printed.  It is easy to customize your manual
@@ -137,6 +137,7 @@ to Python and how to embed it in other applications.
 \input{libresource}
 \input{libsyslog}
 \input{libstat}
+\input{libcommands}
 
 \input{libpdb}			% The Python Debugger
 
diff --git a/Doc/lib/lib.tex b/Doc/lib/lib.tex
index 0e70deb..6198445 100644
--- a/Doc/lib/lib.tex
+++ b/Doc/lib/lib.tex
@@ -1,4 +1,4 @@
-\documentstyle[twoside,11pt,myformat]{report}
+\documentstyle[twoside,openright,10pt,myformat]{report}
 
 % NOTE: this file controls which chapters/sections of the library
 % manual are actually printed.  It is easy to customize your manual
@@ -137,6 +137,7 @@ to Python and how to embed it in other applications.
 \input{libresource}
 \input{libsyslog}
 \input{libstat}
+\input{libcommands}
 
 \input{libpdb}			% The Python Debugger
 
diff --git a/Doc/lib/libcommands.tex b/Doc/lib/libcommands.tex
new file mode 100644
index 0000000..7584931
--- /dev/null
+++ b/Doc/lib/libcommands.tex
@@ -0,0 +1,48 @@
+\section{Standard module \sectcode{commands}}	% If implemented in Python
+\stmodindex{commands}
+
+The \code{commands} module contains wrapper functions for \code{os.popen()} 
+which take a system command as a string and return any output generated by 
+the command, and optionally, the exit status.
+
+The \code{commands} module is only usable on systems which support 
+\code{popen()} (currently \UNIX{}).
+
+The \code{commands} module defines the following functions:
+
+\renewcommand{\indexsubitem}{(in module commands)}
+\begin{funcdesc}{getstatusoutput}{cmd}
+Execute the string \var{cmd} in a shell with \code{os.popen()} and return
+a 2-tuple (status, output).  \var{cmd} is actually run as
+\samp{cmd ; 2$>$\$1}, so that the returned output will contain output
+or error messages. A trailing newline is stripped from the output.
+The exit status for the  command can be interpreted according to the
+rules for the \C{} function \code{wait()}.  
+\end{funcdesc}
+
+\begin{funcdesc}{getoutput}{cmd}
+Like \code{getstatusoutput()}, except the exit status is ignored and
+the return value is a string containing the command's output.  
+\end{funcdesc}
+
+\begin{funcdesc}{getstatus}{file}
+Return the output of \samp{ls -ld \var{file}} as a string.  This
+function uses the \code{getoutput()} function, and properly escapes
+backslashes and dollar signs in the argument.
+\end{funcdesc}
+
+Example:
+
+\begin{verbatim}
+>>> import commands
+>>> commands.getstatusoutput('ls /bin/ls')
+(0, '/bin/ls')
+>>> commands.getstatusoutput('cat /bin/junk')
+(256, 'cat: /bin/junk: No such file or directory')
+>>> commands.getstatusoutput('/bin/junk')
+(256, 'sh: /bin/junk: not found')
+>>> commands.getoutput('ls /bin/ls')
+'/bin/ls'
+>>> commands.getstatus('/bin/ls')
+'-rwxr-xr-x  1 root        13352 Oct 14  1994 /bin/ls'
+\end{verbatim}
diff --git a/Doc/libcommands.tex b/Doc/libcommands.tex
new file mode 100644
index 0000000..7584931
--- /dev/null
+++ b/Doc/libcommands.tex
@@ -0,0 +1,48 @@
+\section{Standard module \sectcode{commands}}	% If implemented in Python
+\stmodindex{commands}
+
+The \code{commands} module contains wrapper functions for \code{os.popen()} 
+which take a system command as a string and return any output generated by 
+the command, and optionally, the exit status.
+
+The \code{commands} module is only usable on systems which support 
+\code{popen()} (currently \UNIX{}).
+
+The \code{commands} module defines the following functions:
+
+\renewcommand{\indexsubitem}{(in module commands)}
+\begin{funcdesc}{getstatusoutput}{cmd}
+Execute the string \var{cmd} in a shell with \code{os.popen()} and return
+a 2-tuple (status, output).  \var{cmd} is actually run as
+\samp{cmd ; 2$>$\$1}, so that the returned output will contain output
+or error messages. A trailing newline is stripped from the output.
+The exit status for the  command can be interpreted according to the
+rules for the \C{} function \code{wait()}.  
+\end{funcdesc}
+
+\begin{funcdesc}{getoutput}{cmd}
+Like \code{getstatusoutput()}, except the exit status is ignored and
+the return value is a string containing the command's output.  
+\end{funcdesc}
+
+\begin{funcdesc}{getstatus}{file}
+Return the output of \samp{ls -ld \var{file}} as a string.  This
+function uses the \code{getoutput()} function, and properly escapes
+backslashes and dollar signs in the argument.
+\end{funcdesc}
+
+Example:
+
+\begin{verbatim}
+>>> import commands
+>>> commands.getstatusoutput('ls /bin/ls')
+(0, '/bin/ls')
+>>> commands.getstatusoutput('cat /bin/junk')
+(256, 'cat: /bin/junk: No such file or directory')
+>>> commands.getstatusoutput('/bin/junk')
+(256, 'sh: /bin/junk: not found')
+>>> commands.getoutput('ls /bin/ls')
+'/bin/ls'
+>>> commands.getstatus('/bin/ls')
+'-rwxr-xr-x  1 root        13352 Oct 14  1994 /bin/ls'
+\end{verbatim}