[AstroPy] Draft specification for PyFITS functional interface

laidler at stsci.edu laidler at stsci.edu
Wed Mar 30 11:31:34 CST 2005

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

  getheader returns a PyFITS header object.

  getval returns a variable of the correct type containing the

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

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
   - 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
       - If the first extension has no data, either, it will
raise an

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

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:

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

Thus the following examples will also work:

....except for getval and update:
Since there is no obvious order of parameters for getval and
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.

More information about the AstroPy mailing list