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