Doc/library/fileinput.rst

   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 .. note::
 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