HDU Lists¶
HDUList
¶
-
class
astropy.io.fits.
HDUList
(hdus=[], file=None)[source] [edit on github]¶ Bases:
list
,astropy.io.fits.verify._Verify
HDU list class. This is the top-level FITS object. When a FITS file is opened, a
HDUList
object is returned.Construct a
HDUList
object.Parameters: - hdus : sequence of HDU objects or single HDU, optional
The HDU object(s) to comprise the
HDUList
. Should be instances of HDU classes likeImageHDU
orBinTableHDU
.- file : file object, bytes, optional
The opened physical file associated with the
HDUList
or a bytes object containing the contents of the FITS file.
-
append
(hdu)[source] [edit on github]¶ Append a new HDU to the
HDUList
.Parameters: - hdu : HDU object
HDU to add to the
HDUList
.
-
close
(output_verify='exception', verbose=False, closed=True)[source] [edit on github]¶ Close the associated FITS file and memmap object, if any.
Parameters: - output_verify : str
Output verification option. Must be one of
"fix"
,"silentfix"
,"ignore"
,"warn"
, or"exception"
. May also be any combination of"fix"
or"silentfix"
with"+ignore"
,+warn
, or+exception" (e.g. ``"fix+warn"
). See Verification options for more info.- verbose : bool
When
True
, print out verbose messages.- closed : bool
When
True
, close the underlying file object.
-
copy
() [edit on github]¶ Return a shallow copy of an HDUList.
Returns:
-
fileinfo
(index)[source] [edit on github]¶ Returns a dictionary detailing information about the locations of the indexed HDU within any associated file. The values are only valid after a read or write of the associated file with no intervening changes to the
HDUList
.Parameters: - index : int
Index of HDU for which info is to be returned.
Returns: - fileinfo : dict or None
The dictionary details information about the locations of the indexed HDU within an associated file. Returns
None
when the HDU is not associated with a file.Dictionary contents:
Key Value file File object associated with the HDU filename Name of associated file object filemode Mode in which the file was opened (readonly, update, append, denywrite, ostream) resized Flag that when True
indicates that the data has been resized since the last read/write so the returned values may not be valid.hdrLoc Starting byte location of header in file datLoc Starting byte location of data block in file datSpan Data size including padding
-
filename
()[source] [edit on github]¶ Return the file name associated with the HDUList object if one exists. Otherwise returns None.
Returns: - filename : a string containing the file name associated with the
HDUList object if an association exists. Otherwise returns None.
-
flush
(output_verify='fix', verbose=False)[source] [edit on github]¶ Force a write of the
HDUList
back to the file (for append and update modes only).Parameters: - output_verify : str
Output verification option. Must be one of
"fix"
,"silentfix"
,"ignore"
,"warn"
, or"exception"
. May also be any combination of"fix"
or"silentfix"
with"+ignore"
,+warn
, or+exception" (e.g. ``"fix+warn"
). See Verification options for more info.- verbose : bool
When
True
, print verbose messages
-
classmethod
fromfile
(fileobj, mode=None, memmap=None, save_backup=False, cache=True, lazy_load_hdus=True, **kwargs)[source] [edit on github]¶ Creates an
HDUList
instance from a file-like object.The actual implementation of
fitsopen()
, and generally shouldn’t be used directly. Useopen()
instead (and see its documentation for details of the parameters accepted by this method).
-
classmethod
fromstring
(data, **kwargs)[source] [edit on github]¶ Creates an
HDUList
instance from a string or other in-memory data buffer containing an entire FITS file. Similar toHDUList.fromfile()
, but does not accept the mode or memmap arguments, as they are only relevant to reading from a file on disk.This is useful for interfacing with other libraries such as CFITSIO, and may also be useful for streaming applications.
Parameters: - data : str, buffer, memoryview, etc.
A string or other memory buffer containing an entire FITS file. It should be noted that if that memory is read-only (such as a Python string) the returned
HDUList
’s data portions will also be read-only.- kwargs : dict
Optional keyword arguments. See
astropy.io.fits.open()
for details.
Returns: - hdul : HDUList
An
HDUList
object representing the in-memory FITS file.
-
index_of
(key)[source] [edit on github]¶ Get the index of an HDU from the
HDUList
.Parameters: - key : int, str, tuple of (string, int) or an HDU object
The key identifying the HDU. If
key
is a tuple, it is of the form(name, ver)
wherever
is anEXTVER
value that must match the HDU being searched for.If the key is ambiguous (e.g. there are multiple ‘SCI’ extensions) the first match is returned. For a more precise match use the
(name, ver)
pair.If even the
(name, ver)
pair is ambiguous (it shouldn’t be but it’s not impossible) the numeric index must be used to index the duplicate HDU.When
key
is an HDU object, this function returns the index of that HDU object in theHDUList
.
Returns: - index : int
The index of the HDU in the
HDUList
.
Raises: - ValueError
If
key
is an HDU object and it is not found in theHDUList
.- KeyError
If an HDU specified by the
key
that is an extension number, extension name, or a tuple of extension name and version is not found in theHDUList
.
-
info
(output=None)[source] [edit on github]¶ Summarize the info of the HDUs in this
HDUList
.Note that this function prints its results to the console—it does not return a value.
Parameters: - output : file, bool, optional
A file-like object to write the output to. If
False
, does not output to a file and instead returns a list of tuples representing the HDU info. Writes tosys.stdout
by default.
-
insert
(index, hdu)[source] [edit on github]¶ Insert an HDU into the
HDUList
at the givenindex
.Parameters: - index : int
Index before which to insert the new HDU.
- hdu : HDU object
The HDU object to insert
-
pop
(index=-1)[source] [edit on github]¶ Remove an item from the list and return it.
Parameters: - index : int, str, tuple of (string, int), optional
An integer value of
index
indicates the position from whichpop()
removes and returns an HDU. A string value or a tuple of(string, int)
functions as a key for identifying the HDU to be removed and returned. Ifkey
is a tuple, it is of the form(key, ver)
wherever
is anEXTVER
value that must match the HDU being searched for.If the key is ambiguous (e.g. there are multiple ‘SCI’ extensions) the first match is returned. For a more precise match use the
(name, ver)
pair.If even the
(name, ver)
pair is ambiguous the numeric index must be used to index the duplicate HDU.
Returns: - hdu : HDU object
The HDU object at position indicated by
index
or having name and version specified byindex
.
-
readall
()[source] [edit on github]¶ Read data of all HDUs into memory.
-
update_extend
()[source] [edit on github]¶ Make sure that if the primary header needs the keyword
EXTEND
that it has it and it is correct.
-
writeto
(fileobj, output_verify='exception', overwrite=False, checksum=False)[source] [edit on github]¶ Write the
HDUList
to a new file.Parameters: - fileobj : file path, file object or file-like object
File to write to. If a file object, must be opened in a writeable mode.
- output_verify : str
Output verification option. Must be one of
"fix"
,"silentfix"
,"ignore"
,"warn"
, or"exception"
. May also be any combination of"fix"
or"silentfix"
with"+ignore"
,+warn
, or+exception" (e.g. ``"fix+warn"
). See Verification options for more info.- overwrite : bool, optional
If
True
, overwrite the output file if it exists. Raises anOSError
ifFalse
and the output file exists. Default isFalse
.Changed in version 1.3:
overwrite
replaces the deprecatedclobber
argument.- checksum : bool
When
True
adds bothDATASUM
andCHECKSUM
cards to the headers of all HDU’s written to the file.