HDU Lists

HDUList

class astropy.io.fits.HDUList(hdus=[], file=None)

Bases: list, _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:

hdusHDU or python:sequence thereof, optional

The HDU object(s) to comprise the HDUList. Should be instances of HDU classes like ImageHDU or BinTableHDU.

filepython:file-like object, bytes, optional

The opened physical file associated with the HDUList or a bytes object containing the contents of the FITS file.

append(hdu)

Append a new HDU to the HDUList.

Parameters:

hduHDU

HDU to add to the HDUList.

close(output_verify='exception', verbose=False, closed=True)

Close the associated FITS file and memmap object, if any.

Parameters:

output_verifypython: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.

verbosebool

When True, print out verbose messages.

closedbool

When True, close the underlying file object.

copy()

Return a shallow copy of an HDUList.

Returns:

copyHDUList

A shallow copy of this HDUList object.

fileinfo(index)

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:

indexpython:int

Index of HDU for which info is to be returned.

Returns:

fileinfopython:dict or python: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()

Return the file name associated with the HDUList object if one exists. Otherwise returns None.

Returns:

filenamepython:str

A string containing the file name associated with the HDUList object if an association exists. Otherwise returns None.

flush(output_verify='fix', verbose=False)

Force a write of the HDUList back to the file (for append and update modes only).

Parameters:

output_verifypython: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.

verbosebool

When True, print verbose messages

classmethod fromfile(fileobj, mode=None, memmap=None, save_backup=False, cache=True, lazy_load_hdus=True, ignore_missing_simple=False, **kwargs)

Creates an HDUList instance from a file-like object.

The actual implementation of fitsopen(), and generally shouldn’t be used directly. Use open() instead (and see its documentation for details of the parameters accepted by this method).

classmethod fromstring(data, **kwargs)

Creates an HDUList instance from a string or other in-memory data buffer containing an entire FITS file. Similar to HDUList.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:

datapython:str, :term:buffer-like, etc.

A string or other memory buffer containing an entire FITS file. Buffer-like objects include bytes, bytearray, memoryview, and ndarray. 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.

**kwargspython:dict

Optional keyword arguments. See astropy.io.fits.open() for details.

Returns:

hdulHDUList

An HDUList object representing the in-memory FITS file.

index_of(key)

Get the index of an HDU from the HDUList.

Parameters:

keypython:int, python:str, python:tuple of (python:str, python:int) or HDU

The key identifying the HDU. If key is a tuple, it is of the form (name, ver) where ver is an EXTVER 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 the HDUList.

Returns:

indexpython:int

The index of the HDU in the HDUList.

Raises:

ValueError

If key is an HDU object and it is not found in the HDUList.

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 the HDUList.

info(output=None)

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:

outputpython:file-like object or 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 to sys.stdout by default.

insert(index, hdu)

Insert an HDU into the HDUList at the given index.

Parameters:

indexpython:int

Index before which to insert the new HDU.

hduHDU

The HDU object to insert

pop(index=-1)

Remove an item from the list and return it.

Parameters:

indexpython:int, python:str, python:tuple of (python:str, python:int), optional

An integer value of index indicates the position from which pop() 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. If key is a tuple, it is of the form (key, ver) where ver is an EXTVER 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:

hduHDU

The HDU object at position indicated by index or having name and version specified by index.

readall()

Read data of all HDUs into memory.

update_extend()

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)

Write the HDUList to a new file.

Parameters:

fileobjpython:str, python:file-like object or pathlib.Path

File to write to. If a file object, must be opened in a writeable mode.

output_verifypython: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.

overwritebool, optional

If True, overwrite the output file if it exists. Raises an OSError if False and the output file exists. Default is False.

checksumbool

When True adds both DATASUM and CHECKSUM cards to the headers of all HDU’s written to the file.