File objects are implemented using C's stdio
package and can be
created with the built-in function open()
described under
Built-in Functions below. 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
0
.
- 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 or no more data is immediately available on a pipe, tty or
similar device). 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.)
- readline ([size])
-
Read one entire line from the file. A trailing newline character is
kept in the string
(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
input.
- readlines ([sizehint])
-
Read until EOF using
readline()
and return a list containing
the lines thus read. If the optional bufferhint argument is
present, instead of reading up to EOF, whole lines totalling
approximately sizehint bytes 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 ftell()
.
- 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
operation).
- 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.)
Classes that are trying to simulate a file object should also have a
writable softspace
attribute, which should be initialized to
zero. (softspace
is used by the print
statement.) This
will be automatic for classes implemented in Python; types implemented
in C will have to provide a writable softspace
attribute.
guido@CNRI.Reston.Va.US