#
3.9 File Objects

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 `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. 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.

#### Footnotes

... Functions.''3.6
  `file()` is new in Python 2.2. The older built-in `open()` is an alias for `file()`.
... line).3.7
  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!).