← Back to branch summary

~ubuntu-branches/ubuntu/maverick/python3.1/maverick

« back to all changes in this revision

Viewing changes to Doc/library/fileinput.rst

  • Committer: Bazaar Package Importer
  • Author(s): Matthias Klose
  • Date: 2009-03-23 00:01:27 UTC
  • Revision ID: james.westby@ubuntu.com-20090323000127-5fstfxju4ufrhthq
Tags: upstream-3.1~a1+20090322
Import upstream version 3.1~a1+20090322

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
 
 
58
The following functions use the global state created by :func:`fileinput.input`;
 
59
if there is no active state, :exc:`RuntimeError` is raised.
 
60
 
 
61
 
 
62
.. function:: filename()
 
63
 
 
64
   Return the name of the file currently being read.  Before the first line has
 
65
   been read, returns ``None``.
 
66
 
 
67
 
 
68
.. function:: fileno()
 
69
 
 
70
   Return the integer "file descriptor" for the current file. When no file is
 
71
   opened (before the first line and between files), returns ``-1``.
 
72
 
 
73
 
 
74
.. function:: lineno()
 
75
 
 
76
   Return the cumulative line number of the line that has just been read.  Before
 
77
   the first line has been read, returns ``0``.  After the last line of the last
 
78
   file has been read, returns the line number of that line.
 
79
 
 
80
 
 
81
.. function:: filelineno()
 
82
 
 
83
   Return the line number in the current file.  Before the first line has been
 
84
   read, returns ``0``.  After the last line of the last file has been read,
 
85
   returns the line number of that line within the file.
 
86
 
 
87
 
 
88
.. function:: isfirstline()
 
89
 
 
90
   Returns true if the line just read is the first line of its file, otherwise
 
91
   returns false.
 
92
 
 
93
 
 
94
.. function:: isstdin()
 
95
 
 
96
   Returns true if the last line was read from ``sys.stdin``, otherwise returns
 
97
   false.
 
98
 
 
99
 
 
100
.. function:: nextfile()
 
101
 
 
102
   Close the current file so that the next iteration will read the first line from
 
103
   the next file (if any); lines not read from the file will not count towards the
 
104
   cumulative line count.  The filename is not changed until after the first line
 
105
   of the next file has been read.  Before the first line has been read, this
 
106
   function has no effect; it cannot be used to skip the first file.  After the
 
107
   last line of the last file has been read, this function has no effect.
 
108
 
 
109
 
 
110
.. function:: close()
 
111
 
 
112
   Close the sequence.
 
113
 
 
114
The class which implements the sequence behavior provided by the module is
 
115
available for subclassing as well:
 
116
 
 
117
 
 
118
.. class:: FileInput([files[, inplace[, backup[, mode[, openhook]]]]])
 
119
 
 
120
   Class :class:`FileInput` is the implementation; its methods :meth:`filename`,
 
121
   :meth:`fileno`, :meth:`lineno`, :meth:`filelineno`, :meth:`isfirstline`,
 
122
   :meth:`isstdin`, :meth:`nextfile` and :meth:`close` correspond to the functions
 
123
   of the same name in the module. In addition it has a :meth:`readline` method
 
124
   which returns the next input line, and a :meth:`__getitem__` method which
 
125
   implements the sequence behavior.  The sequence must be accessed in strictly
 
126
   sequential order; random access and :meth:`readline` cannot be mixed.
 
127
 
 
128
   With *mode* you can specify which file mode will be passed to :func:`open`. It
 
129
   must be one of ``'r'``, ``'rU'``, ``'U'`` and ``'rb'``.
 
130
 
 
131
   The *openhook*, when given, must be a function that takes two arguments,
 
132
   *filename* and *mode*, and returns an accordingly opened file-like object. You
 
133
   cannot use *inplace* and *openhook* together.
 
134
 
 
135
 
 
136
**Optional in-place filtering:** if the keyword argument ``inplace=1`` is passed
 
137
to :func:`fileinput.input` or to the :class:`FileInput` constructor, the file is
 
138
moved to a backup file and standard output is directed to the input file (if a
 
139
file of the same name as the backup file already exists, it will be replaced
 
140
silently).  This makes it possible to write a filter that rewrites its input
 
141
file in place.  If the *backup* parameter is given (typically as
 
142
``backup='.<some extension>'``), it specifies the extension for the backup file,
 
143
and the backup file remains around; by default, the extension is ``'.bak'`` and
 
144
it is deleted when the output file is closed.  In-place filtering is disabled
 
145
when standard input is read.
 
146
 
 
147
.. warning::
 
148
 
 
149
   The current implementation does not work for MS-DOS 8+3 filesystems.
 
150
 
 
151
 
 
152
The two following opening hooks are provided by this module:
 
153
 
 
154
.. function:: hook_compressed(filename, mode)
 
155
 
 
156
   Transparently opens files compressed with gzip and bzip2 (recognized by the
 
157
   extensions ``'.gz'`` and ``'.bz2'``) using the :mod:`gzip` and :mod:`bz2`
 
158
   modules.  If the filename extension is not ``'.gz'`` or ``'.bz2'``, the file is
 
159
   opened normally (ie, using :func:`open` without any decompression).
 
160
 
 
161
   Usage example:  ``fi = fileinput.FileInput(openhook=fileinput.hook_compressed)``
 
162
 
 
163
 
 
164
.. function:: hook_encoded(encoding)
 
165
 
 
166
   Returns a hook which opens each file with :func:`codecs.open`, using the given
 
167
   *encoding* to read the file.
 
168
 
 
169
   Usage example: ``fi =
 
170
   fileinput.FileInput(openhook=fileinput.hook_encoded("iso-8859-1"))``