NestedOutputArchive#

class lsst.images.serialization.NestedOutputArchive(root: str, parent: OutputArchive)#

Bases: OutputArchive, Generic

A proxy output archive that joins a root path into all names before delegating back to its parent archive.

This is intended to be used in the implementation of most serialize_direct and serialize_pointer implementations.

Parameters#

root: Root of all JSON Pointer paths. Should include a leading slash (as we always use absolute JSON Pointers) but no trailing slash.
parent: Parent output archive to delegate to.

Methods Summary

`add_array`(array, *[, name, update_header])	Add an array to the archive.
`add_structured_array`(array, *[, name, ...])	Add a table to the archive.
`add_table`(table, *[, name, update_header])	Add a table to the archive.
`iter_frame_sets`()	Iterate over the frame sets already serialized to this archive.
`serialize_direct`(name, serializer)	Use a serializer function to save a nested object.
`serialize_frame_set`(name, frame_set, ...)	Serialize a frame set and make it available to objects saved later.
`serialize_pointer`(name, serializer, key)	Use a serializer function to save a nested object that may be referenced in multiple locations in the same archive.

Methods Documentation

add_array(array: ~numpy.ndarray, *, name: str | None = None, update_header: ~collections.abc.Callable[[~astropy.io.fits.header.Header], None] = <function no_header_updates>) → ArrayReferenceModel#

Add an array to the archive.

Parameters#

array: Array to save.
name: Name of the array. This should generally be the name of the Pydantic model attribute to which the result will be assigned. It may be left None if there is only one [structured] array or table in a nested object that is being saved.
update_header: A callback that will be given the FITS header for the HDU containing this array in order to add keys to it. This callback may be provided but will not be called if the output format is not FITS.

Returns#

ArrayReferenceModel: A Pydantic model that references the stored array.

add_structured_array(array: ~numpy.ndarray, *, name: str | None = None, units: ~collections.abc.Mapping[str, ~astropy.units.core.Unit] | None = None, descriptions: ~collections.abc.Mapping[str, str] | None = None, update_header: ~collections.abc.Callable[[~astropy.io.fits.header.Header], None] = <function no_header_updates>) → TableReferenceModel#

Add a table to the archive.

Parameters#

name: Attribute of the paired Pydantic model that will be assigned the result of this call. If it will not be assigned to a direct attribute, it may be a JSON Pointer path (relative to the paired Pydantic model) to the location where it will be added.
array: A structured numpy array.
name: Name of the array. This should generally be the name of the Pydantic model attribute to which the result will be assigned. It may be left None if there is only one [structured] array or table in a nested object that is being saved.
units: A mapping of units for columns. Need not be complete.
descriptions: A mapping of descriptions for columns. Need not be complete.
update_header: A callback that will be given the FITS header for the HDU containing this table in order to add keys to it. This callback may be provided but will not be called if the output format is not FITS.

Returns#

TableReferenceModel: A Pydantic model that represents the table. Column definitions are included directly in the model while the actual data is stored elsewhere and referenced by the model.

add_table(table: ~astropy.table.table.Table, *, name: str | None = None, update_header: ~collections.abc.Callable[[~astropy.io.fits.header.Header], None] = <function no_header_updates>) → TableReferenceModel#

Add a table to the archive.

Parameters#

table: Table to save.
name: Name of the table. This should generally be the name of the Pydantic model attribute to which the result will be assigned. It may be left None if there is only one [structured] array or table in a nested object that is being saved.
update_header: A callback that will be given the FITS header for the HDU containing this table in order to add keys to it. This callback may be provided but will not be called if the output format is not FITS.

Returns#

TableReferenceModel: A Pydantic model that represents the table. Column definitions are included directly in the model while the actual data is stored elsewhere and referenced by the model.

iter_frame_sets() → Iterator[tuple[FrameSet, P]]#

Iterate over the frame sets already serialized to this archive.

Yields#

frame_set: A frame set that has already been written to this archive.
reference: An implementation-specific reference model that points to the frame set.

serialize_direct(name: str, serializer: Callable[[OutputArchive[P]], T]) → T#

Use a serializer function to save a nested object.

Parameters#

name: Attribute of the paired Pydantic model that will be assigned the result of this call. If it will not be assigned to a direct attribute, it may be a JSON Pointer path (relative to the paired Pydantic model) to the location where it will be added.
serializer: Callable that takes an OutputArchive and returns a Pydantic model. This will be passed a new OutputArchive that automatically prepends {name}/ (and any root path added by this archive) to names passed to it, so the serializer does not need to know where it appears in the overall tree.

Returns#

T: Result of the call to the serializer.

serialize_frame_set(name: str, frame_set: FrameSet, serializer: Callable[[OutputArchive], T], key: Hashable) → T | P#

Serialize a frame set and make it available to objects saved later.

Parameters#

name: Attribute of the paired Pydantic model that will be assigned the result of this call. If it will not be assigned to a direct attribute, it may be a JSON Pointer path (relative to the paired Pydantic model) to the location where it will be added.
frame_set: The frame set being saved. This will be returned in later calls to iter_frame_sets, along with the returned reference object.
serializer: Callable that takes an OutputArchive and returns a Pydantic model. This will be passed a new OutputArchive that automatically prepends {name}/ (and any root path added by this archive) to names passed to it, so the serializer does not need to know where it appears in the overall tree.
key: A unique identifier for the in-memory object the serializer saves, e.g. a call to the built-in id function.

Returns#

T | P: Either the result of the call to the serializer, or a Pydantic model that can be considered a reference to it and added to a larger model in its place.

serialize_pointer(name: str, serializer: Callable[[OutputArchive[P]], T], key: Hashable) → T | P#

Use a serializer function to save a nested object that may be referenced in multiple locations in the same archive.

Parameters#

name: Attribute of the paired Pydantic model that will be assigned the result of this call. If it will not be assigned to a direct attribute, it may be a JSON Pointer path (relative to the paired Pydantic model) to the location where it will be added.
serializer: Callable that takes an OutputArchive and returns a Pydantic model. This will be passed a new OutputArchive that automatically prepends {name}/ (and any root path added by this archive) to names passed to it, so the serializer does not need to know where it appears in the overall tree.
key: A unique identifier for the in-memory object the serializer saves, e.g. a call to the built-in id function.

Returns#

T | P: Either the result of the call to the serializer, or a Pydantic model that can be considered a reference to it and added to a larger model in its place.