: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.