126.96.36.199 File Objects
File objects are implemented using C's stdiopackage and can be created with the built-in function
open() described section
2.3, ``Built-in Functions.'' They are also returned
by some other built-in functions and methods, e.g.,
posix.popen() and posix.fdopen() and the
makefile() method of socket objects.
When a file operation fails for an I/O-related reason, the exception
IOError is raised. This includes situations where the
operation is not defined for some reason, like seek() on a tty
device or writing a file opened for reading.
Files have the following methods:
- close ()
Close the file. A closed file cannot be read or written anymore.
- flush ()
Flush the internal buffer, like stdio's fflush().
- isatty ()
Return 1 if the file is connected to a tty(-like) device, else
- fileno ()
Return the integer ``file descriptor'' that is used by the underlying
implementation to request I/O operations from the operating system.
This can be useful for other, lower level interfaces that use file
descriptors, e.g. module fcntl or os.read() and friends.
- read ([size])
Read at most size bytes from the file (less if the read hits
EOF before obtaining size bytes). If the size
argument is negative or omitted, read all data until EOF is
reached. The bytes are returned as a string object. An empty
string is returned when EOF is encountered immediately. (For
certain files, like ttys, it makes sense to continue reading after
an EOF is hit.) Note that this method may call the underlying
C function fread() more than once in an effort to
acquire as close to size bytes as possible.
- readline ([size])
Read one entire line from the file. A trailing newline character is
kept in the string2.6 (but may be absent when a file ends with an
incomplete line). If the size argument is present and
non-negative, it is a maximum byte count (including the trailing
newline) and an incomplete line may be returned.
An empty string is returned when EOF is hit
immediately. Note: unlike stdio's fgets(), the returned
string contains null characters ('\0') if they occurred in the
- readlines ([sizehint])
Read until EOF using readline() and return a list containing
the lines thus read. If the optional sizehint argument is
present, instead of reading up to EOF, whole lines totalling
approximately sizehint bytes (possibly after rounding up to an
internal buffer size) are read.
- seek (offset[, whence])
Set the file's current position, like stdio's fseek().
The whence argument is optional and defaults to 0 (absolute file positioning); other values are 1 (seek
relative to the current position) and 2 (seek relative to the
file's end). There is no return value.
- tell ()
Return the file's current position, like stdio's
- truncate ([size])
Truncate the file's size. If the optional size argument present, the
file is truncated to (at most) that size. The size defaults to the
current position. Availability of this function depends on the
operating system version (e.g., not all Unix versions support this
- write (str)
Write a string to the file. There is no return value. Note: due to
buffering, the string may not actually show up in the file until
the flush() or close() method is called.
- writelines (list)
Write a list of strings to the file. There is no return value.
(The name is intended to match readlines();
writelines() does not add line separators.)
File objects also offer the following attributes:
Boolean indicating the current state of the file object. This is a
read-only attribute; the close() method changes the value.
The I/O mode for the file. If the file was created using the
open() built-in function, this will be the value of the
mode parameter. This is a read-only attribute.
If the file object was created using open(), the name of
the file. Otherwise, some string that indicates the source of the
file object, of the form "<...>". This is a read-only
Boolean that indicates whether a space character needs to be printed
before another value when using the print statement.
Classes that are trying to simulate a file object should also have a
writable softspace attribute, which should be initialized to
zero. This will be automatic for classes implemented in Python; types
implemented in C will have to provide a writable softspace
- ... string2.6
The advantage of leaving the newline on is that an empty string
can be returned to mean EOF without being ambiguous. Another
advantage is that (in cases where it might matter, e.g. if you
want to make an exact copy of a file while scanning its lines)
you can tell whether the last line of a file ended in a newline
or not (yes this happens!).
Send comments on this document to email@example.com.