Doc/library/commands.rst

   1
   2 :mod:`commands` --- Utilities for running commands
   3 ==================================================
   4
   5 .. module:: commands
   6    :platform: Unix
   7    :synopsis: Utility functions for running external commands.
   8 .. sectionauthor:: Sue Williams <sbw@provis.com>
   9
  10
  11 The :mod:`commands` module contains wrapper functions for :func:`os.popen` which
  12 take a system command as a string and return any output generated by the command
  13 and, optionally, the exit status.
  14
  15 The :mod:`subprocess` module provides more powerful facilities for spawning new
  16 processes and retrieving their results.  Using the :mod:`subprocess` module is
  17 preferable to using the :mod:`commands` module.
  18
  19 .. warning::
  20
  21    In 3.x, :func:`getstatus` and two undocumented functions (:func:`mk2arg` and
  22    :func:`mkarg`) have been removed.  Also, :func:`getstatusoutput` and
  23    :func:`getoutput` have been moved to the :mod:`subprocess` module.
  24
  25 The :mod:`commands` module defines the following functions:
  26
  27
  28 .. function:: getstatusoutput(cmd)
  29
  30    Execute the string *cmd* in a shell with :func:`os.popen` and return a 2-tuple
  31    ``(status, output)``.  *cmd* is actually run as ``{ cmd ; } 2>&1``, so that the
  32    returned output will contain output or error messages. A trailing newline is
  33    stripped from the output. The exit status for the command can be interpreted
  34    according to the rules for the C function :cfunc:`wait`.
  35
  36
  37 .. function:: getoutput(cmd)
  38
  39    Like :func:`getstatusoutput`, except the exit status is ignored and the return
  40    value is a string containing the command's output.
  41
  42
  43 .. function:: getstatus(file)
  44
  45    Return the output of ``ls -ld file`` as a string.  This function uses the
  46    :func:`getoutput` function, and properly escapes backslashes and dollar signs in
  47    the argument.
  48
  49    .. deprecated:: 2.6
  50       This function is nonobvious and useless.  The name is also misleading in the
  51       presence of :func:`getstatusoutput`.
  52
  53
  54 Example::
  55
  56    >>> import commands
  57    >>> commands.getstatusoutput('ls /bin/ls')
  58    (0, '/bin/ls')
  59    >>> commands.getstatusoutput('cat /bin/junk')
  60    (256, 'cat: /bin/junk: No such file or directory')
  61    >>> commands.getstatusoutput('/bin/junk')
  62    (256, 'sh: /bin/junk: not found')
  63    >>> commands.getoutput('ls /bin/ls')
  64    '/bin/ls'
  65    >>> commands.getstatus('/bin/ls')
  66    '-rwxr-xr-x  1 root        13352 Oct 14  1994 /bin/ls'
  67
  68
  69 .. seealso::
  70
  71    Module :mod:`subprocess`
  72       Module for spawning and managing subprocesses.
  73