Move the 3k reST doc tree in place.

1 files changed, 53 insertions, 0 deletions

diff --git a/Doc/library/commands.rst b/Doc/library/commands.rst
new file mode 100644
index 0000000..79e3d73
--- /dev/null
+++ b/Doc/library/commands.rst
@@ -0,0 +1,53 @@
+
+:mod:`commands` --- Utilities for running commands
+==================================================
+
+.. module:: commands
+   :platform: Unix
+   :synopsis: Utility functions for running external commands.
+.. sectionauthor:: Sue Williams <sbw@provis.com>
+
+
+The :mod:`commands` module contains wrapper functions for :func:`os.popen` which
+take a system command as a string and return any output generated by the command
+and, optionally, the exit status.
+
+The :mod:`subprocess` module provides more powerful facilities for spawning new
+processes and retrieving their results.  Using the :mod:`subprocess` module is
+preferable to using the :mod:`commands` module.
+
+The :mod:`commands` module defines the following functions:
+
+
+.. function:: getstatusoutput(cmd)
+
+   Execute the string *cmd* in a shell with :func:`os.popen` and return a 2-tuple
+   ``(status, output)``.  *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 :cfunc:`wait`.
+
+
+.. function:: getoutput(cmd)
+
+   Like :func:`getstatusoutput`, except the exit status is ignored and the return
+   value is a string containing the command's output.
+
+Example::
+
+   >>> 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'
+
+
+.. seealso::
+
+   Module :mod:`subprocess`
+      Module for spawning and managing subprocesses.
+