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

.. warning::

   In 3.x, :func:`getstatus` and two undocumented functions (:func:`mk2arg` and

   :func:`mkarg`) have been removed.  Also, :func:`getstatusoutput` and

   :func:`getoutput` have been moved to the :mod:`subprocess` 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.

.. function:: getstatus(file)

   Return the output of ``ls -ld file`` as a string.  This function uses the

   :func:`getoutput` function, and properly escapes backslashes and dollar signs in

   the argument.

   .. deprecated:: 2.6

      This function is nonobvious and useless.  The name is also misleading in the

      presence of :func:`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'

.. seealso::

   Module :mod:`subprocess`

      Module for spawning and managing subprocesses.