rest25/library/fileinput.rst => rest262/library/fileinput.rst
n1- 
2:mod:`fileinput` --- Iterate over lines from multiple input streams
3===================================================================
4
5.. module:: fileinput
n5+   :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
n10- 
11- 
12-This module implements a helper class and functions to quickly write a loop over
10+This module implements a helper class and functions to quickly write a
13-standard input or a list of files.
11+loop over standard input or a list of files. If you just want to read or
12+write one file see :func:`open`.
14
15The typical use is::
16
17   import fileinput
18   for line in fileinput.input():
19       process(line)
20
21This iterates over the lines of all files listed in ``sys.argv[1:]``, defaulting
31If ``sys.stdin`` is used more than once, the second and further use will return
32no lines, except perhaps for interactive use, or if it has been explicitly reset
33(e.g. using ``sys.stdin.seek(0)``).
34
35Empty files are opened and immediately closed; the only time their presence in
36the list of filenames is noticeable at all is when the last file opened is
37empty.
38
n39-It is possible that the last line of a file does not end in a newline character;
n38+Lines are returned with any newlines intact, which means that the last line in
40-lines are returned including the trailing newline when it is present.
39+a file may not have one.
41
42You can control how files are opened by providing an opening hook via the
n43-*openhook* parameter to :func:`input` or :class:`FileInput()`. The hook must be
n42+*openhook* parameter to :func:`fileinput.input` or :class:`FileInput()`. The
44-a function that takes two arguments, *filename* and *mode*, and returns an
43+hook must be a function that takes two arguments, *filename* and *mode*, and
45-accordingly opened file-like object. Two useful hooks are already provided by
44+returns an accordingly opened file-like object. Two useful hooks are already
46-this module.
45+provided by this module.
47
48The following function is the primary interface of this module:
49
50
51.. function:: input([files[, inplace[, backup[, mode[, openhook]]]]])
52
53   Create an instance of the :class:`FileInput` class.  The instance will be used
54   as global state for the functions of this module, and is also returned to use
55   during iteration.  The parameters to this function will be passed along to the
56   constructor of the :class:`FileInput` class.
57
58   .. versionchanged:: 2.5
59      Added the *mode* and *openhook* parameters.
60
n61-The following functions use the global state created by :func:`input`; if there
n60+The following functions use the global state created by :func:`fileinput.input`;
62-is no active state, :exc:`RuntimeError` is raised.
61+if there is no active state, :exc:`RuntimeError` is raised.
63
64
65.. function:: filename()
66
67   Return the name of the file currently being read.  Before the first line has
68   been read, returns ``None``.
69
70
118
119The class which implements the sequence behavior provided by the module is
120available for subclassing as well:
121
122
123.. class:: FileInput([files[, inplace[, backup[, mode[, openhook]]]]])
124
125   Class :class:`FileInput` is the implementation; its methods :meth:`filename`,
n126-   :meth:`fileno`, :meth:`lineno`, :meth:`fileline`, :meth:`isfirstline`,
n125+   :meth:`fileno`, :meth:`lineno`, :meth:`filelineno`, :meth:`isfirstline`,
127   :meth:`isstdin`, :meth:`nextfile` and :meth:`close` correspond to the functions
128   of the same name in the module. In addition it has a :meth:`readline` method
129   which returns the next input line, and a :meth:`__getitem__` method which
130   implements the sequence behavior.  The sequence must be accessed in strictly
131   sequential order; random access and :meth:`readline` cannot be mixed.
132
133   With *mode* you can specify which file mode will be passed to :func:`open`. It
134   must be one of ``'r'``, ``'rU'``, ``'U'`` and ``'rb'``.
136   The *openhook*, when given, must be a function that takes two arguments,
137   *filename* and *mode*, and returns an accordingly opened file-like object. You
138   cannot use *inplace* and *openhook* together.
139
140   .. versionchanged:: 2.5
141      Added the *mode* and *openhook* parameters.
142
143**Optional in-place filtering:** if the keyword argument ``inplace=1`` is passed
n144-to :func:`input` or to the :class:`FileInput` constructor, the file is moved to
n143+to :func:`fileinput.input` or to the :class:`FileInput` constructor, the file is
145-a backup file and standard output is directed to the input file (if a file of
144+moved to a backup file and standard output is directed to the input file (if a
146-the same name as the backup file already exists, it will be replaced silently).
145+file of the same name as the backup file already exists, it will be replaced
147-This makes it possible to write a filter that rewrites its input file in place.
146+silently).  This makes it possible to write a filter that rewrites its input
148-If the keyword argument ``backup='.<some extension>'`` is also given, it
147+file in place.  If the *backup* parameter is given (typically as
149-specifies the extension for the backup file, and the backup file remains around;
148+``backup='.<some extension>'``), it specifies the extension for the backup file,
150-by default, the extension is ``'.bak'`` and it is deleted when the output file
149+and the backup file remains around; by default, the extension is ``'.bak'`` and
151-is closed.  In-place filtering is disabled when standard input is read.
150+it is deleted when the output file is closed.  In-place filtering is disabled
151+when standard input is read.
152
n153+.. warning::
154+ 
153-**Caveat:** The current implementation does not work for MS-DOS 8+3 filesystems.
155+   The current implementation does not work for MS-DOS 8+3 filesystems.
156+ 
154
155The two following opening hooks are provided by this module:
t156- 
157
158.. function:: hook_compressed(filename, mode)
159
160   Transparently opens files compressed with gzip and bzip2 (recognized by the
161   extensions ``'.gz'`` and ``'.bz2'``) using the :mod:`gzip` and :mod:`bz2`
162   modules.  If the filename extension is not ``'.gz'`` or ``'.bz2'``, the file is
163   opened normally (ie, using :func:`open` without any decompression).
164
Legends
Colors
 Added 
Changed
Deleted
Links
(f)irst change
(n)ext change
(t)op