Coverage for src/bioimageio/spec/_io.py: 90%
39 statements
« prev ^ index » next coverage.py v7.15.4, created at 2026-08-25 19:19 +0000
1from __future__ import annotations
3from typing import Callable, Literal, TextIO, cast, overload
4from zipfile import ZipFile
6from loguru import logger
7from pydantic import FilePath, NewPath
9from ._description import (
10 DISCOVER,
11 InvalidDescr,
12 LatestResourceDescr,
13 ResourceDescr,
14 build_description,
15 dump_description,
16 ensure_description_is_dataset,
17 ensure_description_is_model,
18)
19from ._internal.common_nodes import ResourceDescrBase
20from ._internal.io import BioimageioYamlContent, YamlValue
21from ._internal.io_basics import Sha256
22from ._internal.io_utils import open_bioimageio_yaml, write_yaml
23from ._internal.types import FormatVersionPlaceholder, PermissiveFileSource
24from ._internal.validation_context import get_validation_context
25from .common import ProgressbarLike
26from .dataset import AnyDatasetDescr, DatasetDescr
27from .model import AnyModelDescr, ModelDescr
28from .summary import ValidationSummary
31@overload
32def load_description(
33 source: PermissiveFileSource | ZipFile,
34 /,
35 *,
36 format_version: Literal["latest"],
37 perform_io_checks: bool | None = None,
38 known_files: dict[str, Sha256 | None] | None = None,
39 sha256: Sha256 | None = None,
40 progressbar: bool | ProgressbarLike | Callable[[], ProgressbarLike] | None = None,
41) -> LatestResourceDescr | InvalidDescr: ...
44@overload
45def load_description(
46 source: PermissiveFileSource | ZipFile,
47 /,
48 *,
49 format_version: FormatVersionPlaceholder | str = DISCOVER,
50 perform_io_checks: bool | None = None,
51 known_files: dict[str, Sha256 | None] | None = None,
52 sha256: Sha256 | None = None,
53 progressbar: bool | ProgressbarLike | Callable[[], ProgressbarLike] | None = None,
54) -> ResourceDescr | InvalidDescr: ...
57def load_description(
58 source: PermissiveFileSource | ZipFile,
59 /,
60 *,
61 format_version: FormatVersionPlaceholder | str = DISCOVER,
62 perform_io_checks: bool | None = None,
63 known_files: dict[str, Sha256 | None] | None = None,
64 sha256: Sha256 | None = None,
65 progressbar: bool | ProgressbarLike | Callable[[], ProgressbarLike] | None = None,
66) -> ResourceDescr | InvalidDescr:
67 """load a bioimage.io resource description
69 Args:
70 source:
71 Path or URL to an rdf.yaml or a bioimage.io package
72 (zip-file with rdf.yaml in it).
73 format_version:
74 (optional) Use this argument to load the resource and
75 convert its metadata to a higher format_version.
76 Note:
77 - Use "latest" to convert to the latest available format version.
78 - Use "discover" to use the format version specified in the RDF.
79 - Only considers major.minor format version, ignores patch version.
80 - Conversion to lower format versions is not supported.
81 perform_io_checks:
82 Wether or not to perform validation that requires file io,
83 e.g. downloading a remote files. The existence of local
84 absolute file paths is still being checked.
85 known_files:
86 Allows to bypass download and hashing of referenced files
87 (even if perform_io_checks is True).
89 Keys should be file paths or URL strings as they appear in the
90 bioimageio.yaml file.
92 Values are Sha256 values compared to hash values in the description.
93 For `None` values no hash value comparison is performed.
95 If `perfrom_io_checks` is True, checked files will be added to
96 this dictionary with their SHA-256 value.
98 If `perform_io_checks` is False and `known_files` is not empty,
99 missing, 'unknown' file references are considered invalid.
100 sha256:
101 Optional SHA-256 value of **source**
102 progressbar:
103 Optional progress bar control forwarded to download/open helpers.
104 Use `False` to disable download progress bars, `True` for the default
105 tqdm bar, or pass a (factory of a) tqdm-like progressbar to customize it.
107 Returns:
108 An object holding all metadata of the bioimage.io resource
110 """
111 if isinstance(source, ResourceDescrBase):
112 name = getattr(source, "name", f"{str(source)[:10]}...")
113 logger.warning("returning already loaded description '{}' as is", name)
114 return source # pyright: ignore[reportReturnType]
116 opened = open_bioimageio_yaml(source, sha256=sha256, progressbar=progressbar)
118 context = get_validation_context().replace(
119 root=opened.original_root,
120 file_name=opened.original_file_name,
121 original_source_name=opened.original_source_name,
122 perform_io_checks=perform_io_checks,
123 known_files=known_files,
124 progressbar=progressbar,
125 )
127 return build_description(
128 opened.content,
129 context=context,
130 format_version=format_version,
131 )
134@overload
135def load_model_description(
136 source: PermissiveFileSource | ZipFile,
137 /,
138 *,
139 format_version: Literal["latest"],
140 perform_io_checks: bool | None = None,
141 known_files: dict[str, Sha256 | None] | None = None,
142 sha256: Sha256 | None = None,
143 progressbar: bool | ProgressbarLike | Callable[[], ProgressbarLike] | None = None,
144) -> ModelDescr: ...
147@overload
148def load_model_description(
149 source: PermissiveFileSource | ZipFile,
150 /,
151 *,
152 format_version: FormatVersionPlaceholder | str = DISCOVER,
153 perform_io_checks: bool | None = None,
154 known_files: dict[str, Sha256 | None] | None = None,
155 sha256: Sha256 | None = None,
156 progressbar: bool | ProgressbarLike | Callable[[], ProgressbarLike] | None = None,
157) -> AnyModelDescr: ...
160def load_model_description(
161 source: PermissiveFileSource | ZipFile,
162 /,
163 *,
164 format_version: FormatVersionPlaceholder | str = DISCOVER,
165 perform_io_checks: bool | None = None,
166 known_files: dict[str, Sha256 | None] | None = None,
167 sha256: Sha256 | None = None,
168 progressbar: bool | ProgressbarLike | Callable[[], ProgressbarLike] | None = None,
169) -> AnyModelDescr:
170 """same as `load_description`, but addtionally ensures that the loaded
171 description is valid and of type 'model'.
173 Raises:
174 ValueError: for invalid or non-model resources
175 """
176 rd = load_description(
177 source,
178 format_version=format_version,
179 perform_io_checks=perform_io_checks,
180 known_files=known_files,
181 sha256=sha256,
182 progressbar=progressbar,
183 )
184 return ensure_description_is_model(rd)
187@overload
188def load_dataset_description(
189 source: PermissiveFileSource | ZipFile,
190 /,
191 *,
192 format_version: Literal["latest"],
193 perform_io_checks: bool | None = None,
194 known_files: dict[str, Sha256 | None] | None = None,
195 sha256: Sha256 | None = None,
196 progressbar: bool | ProgressbarLike | Callable[[], ProgressbarLike] | None = None,
197) -> DatasetDescr: ...
200@overload
201def load_dataset_description(
202 source: PermissiveFileSource | ZipFile,
203 /,
204 *,
205 format_version: FormatVersionPlaceholder | str = DISCOVER,
206 perform_io_checks: bool | None = None,
207 known_files: dict[str, Sha256 | None] | None = None,
208 sha256: Sha256 | None = None,
209 progressbar: bool | ProgressbarLike | Callable[[], ProgressbarLike] | None = None,
210) -> AnyDatasetDescr: ...
213def load_dataset_description(
214 source: PermissiveFileSource | ZipFile,
215 /,
216 *,
217 format_version: FormatVersionPlaceholder | str = DISCOVER,
218 perform_io_checks: bool | None = None,
219 known_files: dict[str, Sha256 | None] | None = None,
220 sha256: Sha256 | None = None,
221 progressbar: bool | ProgressbarLike | Callable[[], ProgressbarLike] | None = None,
222) -> AnyDatasetDescr:
223 """same as `load_description`, but addtionally ensures that the loaded
224 description is valid and of type 'dataset'.
225 """
226 rd = load_description(
227 source,
228 format_version=format_version,
229 perform_io_checks=perform_io_checks,
230 known_files=known_files,
231 sha256=sha256,
232 progressbar=progressbar,
233 )
234 return ensure_description_is_dataset(rd)
237def save_bioimageio_yaml_only(
238 rd: ResourceDescr | BioimageioYamlContent | InvalidDescr,
239 /,
240 file: NewPath | FilePath | TextIO,
241 *,
242 exclude_unset: bool = True,
243 exclude_defaults: bool = False,
244):
245 """write the metadata of a resource description (`rd`) to `file`
246 without writing any of the referenced files in it.
248 Args:
249 rd: bioimageio resource description
250 file: file or stream to save to
251 exclude_unset: Exclude fields that have not explicitly be set.
252 exclude_defaults: Exclude fields that have the default value (even if set explicitly).
254 Note: To save a resource description with its associated files as a package,
255 use `save_bioimageio_package` or `save_bioimageio_package_as_folder`.
256 """
257 if isinstance(rd, ResourceDescrBase):
258 content = dump_description(
259 rd, exclude_unset=exclude_unset, exclude_defaults=exclude_defaults
260 )
261 else:
262 content = rd
264 write_yaml(cast(YamlValue, content), file)
267def load_description_and_validate_format_only(
268 source: PermissiveFileSource | ZipFile,
269 /,
270 *,
271 format_version: FormatVersionPlaceholder | str = DISCOVER,
272 perform_io_checks: bool | None = None,
273 known_files: dict[str, Sha256 | None] | None = None,
274 sha256: Sha256 | None = None,
275 progressbar: bool | ProgressbarLike | Callable[[], ProgressbarLike] | None = None,
276) -> ValidationSummary:
277 """same as `load_description`, but only return the validation summary.
279 Returns:
280 Validation summary of the bioimage.io resource found at `source`.
282 """
283 rd = load_description(
284 source,
285 format_version=format_version,
286 perform_io_checks=perform_io_checks,
287 known_files=known_files,
288 sha256=sha256,
289 progressbar=progressbar,
290 )
291 assert rd.validation_summary is not None
292 return rd.validation_summary