← Back to branch summary

~malept/ubuntu/lucid/python2.6/dev-dependency-fix

« back to all changes in this revision

Viewing changes to Doc/library/fileinput.rst

  • Committer: Bazaar Package Importer
  • Author(s): Matthias Klose
  • Date: 2009-02-13 12:51:00 UTC
  • Revision ID: james.westby@ubuntu.com-20090213125100-uufgcb9yeqzujpqw
Tags: upstream-2.6.1
Import upstream version 2.6.1

Show diffs side-by-side

added added

removed removed

Lines of Context:
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
.. warning::
 
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