InputArchive#

class lsst.images.serialization.InputArchive#

Bases: ABC, Generic

Abstract interface for reading from a file format.

Notes

An input archive instance is assumed to be paired with a Pydantic model that represents a JSON tree, with the archive used to deserialize data that is not native JSON from data that is (which may just be a reference to binary data stored elsewhere in the file). The archive doesn’t actually hold that model instance because we’d prefer to avoid making the input archive generic over the model type. It is expected that most concrete archive implementations will provide a method to load the paired model from a file, but this is not part of the base class interface.

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)	Return basic identifying information for the archive at `path` without deserializing pixel data.
`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.
`open_tree`(path, *[, partial])	Open `path`, load and validate its top-level tree, and yield `(archive, tree, info)` as a context manager.

Methods Documentation

abstract deserialize_pointer(pointer, model_type, deserializer)#

Deserialize an object that was saved by serialize_pointer.

Parameters:

pointer (TypeVar(P, bound= BaseModel)) – 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[TypeVar(P, bound= BaseModel)]], 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.

abstract 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)#

Return basic identifying information for the archive at path without deserializing pixel data.

Each concrete backend reads only the headers/metadata it needs.

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

abstract get_frame_set(ref)#

Return an already-deserialized frame set from the archive.

Parameters:: ref (TypeVar(P, bound= BaseModel)) – 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

abstract 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

abstract 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

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

Open path, load and validate its top-level tree, and yield (archive, tree, info) as a context manager.

Parameters:

path (Union[str, ParseResult, ResourcePath, Path, IO[bytes]]) – File to be opened (local or remote), or a seekable binary stream containing the file’s content.
partial (bool, default: True) – Whether the file should be opened for incremental reads or not. Can be ignored by a backend where not relevant.
**backend_kwargs (Any) – Any keyword parameters that should be forwarded to the backend open.

Raises:

ArchiveReadError – If the file’s schema is not registered.

Return type:

AbstractContextManager[tuple[InputArchive[TypeVar(P, bound= BaseModel)], ArchiveTree, ArchiveInfo]]

Notes

Each concrete backend implements this.