Merged revisions 76893 via svnmerge from

pitrou · pitrou · commit b1a1810ece6a · 2009-12-19T18:23:15.000Z
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. ........
diff --git a/Doc/library/stdtypes.rst b/Doc/library/stdtypes.rst
@@ -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!).
