/Doc/library/pipes.rst

http://unladen-swallow.googlecode.com/ · ReStructuredText · 92 lines · 53 code · 39 blank · 0 comment · 0 complexity · df95c7b0a36e75ebb066f7dfb45a6357 MD5 · raw file

  1. :mod:`pipes` --- Interface to shell pipelines
  2. =============================================
  3. .. module:: pipes
  4. :platform: Unix
  5. :synopsis: A Python interface to Unix shell pipelines.
  6. .. sectionauthor:: Moshe Zadka <moshez@zadka.site.co.il>
  7. The :mod:`pipes` module defines a class to abstract the concept of a *pipeline*
  8. --- a sequence of converters from one file to another.
  9. Because the module uses :program:`/bin/sh` command lines, a POSIX or compatible
  10. shell for :func:`os.system` and :func:`os.popen` is required.
  11. The :mod:`pipes` module defines the following class:
  12. .. class:: Template()
  13. An abstraction of a pipeline.
  14. Example::
  15. >>> import pipes
  16. >>> t=pipes.Template()
  17. >>> t.append('tr a-z A-Z', '--')
  18. >>> f=t.open('/tmp/1', 'w')
  19. >>> f.write('hello world')
  20. >>> f.close()
  21. >>> open('/tmp/1').read()
  22. 'HELLO WORLD'
  23. .. _template-objects:
  24. Template Objects
  25. ----------------
  26. Template objects following methods:
  27. .. method:: Template.reset()
  28. Restore a pipeline template to its initial state.
  29. .. method:: Template.clone()
  30. Return a new, equivalent, pipeline template.
  31. .. method:: Template.debug(flag)
  32. If *flag* is true, turn debugging on. Otherwise, turn debugging off. When
  33. debugging is on, commands to be executed are printed, and the shell is given
  34. ``set -x`` command to be more verbose.
  35. .. method:: Template.append(cmd, kind)
  36. Append a new action at the end. The *cmd* variable must be a valid bourne shell
  37. command. The *kind* variable consists of two letters.
  38. The first letter can be either of ``'-'`` (which means the command reads its
  39. standard input), ``'f'`` (which means the commands reads a given file on the
  40. command line) or ``'.'`` (which means the commands reads no input, and hence
  41. must be first.)
  42. Similarly, the second letter can be either of ``'-'`` (which means the command
  43. writes to standard output), ``'f'`` (which means the command writes a file on
  44. the command line) or ``'.'`` (which means the command does not write anything,
  45. and hence must be last.)
  46. .. method:: Template.prepend(cmd, kind)
  47. Add a new action at the beginning. See :meth:`append` for explanations of the
  48. arguments.
  49. .. method:: Template.open(file, mode)
  50. Return a file-like object, open to *file*, but read from or written to by the
  51. pipeline. Note that only one of ``'r'``, ``'w'`` may be given.
  52. .. method:: Template.copy(infile, outfile)
  53. Copy *infile* to *outfile* through the pipe.