.. currentmodule:: fort

===============
Class fort.File
===============

.. class:: File (fd)

   A Fortran binary (unformatted) file object.
   
   A binary Fortran file can be opened using the open method of this module; a
   File object is returned that supports a writeline method (for writing
   records), a readline method (for reading records) and the iterator protocol
   (for reading).
   
   It is normally easier to use the :func:`~fort.open` factory function rather than construct
   instances directly.
   
   
   **Arguments**
   
     fd
       The underlying file object, which is typically a ``file`` object
       opened in binary mode.
       
Methods
-------

.. currentclass:: fort.File

.. method:: readi ()

   Read a single signed integer from the file and return it.
   
   If at end-of-file then None is returned.  Insufficient data (for
   example, only 3 bytes remaining but 4 required) will raise some sort of
   exception.
   
   
   **Return Value**
   
     Normally the integer value retrieved from the file. If end-of-file
     was encountered then``None`` is returned.
     
   
   **Exceptions Raised**
   
     :exc:`~FileTruncatedError`
       If the file did not contain a complete integer's worth of bytes.
       

.. method:: close ()

   Close the underlying file.
   

.. method:: readline ()

   Read a single binary record as a string.
   
   
   **Return Value**
   
     Normally a string containing the bytes of the record.
     If end-of-file was encountered then``None`` is returned.
     
   
   **Exceptions Raised**
   
     :exc:`~FileFormatError`
       If the record has mismatching record length prefix and suffix
       markers.
       
     :exc:`~FileTruncatedError`
       If the file did not apparently contain a complete record.
       

.. method:: writeline (record)

   Write a single record to the Fortran binary file.
   
   
   **Arguments**
   
     *record*
       A string containing the bytes for the record.
       

.. method:: next ()

   Provides itertator protocol support.
   
   This is not normally invoked directly. It is more common to use the idiom
   
   .. code-block:: py
      :linenos:
   
      for record in myFile:
          ...
   

Attributes
----------

.. currentclass:: fort.File

.. attribute:: fd()

   Underlying file descriptor.  Usually returned by builtin open, but
   any object with a suitable read-like interface should do.
   

.. attribute:: w()

   The number of bytes in the natural word size used in the file.
   

.. attribute:: bos()

   Byte Order and Size.  Specifies the byte order and sizes used in the
   underlying file.  This is used in a Python struct format so we use
   the same convention.  See
   http://docs.python.org/lib/module-struct.html
   '<' little-endian, '>' big-endian.