read

lsst.images.serialization.read(path: str | ParseResult | ResourcePath | Path, cls: type[T], **kwargs: Any) → T

lsst.images.serialization.read(path: str | ParseResult | ResourcePath | Path, cls: None = None, **kwargs: Any) → Any

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

Dispatches to the appropriate backend based on path’s extension, 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.

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

Parameters

path

File to read; convertible to lsst.resources.ResourcePath.

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.

**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 for those.

Returns

object

The deserialized object.

Raises

ValueError

Raised by backend_for_path if the file extension is not recognized.

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.