1. The input_reader module

input_reader is a python module that provides tools to help read the contents of a block-type input file. If you have ever written a custom parser for an input file, you will know that there are many non-obvious challenges that must be overcome, mostly in the realm of error handling. The challenges include dealing with unknown or missing keys, incorrect input (str vs float), data storage, and parse ordering. Handling these issues can make a seemingly easy task become a complicated mess that obscures the intent of your program.

The input_reader module was designed with a balance of conciseness and clarity in mind, as well as a strong resemblance to the argparse module in the python standard library. With input_reader, you can define how to read your input files in a relatively small number of lines (~1-2 per keyword) that are (for the most part) easy to read.

This documentation is written in a combination API/tutorial style. You will be guided through creating a generic input_reader definition for a generic input file while being introduced to the functionality of the InputReader one piece at a time.

1.1. Installation

Installation of input_reader is ultra-easy. Simply execute from the command line:

easy_install input_reader

or, if you have pip (preferred over easy_install):

pip install input_reader

Both of the above commands will download the source for you.

You can also download the source from http://pypi.python.org/pypi/input_reader, or browse the git repository at https://github.com/SethMMorton/input_reader.

If you choose to install from source, you can unzip the source archive and enter the directory, and type:

python setup.py install

If you wish to run the unit tests, enter:

python setup.py test

If you want to build this documentation, enter:

python setup.py build_sphinx

1.2. Exported objects

input_reader exports the following objects by default (i.e. with from input_reader import *):

1. The class InputReader

   This is the workhorse of the input_reader module. It is used to define what is to be read in and also read the input file.

2. The exception ReaderError

   This exception is raised when an error occurs reading in the file.

3. The class SUPPRESS

   This is an empty class that is used to specify that a key not included in the input file should not be included in the Namespace.

4. The function abs_file_path()

   This function returns the absolute path of a file, substituting any environment variables or the ~ character correctly.

5. The function file_safety_check()

   Checks that a file is “safe”, i.e. it exists and can be opened.

6. The function range_check()

   Checks that a given range is valied, i.e. the low value is lower than the high value.

Optionally, the class Namespace may be imported by name. This class contains all the data read into the input file.