read_archive

lsst.images.serialization.read_archive(path, cls=None, *, format=None, **kwargs)

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 (Union[str, ParseResult, ResourcePath, Path, IO[bytes]]) – 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 (type[Any] | None, default: None) – 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 (str | None, default: None) – 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 (Any) – 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:

The deserialized object.

Return type:

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.