read_archive#

Read an archive whose in-memory type is inferred from its schema.

Dispatches to the appropriate backend based on path’s extension (or, for stream input, its leading bytes), resolves the registered in-memory type from the file’s schema, and returns the fully deserialized object. Schema-version compatibility is enforced when the model validates the on-disk tree, via min_read_version. A path with a .gz/.zst compression suffix is decompressed transparently; stream input must already be decompressed.

This is the convenient way to read a whole object. To read individual components, or to reach the metadata and butler info stored alongside the object, use open_archive instead.

Parameters#

path: File to read; convertible to lsst.resources.ResourcePath, or a seekable binary stream containing the file’s content (e.g. io.BytesIO(data) for in-memory bytes).
cls: Optional expected in-memory type. When given, the file’s schema is checked against cls and the deserialized object is validated with isinstance (raising TypeError otherwise), and the static return type is T.
format: Optional backend name ("fits", "ndf", or "json") forcing the backend, instead of dispatching on the path’s extension or the stream’s leading bytes.
**kwargs: Type-specific keyword arguments forwarded to the object’s deserialize (e.g. bbox for an image subset read). Mis-targeted arguments surface as TypeError. Backend-specific open options (e.g. page_size) are not accepted here; use open_archive for those.

Returns#

object: The deserialized object.

Raises#

ValueError: Raised by backend_for_path if the file extension is not recognized, by backend_for_stream if a stream’s leading bytes are not recognized, or by backend_for_name if format is not a known backend name.
ArchiveReadError: Raised when the file’s schema_name is not registered, or propagated from the model’s min_read_version check on model_validate*.
TypeError: Raised when cls is given and the file’s schema or the deserialized object is not compatible with it.