← Back to branch summary

~ubuntu-branches/ubuntu/trusty/python3.4/trusty-proposed

« back to all changes in this revision

Viewing changes to Doc/library/pipes.rst

  • Committer: Package Import Robot
  • Author(s): Matthias Klose
  • Date: 2013-11-25 09:44:27 UTC
  • Revision ID: package-import@ubuntu.com-20131125094427-lzxj8ap5w01lmo7f
Tags: upstream-3.4~b1
Import upstream version 3.4~b1

Show diffs side-by-side

added added

removed removed

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