def info(filename, output=None, **kwargs):
"""
Print the summary information on a FITS file.
This includes the name, type, length of header, data shape and type
for each extension.
Parameters
----------
filename : file path, file object, or file like object
FITS file to obtain info from. If opened, mode must be one of
the following: rb, rb+, or ab+.
output : file (optional)
File-like object to output the HDU info to. Outputs to stdout by
default.
kwargs
Any additional keyword arguments to be passed to `pyfits.open`.
*Note:* This function sets ``ignore_missing_end=True`` by default.
"""
mode, closed = _get_file_mode(filename, default='copyonwrite')
# Set the default value for the ignore_missing_end parameter
if not 'ignore_missing_end' in kwargs:
kwargs['ignore_missing_end'] = True
f = fitsopen(filename, mode=mode, **kwargs)
ret = f.info(output=output)
if closed:
f.close()
return ret
def tabledump(filename, datafile=None, cdfile=None, hfile=None, ext=1,
clobber=False):
"""
Dump a table HDU to a file in ASCII format. The table may be
dumped in three separate files, one containing column definitions,
one containing header parameters, and one for table data.
Parameters
----------
filename : file path, file object or file-like object
Input fits file.
datafile : file path, file object or file-like object (optional)
Output data file. The default is the root name of the input
fits file appended with an underscore, followed by the
extension number (ext), followed by the extension ``.txt``.
cdfile : file path, file object or file-like object (optional)
Output column definitions file. The default is `None`,
no column definitions output is produced.
hfile : file path, file object or file-like object (optional)
Output header parameters file. The default is `None`,
no header parameters output is produced.
ext : int
The number of the extension containing the table HDU to be
dumped.
clobber : bool
Overwrite the output files if they exist.
Notes
-----
The primary use for the `tabledump` function is to allow editing in a
standard text editor of the table data and parameters. The
`tcreate` function can be used to reassemble the table from the
three ASCII files.
"""
# allow file object to already be opened in any of the valid modes
# and leave the file in the same state (opened or closed) as when
# the function was called
mode, closed = _get_file_mode(filename, default='copyonwrite')
f = fitsopen(filename, mode=mode)
# Create the default data file name if one was not provided
if not datafile:
root, tail = os.path.splitext(f._HDUList__file.name)
datafile = root + '_' + repr(ext) + '.txt'
# Dump the data from the HDU to the files
f[ext].dump(datafile, cdfile, hfile, clobber)
if closed:
f.close()
def __init__(self, a, b, ignore_keywords=[], ignore_comments=[],
ignore_fields=[], numdiffs=10, tolerance=0.0,
ignore_blanks=True, ignore_blank_cards=True):
"""
Parameters
----------
a : str or `HDUList`
The filename of a FITS file on disk, or an `HDUList` object.
b : str or `HDUList`
The filename of a FITS file on disk, or an `HDUList` object to
compare to the first file.
ignore_keywords : sequence (optional)
Header keywords to ignore when comparing two headers; the presence
of these keywords and their values are ignored. Wildcard strings
may also be included in the list.
ignore_comments : sequence (optional)
A list of header keywords whose comments should be ignored in the
comparison. May contain wildcard strings as with ignore_keywords.
ignore_fields : sequence (optional)
The (case-insensitive) names of any table columns to ignore if any
table data is to be compared.
numdiffs : int (optional)
The number of pixel/table values to output when reporting HDU data
differences. Though the count of differences is the same either
way, this allows controlling the number of different values that
are kept in memory or output. If a negative value is given, then
numdifs is treated as unlimited (default: 10).
tolerance : float (optional)
The relative difference to allow when comparing two float values
either in header values, image arrays, or table columns
(default: 0.0).
ignore_blanks : bool (optional)
Ignore extra whitespace at the end of string values either in
headers or data. Extra leading whitespace is not ignored
(default: True).
"""
if isinstance(a, basestring):
try:
a = fitsopen(a)
except Exception, e:
raise IOError("error opening file a (%s): %s: %s" %
(a, e.__class.__name__, e.args[0]))
close_a = True
def _getext(filename, mode, *args, **kwargs):
"""
Open the input file, return the `HDUList` and the extension.
This supports several different styles of extension selection. See the
:func:`getdata()` documentation for the different possibilities.
"""
ext = kwargs.pop('ext', None)
extname = kwargs.pop('extname', None)
extver = kwargs.pop('extver', None)
err_msg = ('Redundant/conflicting extension arguments(s): %s' %
({'args': args, 'ext': ext, 'extname': extname,
'extver': extver},))
# This code would be much simpler if just one way of specifying an
# extension were picked. But now we need to support all possible ways for
# the time being.
if len(args) == 1:
# Must be either an extension number, an extension name, or an
# (extname, extver) tuple
if _is_int(args[0]) or (isinstance(ext, tuple) and len(ext) == 2):
if ext is not None or extname is not None or extver is not None:
raise TypeError(err_msg)
ext = args[0]
elif isinstance(args[0], basestring):
# The first arg is an extension name; it could still be valid
# to provide an extver kwarg
if ext is not None or extname is not None:
raise TypeError(err_msg)
extname = args[0]
else:
# Take whatever we have as the ext argument; we'll validate it
# below
ext = args[0]
elif len(args) == 2:
# Must be an extname and extver
if ext is not None or extname is not None or extver is not None:
raise TypeError(err_msg)
extname = args[0]
extver = args[1]
elif len(args) > 2:
raise TypeError('Too many positional arguments.')
if (ext is not None and
not (_is_int(ext) or
(isinstance(ext, tuple) and len(ext) == 2 and
isinstance(ext[0], basestring) and _is_int(ext[1])))):
raise ValueError(
'The ext keyword must be either an extension number '
'(zero-indexed) or a (extname, extver) tuple.')
if extname is not None and not isinstance(extname, basestring):
raise ValueError('The extname argument must be a string.')
if extver is not None and not _is_int(extver):
raise ValueError('The extver argument must be an integer.')
if ext is None and extname is None and extver is None:
ext = 0
elif ext is not None and (extname is not None or extver is not None):
raise TypeError(err_msg)
elif extname:
if extver:
ext = (extname, extver)
else:
ext = (extname, 1)
elif extver and extname is None:
raise TypeError('extver alone cannot specify an extension.')
hdulist = fitsopen(filename, mode=mode, **kwargs)
return hdulist, ext
def append(filename, data, header=None, checksum=False, verify=True, **kwargs):
"""
Append the header/data to FITS file if filename exists, create if not.
If only `data` is supplied, a minimal header is created.
Parameters
----------
filename : file path, file object, or file like object
File to write to. If opened, must be opened for update (rb+)
unless it is a new file, then it must be opened for append
(ab+). A file or `GzipFile` object opened for update will be
closed after return.
data : array, table, or group data object
the new data used for appending
header : `Header` object (optional)
The header associated with `data`. If `None`, an appropriate
header will be created for the data object supplied.
checksum : bool (optional)
When `True` adds both ``DATASUM`` and ``CHECKSUM`` cards to
the header of the HDU when written to the file.
verify: bool (optional)
When `True`, the existing FITS file will be read in to verify
it for correctness before appending. When `False`, content is
simply appended to the end of the file. Setting *verify* to
`False` can be much faster.
kwargs
Any additional keyword arguments to be passed to `pyfits.open`.
"""
name, closed, noexist_or_empty = _stat_filename_or_fileobj(filename)
if noexist_or_empty:
#
# The input file or file like object either doesn't exits or is
# empty. Use the writeto convenience function to write the
# output to the empty object.
#
writeto(filename, data, header, checksum=checksum, **kwargs)
else:
hdu = _makehdu(data, header)
if isinstance(hdu, PrimaryHDU):
hdu = ImageHDU(data, header)
if verify or not closed:
f = fitsopen(filename, mode='append')
f.append(hdu)
# Set a flag in the HDU so that only this HDU gets a checksum when
# writing the file.
hdu._output_checksum = checksum
f.close(closed=closed)
else:
f = _File(filename, mode='append')
hdu._output_checksum = checksum
hdu._writeto(f)
f.close()
(default: True).
"""
if isinstance(a, basestring):
try:
a = fitsopen(a)
except Exception, e:
raise IOError("error opening file a (%s): %s: %s" %
(a, e.__class.__name__, e.args[0]))
close_a = True
else:
close_a = False
if isinstance(b, basestring):
try:
b = fitsopen(b)
except Exception, e:
raise IOError("error opening file b (%s): %s: %s" %
(b, e.__class.__name__, e.args[0]))
close_b = True
else:
close_b = False
# Normalize keywords/fields to ignore to upper case
self.ignore_keywords = set(k.upper() for k in ignore_keywords)
self.ignore_comments = set(k.upper() for k in ignore_comments)
self.ignore_fields = set(k.upper() for k in ignore_fields)
self.numdiffs = numdiffs
self.tolerance = tolerance
self.ignore_blanks = ignore_blanks
def __init__(self, a, b, ignore_keywords=[], ignore_comments=[],
ignore_fields=[], numdiffs=10, tolerance=0.0,
ignore_blanks=True, ignore_blank_cards=True):
"""
Parameters
----------
a : str or `HDUList`
The filename of a FITS file on disk, or an `HDUList` object.
b : str or `HDUList`
The filename of a FITS file on disk, or an `HDUList` object to
compare to the first file.
ignore_keywords : sequence (optional)
Header keywords to ignore when comparing two headers; the presence
of these keywords and their values are ignored. Wildcard strings
may also be included in the list.
ignore_comments : sequence (optional)
A list of header keywords whose comments should be ignored in the
comparison. May contain wildcard strings as with ignore_keywords.
ignore_fields : sequence (optional)
The (case-insensitive) names of any table columns to ignore if any
table data is to be compared.
numdiffs : int (optional)
The number of pixel/table values to output when reporting HDU data
differences. Though the count of differences is the same either
way, this allows controlling the number of different values that
are kept in memory or output. If a negative value is given, then
numdifs is treated as unlimited (default: 10).
tolerance : float (optional)
The relative difference to allow when comparing two float values
either in header values, image arrays, or table columns
(default: 0.0).
ignore_blanks : bool (optional)
Ignore extra whitespace at the end of string values either in
headers or data. Extra leading whitespace is not ignored
(default: True).
"""
if isinstance(a, basestring):
a = fitsopen(a)
close_a = True
else:
close_a = False
if isinstance(b, basestring):
b = fitsopen(b)
close_b = True
else:
close_b = False
# Normalize keywords/fields to ignore to upper case
self.ignore_keywords = set(k.upper() for k in ignore_keywords)
self.ignore_comments = set(k.upper() for k in ignore_comments)
self.ignore_fields = set(k.upper() for k in ignore_fields)
self.numdiffs = numdiffs
self.tolerance = tolerance
self.ignore_blanks = ignore_blanks
self.ignore_blank_cards = ignore_blank_cards
self.diff_hdu_count = ()
self.diff_hdus = []
try:
super(FITSDiff, self).__init__(a, b)
finally:
if close_a:
a.close()
if close_b:
b.close()
