| [2] | 1 |
|
|---|
| 2 | :mod:`commands` --- Utilities for running commands
|
|---|
| 3 | ==================================================
|
|---|
| 4 |
|
|---|
| 5 | .. module:: commands
|
|---|
| 6 | :platform: Unix
|
|---|
| 7 | :synopsis: Utility functions for running external commands.
|
|---|
| [391] | 8 | :deprecated:
|
|---|
| 9 |
|
|---|
| 10 | .. deprecated:: 2.6
|
|---|
| 11 | The :mod:`commands` module has been removed in Python 3. Use the
|
|---|
| 12 | :mod:`subprocess` module instead.
|
|---|
| 13 |
|
|---|
| [2] | 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
|
|---|
| [391] | 41 | according to the rules for the C function :c:func:`wait`.
|
|---|
| [2] | 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 |
|
|---|
