[AstroPy] Draft specification for PyFITS functional interface

[laidler at stsci.edu]

After some iterations among the STScI group, here is a draft
specification for these convenience functions. 



Proposed specifications for functional user interface for PyFITS
29 March 05

Functions to include:
--------------------
Reading: getdata, getheader, getval
  getdata returns a numarray (image extension) or recarray(table
  extension) object by default; if the keyword argument
'header' is
  specified with a value other than None, it returns a
(data,header)
  tuple. .

  getheader returns a PyFITS header object.

  getval returns a variable of the correct type containing the
data.

Writing: writeto, update, append
  Return nothing.

Informational: info
  Returns a (multiline) string.

Exception conditions:
--------------------

File does not exist:
~~~~~~~~~~~~~~~~~~~
Read, info, and update functions will raise an exception of the 
specified file
does not exist.

Ambiguity in specifying the extension:
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
All ambiguous specifications will raise an exception, eg
  getdata('myfile.fits',ext=(sci,1),extname='err',extver=2)

Attempting to read data that is not found:
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

All the read functions will raise an exception if the
requested data
is not found in the file, that is:
  - if there is no such file
  - if there is no such extension
  - if the specified extension contains no data (for getdata)
  - if the header of the specified extension does not contain the
  specified keyword (for getval)

There is one special case which will be handled without raising an
exception:
   - If getdata is called without specifying an extension, it will
   return data from the primary extension.
     - If the primary has no data, it will return data from
the first
     extension.
       - If the first extension has no data, either, it will
raise an
       exception.

Overwriting an existing file:
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
writeto will raise an exception if the specified filename already
exists.


Specifying the extension:
------------------------

Pure PyFITS will not support specifying the extension as part
of the
filename string. This functionality will, however, be
supported in a
layered module.

If no extension is specified, the primary HDU will be used.

Several keyword arguments will be provided.
All keyword arguments will be lower case.

Using the ext keyword:
~~~~~~~~~~~~~~~~~~~~~~
getdata('myfile.fits', ext=1)         - extension number
getdata('myfile.fits', ext='sci')     - extension name
getdata('myfile.fits', ext=('sci',2)) - extension name and version

Using the extname keyword:
~~~~~~~~~~~~~~~~~~~~~~~~~~
getdata('myfiles.fits',extname='sci') - selects first encountered
                                        'sci' extension

Using the extver keyword:
~~~~~~~~~~~~~~~~~~~~~~~~~
getdata('myfile.fits',extname='sci',extver=2)



Keyword syntax will *not* be enforced....:
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Although keyword syntax will be recommended, it will not be
enforced.
The order of the positional arguments will be filename, ext,
[extver].

Thus the following examples will also work:
  getdata('myfile.fits',3)
  getdata('myfile.fits','sci')
  getdata('myfile.fits','sci',2)
  getdata('myfile.fits',('sci',2))

....except for getval and update:
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Since there is no obvious order of parameters for getval and
update,
keyword syntax *will* be enforced for these functions.


Keyword inheritance:
-------------------
Pure PyFITS will not handle inheritance of keywords. This
functionality may, however, be supported by a separate function,
merge_headers, provided in a layered module.