Merged revisions 76893 via svnmerge from

svn+ssh://pythondev@svn.python.org/python/branches/py3k

........
  r76893 | antoine.pitrou | 2009-12-19 19:22:15 +0100 (sam., 19 déc. 2009) | 4 lines

  Issue #7508: remove obsolete documentation about built-in file objects.
........
This commit is contained in:
Antoine Pitrou 2009-12-19 18:23:15 +00:00
parent 2297b0911a
commit b1a1810ece
1 changed files with 2 additions and 285 deletions

View File

@ -12,7 +12,7 @@ interpreter.
.. index:: pair: built-in; types
The principal built-in types are numerics, sequences, mappings, files, classes,
The principal built-in types are numerics, sequences, mappings, classes,
instances and exceptions.
Some operations are supported by several object types; in particular,
@ -165,7 +165,7 @@ This table summarizes the comparison operations:
pair: objects; comparing
Objects of different types, except different numeric types, never compare equal.
Furthermore, some types (for example, file objects) support only a degenerate
Furthermore, some types (for example, function objects) support only a degenerate
notion of comparison where any two objects of that type are unequal. The ``<``,
``<=``, ``>`` and ``>=`` operators will raise a :exc:`TypeError` exception when
any operand is a complex number, the objects are of different types that cannot
@ -2066,283 +2066,6 @@ An example of dictionary view usage::
{'bacon'}
.. _bltin-file-objects:
File Objects
============
.. index::
object: file
builtin: file
module: os
module: socket
.. XXX this is quite out of date, must be updated with "io" module
File objects are implemented using C's ``stdio`` package and can be
created with the built-in :func:`open` function. File
objects are also returned by some other built-in functions and methods,
such as :func:`os.popen` and :func:`os.fdopen` and the :meth:`makefile`
method of socket objects. Temporary files can be created using the
:mod:`tempfile` module, and high-level file operations such as copying,
moving, and deleting files and directories can be achieved with the
:mod:`shutil` module.
When a file operation fails for an I/O-related reason, the exception
:exc:`IOError` is raised. This includes situations where the operation is not
defined for some reason, like :meth:`seek` on a tty device or writing a file
opened for reading.
Files have the following methods:
.. method:: file.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 :exc:`ValueError` after the
file has been closed. Calling :meth:`close` more than once is allowed.
You can avoid having to call this method explicitly if you use
the :keyword:`with` statement. For example, the following code will
automatically close *f* when the :keyword:`with` block is exited::
from __future__ import with_statement # This isn't required in Python 2.6
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
:keyword:`with` statement. If your code is intended to work with any file-like
object, you can use the function :func:`contextlib.closing` instead of using
the object directly.
.. method:: file.flush()
Flush the internal buffer, like ``stdio``'s :cfunc:`fflush`. This may be a
no-op on some file-like objects.
.. note::
:meth:`flush` does not necessarily write the file's data to disk. Use
:meth:`flush` followed by :func:`os.fsync` to ensure this behavior.
.. method:: file.fileno()
.. index::
pair: file; descriptor
module: fcntl
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
:mod:`fcntl` module or :func:`os.read` and friends.
.. note::
File-like objects which do not have a real file descriptor should *not* provide
this method!
.. method:: file.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.
.. method:: file.__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
:keyword:`for` loop (for example, ``for line in f: print(line)``), the
:meth:`__next__` method is called repeatedly. This method returns the next
input line, or raises :exc:`StopIteration` when EOF is hit when the file is open
for reading (behavior is undefined when the file is open for writing). In order
to make a :keyword:`for` loop the most efficient way of looping over the lines
of a file (a very common operation), the :meth:`__next__` method uses a hidden
read-ahead buffer. As a consequence of using a read-ahead buffer, combining
:meth:`__next__` with other file methods (like :meth:`readline`) does not work
right. However, using :meth:`seek` to reposition the file to an absolute
position will flush the read-ahead buffer.
.. method:: file.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 :cfunc:`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 was requested may be
returned, even if no *size* parameter was given.
.. method:: file.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 *only* when EOF is encountered immediately.
.. note::
Unlike ``stdio``'s :cfunc:`fgets`, the returned string contains null characters
(``'\0'``) if they occurred in the input.
.. method:: file.readlines([sizehint])
Read until EOF using :meth:`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.
.. method:: file.seek(offset[, whence])
Set the file's current position, like ``stdio``'s :cfunc:`fseek`. The *whence*
argument is optional and defaults to ``os.SEEK_SET`` or ``0`` (absolute file
positioning); other values are ``os.SEEK_CUR`` or ``1`` (seek relative to the
current position) and ``os.SEEK_END`` or ``2`` (seek relative to the file's
end). There is no return value.
For example, ``f.seek(2, os.SEEK_CUR)`` advances the position by two and
``f.seek(-3, os.SEEK_END)`` sets the position to the third to last.
Note that if the file is opened for appending
(mode ``'a'`` or ``'a+'``), any :meth:`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 :meth:`tell` are
legal. Use of other offsets causes undefined behavior.
Note that not all file objects are seekable.
.. method:: file.tell()
Return the file's current position, like ``stdio``'s :cfunc:`ftell`.
.. note::
On Windows, :meth:`tell` can return illegal values (after an :cfunc:`fgets`)
when reading files with Unix-style line-endings. Use binary mode (``'rb'``) to
circumvent this problem.
.. method:: file.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.
.. method:: file.write(str)
Write a string to the file. Due to buffering, the string may not actually
show up in the file until the :meth:`flush` or :meth:`close` method is
called.
The meaning of the return value is not defined for every file-like object.
Some (mostly low-level) file-like objects may return the number of bytes
actually written, others return ``None``.
.. method:: file.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 :meth:`readlines`; :meth:`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 :meth:`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.
.. attribute:: file.closed
bool indicating the current state of the file object. This is a read-only
attribute; the :meth:`close` method changes the value. It may not be available
on all file-like objects.
.. XXX does this still apply?
.. attribute:: file.encoding
The encoding that this file uses. When 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 strings.
.. attribute:: file.errors
The Unicode error handler used along with the encoding.
.. attribute:: file.mode
The I/O mode for the file. If the file was created using the :func:`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.
.. attribute:: file.name
If the file object was created using :func:`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.
.. attribute:: file.newlines
If Python was built with the :option:`--with-universal-newlines` option to
:program:`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``.
.. _typememoryview:
memoryview Types
@ -2777,9 +2500,3 @@ The following attributes are only supported by :term:`new-style class`\ es.
.. [#] To format only a tuple you should therefore provide a singleton tuple whose only
element is the tuple to be formatted.
.. [#] 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!).