``commands`` --- Utilities for running commands
***********************************************

Platform: Unix

*Platforms: *Unix

The ``commands`` module contains wrapper functions for ``os.popen()``
which take a system command as a string and return any output
generated by the command and, optionally, the exit status.

The ``subprocess`` module provides more powerful facilities for
spawning new processes and retrieving their results.  Using the
``subprocess`` module is preferable to using the ``commands`` module.

Note: In Python 3.x, ``getstatus()`` and two undocumented functions
  (``mk2arg()`` and ``mkarg()``) have been removed.  Also,
  ``getstatusoutput()`` and ``getoutput()`` have been moved to the
  ``subprocess`` module.

The ``commands`` module defines the following functions:

commands.getstatusoutput(cmd)

   Execute the string *cmd* in a shell with ``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 ``wait()``.

commands.getoutput(cmd)

   Like ``getstatusoutput()``, except the exit status is ignored and
   the return value is a string containing the command's output.

commands.getstatus(file)

   Return the output of ``ls -ld file`` as a string.  This function
   uses the ``getoutput()`` function, and properly escapes backslashes
   and dollar signs in the argument.

   Deprecated since version 2.6: This function is nonobvious and
   useless.  The name is also misleading in the presence of
   ``getstatusoutput()``.

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'
   >>> commands.getstatus('/bin/ls')
   '-rwxr-xr-x  1 root        13352 Oct 14  1994 /bin/ls'

See also:

   Module ``subprocess``
      Module for spawning and managing subprocesses.