File objects are implemented using C's stdio
package and can be created with the built-in constructor
file() described in section
2.1, ``Built-in Functions.''3.6 File objects are also returned
by some other built-in functions and methods, such as
os.popen() and os.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 any more.
Any operation which requires that the file be open will raise a
ValueError after the file has been closed. Calling
close() more than once is allowed.
As of Python 2.5, you can avoid having to call this method explicitly
if you use the with statement. For example, the following
code will automatically close f when the with block
is exited:
from __future__ import with_statement
with open("hello.txt") as f:
for line in f:
print line
In older versions of Python, you would have needed to do this to get
the same effect:
f = open("hello.txt")
try:
for line in f:
print line
finally:
f.close()
Note:
Not all ``file-like'' types in Python support use as a context
manager for the with statement. If your code is intended to
work with any file-like object, you can use the closing()
function in the contextlib module instead of using the object
directly. See section 26.5 for details.
flush(
)
Flush the internal buffer, like stdio's
fflush(). This may be a no-op on some file-like
objects.
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, such as the
fcntl module or
os.read() and friends. Note:
File-like objects
which do not have a real file descriptor should not provide
this method!
isatty(
)
Return True if the file is connected to a tty(-like) device, else
False. Note:
If a file-like object is not associated
with a real file, this method should not be implemented.
next(
)
A file object is its own iterator, for example iter(f) returns
f (unless f is closed). When a file is used as an
iterator, typically in a for loop (for example,
for line in f: print line), the next() method is
called repeatedly. This method returns the next input line, or raises
StopIteration when EOF is hit. In order to make a
for loop the most efficient way of looping over the lines of
a file (a very common operation), the next() method uses a
hidden read-ahead buffer. As a consequence of using a read-ahead
buffer, combining next() with other file methods (like
readline()) does not work right. However, using
seek() to reposition the file to an absolute position will
flush the read-ahead buffer.
New in version 2.3.
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. Also note that
when in non-blocking mode, less data than what was requested may
be returned, even if no size parameter was given.
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).3.7 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 only when EOF is encountered
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 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. Objects implementing a file-like
interface may choose to ignore sizehint if it cannot be
implemented, or cannot be implemented efficiently.
xreadlines(
)
This method returns the same thing as iter(f).
New in version 2.1.
Deprecated since release 2.3.
Use "for line in file" instead.
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. Note that if the file is
opened for appending (mode 'a' or 'a+'), any
seek() operations will be undone at the next write. If the
file is only opened for writing in append mode (mode 'a'),
this method is essentially a no-op, but it remains useful for files
opened in append mode with reading enabled (mode 'a+'). If the
file is opened in text mode (without 'b'), only offsets returned
by tell() are legal. Use of other offsets causes undefined
behavior.
Note that not all file objects are seekable.
tell(
)
Return the file's current position, like stdio's
ftell().
Note:
On Windows, tell() can return illegal values (after an
fgets()) when reading files with Unix-style line-endings.
Use binary mode ('rb') to circumvent this problem.
truncate(
[size])
Truncate the file's size. If the optional size argument is
present, the file is truncated to (at most) that size. The size
defaults to the current position. The current file position is
not changed. Note that if a specified size exceeds the file's
current size, the result is platform-dependent: possibilities
include that the file may remain unchanged, increase to the specified
size as if zero-filled, or increase to the specified size with
undefined new content.
Availability: Windows, many Unix variants.
write(
str)
Write a string to the file. There is no return value. Due to
buffering, the string may not actually show up in the file until
the flush() or close() method is called.
writelines(
sequence)
Write a sequence of strings to the file. The sequence can be any
iterable object producing strings, typically a list of strings.
There is no return value.
(The name is intended to match readlines();
writelines() does not add line separators.)
Files support the iterator protocol. Each iteration returns the same
result as file.readline(), and iteration ends when the
readline() method returns an empty string.
File objects also offer a number of other interesting attributes.
These are not required for file-like objects, but should be
implemented if they make sense for the particular object.
closed
bool indicating the current state of the file object. This is a
read-only attribute; the close() method changes the value.
It may not be available on all file-like objects.
encoding
The encoding that this file uses. When Unicode strings are written
to a file, they will be converted to byte strings using this encoding.
In addition, when the file is connected to a terminal, the attribute
gives the encoding that the terminal is likely to use (that
information might be incorrect if the user has misconfigured the
terminal). The attribute is read-only and may not be present on
all file-like objects. It may also be None, in which case
the file uses the system default encoding for converting Unicode
strings.
New in version 2.3.
mode
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 and may not be
present on all file-like objects.
name
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
attribute and may not be present on all file-like objects.
newlines
If Python was built with the --with-universal-newlines
option to configure (the default) this read-only attribute
exists, and for files opened in
universal newline read mode it keeps track of the types of newlines
encountered while reading the file. The values it can take are
'\r', '\n', '\r\n', None (unknown,
no newlines read yet) or a tuple containing all the newline
types seen, to indicate that multiple
newline conventions were encountered. For files not opened in universal
newline read mode the value of this attribute will be None.
softspace
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 most classes implemented in Python
(care may be needed for objects that override attribute access); types
implemented in C will have to provide a writable
softspace attribute.
Note:
This attribute is not used to control the
print statement, but to allow the implementation of
print to keep track of its internal state.
The advantage of leaving the newline on is that
returning an empty string is then an unambiguous EOF
indication. It is also possible (in cases where it might
matter, for example, if you
want to make an exact copy of a file while scanning its lines)
to tell whether the last line of a file ended in a newline
or not (yes this happens!).
