mirror of https://github.com/python/cpython
Issue #7508: remove obsolete documentation about built-in file objects.
This commit is contained in:
Antoine Pitrou
parent
62423cba95
commit
e231e39c28
|
|
@ -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
|
||||
|
|
@ -2070,283 +2070,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
|
||||
|
|
@ -2781,9 +2504,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!).
|
||||
|
|
|
|||
Loading…
Reference in New Issue