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