|
1 :mod:`fileinput` --- Iterate over lines from multiple input streams |
|
2 =================================================================== |
|
3 |
|
4 .. module:: fileinput |
|
5 :synopsis: Loop over standard input or a list of files. |
|
6 .. moduleauthor:: Guido van Rossum <guido@python.org> |
|
7 .. sectionauthor:: Fred L. Drake, Jr. <fdrake@acm.org> |
|
8 |
|
9 |
|
10 This module implements a helper class and functions to quickly write a |
|
11 loop over standard input or a list of files. If you just want to read or |
|
12 write one file see :func:`open`. |
|
13 |
|
14 The typical use is:: |
|
15 |
|
16 import fileinput |
|
17 for line in fileinput.input(): |
|
18 process(line) |
|
19 |
|
20 This iterates over the lines of all files listed in ``sys.argv[1:]``, defaulting |
|
21 to ``sys.stdin`` if the list is empty. If a filename is ``'-'``, it is also |
|
22 replaced by ``sys.stdin``. To specify an alternative list of filenames, pass it |
|
23 as the first argument to :func:`input`. A single file name is also allowed. |
|
24 |
|
25 All files are opened in text mode by default, but you can override this by |
|
26 specifying the *mode* parameter in the call to :func:`input` or |
|
27 :class:`FileInput()`. If an I/O error occurs during opening or reading a file, |
|
28 :exc:`IOError` is raised. |
|
29 |
|
30 If ``sys.stdin`` is used more than once, the second and further use will return |
|
31 no lines, except perhaps for interactive use, or if it has been explicitly reset |
|
32 (e.g. using ``sys.stdin.seek(0)``). |
|
33 |
|
34 Empty files are opened and immediately closed; the only time their presence in |
|
35 the list of filenames is noticeable at all is when the last file opened is |
|
36 empty. |
|
37 |
|
38 Lines are returned with any newlines intact, which means that the last line in |
|
39 a file may not have one. |
|
40 |
|
41 You can control how files are opened by providing an opening hook via the |
|
42 *openhook* parameter to :func:`fileinput.input` or :class:`FileInput()`. The |
|
43 hook must be a function that takes two arguments, *filename* and *mode*, and |
|
44 returns an accordingly opened file-like object. Two useful hooks are already |
|
45 provided by this module. |
|
46 |
|
47 The following function is the primary interface of this module: |
|
48 |
|
49 |
|
50 .. function:: input([files[, inplace[, backup[, mode[, openhook]]]]]) |
|
51 |
|
52 Create an instance of the :class:`FileInput` class. The instance will be used |
|
53 as global state for the functions of this module, and is also returned to use |
|
54 during iteration. The parameters to this function will be passed along to the |
|
55 constructor of the :class:`FileInput` class. |
|
56 |
|
57 .. versionchanged:: 2.5 |
|
58 Added the *mode* and *openhook* parameters. |
|
59 |
|
60 The following functions use the global state created by :func:`fileinput.input`; |
|
61 if there is no active state, :exc:`RuntimeError` is raised. |
|
62 |
|
63 |
|
64 .. function:: filename() |
|
65 |
|
66 Return the name of the file currently being read. Before the first line has |
|
67 been read, returns ``None``. |
|
68 |
|
69 |
|
70 .. function:: fileno() |
|
71 |
|
72 Return the integer "file descriptor" for the current file. When no file is |
|
73 opened (before the first line and between files), returns ``-1``. |
|
74 |
|
75 .. versionadded:: 2.5 |
|
76 |
|
77 |
|
78 .. function:: lineno() |
|
79 |
|
80 Return the cumulative line number of the line that has just been read. Before |
|
81 the first line has been read, returns ``0``. After the last line of the last |
|
82 file has been read, returns the line number of that line. |
|
83 |
|
84 |
|
85 .. function:: filelineno() |
|
86 |
|
87 Return the line number in the current file. Before the first line has been |
|
88 read, returns ``0``. After the last line of the last file has been read, |
|
89 returns the line number of that line within the file. |
|
90 |
|
91 |
|
92 .. function:: isfirstline() |
|
93 |
|
94 Returns true if the line just read is the first line of its file, otherwise |
|
95 returns false. |
|
96 |
|
97 |
|
98 .. function:: isstdin() |
|
99 |
|
100 Returns true if the last line was read from ``sys.stdin``, otherwise returns |
|
101 false. |
|
102 |
|
103 |
|
104 .. function:: nextfile() |
|
105 |
|
106 Close the current file so that the next iteration will read the first line from |
|
107 the next file (if any); lines not read from the file will not count towards the |
|
108 cumulative line count. The filename is not changed until after the first line |
|
109 of the next file has been read. Before the first line has been read, this |
|
110 function has no effect; it cannot be used to skip the first file. After the |
|
111 last line of the last file has been read, this function has no effect. |
|
112 |
|
113 |
|
114 .. function:: close() |
|
115 |
|
116 Close the sequence. |
|
117 |
|
118 The class which implements the sequence behavior provided by the module is |
|
119 available for subclassing as well: |
|
120 |
|
121 |
|
122 .. class:: FileInput([files[, inplace[, backup[, mode[, openhook]]]]]) |
|
123 |
|
124 Class :class:`FileInput` is the implementation; its methods :meth:`filename`, |
|
125 :meth:`fileno`, :meth:`lineno`, :meth:`filelineno`, :meth:`isfirstline`, |
|
126 :meth:`isstdin`, :meth:`nextfile` and :meth:`close` correspond to the functions |
|
127 of the same name in the module. In addition it has a :meth:`readline` method |
|
128 which returns the next input line, and a :meth:`__getitem__` method which |
|
129 implements the sequence behavior. The sequence must be accessed in strictly |
|
130 sequential order; random access and :meth:`readline` cannot be mixed. |
|
131 |
|
132 With *mode* you can specify which file mode will be passed to :func:`open`. It |
|
133 must be one of ``'r'``, ``'rU'``, ``'U'`` and ``'rb'``. |
|
134 |
|
135 The *openhook*, when given, must be a function that takes two arguments, |
|
136 *filename* and *mode*, and returns an accordingly opened file-like object. You |
|
137 cannot use *inplace* and *openhook* together. |
|
138 |
|
139 .. versionchanged:: 2.5 |
|
140 Added the *mode* and *openhook* parameters. |
|
141 |
|
142 **Optional in-place filtering:** if the keyword argument ``inplace=1`` is passed |
|
143 to :func:`fileinput.input` or to the :class:`FileInput` constructor, the file is |
|
144 moved to a backup file and standard output is directed to the input file (if a |
|
145 file of the same name as the backup file already exists, it will be replaced |
|
146 silently). This makes it possible to write a filter that rewrites its input |
|
147 file in place. If the *backup* parameter is given (typically as |
|
148 ``backup='.<some extension>'``), it specifies the extension for the backup file, |
|
149 and the backup file remains around; by default, the extension is ``'.bak'`` and |
|
150 it is deleted when the output file is closed. In-place filtering is disabled |
|
151 when standard input is read. |
|
152 |
|
153 .. warning:: |
|
154 |
|
155 The current implementation does not work for MS-DOS 8+3 filesystems. |
|
156 |
|
157 |
|
158 The two following opening hooks are provided by this module: |
|
159 |
|
160 .. function:: hook_compressed(filename, mode) |
|
161 |
|
162 Transparently opens files compressed with gzip and bzip2 (recognized by the |
|
163 extensions ``'.gz'`` and ``'.bz2'``) using the :mod:`gzip` and :mod:`bz2` |
|
164 modules. If the filename extension is not ``'.gz'`` or ``'.bz2'``, the file is |
|
165 opened normally (ie, using :func:`open` without any decompression). |
|
166 |
|
167 Usage example: ``fi = fileinput.FileInput(openhook=fileinput.hook_compressed)`` |
|
168 |
|
169 .. versionadded:: 2.5 |
|
170 |
|
171 |
|
172 .. function:: hook_encoded(encoding) |
|
173 |
|
174 Returns a hook which opens each file with :func:`codecs.open`, using the given |
|
175 *encoding* to read the file. |
|
176 |
|
177 Usage example: ``fi = |
|
178 fileinput.FileInput(openhook=fileinput.hook_encoded("iso-8859-1"))`` |
|
179 |
|
180 .. note:: |
|
181 |
|
182 With this hook, :class:`FileInput` might return Unicode strings depending on the |
|
183 specified *encoding*. |
|
184 |
|
185 .. versionadded:: 2.5 |
|
186 |