Doc/library/pipes.rst

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