GNU Info

(python2.1-tut.info)Methods of File Objects

---

Next: pickle Module Prev: Reading and Writing Files Up: Reading and Writing Files

---

Enter node , (file) or (file)node

Methods of File Objects
-----------------------

The rest of the examples in this section will assume that a file object
called `f' has already been created.

To read a file's contents, call `f.read(SIZE)', which reads some
quantity of data and returns it as a string.  SIZE is an optional
numeric argument.  When SIZE is omitted or negative, the entire
contents of the file will be read and returned; it's your problem if
the file is twice as large as your machine's memory.  Otherwise, at
most SIZE bytes are read and returned.  If the end of the file has been
reached, `f.read()' will return an empty string (`""').
     >>> f.read()
     'This is the entire file.\n'
     >>> f.read()
     ''

`f.readline()' reads a single line from the file; a newline character
(`\n') is left at the end of the string, and is only omitted on the
last line of the file if the file doesn't end in a newline.  This makes
the return value unambiguous; if `f.readline()' returns an empty
string, the end of the file has been reached, while a blank line is
represented by `'\n'', a string containing only a single newline.

     >>> f.readline()
     'This is the first line of the file.\n'
     >>> f.readline()
     'Second line of the file\n'
     >>> f.readline()
     ''

`f.readlines()' returns a list containing all the lines of data in the
file.  If given an optional parameter SIZEHINT, it reads that many
bytes from the file and enough more to complete a line, and returns the
lines from that.  This is often used to allow efficient reading of a
large file by lines, but without having to load the entire file in
memory.  Only complete lines will be returned.

     >>> f.readlines()
     ['This is the first line of the file.\n', 'Second line of the file\n']

`f.write(STRING)' writes the contents of STRING to the file, returning
`None'.

     >>> f.write('This is a test\n')

`f.tell()' returns an integer giving the file object's current position
in the file, measured in bytes from the beginning of the file.  To
change the file object's position, use `f.seek(OFFSET, FROM_WHAT)'.
The position is computed from adding OFFSET to a reference point; the
reference point is selected by the FROM_WHAT argument.  A FROM_WHAT
value of 0 measures from the beginning of the file, 1 uses the current
file position, and 2 uses the end of the file as the reference point.
FROM_WHAT can be omitted and defaults to 0, using the beginning of the
file as the reference point.

     >>> f=open('/tmp/workfile', 'r+')
     >>> f.write('0123456789abcdef')
     >>> f.seek(5)     # Go to the 5th byte in the file
     >>> f.read(1)
     '5'
     >>> f.seek(-3, 2) # Go to the 3rd byte before the end
     >>> f.read(1)
     'd'

When you're done with a file, call `f.close()' to close it and free up
any system resources taken up by the open file.  After calling
`f.close()', attempts to use the file object will automatically fail.

     >>> f.close()
     >>> f.read()
     Traceback (most recent call last):
       File "<stdin>", line 1, in ?
     ValueError: I/O operation on closed file

File objects have some additional methods, such as `isatty()' and
`truncate()' which are less frequently used; consult the Library
Reference for a complete guide to file objects.