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