astro py:docs

- Index
- Modules

### Navigation

- next »
- « previous |
- Astropy v5.2.1 »
- FITS File Handling (`astropy.io.fits`) »
- HDU Lists

# 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:
    hdus HDU or python:sequence thereof, optional

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

    file python: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:
      hdu HDU

        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_verify `python: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()

    Return a shallow copy of an HDUList.

    Returns:
      copy `HDUList`

        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:
      index `python:int`

        Index of HDU for which info is to be returned.

    Returns:
      fileinfo `python: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:
      filename `python: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_verify `python: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, 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:
      data `python: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.

      **kwargs `python: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)

    Get the index of an HDU from the `HDUList`.

    Parameters:
      key `python: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:
      index `python: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:
      output python: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:
      index `python:int`

        Index before which to insert the new HDU.

      hdu HDU

        The HDU object to insert

  pop(index=-1)

    Remove an item from the list and return it.

    Parameters:
      index `python: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:
      hdu HDU

        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:
      fileobj `python:str`, python:file-like object or `pathlib.Path`

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

      output_verify `python: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 an `OSError` if `False` and the output file exists. Default is `False`.

      checksum bool

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