FitsInputArchive#

class lsst.images.fits.FitsInputArchive(stream)#

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.

Parameters:: stream (IO[bytes]) – Open binary stream the archive reads from.

Attributes Summary

info

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

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`(cls, path, *[, page_size, partial])	Create an output archive that writes to the given file.
`open_tree`(cls, 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, model_type, deserializer)#

Deserialize an object that was saved by serialize_pointer.

Parameters:

pointer (PointerModel) – JSON Pointer model to dereference.
model_type (type[TypeVar(U, bound= ArchiveTree)]) – Pydantic model type that the pointer should dereference to.
deserializer (Callable[[TypeVar(U, bound= ArchiveTree), InputArchive[PointerModel]], TypeVar(V)]) – Callable that takes an instance of model_type and an input archive, and returns the deserialized object.

Returns:

The deserialized object.

Return type:

V

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, *, slices=Ellipsis, strip_header=<function no_header_updates>)#

Load an array from the archive.

Parameters:

model (ArrayReferenceModel | InlineArrayModel) – A Pydantic model that references or holds the array.
slices (tuple[slice, ...] | EllipsisType, default: Ellipsis) – Slices that specify a subset of the original array to read.
strip_header (Callable[[Header], None], default: <function no_header_updates at 0x7f27576196c0>) – A callable that strips out any FITS header cards added by the update_header argument in the corresponding call to add_array.

Return type:

ndarray

classmethod get_basic_info(path)#

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.

Parameters:: path (str | ParseResult | ResourcePath | Path) – Path to the archive to read.
Return type:: ArchiveInfo

get_frame_set(ref)#

Return an already-deserialized frame set from the archive.

Parameters:: ref (PointerModel) – Implementation-specific reference to the frame set.
Returns:: Loaded frame set.
Return type:: FrameSet

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.

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

get_structured_array(model, strip_header=<function no_header_updates>)#

Load a table from the archive as a structured array.

Parameters:

model (TableModel) – A Pydantic model that references or holds the table.
strip_header (Callable[[Header], None], default: <function no_header_updates at 0x7f27576196c0>) – A callable that strips out any FITS header cards added by the update_header argument in the corresponding call to add_structured_array.

Returns:

The loaded table as a structured array.

Return type:

numpy.ndarray

get_table(model, strip_header=<function no_header_updates>)#

Load a table from the archive.

Parameters:

model (TableModel) – A Pydantic model that references or holds the table.
strip_header (Callable[[Header], None], default: <function no_header_updates at 0x7f27576196c0>) – A callable that strips out any FITS header cards added by the update_header argument in the corresponding call to add_table.

Returns:

The loaded table.

Return type:

astropy.table.Table

get_tree(model_type)#

Read the JSON tree from the archive.

Parameters:: model_type (type[TypeVar(T, bound= ArchiveTree)]) – A Pydantic model type to use to validate the JSON.
Returns:: The validated Pydantic model.
Return type:: T

classmethod open(cls, path, *, page_size=2304000, partial=False)#

Create an output archive that writes to the given file.

Parameters:

path (Union[str, ParseResult, ResourcePath, Path, IO[bytes]]) – File to read; convertible to lsst.resources.ResourcePath, or a seekable binary stream containing the file’s content. For stream input page_size and partial are ignored: the data is already in memory and needs no paging.
page_size (int, default: 2304000) – 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 (bool, default: False) – 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:

A context manager that returns a FitsInputArchive when entered.

Return type:

contextlib.AbstractContextManager [FitsInputArchive]

classmethod open_tree(cls, path, *, partial=True, **backend_kwargs)#

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

Parameters:

path (Union[str, ParseResult, ResourcePath, Path, IO[bytes]]) – The file resource to open, or a seekable binary stream containing the file’s content.
partial (bool, default: True) – If True the file is opened without reading it all into memory.
**backend_kwargs (Any) – 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).

Return type:

Iterator[tuple[Self, ArchiveTree, ArchiveInfo]]