FitsInputArchive#

class lsst.images.fits.FitsInputArchive(stream: IO[bytes])#

Bases: InputArchive[PointerModel]

An implementation of the serialization.InputArchive interface that reads from FITS files.

Instances of this class should only be constructed via the open context manager.

Attributes Summary

info

Schema/format info read from the primary header on open.

Methods Summary

`deserialize_pointer`(pointer, model_type, ...)	Deserialize an object that was saved by `serialize_pointer`.
`get_array`(model, *[, slices, strip_header])	Load an array from the archive.
`get_basic_info`(path)	Read `DATAMODL` (schema URL) and `FMTVER` (container version) from the primary header.
`get_frame_set`(ref)	Return an already-deserialized frame set from the archive.
`get_opaque_metadata`()	Return opaque metadata loaded from the file that should be saved if another version of the object is saved to the same file format.
`get_structured_array`(model[, strip_header])	Load a table from the archive as a structured array.
`get_table`(model[, strip_header])	Load a table from the archive.
`get_tree`(model_type)	Read the JSON tree from the archive.
`open`(path, *[, page_size, partial])	Create an output archive that writes to the given file.
`open_tree`(path, *[, partial])	Open the FITS file and yield `(archive, tree, info)`.

Attributes Documentation

info#: Schema/format info read from the primary header on open. (serialization.ArchiveInfo)

Methods Documentation

deserialize_pointer(pointer: PointerModel, model_type: type[U], deserializer: Callable[[U, InputArchive[PointerModel]], V]) → V#

Deserialize an object that was saved by serialize_pointer.

Parameters#

pointer: JSON Pointer model to dereference.
model_type: Pydantic model type that the pointer should dereference to.
deserializer: Callable that takes an instance of model_type and an input archive, and returns the deserialized object.

Returns#

V: The deserialized object.

Notes#

Implementations are required to remember previously-deserialized objects and return them when the same pointer is passed in multiple times.

There is no deserialize_direct (to pair with serialize_direct) because the caller can just call a deserializer function directly on a sub-model of its Pydantic tree.

get_array(model: ~lsst.images.serialization._asdf_utils.ArrayReferenceModel | ~lsst.images.serialization._asdf_utils.InlineArrayModel, *, slices: tuple[slice, ...] | ellipsis = Ellipsis, strip_header: ~collections.abc.Callable[[~astropy.io.fits.header.Header], None] = <function no_header_updates>) → ndarray#

Load an array from the archive.

Parameters#

model: A Pydantic model that references or holds the array.
slices: Slices that specify a subset of the original array to read.
strip_header: A callable that strips out any FITS header cards added by the update_header argument in the corresponding call to add_array.

classmethod get_basic_info(path: str | ParseResult | ResourcePath | Path) → ArchiveInfo#

Read DATAMODL (schema URL) and FMTVER (container version) from the primary header.

Every FITS file written by this package records the schema URL in the DATAMODL card, so the schema can be identified without reading the (potentially large) JSON tree HDU.

get_frame_set(ref: PointerModel) → FrameSet#

Return an already-deserialized frame set from the archive.

Parameters#

ref: Implementation-specific reference to the frame set.

Returns#

FrameSet: Loaded frame set.

get_opaque_metadata() → FitsOpaqueMetadata#

Return opaque metadata loaded from the file that should be saved if another version of the object is saved to the same file format.

Returns#

OpaqueArchiveMetadata: Opaque metadata specific to this archive type that should be round-tripped if it is saved in the same format.

get_structured_array(model: ~lsst.images.serialization._tables.TableModel, strip_header: ~collections.abc.Callable[[~astropy.io.fits.header.Header], None] = <function no_header_updates>) → ndarray#

Load a table from the archive as a structured array.

Parameters#

model: A Pydantic model that references or holds the table.
strip_header: A callable that strips out any FITS header cards added by the update_header argument in the corresponding call to add_structured_array.

Returns#

numpy.ndarray: The loaded table as a structured array.

get_table(model: ~lsst.images.serialization._tables.TableModel, strip_header: ~collections.abc.Callable[[~astropy.io.fits.header.Header], None] = <function no_header_updates>) → Table#

Load a table from the archive.

Parameters#

model: A Pydantic model that references or holds the table.
strip_header: A callable that strips out any FITS header cards added by the update_header argument in the corresponding call to add_table.

Returns#

astropy.table.Table: The loaded table.

get_tree(model_type: type[T]) → T#

Read the JSON tree from the archive.

Parameters#

model_type: A Pydantic model type to use to validate the JSON.

Returns#

T: The validated Pydantic model.

classmethod open(path: str | ParseResult | ResourcePath | Path, *, page_size: int = 2304000, partial: bool = False) → Iterator[Self]#

Create an output archive that writes to the given file.

Parameters#

path: File to read; convertible to lsst.resources.ResourcePath.
page_size: Size of the fsspec read block for partial (remote) reads, in bytes; a multiple of the FITS block size (2880) is recommended. Defaults to DEFAULT_PAGE_SIZE; see it for the tuning tradeoff.
partial: Whether we will be reading only some of the archive, or if memory pressure forces us to read it only a little at a time. If False (default), the entire raw file may be read into memory up front.

Returns#

contextlib.AbstractContextManager [FitsInputArchive]: A context manager that returns a FitsInputArchive when entered.

classmethod open_tree(path: str | ParseResult | ResourcePath | Path, *, partial: bool = True, **backend_kwargs: Any) → Iterator[tuple[Self, ArchiveTree, ArchiveInfo]]#

Open the FITS file and yield (archive, tree, info).

Parameters#

path: The file resource to open.
partial: If True the file is opened without reading it all into memory.
**backend_kwargs: Optional parameters for this backend. Currently supports page_size which can be used to override the default page size (which can be overridden globally by modifying DEFAULT_PAGE_SIZE).