open_archive

lsst.images.serialization.open_archive(path, cls=None, *, format=None, partial=True, **backend_kwargs)

Open an lsst.images file for incremental, component-wise reads.

Dispatches to the appropriate backend by file extension (or, for stream input, by the leading bytes), resolves the registered in-memory type from the file’s schema, and returns a Reader context manager.

A path with a .gz/.zst compression suffix is stream-decompressed into an anonymous temporary file first (in bounded-memory chunks, since compressed data has no random access; partial is ignored for it). zstd requires Python >= 3.14 or the zstandard package. Stream input must already be decompressed: whoever produced the stream knows how it was compressed.

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.

• cls (type[Any] | None, default: None) – Optional expected in-memory type. When given, open_archive validates that the file’s schema resolves to a subclass of cls (raising TypeError otherwise) and the returned Reader is typed accordingly, so Reader.read needs no cast.

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

• partial (bool, default: True) – Forwarded to the backend open_tree; defaults to True (a reader is for incremental access). A no-op for the JSON and NDF backends and for stream input.

• **backend_kwargs (Any) – Backend-specific open options (e.g. page_size for FITS).

Raises:

• ValueError – If the file extension or the stream’s leading bytes are not recognized, or format is not a known backend name.

• ArchiveReadError – If the file’s schema is not registered.

• TypeError – If cls is given and the file’s schema resolves to an incompatible type.

Return type:

Iterator[Reader]