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