JsonOutputArchive#

class lsst.images.json.JsonOutputArchive#

Bases: OutputArchive[JsonRef]

An implementation of the serialization.OutputArchive interface that writes to JSON files.

This archive type is designed for pure-JSON objects and cases where any images or tables are tiny. It will be extremely inefficient for large images or tables, if it works at all.

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.
`finish`(tree)	Finish serialization.
`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.
`serialize_root`(obj[, metadata, butler_info])	Serialize `obj` to a root tree, apply write-time overrides, and warn if the tree uses a development schema.

Methods Documentation

add_array(array, *, name=None, update_header=<function no_header_updates>, tile_shape=None, options_name=None)#

Add an array to the archive.

Parameters:

array (ndarray) – Array to save.
name (str | None, default: None) – 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 (Callable[[Header], None], default: <function no_header_updates at 0x7f27576196c0>) – 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.
tile_shape (tuple[int, ...] | None, default: None) – The recommended shape of each tile if the implementation will save the array in distinct tiles for faster subarray retrieval. This is a hint; implementations are not required to use this value.
options_name (str | None, default: None) – Use the options (e.g. for compression) associated with this name when saving this array.

Returns:

A Pydantic model that references or holds the stored array.

Return type:

ArrayReferenceModel | InlineArrayModel

add_structured_array(array, *, name=None, units=None, descriptions=None, update_header=<function no_header_updates>)#

Add a table to the archive.

Parameters:

array (ndarray) – A structured numpy array.
name (str | None, default: None) – 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 (Mapping[str, Unit] | None, default: None) – A mapping of units for columns. Need not be complete.
descriptions (Mapping[str, str] | None, default: None) – A mapping of descriptions for columns. Need not be complete.
update_header (Callable[[Header], None], default: <function no_header_updates at 0x7f27576196c0>) – 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:

A Pydantic model that represents the table.

Return type:

TableModel

add_table(table, *, name=None, update_header=<function no_header_updates>)#

Add a table to the archive.

Parameters:

table (Table) – Table to save.
name (str | None, default: None) – 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 (Callable[[Header], None], default: <function no_header_updates at 0x7f27576196c0>) – 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:

A Pydantic model that represents the table.

Return type:

TableModel

finish(tree)#

Finish serialization.

Parameters:: tree (TypeVar(T, bound= ArchiveTree)) – Serialized archive tree to write, which is modified in place (the indirect attribute is overwritten) and then returned.
Return type:: TypeVar(T, bound= ArchiveTree)

iter_frame_sets()#

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.

Return type:

Iterator[tuple[FrameSet, JsonRef]]

serialize_direct(name, serializer)#

Use a serializer function to save a nested object.

Parameters:

name (str) – 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[[OutputArchive[JsonRef]], TypeVar(T, bound= BaseModel | None)]) – 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:

Result of the call to the serializer.

Return type:

T

serialize_frame_set(name, frame_set, serializer, key)#

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

Parameters:

name (str) – 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 (FrameSet) – The frame set being saved. This will be returned in later calls to iter_frame_sets, along with the returned reference object.
serializer (Callable[[OutputArchive], TypeVar(T, bound= ArchiveTree)]) – 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 (Hashable) – A unique identifier for the in-memory object the serializer saves, e.g. a call to the built-in id function.

Returns:

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.

Return type:

T | P

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.

Parameters:

name (str) – 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[[OutputArchive[JsonRef]], TypeVar(T, bound= ArchiveTree)]) – 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 (Hashable) – A unique identifier for the in-memory object the serializer saves, e.g. a call to the built-in id function.

Returns:

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.

Return type:

T | P

serialize_root(obj, metadata=None, butler_info=None)#

Serialize obj to a root tree, apply write-time overrides, and warn if the tree uses a development schema.

Every backend’s top-level write funnel calls this so the metadata and butler overrides and the development-schema warning are applied uniformly, regardless of file format.

Parameters:

obj (Any) – Object with a serialize method (and an optional _archive_default_name) to serialize.
metadata (dict[str, TypeAliasType] | None, default: None) – Extra metadata to merge into the tree, or None.
butler_info (ButlerInfo | None, default: None) – Butler information to set on the tree, or None.

Returns:

The serialized root tree.

Return type:

ArchiveTree