| 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 <[email protected]> |
| 8 |
.. sectionauthor:: Fred L. Drake, Jr. <[email protected]> |
| 9 |
|
| 10 |
**Source code:** :source:`Lib/fileinput.py` |
| 11 |
|
| 12 |
-------------- |
| 13 |
|
| 14 |
This module implements a helper class and functions to quickly write a |
| 15 |
loop over standard input or a list of files. If you just want to read or |
| 16 |
write one file see :func:`open`. |
| 17 |
|
| 18 |
The typical use is:: |
| 19 |
|
| 20 |
import fileinput |
| 21 |
for line in fileinput.input(encoding="utf-8"): |
| 22 |
process(line) |
| 23 |
|
| 24 |
This iterates over the lines of all files listed in ``sys.argv[1:]``, defaulting |
| 25 |
to ``sys.stdin`` if the list is empty. If a filename is ``'-'``, it is also |
| 26 |
replaced by ``sys.stdin`` and the optional arguments *mode* and *openhook* |
| 27 |
are ignored. To specify an alternative list of filenames, pass it as the |
| 28 |
first argument to :func:`.input`. A single file name is also allowed. |
| 29 |
|
| 30 |
All files are opened in text mode by default, but you can override this by |
| 31 |
specifying 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 |
|
| 38 |
If ``sys.stdin`` is used more than once, the second and further use will return |
| 39 |
no lines, except perhaps for interactive use, or if it has been explicitly reset |
| 40 |
(e.g. using ``sys.stdin.seek(0)``). |
| 41 |
|
| 42 |
Empty files are opened and immediately closed; the only time their presence in |
| 43 |
the list of filenames is noticeable at all is when the last file opened is |
| 44 |
empty. |
| 45 |
|
| 46 |
Lines are returned with any newlines intact, which means that the last line in |
| 47 |
a file may not have one. |
| 48 |
|
| 49 |
You can control how files are opened by providing an opening hook via the |
| 50 |
*openhook* parameter to :func:`fileinput.input` or :func:`FileInput`. The |
| 51 |
hook must be a function that takes two arguments, *filename* and *mode*, and |
| 52 |
returns an accordingly opened file-like object. If *encoding* and/or *errors* |
| 53 |
are specified, they will be passed to the hook as additional keyword arguments. |
| 54 |
This module provides a :func:`hook_compressed` to support compressed files. |
| 55 |
|
| 56 |
The 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 |
|
| 84 |
The following functions use the global state created by :func:`fileinput.input`; |
| 85 |
if 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 |
|
| 140 |
The class which implements the sequence behavior provided by the module is |
| 141 |
available 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 is :term:`iterable` |
| 150 |
and has a :meth:`~io.TextIOBase.readline` method which returns the next |
| 151 |
input line. The sequence must be accessed in strictly sequential order; |
| 152 |
random access and :meth:`~io.TextIOBase.readline` cannot be mixed. |
| 153 |
|
| 154 |
With *mode* you can specify which file mode will be passed to :func:`open`. It |
| 155 |
must be one of ``'r'`` and ``'rb'``. |
| 156 |
|
| 157 |
The *openhook*, when given, must be a function that takes two arguments, |
| 158 |
*filename* and *mode*, and returns an accordingly opened file-like object. You |
| 159 |
cannot use *inplace* and *openhook* together. |
| 160 |
|
| 161 |
You can specify *encoding* and *errors* that is passed to :func:`open` or *openhook*. |
| 162 |
|
| 163 |
A :class:`FileInput` instance can be used as a context manager in the |
| 164 |
:keyword:`with` statement. In this example, *input* is closed after the |
| 165 |
:keyword:`!with` statement is exited, even if an exception occurs:: |
| 166 |
|
| 167 |
with FileInput(files=('spam.txt', 'eggs.txt')) as input: |
| 168 |
process(input) |
| 169 |
|
| 170 |
.. versionchanged:: 3.2 |
| 171 |
Can be used as a context manager. |
| 172 |
|
| 173 |
.. versionchanged:: 3.8 |
| 174 |
The keyword parameter *mode* and *openhook* are now keyword-only. |
| 175 |
|
| 176 |
.. versionchanged:: 3.10 |
| 177 |
The keyword-only parameter *encoding* and *errors* are added. |
| 178 |
|
| 179 |
.. versionchanged:: 3.11 |
| 180 |
The ``'rU'`` and ``'U'`` modes and the :meth:`!__getitem__` method have |
| 181 |
been removed. |
| 182 |
|
| 183 |
|
| 184 |
**Optional in-place filtering:** if the keyword argument ``inplace=True`` is |
| 185 |
passed to :func:`fileinput.input` or to the :class:`FileInput` constructor, the |
| 186 |
file is moved to a backup file and standard output is directed to the input file |
| 187 |
(if a file of the same name as the backup file already exists, it will be |
| 188 |
replaced silently). This makes it possible to write a filter that rewrites its |
| 189 |
input file in place. If the *backup* parameter is given (typically as |
| 190 |
``backup='.<some extension>'``), it specifies the extension for the backup file, |
| 191 |
and the backup file remains around; by default, the extension is ``'.bak'`` and |
| 192 |
it is deleted when the output file is closed. In-place filtering is disabled |
| 193 |
when standard input is read. |
| 194 |
|
| 195 |
|
| 196 |
The two following opening hooks are provided by this module: |
| 197 |
|
| 198 |
.. function:: hook_compressed(filename, mode, *, encoding=None, errors=None) |
| 199 |
|
| 200 |
Transparently opens files compressed with gzip and bzip2 (recognized by the |
| 201 |
extensions ``'.gz'`` and ``'.bz2'``) using the :mod:`gzip` and :mod:`bz2` |
| 202 |
modules. If the filename extension is not ``'.gz'`` or ``'.bz2'``, the file is |
| 203 |
opened normally (ie, using :func:`open` without any decompression). |
| 204 |
|
| 205 |
The *encoding* and *errors* values are passed to :class:`io.TextIOWrapper` |
| 206 |
for compressed files and open for normal files. |
| 207 |
|
| 208 |
Usage example: ``fi = fileinput.FileInput(openhook=fileinput.hook_compressed, encoding="utf-8")`` |
| 209 |
|
| 210 |
.. versionchanged:: 3.10 |
| 211 |
The keyword-only parameter *encoding* and *errors* are added. |
| 212 |
|
| 213 |
|
| 214 |
.. function:: hook_encoded(encoding, errors=None) |
| 215 |
|
| 216 |
Returns a hook which opens each file with :func:`open`, using the given |
| 217 |
*encoding* and *errors* to read the file. |
| 218 |
|
| 219 |
Usage example: ``fi = |
| 220 |
fileinput.FileInput(openhook=fileinput.hook_encoded("utf-8", |
| 221 |
"surrogateescape"))`` |
| 222 |
|
| 223 |
.. versionchanged:: 3.6 |
| 224 |
Added the optional *errors* parameter. |
| 225 |
|
| 226 |
.. deprecated:: 3.10 |
| 227 |
This function is deprecated since :func:`fileinput.input` and :class:`FileInput` |
| 228 |
now have *encoding* and *errors* parameters. |