Coverage for python/lsst/images/serialization/_reader.py: 97%
71 statements
« prev ^ index » next coverage.py v7.15.0, created at 2026-07-08 09:10 +0000
1# This file is part of lsst-images.
2#
3# Developed for the LSST Data Management System.
4# This product includes software developed by the LSST Project
5# (https://www.lsst.org).
6# See the COPYRIGHT file at the top-level directory of this distribution
7# for details of code ownership.
8#
9# Use of this source code is governed by a 3-clause BSD-style
10# license that can be found in the LICENSE file.
11"""User-facing ``open`` reader for incremental, component-wise reads."""
13from __future__ import annotations
15__all__ = ("Reader", "open")
17from collections.abc import Iterator
18from contextlib import AbstractContextManager, contextmanager
19from typing import IO, Any, TypeVar, overload
21from lsst.resources import ResourcePathExpression
23from ._backends import (
24 _decompress_path_to_temp_file,
25 _is_binary_stream,
26 _path_is_compressed,
27 backend_for_name,
28 backend_for_path,
29 backend_for_stream,
30)
31from ._common import ArchiveTree, ButlerInfo, MetadataValue
32from ._input_archive import ArchiveInfo, InputArchive
33from ._io import public_type_for_schema
35# This pre-python-3.12 declaration is needed so Sphinx (the
36# autodoc-typehints plugin) can resolve the ``T`` forward reference in the
37# stringized annotations; the PEP 695 ``[T]`` parameters below are scoped to
38# their class/function and are not visible in the module globals.
39T = TypeVar("T")
42class Reader[T]:
43 """A handle to an open ``lsst.images`` file.
45 Returned by `open`.
46 Lets the caller pull individual components, or the whole object, out of a
47 file that is opened once; the underlying archive caches dereferenced
48 pointers so repeated reads share work.
49 Valid only inside the ``with`` block that produced it.
51 Parameters
52 ----------
53 archive
54 Input archive backing the open file.
55 tree
56 Validated on-disk deserialization tree for the file.
57 info
58 Schema name, version, URL, and format version for the file.
59 expected_cls
60 Expected type of the deserialized object, or `None` to accept any
61 type.
62 """
64 def __init__(
65 self,
66 archive: InputArchive[Any],
67 tree: ArchiveTree,
68 info: ArchiveInfo,
69 expected_cls: type[T] | None,
70 ) -> None:
71 self._archive = archive
72 self._tree = tree
73 self._info = info
74 self._expected_cls = expected_cls
75 self._closed = False
77 def _check_open(self) -> None:
78 if self._closed:
79 raise RuntimeError("Reader is closed; use it only inside its 'with' block.")
81 @property
82 def info(self) -> ArchiveInfo:
83 """Schema name/version/url and format version for this file."""
84 return self._info
86 @property
87 def metadata(self) -> dict[str, MetadataValue]:
88 """Flexible metadata stored with the object."""
89 return self._tree.metadata
91 @property
92 def butler_info(self) -> ButlerInfo | None:
93 """Butler dataset info stored with the object, or `None`."""
94 return self._tree.butler_info
96 def get_tree(self) -> ArchiveTree:
97 """Return the validated on-disk tree for advanced, low-level access.
99 Most callers want `read` or `get_component` instead; the tree is the
100 raw deserialization model that those methods build on.
101 """
102 self._check_open()
103 return self._tree
105 def get_component(self, name: str, **kwargs: Any) -> Any:
106 """Deserialize and return a single named component.
108 Raises `~lsst.images.serialization.InvalidComponentError` for an
109 unknown component name.
111 Parameters
112 ----------
113 name
114 Name of the component to deserialize.
115 **kwargs
116 Additional keyword arguments forwarded to the component
117 deserializer.
118 """
119 self._check_open()
120 return self._tree.deserialize_component(name, self._archive, **kwargs)
122 def read(self, **kwargs: Any) -> T:
123 """Deserialize and return the whole object.
125 Parameters
126 ----------
127 **kwargs
128 Additional keyword arguments forwarded to the deserializer.
129 """
130 self._check_open()
131 obj = self._tree.deserialize(self._archive, **kwargs)
132 if hasattr(obj, "_opaque_metadata"):
133 obj._opaque_metadata = self._archive.get_opaque_metadata()
134 if self._expected_cls is not None and not isinstance(obj, self._expected_cls): 134 ↛ 135line 134 didn't jump to line 135 because the condition on line 134 was never true
135 raise TypeError(
136 f"{self._info.schema_name!r} deserialized to {type(obj).__name__}, "
137 f"not the requested {self._expected_cls.__name__}."
138 )
139 return obj
142@overload
143def open[T](
144 path: ResourcePathExpression | IO[bytes],
145 cls: type[T],
146 *,
147 format: str | None = ...,
148 partial: bool = ...,
149 **backend_kwargs: Any,
150) -> AbstractContextManager[Reader[T]]: ...
151@overload
152def open( 152 ↛ exitline 152 didn't return from function 'open' because
153 path: ResourcePathExpression | IO[bytes],
154 cls: None = ...,
155 *,
156 format: str | None = ...,
157 partial: bool = ...,
158 **backend_kwargs: Any,
159) -> AbstractContextManager[Reader[Any]]: ...
160@contextmanager
161def open(
162 path: ResourcePathExpression | IO[bytes],
163 cls: type[Any] | None = None,
164 *,
165 format: str | None = None,
166 partial: bool = True,
167 **backend_kwargs: Any,
168) -> Iterator[Reader]:
169 """Open an ``lsst.images`` file for incremental, component-wise reads.
171 Dispatches to the appropriate backend by file extension (or, for stream
172 input, by the leading bytes), resolves the registered in-memory type
173 from the file's schema, and returns a `Reader` context manager.
175 A path with a ``.gz``/``.zst`` compression suffix is stream-decompressed
176 into an anonymous temporary file first (in bounded-memory chunks, since
177 compressed data has no random access; ``partial`` is ignored for it).
178 zstd requires Python >= 3.14 or the ``zstandard`` package.
179 Stream input must already be decompressed: whoever produced the stream
180 knows how it was compressed.
182 Parameters
183 ----------
184 path
185 File to read; convertible to `lsst.resources.ResourcePath`, or a
186 seekable binary stream containing the file's content.
187 cls
188 Optional expected in-memory type.
189 When given, `open` validates that the file's schema resolves to a
190 subclass of ``cls`` (raising `TypeError` otherwise) and the returned
191 `Reader` is typed accordingly, so `Reader.read` needs no cast.
192 format
193 Optional backend name (``"fits"``, ``"ndf"``, or ``"json"``)
194 forcing the backend, instead of dispatching on the path's extension
195 or the stream's leading bytes.
196 partial
197 Forwarded to the backend ``open_tree``; defaults to `True` (a reader
198 is for incremental access).
199 A no-op for the JSON and NDF backends and for stream input.
200 **backend_kwargs
201 Backend-specific open options (e.g. ``page_size`` for FITS).
203 Raises
204 ------
205 ValueError
206 If the file extension or the stream's leading bytes are not
207 recognized, or ``format`` is not a known backend name.
208 ArchiveReadError
209 If the file's schema is not registered.
210 TypeError
211 If ``cls`` is given and the file's schema resolves to an
212 incompatible type.
213 """
214 source: ResourcePathExpression | IO[bytes]
215 temp_file: IO[bytes] | None = None
216 if _is_binary_stream(path):
217 source = path
218 backend = backend_for_name(format) if format is not None else backend_for_stream(path)
219 else:
220 backend = backend_for_name(format) if format is not None else backend_for_path(path)
221 if _path_is_compressed(path):
222 temp_file = _decompress_path_to_temp_file(path)
223 source = temp_file
224 else:
225 source = path
226 try:
227 with backend.input_archive.open_tree(source, partial=partial, **backend_kwargs) as (
228 archive,
229 tree,
230 info,
231 ):
232 if cls is not None:
233 resolved = public_type_for_schema(info.schema_name)
234 if resolved is not None and not issubclass(resolved, cls):
235 raise TypeError(
236 f"{path!r} has schema {info.schema_name!r} (type {resolved.__name__}), "
237 f"which is not a {cls.__name__}."
238 )
239 reader: Reader[Any] = Reader(archive, tree, info, cls)
240 try:
241 yield reader
242 finally:
243 reader._closed = True
244 finally:
245 if temp_file is not None:
246 temp_file.close()