From e231e39c2851e93254344626e05e81f1b543f88a Mon Sep 17 00:00:00 2001 From: Antoine Pitrou Date: Sat, 19 Dec 2009 18:22:15 +0000 Subject: [PATCH] Issue #7508: remove obsolete documentation about built-in file objects. --- Doc/library/stdtypes.rst | 287 +-------------------------------------- 1 file changed, 2 insertions(+), 285 deletions(-) diff --git a/Doc/library/stdtypes.rst b/Doc/library/stdtypes.rst index 2f5d93d60dc..89c7b672514 100644 --- 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 @@ -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!).