Mercurial > cpython-lru_cache-weakref
annotate Doc/lib/libfileinput.tex @ 39042:c02fa187e0f4 legacy-trunk
Part of SF patch #1484695. This removes dead code. The chksum was
already verified in .frombuf() on the lines above. If there was
a problem an exception is raised, so there was no way this condition
could have been true.
| author | Neal Norwitz <nnorwitz@gmail.com> |
|---|---|
| date | Mon, 10 Jul 2006 00:23:17 +0000 |
| parents | f6d6e5220823 |
| children |
| rev | line source |
|---|---|
| 8918 | 1 \section{\module{fileinput} --- |
|
11076
4a1d6c7b0950
Minor wording change in section title.
Fred Drake <fdrake@acm.org>
parents:
8918
diff
changeset
|
2 Iterate over lines from multiple input streams} |
|
8716
760dcf197048
Adjusted to use the new module synopsis support macros.
Fred Drake <fdrake@acm.org>
parents:
7860
diff
changeset
|
3 \declaremodule{standard}{fileinput} |
| 8918 | 4 \moduleauthor{Guido van Rossum}{guido@python.org} |
| 5 \sectionauthor{Fred L. Drake, Jr.}{fdrake@acm.org} | |
|
8716
760dcf197048
Adjusted to use the new module synopsis support macros.
Fred Drake <fdrake@acm.org>
parents:
7860
diff
changeset
|
6 |
| 8918 | 7 \modulesynopsis{Perl-like iteration over lines from multiple input |
| 8 streams, with ``save in place'' capability.} | |
|
8716
760dcf197048
Adjusted to use the new module synopsis support macros.
Fred Drake <fdrake@acm.org>
parents:
7860
diff
changeset
|
9 |
| 7860 | 10 |
| 11 This module implements a helper class and functions to quickly write a | |
| 12 loop over standard input or a list of files. | |
| 13 | |
| 14 The typical use is: | |
| 15 | |
| 16 \begin{verbatim} | |
| 17 import fileinput | |
| 18 for line in fileinput.input(): | |
| 19 process(line) | |
| 20 \end{verbatim} | |
| 21 | |
| 22 This iterates over the lines of all files listed in | |
| 23 \code{sys.argv[1:]}, defaulting to \code{sys.stdin} if the list is | |
| 24 empty. If a filename is \code{'-'}, it is also replaced by | |
| 25 \code{sys.stdin}. To specify an alternative list of filenames, pass | |
| 26 it as the first argument to \function{input()}. A single file name is | |
| 27 also allowed. | |
| 28 | |
|
36595
c6fba456227b
Patch #1212287: fileinput.input() now has a mode parameter for
Georg Brandl <georg@python.org>
parents:
36594
diff
changeset
|
29 All files are opened in text mode by default, but you can override this by |
|
c6fba456227b
Patch #1212287: fileinput.input() now has a mode parameter for
Georg Brandl <georg@python.org>
parents:
36594
diff
changeset
|
30 specifying the \var{mode} parameter in the call to \function{input()} |
|
c6fba456227b
Patch #1212287: fileinput.input() now has a mode parameter for
Georg Brandl <georg@python.org>
parents:
36594
diff
changeset
|
31 or \class{FileInput()}. If an I/O error occurs during opening or reading |
|
c6fba456227b
Patch #1212287: fileinput.input() now has a mode parameter for
Georg Brandl <georg@python.org>
parents:
36594
diff
changeset
|
32 a file, \exception{IOError} is raised. |
| 7860 | 33 |
| 34 If \code{sys.stdin} is used more than once, the second and further use | |
| 35 will return no lines, except perhaps for interactive use, or if it has | |
| 36 been explicitly reset (e.g. using \code{sys.stdin.seek(0)}). | |
| 37 | |
| 38 Empty files are opened and immediately closed; the only time their | |
| 39 presence in the list of filenames is noticeable at all is when the | |
| 40 last file opened is empty. | |
| 41 | |
| 42 It is possible that the last line of a file does not end in a newline | |
| 43 character; lines are returned including the trailing newline when it | |
| 44 is present. | |
| 45 | |
|
36596
e57377f0a167
Patch #1215184: FileInput now can be given an opening hook which can
Georg Brandl <georg@python.org>
parents:
36595
diff
changeset
|
46 You can control how files are opened by providing an opening hook via the |
|
e57377f0a167
Patch #1215184: FileInput now can be given an opening hook which can
Georg Brandl <georg@python.org>
parents:
36595
diff
changeset
|
47 \var{openhook} parameter to \function{input()} or \class{FileInput()}. |
|
e57377f0a167
Patch #1215184: FileInput now can be given an opening hook which can
Georg Brandl <georg@python.org>
parents:
36595
diff
changeset
|
48 The hook must be a function that takes two arguments, \var{filename} |
|
e57377f0a167
Patch #1215184: FileInput now can be given an opening hook which can
Georg Brandl <georg@python.org>
parents:
36595
diff
changeset
|
49 and \var{mode}, and returns an accordingly opened file-like object. |
|
e57377f0a167
Patch #1215184: FileInput now can be given an opening hook which can
Georg Brandl <georg@python.org>
parents:
36595
diff
changeset
|
50 Two useful hooks are already provided by this module. |
|
e57377f0a167
Patch #1215184: FileInput now can be given an opening hook which can
Georg Brandl <georg@python.org>
parents:
36595
diff
changeset
|
51 |
| 7860 | 52 The following function is the primary interface of this module: |
| 53 | |
|
36596
e57377f0a167
Patch #1215184: FileInput now can be given an opening hook which can
Georg Brandl <georg@python.org>
parents:
36595
diff
changeset
|
54 \begin{funcdesc}{input}{\optional{files\optional{, inplace\optional{, |
|
e57377f0a167
Patch #1215184: FileInput now can be given an opening hook which can
Georg Brandl <georg@python.org>
parents:
36595
diff
changeset
|
55 backup\optional{, mode\optional{, openhook}}}}}} |
| 7860 | 56 Create an instance of the \class{FileInput} class. The instance |
| 57 will be used as global state for the functions of this module, and | |
|
17714
6493d5e941c2
Note that when inplace=1 existing backup files will be removed silently.
Fred Drake <fdrake@acm.org>
parents:
12223
diff
changeset
|
58 is also returned to use during iteration. The parameters to this |
|
6493d5e941c2
Note that when inplace=1 existing backup files will be removed silently.
Fred Drake <fdrake@acm.org>
parents:
12223
diff
changeset
|
59 function will be passed along to the constructor of the |
|
6493d5e941c2
Note that when inplace=1 existing backup files will be removed silently.
Fred Drake <fdrake@acm.org>
parents:
12223
diff
changeset
|
60 \class{FileInput} class. |
|
36595
c6fba456227b
Patch #1212287: fileinput.input() now has a mode parameter for
Georg Brandl <georg@python.org>
parents:
36594
diff
changeset
|
61 |
|
36596
e57377f0a167
Patch #1215184: FileInput now can be given an opening hook which can
Georg Brandl <georg@python.org>
parents:
36595
diff
changeset
|
62 \versionchanged[Added the \var{mode} and \var{openhook} parameters]{2.5} |
| 7860 | 63 \end{funcdesc} |
| 64 | |
| 65 | |
| 66 The following functions use the global state created by | |
| 67 \function{input()}; if there is no active state, | |
| 68 \exception{RuntimeError} is raised. | |
| 69 | |
| 70 \begin{funcdesc}{filename}{} | |
| 71 Return the name of the file currently being read. Before the first | |
| 72 line has been read, returns \code{None}. | |
| 73 \end{funcdesc} | |
| 74 | |
|
36594
781654be55ef
Patch #1215184: fileinput now has a fileno() function for getting the
Georg Brandl <georg@python.org>
parents:
30896
diff
changeset
|
75 \begin{funcdesc}{fileno}{} |
|
781654be55ef
Patch #1215184: fileinput now has a fileno() function for getting the
Georg Brandl <georg@python.org>
parents:
30896
diff
changeset
|
76 Return the integer ``file descriptor'' for the current file. When no |
|
781654be55ef
Patch #1215184: fileinput now has a fileno() function for getting the
Georg Brandl <georg@python.org>
parents:
30896
diff
changeset
|
77 file is opened (before the first line and between files), returns |
|
781654be55ef
Patch #1215184: fileinput now has a fileno() function for getting the
Georg Brandl <georg@python.org>
parents:
30896
diff
changeset
|
78 \code{-1}. |
| 36603 | 79 \versionadded{2.5} |
|
36594
781654be55ef
Patch #1215184: fileinput now has a fileno() function for getting the
Georg Brandl <georg@python.org>
parents:
30896
diff
changeset
|
80 \end{funcdesc} |
|
781654be55ef
Patch #1215184: fileinput now has a fileno() function for getting the
Georg Brandl <georg@python.org>
parents:
30896
diff
changeset
|
81 |
| 7860 | 82 \begin{funcdesc}{lineno}{} |
| 83 Return the cumulative line number of the line that has just been | |
| 84 read. Before the first line has been read, returns \code{0}. After | |
| 85 the last line of the last file has been read, returns the line | |
| 86 number of that line. | |
| 87 \end{funcdesc} | |
| 88 | |
| 89 \begin{funcdesc}{filelineno}{} | |
| 90 Return the line number in the current file. Before the first line | |
| 91 has been read, returns \code{0}. After the last line of the last | |
| 92 file has been read, returns the line number of that line within the | |
| 93 file. | |
| 94 \end{funcdesc} | |
| 95 | |
| 96 \begin{funcdesc}{isfirstline}{} | |
| 30896 | 97 Returns true if the line just read is the first line of its file, |
|
12223
e82e82b3b9ad
Merged changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
11076
diff
changeset
|
98 otherwise returns false. |
| 7860 | 99 \end{funcdesc} |
| 100 | |
| 101 \begin{funcdesc}{isstdin}{} | |
|
12223
e82e82b3b9ad
Merged changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
11076
diff
changeset
|
102 Returns true if the last line was read from \code{sys.stdin}, |
|
e82e82b3b9ad
Merged changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
11076
diff
changeset
|
103 otherwise returns false. |
| 7860 | 104 \end{funcdesc} |
| 105 | |
| 106 \begin{funcdesc}{nextfile}{} | |
| 107 Close the current file so that the next iteration will read the | |
| 108 first line from the next file (if any); lines not read from the file | |
| 109 will not count towards the cumulative line count. The filename is | |
| 110 not changed until after the first line of the next file has been | |
| 111 read. Before the first line has been read, this function has no | |
| 112 effect; it cannot be used to skip the first file. After the last | |
| 113 line of the last file has been read, this function has no effect. | |
| 114 \end{funcdesc} | |
| 115 | |
| 116 \begin{funcdesc}{close}{} | |
| 117 Close the sequence. | |
| 118 \end{funcdesc} | |
| 119 | |
| 120 | |
| 121 The class which implements the sequence behavior provided by the | |
| 122 module is available for subclassing as well: | |
| 123 | |
| 124 \begin{classdesc}{FileInput}{\optional{files\optional{, | |
|
36596
e57377f0a167
Patch #1215184: FileInput now can be given an opening hook which can
Georg Brandl <georg@python.org>
parents:
36595
diff
changeset
|
125 inplace\optional{, backup\optional{, |
|
e57377f0a167
Patch #1215184: FileInput now can be given an opening hook which can
Georg Brandl <georg@python.org>
parents:
36595
diff
changeset
|
126 mode\optional{, openhook}}}}}} |
| 7860 | 127 Class \class{FileInput} is the implementation; its methods |
|
36594
781654be55ef
Patch #1215184: fileinput now has a fileno() function for getting the
Georg Brandl <georg@python.org>
parents:
30896
diff
changeset
|
128 \method{filename()}, \method{fileno()}, \method{lineno()}, |
|
781654be55ef
Patch #1215184: fileinput now has a fileno() function for getting the
Georg Brandl <georg@python.org>
parents:
30896
diff
changeset
|
129 \method{fileline()}, \method{isfirstline()}, \method{isstdin()}, |
|
781654be55ef
Patch #1215184: fileinput now has a fileno() function for getting the
Georg Brandl <georg@python.org>
parents:
30896
diff
changeset
|
130 \method{nextfile()} and \method{close()} correspond to the functions |
|
781654be55ef
Patch #1215184: fileinput now has a fileno() function for getting the
Georg Brandl <georg@python.org>
parents:
30896
diff
changeset
|
131 of the same name in the module. |
|
781654be55ef
Patch #1215184: fileinput now has a fileno() function for getting the
Georg Brandl <georg@python.org>
parents:
30896
diff
changeset
|
132 In addition it has a \method{readline()} method which |
| 7860 | 133 returns the next input line, and a \method{__getitem__()} method |
| 134 which implements the sequence behavior. The sequence must be | |
| 135 accessed in strictly sequential order; random access and | |
| 136 \method{readline()} cannot be mixed. | |
|
36595
c6fba456227b
Patch #1212287: fileinput.input() now has a mode parameter for
Georg Brandl <georg@python.org>
parents:
36594
diff
changeset
|
137 |
|
c6fba456227b
Patch #1212287: fileinput.input() now has a mode parameter for
Georg Brandl <georg@python.org>
parents:
36594
diff
changeset
|
138 With \var{mode} you can specify which file mode will be passed to |
|
c6fba456227b
Patch #1212287: fileinput.input() now has a mode parameter for
Georg Brandl <georg@python.org>
parents:
36594
diff
changeset
|
139 \function{open()}. It must be one of \code{'r'}, \code{'rU'}, |
|
c6fba456227b
Patch #1212287: fileinput.input() now has a mode parameter for
Georg Brandl <georg@python.org>
parents:
36594
diff
changeset
|
140 \code{'U'} and \code{'rb'}. |
|
c6fba456227b
Patch #1212287: fileinput.input() now has a mode parameter for
Georg Brandl <georg@python.org>
parents:
36594
diff
changeset
|
141 |
|
36596
e57377f0a167
Patch #1215184: FileInput now can be given an opening hook which can
Georg Brandl <georg@python.org>
parents:
36595
diff
changeset
|
142 The \var{openhook}, when given, must be a function that takes two arguments, |
|
e57377f0a167
Patch #1215184: FileInput now can be given an opening hook which can
Georg Brandl <georg@python.org>
parents:
36595
diff
changeset
|
143 \var{filename} and \var{mode}, and returns an accordingly opened |
|
e57377f0a167
Patch #1215184: FileInput now can be given an opening hook which can
Georg Brandl <georg@python.org>
parents:
36595
diff
changeset
|
144 file-like object. |
|
e57377f0a167
Patch #1215184: FileInput now can be given an opening hook which can
Georg Brandl <georg@python.org>
parents:
36595
diff
changeset
|
145 You cannot use \var{inplace} and \var{openhook} together. |
|
e57377f0a167
Patch #1215184: FileInput now can be given an opening hook which can
Georg Brandl <georg@python.org>
parents:
36595
diff
changeset
|
146 |
|
e57377f0a167
Patch #1215184: FileInput now can be given an opening hook which can
Georg Brandl <georg@python.org>
parents:
36595
diff
changeset
|
147 \versionchanged[Added the \var{mode} and \var{openhook} parameters]{2.5} |
| 7860 | 148 \end{classdesc} |
| 149 | |
| 150 \strong{Optional in-place filtering:} if the keyword argument | |
| 151 \code{\var{inplace}=1} is passed to \function{input()} or to the | |
| 152 \class{FileInput} constructor, the file is moved to a backup file and | |
|
17714
6493d5e941c2
Note that when inplace=1 existing backup files will be removed silently.
Fred Drake <fdrake@acm.org>
parents:
12223
diff
changeset
|
153 standard output is directed to the input file (if a file of the same |
|
6493d5e941c2
Note that when inplace=1 existing backup files will be removed silently.
Fred Drake <fdrake@acm.org>
parents:
12223
diff
changeset
|
154 name as the backup file already exists, it will be replaced silently). |
| 7860 | 155 This makes it possible to write a filter that rewrites its input file |
| 156 in place. If the keyword argument \code{\var{backup}='.<some | |
| 157 extension>'} is also given, it specifies the extension for the backup | |
| 158 file, and the backup file remains around; by default, the extension is | |
| 159 \code{'.bak'} and it is deleted when the output file is closed. In-place | |
| 160 filtering is disabled when standard input is read. | |
| 161 | |
| 162 \strong{Caveat:} The current implementation does not work for MS-DOS | |
| 163 8+3 filesystems. | |
|
36596
e57377f0a167
Patch #1215184: FileInput now can be given an opening hook which can
Georg Brandl <georg@python.org>
parents:
36595
diff
changeset
|
164 |
|
e57377f0a167
Patch #1215184: FileInput now can be given an opening hook which can
Georg Brandl <georg@python.org>
parents:
36595
diff
changeset
|
165 |
|
e57377f0a167
Patch #1215184: FileInput now can be given an opening hook which can
Georg Brandl <georg@python.org>
parents:
36595
diff
changeset
|
166 The two following opening hooks are provided by this module: |
|
e57377f0a167
Patch #1215184: FileInput now can be given an opening hook which can
Georg Brandl <georg@python.org>
parents:
36595
diff
changeset
|
167 |
|
e57377f0a167
Patch #1215184: FileInput now can be given an opening hook which can
Georg Brandl <georg@python.org>
parents:
36595
diff
changeset
|
168 \begin{funcdesc}{hook_compressed}{filename, mode} |
|
36597
38f4b098ea69
Clarify how hook_compressed determines how to open a file.
Georg Brandl <georg@python.org>
parents:
36596
diff
changeset
|
169 Transparently opens files compressed with gzip and bzip2 (recognized |
|
38f4b098ea69
Clarify how hook_compressed determines how to open a file.
Georg Brandl <georg@python.org>
parents:
36596
diff
changeset
|
170 by the extensions \code{'.gz'} and \code{'.bz2'}) using the \module{gzip} |
| 36603 | 171 and \module{bz2} modules. If the filename extension is not \code{'.gz'} |
| 36606 | 172 or \code{'.bz2'}, the file is opened normally (ie, |
| 36603 | 173 using \function{open()} without any decompression). |
|
36596
e57377f0a167
Patch #1215184: FileInput now can be given an opening hook which can
Georg Brandl <georg@python.org>
parents:
36595
diff
changeset
|
174 |
|
e57377f0a167
Patch #1215184: FileInput now can be given an opening hook which can
Georg Brandl <georg@python.org>
parents:
36595
diff
changeset
|
175 Usage example: |
|
e57377f0a167
Patch #1215184: FileInput now can be given an opening hook which can
Georg Brandl <georg@python.org>
parents:
36595
diff
changeset
|
176 \samp{fi = fileinput.FileInput(openhook=fileinput.hook_compressed)} |
|
e57377f0a167
Patch #1215184: FileInput now can be given an opening hook which can
Georg Brandl <georg@python.org>
parents:
36595
diff
changeset
|
177 |
|
e57377f0a167
Patch #1215184: FileInput now can be given an opening hook which can
Georg Brandl <georg@python.org>
parents:
36595
diff
changeset
|
178 \versionadded{2.5} |
|
e57377f0a167
Patch #1215184: FileInput now can be given an opening hook which can
Georg Brandl <georg@python.org>
parents:
36595
diff
changeset
|
179 \end{funcdesc} |
|
e57377f0a167
Patch #1215184: FileInput now can be given an opening hook which can
Georg Brandl <georg@python.org>
parents:
36595
diff
changeset
|
180 |
|
e57377f0a167
Patch #1215184: FileInput now can be given an opening hook which can
Georg Brandl <georg@python.org>
parents:
36595
diff
changeset
|
181 \begin{funcdesc}{hook_encoded}{encoding} |
|
e57377f0a167
Patch #1215184: FileInput now can be given an opening hook which can
Georg Brandl <georg@python.org>
parents:
36595
diff
changeset
|
182 Returns a hook which opens each file with \function{codecs.open()}, |
|
e57377f0a167
Patch #1215184: FileInput now can be given an opening hook which can
Georg Brandl <georg@python.org>
parents:
36595
diff
changeset
|
183 using the given \var{encoding} to read the file. |
|
e57377f0a167
Patch #1215184: FileInput now can be given an opening hook which can
Georg Brandl <georg@python.org>
parents:
36595
diff
changeset
|
184 |
|
e57377f0a167
Patch #1215184: FileInput now can be given an opening hook which can
Georg Brandl <georg@python.org>
parents:
36595
diff
changeset
|
185 Usage example: |
|
e57377f0a167
Patch #1215184: FileInput now can be given an opening hook which can
Georg Brandl <georg@python.org>
parents:
36595
diff
changeset
|
186 \samp{fi = fileinput.FileInput(openhook=fileinput.hook_encoded("iso-8859-1"))} |
|
e57377f0a167
Patch #1215184: FileInput now can be given an opening hook which can
Georg Brandl <georg@python.org>
parents:
36595
diff
changeset
|
187 |
|
e57377f0a167
Patch #1215184: FileInput now can be given an opening hook which can
Georg Brandl <georg@python.org>
parents:
36595
diff
changeset
|
188 \note{With this hook, \class{FileInput} might return Unicode strings |
|
e57377f0a167
Patch #1215184: FileInput now can be given an opening hook which can
Georg Brandl <georg@python.org>
parents:
36595
diff
changeset
|
189 depending on the specified \var{encoding}.} |
|
e57377f0a167
Patch #1215184: FileInput now can be given an opening hook which can
Georg Brandl <georg@python.org>
parents:
36595
diff
changeset
|
190 \versionadded{2.5} |
|
e57377f0a167
Patch #1215184: FileInput now can be given an opening hook which can
Georg Brandl <georg@python.org>
parents:
36595
diff
changeset
|
191 \end{funcdesc} |
|
e57377f0a167
Patch #1215184: FileInput now can be given an opening hook which can
Georg Brandl <georg@python.org>
parents:
36595
diff
changeset
|
192 |