[DOC-SIG] Re: [PYTHON DOC-SIG] contributing documentation

[Sue Williams]

OK, I documented commands.py.  (Thanks for the pointer to Doc/libtemplate.tex.
It was very helpful.)  Spent the better part of the afternoon
trying to duplicate what I was sure was a buffer limitation only it turns
out that its one of my own modules that has that limitation, not commands...
(Hmm.  Well, whatever.)

I do not have access to laTex here (at least I don't think I do).
Hopefully this parses.  There is only one thing I did (intentionally)
that may be suspicious--can you put macros inside quoted strings?
This file contains a line: 
Return the output of "ls -ld \var{file}" as a string ...
I don't know if that's legal.

So:  I've got a libcommands.tex file here, as well as some diffs of
commands.py to add doc strings (one for the module, a one-liner for
each of three functions).

sue

libcommands.tex:
-------------------------------

\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 "{ 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 "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}

-------------------------
commands.py diffs:
-------------------------
*** commands.py Tue Jun 10 15:17:01 1997
--- commands.py.orig    Wed Jan  4 13:20:00 1995
***************
*** 1,24 ****
- """Execute shell commands via os.popen() and return status, output.
- 
- Interface summary:
-  
-        import commands
-         
-        outtext = commands.getoutput(cmd)
-        (exitstatus, outtext) = commands.getstatusoutput(cmd)
-        outtext = commands.getstatus(file)  # returns output of "ls -ld file"
- 
- A trailing newline is removed from the output string.
- 
- Encapsulates the basic operation:
-                          
-       pipe = os.popen('{ ' + cmd + '; } 2>&1', 'r')
-       text = pipe.read()
-       sts = pipe.close()
- 
- [Note:  it would be nice to add functions to interpret the exit status.]
- """
- 
  # Module 'commands'
  #
  # Various tools for executing commands and looking at their output and status.--- 1,3 ----
***************
*** 29,35 ****
  # Get 'ls -l' status for an object into a string
  #
  def getstatus(file):
-       """Return output of "ls -ld <file>" in a string"""
        return getoutput('ls -ld' + mkarg(file))
  
  
--- 8,13 ----
***************
*** 38,44 ****
  # Assume the command will work with '{ ... ; } 2>&1' around it..
  #
  def getoutput(cmd):
-       """Return output (stdout or stderr) of executing cmd in a shell"""
        return getstatusoutput(cmd)[1]
  
  
--- 16,21 ----
***************
*** 46,52 ****
  # Returns a pair (sts, output)
  #
  def getstatusoutput(cmd):
-       """Return (status, output) of executing cmd in a shell"""
        import os
        pipe = os.popen('{ ' + cmd + '; } 2>&1', 'r')
        text = pipe.read()
--- 23,28 ----

_______________
DOC-SIG  - SIG for the Python Documentation Project

send messages to: doc-sig@python.org
administrivia to: doc-sig-request@python.org
_______________