/Doc/library/commands.rst

http://unladen-swallow.googlecode.com/ · ReStructuredText · 74 lines · 49 code · 25 blank · 0 comment · 0 complexity · 96093b1c13e7718434a0d07d05931e59 MD5 · raw file

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