/Doc/library/commands.rst
http://unladen-swallow.googlecode.com/ · ReStructuredText · 74 lines · 49 code · 25 blank · 0 comment · 0 complexity · 96093b1c13e7718434a0d07d05931e59 MD5 · raw file
- :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.
- .. note::
- In Python 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.