n | |
| :mod:`fileinput` --- Iterate over lines from multiple input streams |
| =================================================================== |
| |
| .. module:: fileinput |
n | :synopsis: Loop over standard input or a list of files. |
| .. moduleauthor:: Guido van Rossum <guido@python.org> |
| .. sectionauthor:: Fred L. Drake, Jr. <fdrake@acm.org> |
| |
| |
n | |
| |
| This module implements a helper class and functions to quickly write a loop over |
| This module implements a helper class and functions to quickly write a |
| standard input or a list of files. |
| loop over standard input or a list of files. If you just want to read or |
| write one file see :func:`open`. |
| |
| The typical use is:: |
| |
| import fileinput |
| for line in fileinput.input(): |
| process(line) |
| |
| This iterates over the lines of all files listed in ``sys.argv[1:]``, defaulting |
| If ``sys.stdin`` is used more than once, the second and further use will return |
| no lines, except perhaps for interactive use, or if it has been explicitly reset |
| (e.g. using ``sys.stdin.seek(0)``). |
| |
| Empty files are opened and immediately closed; the only time their presence in |
| the list of filenames is noticeable at all is when the last file opened is |
| empty. |
| |
n | It is possible that the last line of a file does not end in a newline character; |
n | Lines are returned with any newlines intact, which means that the last line in |
| lines are returned including the trailing newline when it is present. |
| a file may not have one. |
| |
| You can control how files are opened by providing an opening hook via the |
n | *openhook* parameter to :func:`input` or :class:`FileInput()`. The hook must be |
n | *openhook* parameter to :func:`fileinput.input` or :class:`FileInput()`. The |
| a function that takes two arguments, *filename* and *mode*, and returns an |
| hook must be a function that takes two arguments, *filename* and *mode*, and |
| accordingly opened file-like object. Two useful hooks are already provided by |
| returns an accordingly opened file-like object. Two useful hooks are already |
| this module. |
| provided by this module. |
| |
| The following function is the primary interface of this module: |
| |
| |
| .. function:: input([files[, inplace[, backup[, mode[, openhook]]]]]) |
| |
| Create an instance of the :class:`FileInput` class. The instance will be used |
| as global state for the functions of this module, and is also returned to use |
| during iteration. The parameters to this function will be passed along to the |
| constructor of the :class:`FileInput` class. |
| |
| .. versionchanged:: 2.5 |
| Added the *mode* and *openhook* parameters. |
| |
n | The following functions use the global state created by :func:`input`; if there |
n | The following functions use the global state created by :func:`fileinput.input`; |
| is no active state, :exc:`RuntimeError` is raised. |
| if there is no active state, :exc:`RuntimeError` is raised. |
| |
| |
| .. function:: filename() |
| |
| Return the name of the file currently being read. Before the first line has |
| been read, returns ``None``. |
| |
| |
| |
| The class which implements the sequence behavior provided by the module is |
| available for subclassing as well: |
| |
| |
| .. class:: FileInput([files[, inplace[, backup[, mode[, openhook]]]]]) |
| |
| Class :class:`FileInput` is the implementation; its methods :meth:`filename`, |
n | :meth:`fileno`, :meth:`lineno`, :meth:`fileline`, :meth:`isfirstline`, |
n | :meth:`fileno`, :meth:`lineno`, :meth:`filelineno`, :meth:`isfirstline`, |
| :meth:`isstdin`, :meth:`nextfile` and :meth:`close` correspond to the functions |
| of the same name in the module. In addition it has a :meth:`readline` method |
| which returns the next input line, and a :meth:`__getitem__` method which |
| implements the sequence behavior. The sequence must be accessed in strictly |
| sequential order; random access and :meth:`readline` cannot be mixed. |
| |
| With *mode* you can specify which file mode will be passed to :func:`open`. It |
| must be one of ``'r'``, ``'rU'``, ``'U'`` and ``'rb'``. |
| The *openhook*, when given, must be a function that takes two arguments, |
| *filename* and *mode*, and returns an accordingly opened file-like object. You |
| cannot use *inplace* and *openhook* together. |
| |
| .. versionchanged:: 2.5 |
| Added the *mode* and *openhook* parameters. |
| |
| **Optional in-place filtering:** if the keyword argument ``inplace=1`` is passed |
n | to :func:`input` or to the :class:`FileInput` constructor, the file is moved to |
n | to :func:`fileinput.input` or to the :class:`FileInput` constructor, the file is |
| a backup file and standard output is directed to the input file (if a file of |
| moved to a backup file and standard output is directed to the input file (if a |
| the same name as the backup file already exists, it will be replaced silently). |
| file of the same name as the backup file already exists, it will be replaced |
| This makes it possible to write a filter that rewrites its input file in place. |
| silently). This makes it possible to write a filter that rewrites its input |
| If the keyword argument ``backup='.<some extension>'`` is also given, it |
| file in place. If the *backup* parameter is given (typically as |
| specifies the extension for the backup file, and the backup file remains around; |
| ``backup='.<some extension>'``), it specifies the extension for the backup file, |
| by default, the extension is ``'.bak'`` and it is deleted when the output file |
| and the backup file remains around; by default, the extension is ``'.bak'`` and |
| is closed. In-place filtering is disabled when standard input is read. |
| it is deleted when the output file is closed. In-place filtering is disabled |
| when standard input is read. |
| |
n | .. warning:: |
| |
| **Caveat:** The current implementation does not work for MS-DOS 8+3 filesystems. |
| The current implementation does not work for MS-DOS 8+3 filesystems. |
| |
| |
| The two following opening hooks are provided by this module: |
t | |
| |
| .. function:: hook_compressed(filename, mode) |
| |
| Transparently opens files compressed with gzip and bzip2 (recognized by the |
| extensions ``'.gz'`` and ``'.bz2'``) using the :mod:`gzip` and :mod:`bz2` |
| modules. If the filename extension is not ``'.gz'`` or ``'.bz2'``, the file is |
| opened normally (ie, using :func:`open` without any decompression). |
| |