fitsmgmt.header.hdrval

fitsmgmt.header.hdrval(
    value=None,
    header=None,
    key=None,
    default=None,
    unit=None,
    verbose=False,
    to_value=False,
    return_source=False,
)

Get a value by priority: value > header[key] > default.

Parameters

value : object, optional. = None

If not None, header, key, and default will not be used. This is different from header.get(key, default). It is therefore useful if the API wants to override the header value by the user-provided one. Default: None.

header : ~astropy.io.fits.Header, optional. = None

The header to extract the value if value is None. Default: None.

key : str, optional. = None

The header keyword to extract if value is None. Default: None.

default : object, optional. = None

The default value. If value is None and header[key] is not available, this value is used. Default: None.

unit : str or ~astropy.units.Unit, optional. = None

None to ignore unit. '' (empty string) is interpreted as ~astropy.units.dimensionless_unscaled. Better to leave it as None unless an astropy unit is truly needed. Default: None.

verbose : bool, optional. = False

Whether to log the source and missing-key fallback. Default: False.

to_value : bool, optional. = False

Whether to return only the scalar value when the result is an ~astropy.units.Quantity. Default: False.

return_source : bool, optional. = False

Whether to return (value, source). source is one of "the user", "{KEY} in header", or "default". Default: False.

Notes

It takes << 10 us (when unit=None) or for any case for a reasonably lengthy header. See Tests below. Tested on MBP 15” [2018, macOS 11.6, i7-8850H (2.6 GHz; 6-core), RAM 16 GB (2400MHz DDR4), Radeon Pro 560X (4GB)].

Tests

real_q = 20*u.s
real_v = 20
default_q = 0*u.s
default_v = 0
test_q = 3*u.s
test_v = 3

# w/o unit  Times are the %timeit result of the LHS
assert hdrval(None,   hdr, "EXPTIME", default=0) == real_v  # ~ 6.5 us
assert hdrval(None,   hdr, "EXPTIxx", default=0) == default_v # ~ 3.5 us
assert hdrval(test_v, hdr, "EXPTIxx", default=0) == test_v  # ~ 0.3 us
assert hdrval(test_q, hdr, "EXPTIxx", default=0) == test_v  # ~ 0.6 us
# w/ unit  Times are the %timeit result of the LHS
assert hdrval(None,   hdr, "EXPTIME", default=0, unit='s') == real_q  # ~ 23 us
assert hdrval(None,   hdr, "EXPTIxx", default=0, unit='s') == default_q # ~ 16 us
assert hdrval(test_v, hdr, "EXPTIxx", default=0, unit='s') == test_q  # ~ 11 us
assert hdrval(test_q, hdr, "EXPTIxx", default=0, unit='s') == test_q  # ~ 15 us

For a test astropy.nddata.CCDData, the following timing gave ~ 0.5 ms on MBP 15" [2018,
macOS 11.6, i7-8850H (2.6 GHz; 6-core), RAM 16 GB (2400MHz DDR4), Radeon
Pro 560X (4GB)]
%timeit ((air.hdrval(None, ccd.header, "EXPTIME", unit=u.s)
         / air.hdrval(3*u.s, ccd.header, "EXPTIME", unit=u.s)).si.value)

Same tests on MBP 14" [2024, macOS 26.4.1,
M4Pro(8P+4E/G20c/N16c/48G)], 2026-05-27:

# w/o unit
assert hdrval(None,   hdr, "EXPTIME", default=0) == real_v  # ~ 1.65 us
assert hdrval(None,   hdr, "EXPTIxx", default=0) == default_v # ~ 0.798 us
assert hdrval(test_v, hdr, "EXPTIxx", default=0) == test_v  # ~ 0.073 us
assert hdrval(test_q, hdr, "EXPTIxx", default=0) == test_v  # ~ 0.207 us
# w/ unit
assert hdrval(None,   hdr, "EXPTIME", default=0, unit='s') == real_q  # ~ 4.23 us
assert hdrval(None,   hdr, "EXPTIxx", default=0, unit='s') == default_q # ~ 3.23 us
assert hdrval(test_v, hdr, "EXPTIxx", default=0, unit='s') == test_q  # ~ 2.37 us
assert hdrval(test_q, hdr, "EXPTIxx", default=0, unit='s') == test_q  # ~ 2.31 us

%timeit ((air.hdrval(None, hdr, "EXPTIME", unit=u.s)
         / air.hdrval(3*u.s, hdr, "EXPTIME", unit=u.s)).si.value)
# 16.5 µs ± 201 ns per loop (7 runs, 5000 loops each)