OutputArchive#

class lsst.images.serialization.OutputArchive#

Bases: ABC, Generic

Abstract interface for writing to a file format.

Notes#

An output archive instance is assumed to be paired with a Pydantic model that represents a JSON tree, with the archive used to serialize data that is not natively JSON into 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 don’t want to assume it can be built via default-initialization and assignment, and because we’d prefer to avoid making the output archive generic over the model type. It is expected that most concrete archive implementations will accept the paired model in some sort of finalization method in order to write it into the file, but this is not part of the base class interface.

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

abstract 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.

abstract 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.

abstract 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.

abstract 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.

abstract serialize_direct(name: str, serializer: Callable[[OutputArchive], 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.

abstract 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.

abstract serialize_pointer(name: str, serializer: Callable[[OutputArchive], 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.