open_archive#

lsst.images.serialization.open_archive(path: ResourcePathExpression | IO[bytes], cls: type[T], *, format: str | None = None, partial: bool = True, **backend_kwargs: Any) → AbstractContextManager[Reader[T]]#

lsst.images.serialization.open_archive(path: ResourcePathExpression | IO[bytes], cls: None = None, *, format: str | None = None, partial: bool = True, **backend_kwargs: Any) → AbstractContextManager[Reader[Any]]

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: File to read; convertible to lsst.resources.ResourcePath, or a seekable binary stream containing the file’s content.
cls: 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: 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: 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: 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.