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 7.. moduleauthor:: Guido van Rossum <guido@python.org> 8.. sectionauthor:: Fred L. Drake, Jr. <fdrake@acm.org> 9 10**Source code:** :source:`Lib/fileinput.py` 11 12-------------- 13 14This module implements a helper class and functions to quickly write a 15loop over standard input or a list of files. If you just want to read or 16write one file see :func:`open`. 17 18The typical use is:: 19 20 import fileinput 21 for line in fileinput.input(encoding="utf-8"): 22 process(line) 23 24This iterates over the lines of all files listed in ``sys.argv[1:]``, defaulting 25to ``sys.stdin`` if the list is empty. If a filename is ``'-'``, it is also 26replaced by ``sys.stdin`` and the optional arguments *mode* and *openhook* 27are ignored. To specify an alternative list of filenames, pass it as the 28first argument to :func:`.input`. A single file name is also allowed. 29 30All files are opened in text mode by default, but you can override this by 31specifying the *mode* parameter in the call to :func:`.input` or 32:class:`FileInput`. If an I/O error occurs during opening or reading a file, 33:exc:`OSError` is raised. 34 35.. versionchanged:: 3.3 36 :exc:`IOError` used to be raised; it is now an alias of :exc:`OSError`. 37 38If ``sys.stdin`` is used more than once, the second and further use will return 39no lines, except perhaps for interactive use, or if it has been explicitly reset 40(e.g. using ``sys.stdin.seek(0)``). 41 42Empty files are opened and immediately closed; the only time their presence in 43the list of filenames is noticeable at all is when the last file opened is 44empty. 45 46Lines are returned with any newlines intact, which means that the last line in 47a file may not have one. 48 49You can control how files are opened by providing an opening hook via the 50*openhook* parameter to :func:`fileinput.input` or :class:`FileInput()`. The 51hook must be a function that takes two arguments, *filename* and *mode*, and 52returns an accordingly opened file-like object. If *encoding* and/or *errors* 53are specified, they will be passed to the hook as additional keyword arguments. 54This module provides a :func:`hook_compressed` to support compressed files. 55 56The following function is the primary interface of this module: 57 58 59.. function:: input(files=None, inplace=False, backup='', *, mode='r', openhook=None, encoding=None, errors=None) 60 61 Create an instance of the :class:`FileInput` class. The instance will be used 62 as global state for the functions of this module, and is also returned to use 63 during iteration. The parameters to this function will be passed along to the 64 constructor of the :class:`FileInput` class. 65 66 The :class:`FileInput` instance can be used as a context manager in the 67 :keyword:`with` statement. In this example, *input* is closed after the 68 :keyword:`!with` statement is exited, even if an exception occurs:: 69 70 with fileinput.input(files=('spam.txt', 'eggs.txt'), encoding="utf-8") as f: 71 for line in f: 72 process(line) 73 74 .. versionchanged:: 3.2 75 Can be used as a context manager. 76 77 .. versionchanged:: 3.8 78 The keyword parameters *mode* and *openhook* are now keyword-only. 79 80 .. versionchanged:: 3.10 81 The keyword-only parameter *encoding* and *errors* are added. 82 83 84The following functions use the global state created by :func:`fileinput.input`; 85if there is no active state, :exc:`RuntimeError` is raised. 86 87 88.. function:: filename() 89 90 Return the name of the file currently being read. Before the first line has 91 been read, returns ``None``. 92 93 94.. function:: fileno() 95 96 Return the integer "file descriptor" for the current file. When no file is 97 opened (before the first line and between files), returns ``-1``. 98 99 100.. function:: lineno() 101 102 Return the cumulative line number of the line that has just been read. Before 103 the first line has been read, returns ``0``. After the last line of the last 104 file has been read, returns the line number of that line. 105 106 107.. function:: filelineno() 108 109 Return the line number in the current file. Before the first line has been 110 read, returns ``0``. After the last line of the last file has been read, 111 returns the line number of that line within the file. 112 113 114.. function:: isfirstline() 115 116 Return ``True`` if the line just read is the first line of its file, otherwise 117 return ``False``. 118 119 120.. function:: isstdin() 121 122 Return ``True`` if the last line was read from ``sys.stdin``, otherwise return 123 ``False``. 124 125 126.. function:: nextfile() 127 128 Close the current file so that the next iteration will read the first line from 129 the next file (if any); lines not read from the file will not count towards the 130 cumulative line count. The filename is not changed until after the first line 131 of the next file has been read. Before the first line has been read, this 132 function has no effect; it cannot be used to skip the first file. After the 133 last line of the last file has been read, this function has no effect. 134 135 136.. function:: close() 137 138 Close the sequence. 139 140The class which implements the sequence behavior provided by the module is 141available for subclassing as well: 142 143 144.. class:: FileInput(files=None, inplace=False, backup='', *, mode='r', openhook=None, encoding=None, errors=None) 145 146 Class :class:`FileInput` is the implementation; its methods :meth:`filename`, 147 :meth:`fileno`, :meth:`lineno`, :meth:`filelineno`, :meth:`isfirstline`, 148 :meth:`isstdin`, :meth:`nextfile` and :meth:`close` correspond to the 149 functions of the same name in the module. In addition it has a 150 :meth:`~io.TextIOBase.readline` method which returns the next input line, 151 and a :meth:`__getitem__` method which implements the sequence behavior. 152 The sequence must be accessed in strictly sequential order; random access 153 and :meth:`~io.TextIOBase.readline` cannot be mixed. 154 155 With *mode* you can specify which file mode will be passed to :func:`open`. It 156 must be one of ``'r'``, ``'rU'``, ``'U'`` and ``'rb'``. 157 158 The *openhook*, when given, must be a function that takes two arguments, 159 *filename* and *mode*, and returns an accordingly opened file-like object. You 160 cannot use *inplace* and *openhook* together. 161 162 You can specify *encoding* and *errors* that is passed to :func:`open` or *openhook*. 163 164 A :class:`FileInput` instance can be used as a context manager in the 165 :keyword:`with` statement. In this example, *input* is closed after the 166 :keyword:`!with` statement is exited, even if an exception occurs:: 167 168 with FileInput(files=('spam.txt', 'eggs.txt')) as input: 169 process(input) 170 171 .. versionchanged:: 3.2 172 Can be used as a context manager. 173 174 .. deprecated:: 3.4 175 The ``'rU'`` and ``'U'`` modes. 176 177 .. deprecated:: 3.8 178 Support for :meth:`__getitem__` method is deprecated. 179 180 .. versionchanged:: 3.8 181 The keyword parameter *mode* and *openhook* are now keyword-only. 182 183 .. versionchanged:: 3.10 184 The keyword-only parameter *encoding* and *errors* are added. 185 186 187**Optional in-place filtering:** if the keyword argument ``inplace=True`` is 188passed to :func:`fileinput.input` or to the :class:`FileInput` constructor, the 189file is moved to a backup file and standard output is directed to the input file 190(if a file of the same name as the backup file already exists, it will be 191replaced silently). This makes it possible to write a filter that rewrites its 192input file in place. If the *backup* parameter is given (typically as 193``backup='.<some extension>'``), it specifies the extension for the backup file, 194and the backup file remains around; by default, the extension is ``'.bak'`` and 195it is deleted when the output file is closed. In-place filtering is disabled 196when standard input is read. 197 198 199The two following opening hooks are provided by this module: 200 201.. function:: hook_compressed(filename, mode, *, encoding=None, errors=None) 202 203 Transparently opens files compressed with gzip and bzip2 (recognized by the 204 extensions ``'.gz'`` and ``'.bz2'``) using the :mod:`gzip` and :mod:`bz2` 205 modules. If the filename extension is not ``'.gz'`` or ``'.bz2'``, the file is 206 opened normally (ie, using :func:`open` without any decompression). 207 208 The *encoding* and *errors* values are passed to :class:`io.TextIOWrapper` 209 for compressed files and open for normal files. 210 211 Usage example: ``fi = fileinput.FileInput(openhook=fileinput.hook_compressed, encoding="utf-8")`` 212 213 .. versionchanged:: 3.10 214 The keyword-only parameter *encoding* and *errors* are added. 215 216 217.. function:: hook_encoded(encoding, errors=None) 218 219 Returns a hook which opens each file with :func:`open`, using the given 220 *encoding* and *errors* to read the file. 221 222 Usage example: ``fi = 223 fileinput.FileInput(openhook=fileinput.hook_encoded("utf-8", 224 "surrogateescape"))`` 225 226 .. versionchanged:: 3.6 227 Added the optional *errors* parameter. 228 229 .. deprecated:: 3.10 230 This function is deprecated since :func:`input` and :class:`FileInput` 231 now have *encoding* and *errors* parameters. 232