Coverage for src / bioimageio / spec / _description.py: 92%
52 statements
« prev ^ index » next coverage.py v7.13.5, created at 2026-03-27 14:45 +0000
1from types import MappingProxyType
2from typing import Any, Literal, Optional, TypeVar, Union, overload
4from pydantic import Discriminator
5from typing_extensions import Annotated
7from ._description_impl import DISCOVER, build_description_impl, get_rd_class_impl
8from ._internal.common_nodes import InvalidDescr
9from ._internal.io import BioimageioYamlContent, BioimageioYamlContentView
10from ._internal.types import FormatVersionPlaceholder
11from ._internal.validation_context import ValidationContext, get_validation_context
12from .application import (
13 AnyApplicationDescr,
14 ApplicationDescr,
15 ApplicationDescr_v0_2,
16 ApplicationDescr_v0_3,
17)
18from .dataset import AnyDatasetDescr, DatasetDescr, DatasetDescr_v0_2, DatasetDescr_v0_3
19from .generic import AnyGenericDescr, GenericDescr, GenericDescr_v0_2, GenericDescr_v0_3
20from .model import AnyModelDescr, ModelDescr, ModelDescr_v0_4, ModelDescr_v0_5
21from .notebook import (
22 AnyNotebookDescr,
23 NotebookDescr,
24 NotebookDescr_v0_2,
25 NotebookDescr_v0_3,
26)
27from .summary import ValidationSummary
29LATEST: Literal["latest"] = "latest"
30"""placeholder for the latest available format version"""
33LatestResourceDescr = Union[
34 Annotated[
35 Union[
36 ApplicationDescr,
37 DatasetDescr,
38 ModelDescr,
39 NotebookDescr,
40 ],
41 Discriminator("type"),
42 ],
43 GenericDescr,
44]
45"""A resource description following the latest specification format"""
48SpecificResourceDescr = Annotated[
49 Union[
50 AnyApplicationDescr,
51 AnyDatasetDescr,
52 AnyModelDescr,
53 AnyNotebookDescr,
54 ],
55 Discriminator("type"),
56]
57"""Any of the implemented, non-generic resource descriptions"""
59ResourceDescr = Union[SpecificResourceDescr, AnyGenericDescr]
60"""Any of the implemented resource descriptions"""
63def dump_description(
64 rd: Union[ResourceDescr, InvalidDescr],
65 /,
66 *,
67 exclude_unset: bool = True,
68 exclude_defaults: bool = False,
69) -> BioimageioYamlContent:
70 """Converts a resource to a dictionary containing only simple types that can directly be serialzed to YAML.
72 Args:
73 rd: bioimageio resource description
74 exclude_unset: Exclude fields that have not explicitly be set.
75 exclude_defaults: Exclude fields that have the default value (even if set explicitly).
76 """
77 return rd.model_dump(
78 mode="json", exclude_unset=exclude_unset, exclude_defaults=exclude_defaults
79 )
82RD = TypeVar("RD", bound=ResourceDescr)
85LATEST_DESCRIPTIONS_MAP = MappingProxyType(
86 {
87 None: GenericDescr,
88 "generic": GenericDescr,
89 "application": ApplicationDescr,
90 "dataset": DatasetDescr,
91 "notebook": NotebookDescr,
92 "model": ModelDescr,
93 }
94)
95DESCRIPTIONS_MAP = MappingProxyType(
96 {
97 None: MappingProxyType(
98 {
99 "0.2": GenericDescr_v0_2,
100 "0.3": GenericDescr_v0_3,
101 "latest": GenericDescr,
102 }
103 ),
104 "generic": MappingProxyType(
105 {
106 "0.2": GenericDescr_v0_2,
107 "0.3": GenericDescr_v0_3,
108 "latest": GenericDescr,
109 }
110 ),
111 "application": MappingProxyType(
112 {
113 "0.2": ApplicationDescr_v0_2,
114 "0.3": ApplicationDescr_v0_3,
115 "latest": ApplicationDescr,
116 }
117 ),
118 "dataset": MappingProxyType(
119 {
120 "0.2": DatasetDescr_v0_2,
121 "0.3": DatasetDescr_v0_3,
122 "latest": DatasetDescr,
123 }
124 ),
125 "notebook": MappingProxyType(
126 {
127 "0.2": NotebookDescr_v0_2,
128 "0.3": NotebookDescr_v0_3,
129 "latest": NotebookDescr,
130 }
131 ),
132 "model": MappingProxyType(
133 {
134 "0.3": ModelDescr_v0_4,
135 "0.4": ModelDescr_v0_4,
136 "0.5": ModelDescr_v0_5,
137 "latest": ModelDescr,
138 }
139 ),
140 }
141)
142"""A mapping to determine the appropriate Description class
143 for a given **type** and **format_version**."""
146def _get_rd_class(typ: Any, format_version: Any, fallback_to_latest: bool):
147 return get_rd_class_impl(
148 typ, format_version, DESCRIPTIONS_MAP, fallback_to_latest=fallback_to_latest
149 )
152@overload
153def build_description(
154 content: BioimageioYamlContentView,
155 /,
156 *,
157 context: Optional[ValidationContext] = None,
158 format_version: Literal["latest"],
159) -> Union[LatestResourceDescr, InvalidDescr]: ...
162@overload
163def build_description(
164 content: BioimageioYamlContentView,
165 /,
166 *,
167 context: Optional[ValidationContext] = None,
168 format_version: Union[FormatVersionPlaceholder, str] = DISCOVER,
169) -> Union[ResourceDescr, InvalidDescr]: ...
172def build_description(
173 content: BioimageioYamlContentView,
174 /,
175 *,
176 context: Optional[ValidationContext] = None,
177 format_version: Union[FormatVersionPlaceholder, str] = DISCOVER,
178) -> Union[ResourceDescr, InvalidDescr]:
179 """build a bioimage.io resource description from an RDF's content.
181 Use `load_description` if you want to build a resource description from an rdf.yaml
182 or bioimage.io zip-package.
184 Args:
185 content: loaded rdf.yaml file (loaded with YAML, not bioimageio.spec)
186 context: validation context to use during validation
187 format_version:
188 (optional) use this argument to load the resource and
189 convert its metadata to a higher format_version.
190 Note:
191 - Use "latest" to convert to the latest available format version.
192 - Use "discover" to use the format version specified in the RDF.
193 - Only considers major.minor format version, ignores patch version.
194 - Conversion to lower format versions is not supported.
196 Returns:
197 An object holding all metadata of the bioimage.io resource
199 """
201 return build_description_impl(
202 content,
203 context=context,
204 format_version=format_version,
205 get_rd_class=_get_rd_class,
206 )
209def validate_format(
210 data: BioimageioYamlContent,
211 /,
212 *,
213 format_version: Union[Literal["discover", "latest"], str] = DISCOVER,
214 context: Optional[ValidationContext] = None,
215) -> ValidationSummary:
216 """Validate a dictionary holding a bioimageio description.
217 See `bioimagieo.spec.load_description_and_validate_format_only`
218 to validate a file source.
220 Args:
221 data: Dictionary holding the raw bioimageio.yaml content.
222 format_version:
223 Format version to (update to and) use for validation.
224 Note:
225 - Use "latest" to convert to the latest available format version.
226 - Use "discover" to use the format version specified in the RDF.
227 - Only considers major.minor format version, ignores patch version.
228 - Conversion to lower format versions is not supported.
229 context: Validation context, see `bioimagieo.spec.ValidationContext`
231 Note:
232 Use `bioimagieo.spec.load_description_and_validate_format_only` to validate a
233 file source instead of loading the YAML content and creating the appropriate
234 `ValidationContext`.
236 Alternatively you can use `bioimagieo.spec.load_description` and access the
237 `validation_summary` attribute of the returned object.
238 """
239 with context or get_validation_context():
240 rd = build_description(data, format_version=format_version)
242 assert rd.validation_summary is not None
243 return rd.validation_summary
246def ensure_description_is_model(
247 rd: Union[InvalidDescr, ResourceDescr],
248) -> AnyModelDescr:
249 """
250 Raises:
251 ValueError: for invalid or non-model resources
252 """
253 if isinstance(rd, InvalidDescr):
254 raise ValueError(f"Invalid {rd.type} description:\n{rd.get_reason()}")
256 if rd.type != "model":
257 raise ValueError(
258 f"Expected a model resource, but got resource type '{rd.type}'"
259 )
261 assert not isinstance(
262 rd,
263 (
264 GenericDescr_v0_2,
265 GenericDescr_v0_3,
266 ),
267 )
269 return rd
272def ensure_description_is_dataset(
273 rd: Union[InvalidDescr, ResourceDescr],
274) -> AnyDatasetDescr:
275 if isinstance(rd, InvalidDescr):
276 raise ValueError(f"Invalid {rd.type} description:\n{rd.get_reason()}")
278 if rd.type != "dataset":
279 raise ValueError(
280 f"Expected a dataset resource, but got resource type '{rd.type}'"
281 )
283 assert not isinstance(
284 rd,
285 (
286 GenericDescr_v0_2,
287 GenericDescr_v0_3,
288 ),
289 )
291 return rd