==============================
:mod:`fort` -- The fort module
==============================

.. toctree::
   :maxdepth: 1

   m-fort_c-fort.File.rst


.. module:: fort

Suport for Python/Fortran interworking.

This module provides support for writing Python modules and programs that need
to interwork with Fortran in various ways.

The main thing this module provides is the :class:`~fort.File` class, which supports access
to unformatted files; a binary file format.

The other main feature is the :func:`~fort.unpackRecord` function, which can be useful
during the initial stages of converting a Fortran program to reasonably simliar
looking Python code.

Classes
-------

  .. describe:: File
  
  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.
  
  See :class:`fort.File` for details
  
Functions
---------

  .. function:: open (name, mode)
  
     Open a binary Fortran file.
     
     
     **Return Value**
     
       A :class:`~fort.File` instance for the newly opened file.
       
     
     **Arguments**
     
       *name*
         The path of the file to be opened.
         
       *mode*
         The file's access mode, as per the builtin open function. The default
         is 'rb' and **must** always include 'b'.
         

  .. function:: unpackRecord (line, start, format)
  
     A simple function to unpack Fortran formatted records.
     
     The intention is to make translation of Fortran such as the following
     relatively striaghtforward:
     ::
     
        read(line(2:64), '(i4,i5,a12,i4,a36)') lat, lon, sid, ht, name
        read(line, '(i4,3i4,i4)') a, arr, b
     
     In Python the above then becomes:
     ::
     
        lat, lon, sid, ht, name = unpackRecord(line, 2, 'i4,i5,a12,i4,a36')
        a, arr, b = unpackRecord(line, 1, 'i4,3i4,i4')
     
     The result is obviously not idiomatic Python, but it is much easier to compare
     the Python to the original Fortran code.
     
     This function only supports a small subset of the Fortran format strings.
     Basically you can use:
     
     aN, iN
      A string or integer in a field width of ``N``. For example 'i5, s20'.
     
     MiN
      An array of ``M`` intgers, each in an ``N`` character field.
      The returned value is a list of integers.
     
     Note: This is throw-away code, which does very little error checking.
     
     
     **Return Value**
     
       A tuple of values, where each entry corresponds to a value decoded
       using the rules defined in the *format* argument. Where the format
       argument indicates an array of values, the tuple entry is itself a
       tuple.
       
     
     **Arguments**
     
       *line*
         The line of text to be 'unpacked'.
         
       *start*
         The start character in *line* to read from. Fortran indexing is used;
         i.e. the first character is as position 1.
         
       *format*
         The format string. This follows the Fortran conventions, but without the
         parentheses.
         

Exceptions
----------

  .. class:: Error (...)
  
     Base class for exceptions.
     
  .. class:: FileFormatError (...)
  
     Raised when an error in the format of a binary file is detected.
     
     For example, each record in a Fortram unformatted file should start and end
     with the same record length value. A record where the leading and trailing
     lengths do not match is a situation that will cause this error to be
     raised.
     
  .. class:: FileTruncatedError (...)
  
     Raised when there are unsufficent bytes in the file.
     
     This can occur if, for example, a record header indicates that the next record
     (plus trailer) requires more bytes than remain to be read from the file.