Coverage for src/bioimageio/spec/generic/v0_2.py: 93%
187 statements
« prev ^ index » next coverage.py v7.15.4, created at 2026-08-18 09:17 +0000
1from __future__ import annotations
3import string
4from typing import (
5 TYPE_CHECKING,
6 Any,
7 Callable,
8 ClassVar,
9 List,
10 Literal,
11 Mapping,
12 Sequence,
13 TypeVar,
14 cast,
15)
17import annotated_types
18import pydantic
19from annotated_types import Len, LowerCase, MaxLen
20from pydantic import (
21 EmailStr,
22 Field,
23 RootModel,
24 ValidationInfo,
25 field_validator,
26 model_validator,
27)
28from typing_extensions import Annotated, Self, assert_never
30from .._internal.common_nodes import Node, ResourceDescrBase
31from .._internal.constants import TAG_CATEGORIES
32from .._internal.field_warning import as_warning, issue_warning, warn
33from .._internal.io import (
34 BioimageioYamlContent,
35 WithSuffix,
36 YamlValue,
37 wo_special_file_name,
38)
39from .._internal.io_packaging import FileSource_package, include_in_package
40from .._internal.type_guards import is_sequence
41from .._internal.types import (
42 DeprecatedLicenseId,
43 FilePath,
44 FileSource,
45 LicenseId,
46 NotEmpty,
47)
48from .._internal.types import Doi as Doi
49from .._internal.types import OrcidId as OrcidId
50from .._internal.types import RelativeFilePath as RelativeFilePath
51from .._internal.url import HttpUrl as HttpUrl
52from .._internal.validated_string import ValidatedString
53from .._internal.validator_annotations import AfterValidator, RestrictCharacters
54from .._internal.version_type import Version as Version
55from ._v0_2_converter import convert_from_older_format as _convert_from_older_format
58class ResourceId(ValidatedString):
59 root_model: ClassVar[type[RootModel[Any]]] = RootModel[
60 Annotated[
61 NotEmpty[str],
62 AfterValidator(str.lower), # convert upper case on the fly
63 RestrictCharacters(string.ascii_lowercase + string.digits + "_-/."),
64 annotated_types.Predicate(
65 lambda s: not (s.startswith("/") or s.endswith("/"))
66 ),
67 ]
68 ]
71KNOWN_SPECIFIC_RESOURCE_TYPES = (
72 "application",
73 "collection",
74 "dataset",
75 "model",
76 "notebook",
77)
79VALID_COVER_IMAGE_EXTENSIONS = (
80 ".gif",
81 ".jpeg",
82 ".jpg",
83 ".png",
84 ".svg",
85 ".tif",
86 ".tiff",
87)
90_FileSource_cover = Annotated[
91 FileSource_package,
92 WithSuffix(VALID_COVER_IMAGE_EXTENSIONS, case_sensitive=False),
93]
96class AttachmentsDescr(Node, extra="allow"):
97 files: list[FileSource_package] = Field(
98 default_factory=cast(Callable[[], List[FileSource]], list)
99 )
100 """File attachments"""
103def _remove_slashes(s: str):
104 return s.replace("/", "").replace("\\", "")
107class Uploader(Node):
108 email: EmailStr
109 """Email"""
110 name: Annotated[str, AfterValidator(_remove_slashes)] | None = None
111 """name"""
114class _Person(Node):
115 affiliation: str | None = None
116 """Affiliation"""
118 email: EmailStr | None = None
119 """Email"""
121 orcid: Annotated[OrcidId | None, Field(examples=["0000-0001-2345-6789"])] = None
122 """An [ORCID iD](https://support.orcid.org/hc/en-us/sections/360001495313-What-is-ORCID
123 ) in hyphenated groups of 4 digits, (and [valid](
124 https://support.orcid.org/hc/en-us/articles/360006897674-Structure-of-the-ORCID-Identifier
125 ) as per ISO 7064 11,2.)
126 """
129class Author(_Person):
130 name: Annotated[str, AfterValidator(_remove_slashes)]
131 github_user: str | None = None # TODO: validate github_user
134class Maintainer(_Person):
135 name: Annotated[str, AfterValidator(_remove_slashes)] | None = None
136 github_user: str
139class BadgeDescr(Node):
140 """A custom badge"""
142 label: Annotated[str, Field(examples=["Open in Colab"])]
143 """badge label to display on hover"""
145 icon: Annotated[
146 Annotated[
147 FilePath | RelativeFilePath,
148 AfterValidator(wo_special_file_name),
149 include_in_package,
150 ]
151 | HttpUrl
152 | pydantic.HttpUrl
153 | None,
154 Field(examples=["https://colab.research.google.com/assets/colab-badge.svg"]),
155 ] = None
156 """badge icon (included in bioimage.io package if not a URL)"""
158 url: Annotated[
159 HttpUrl,
160 Field(
161 examples=[
162 "https://colab.research.google.com/github/HenriquesLab/ZeroCostDL4Mic/blob/master/Colab_notebooks/U-net_2D_ZeroCostDL4Mic.ipynb"
163 ]
164 ),
165 ]
166 """target URL"""
169class CiteEntry(Node):
170 text: str
171 """free text description"""
173 doi: Doi | None = None
174 """A digital object identifier (DOI) is the prefered citation reference.
175 See https://www.doi.org/ for details. (alternatively specify `url`)"""
177 @field_validator("doi", mode="before")
178 @classmethod
179 def accept_prefixed_doi(cls, doi: Any) -> Any:
180 if isinstance(doi, str):
181 for doi_prefix in ("https://doi.org/", "http://dx.doi.org/"):
182 if doi.startswith(doi_prefix):
183 doi = doi[len(doi_prefix) :]
184 break
186 return doi
188 url: str | None = None
189 """URL to cite (preferably specify a `doi` instead)"""
191 @model_validator(mode="after")
192 def _check_doi_or_url(self) -> Self:
193 if not self.doi and not self.url:
194 raise ValueError("Either 'doi' or 'url' is required")
196 return self
199class LinkedResource(Node):
200 """Reference to a bioimage.io resource"""
202 id: ResourceId
203 """A valid resource `id` from the bioimage.io collection."""
205 version_number: int | None = None
206 """version number (n-th published version, not the semantic version) of linked resource"""
209class GenericModelDescrBase(ResourceDescrBase):
210 """Base for all resource descriptions including of model descriptions"""
212 name: Annotated[NotEmpty[str], warn(MaxLen(128), "Longer than 128 characters.")]
213 """A human-friendly name of the resource description"""
215 description: str
217 covers: list[_FileSource_cover] = Field(
218 default_factory=cast(Callable[[], List[_FileSource_cover]], list),
219 examples=[["cover.png"]],
220 description=(
221 "Cover images. Please use an image smaller than 500KB and an aspect"
222 " ratio width to height of 2:1.\nThe supported image formats are:"
223 f" {VALID_COVER_IMAGE_EXTENSIONS}"
224 ),
225 )
226 """Cover images. Please use an image smaller than 500KB and an aspect ratio width to height of 2:1."""
228 id_emoji: (
229 Annotated[str, Len(min_length=1, max_length=1), Field(examples=["🦈", "🦥"])]
230 | None
231 ) = None
232 """UTF-8 emoji for display alongside the `id`."""
234 authors: list[Author] = Field( # pyright: ignore[reportUnknownVariableType]
235 default_factory=list
236 )
237 """The authors are the creators of the RDF and the primary points of contact."""
239 @field_validator("authors", mode="before")
240 @classmethod
241 def accept_author_strings(cls, authors: Any | Sequence[Any]) -> Any:
242 """we unofficially accept strings as author entries"""
243 if is_sequence(authors):
244 authors = [{"name": a} if isinstance(a, str) else a for a in authors]
246 if not authors:
247 issue_warning("missing", value=authors, field="authors")
249 return authors
251 attachments: AttachmentsDescr | None = None
252 """file and other attachments"""
254 cite: list[CiteEntry] = Field( # pyright: ignore[reportUnknownVariableType]
255 default_factory=list
256 )
257 """citations"""
259 @field_validator("cite", mode="after")
260 @classmethod
261 def _warn_empty_cite(cls, value: Any):
262 if not value:
263 issue_warning("missing", value=value, field="cite")
265 return value
267 config: Annotated[
268 dict[str, YamlValue],
269 Field(
270 examples=[
271 {
272 "bioimageio": {
273 "my_custom_key": 3837283,
274 "another_key": {"nested": "value"},
275 },
276 "imagej": {"macro_dir": "path/to/macro/file"},
277 }
278 ],
279 ),
280 ] = Field(default_factory=dict)
281 """A field for custom configuration that can contain any keys not present in the RDF spec.
282 This means you should not store, for example, a github repo URL in `config` since we already have the
283 `git_repo` field defined in the spec.
284 Keys in `config` may be very specific to a tool or consumer software. To avoid conflicting definitions,
285 it is recommended to wrap added configuration into a sub-field named with the specific domain or tool name,
286 for example:
287 ```yaml
288 config:
289 bioimageio: # here is the domain name
290 my_custom_key: 3837283
291 another_key:
292 nested: value
293 imagej: # config specific to ImageJ
294 macro_dir: path/to/macro/file
295 ```
296 If possible, please use [`snake_case`](https://en.wikipedia.org/wiki/Snake_case) for keys in `config`.
297 You may want to list linked files additionally under `attachments` to include them when packaging a resource
298 (packaging a resource means downloading/copying important linked files and creating a ZIP archive that contains
299 an altered rdf.yaml file with local references to the downloaded files)"""
301 download_url: HttpUrl | None = None
302 """URL to download the resource from (deprecated)"""
304 git_repo: Annotated[
305 str | None,
306 Field(
307 examples=[
308 "https://github.com/bioimage-io/spec-bioimage-io/tree/main/example_descriptions/models/unet2d_nuclei_broad"
309 ],
310 ),
311 ] = None
312 """A URL to the Git repository where the resource is being developed."""
314 icon: Annotated[str, Len(min_length=1, max_length=2)] | FileSource | None = None
315 """An icon for illustration"""
317 links: Annotated[
318 list[str],
319 Field(
320 examples=[
321 (
322 "ilastik/ilastik",
323 "deepimagej/deepimagej",
324 "zero/notebook_u-net_3d_zerocostdl4mic",
325 )
326 ],
327 ),
328 ] = Field(default_factory=list)
329 """IDs of other bioimage.io resources"""
331 uploader: Uploader | None = None
332 """The person who uploaded the model (e.g. to bioimage.io)"""
334 # TODO: (py>3.8) remove pyright ignore
335 maintainers: list[Maintainer] = Field( # pyright: ignore[reportUnknownVariableType]
336 default_factory=list
337 )
338 """Maintainers of this resource.
339 If not specified `authors` are maintainers and at least some of them should specify their `github_user` name"""
341 rdf_source: FileSource | None = None
342 """Resource description file (RDF) source; used to keep track of where an rdf.yaml was loaded from.
343 Do not set this field in a YAML file."""
345 tags: Annotated[
346 list[str],
347 Field(examples=[("unet2d", "pytorch", "nucleus", "segmentation", "dsb2018")]),
348 ] = Field(default_factory=list)
349 """Associated tags"""
351 @as_warning
352 @field_validator("tags")
353 @classmethod
354 def warn_about_tag_categories(
355 cls, value: list[str], info: ValidationInfo
356 ) -> list[str]:
357 categories = TAG_CATEGORIES.get(info.data["type"], {})
358 missing_categories: list[Mapping[str, Sequence[str]]] = []
359 for cat, entries in categories.items():
360 if not any(e in value for e in entries):
361 missing_categories.append({cat: entries})
363 if missing_categories:
364 raise ValueError(
365 "Missing tags from bioimage.io categories: {missing_categories}"
366 )
368 return value
370 version: Version | None = None
371 """The version of the resource following SemVer 2.0."""
373 version_number: int | None = None
374 """version number (n-th published version, not the semantic version)"""
377class GenericDescrBase(GenericModelDescrBase):
378 """Base for all resource descriptions except for the model descriptions"""
380 implemented_format_version: ClassVar[Literal["0.2.4"]] = "0.2.4"
381 if TYPE_CHECKING:
382 format_version: Literal["0.2.4"] = "0.2.4"
383 else:
384 format_version: Literal["0.2.4"]
385 """The format version of this resource specification
386 (not the `version` of the resource description)
387 When creating a new resource always use the latest micro/patch version described here.
388 The `format_version` is important for any consumer software to understand how to parse the fields.
389 """
391 @model_validator(mode="before")
392 @classmethod
393 def _convert_from_older_format(
394 cls, data: BioimageioYamlContent, /
395 ) -> BioimageioYamlContent:
396 _convert_from_older_format(data)
397 return data
399 badges: list[BadgeDescr] = Field( # pyright: ignore[reportUnknownVariableType]
400 default_factory=list
401 )
402 """badges associated with this resource"""
404 documentation: Annotated[
405 FileSource | None,
406 Field(
407 examples=[
408 "https://raw.githubusercontent.com/bioimage-io/spec-bioimage-io/main/example_descriptions/models/unet2d_nuclei_broad/README.md",
409 "README.md",
410 ],
411 ),
412 ] = None
413 """URL or relative path to a markdown file with additional documentation.
414 The recommended documentation file name is `README.md`. An `.md` suffix is mandatory."""
416 license: Annotated[
417 LicenseId | DeprecatedLicenseId | str | None,
418 Field(union_mode="left_to_right", examples=["CC0-1.0", "MIT", "BSD-2-Clause"]),
419 ] = None
420 """A [SPDX license identifier](https://spdx.org/licenses/).
421 We do not support custom license beyond the SPDX license list, if you need that please
422 [open a GitHub issue](https://github.com/bioimage-io/spec-bioimage-io/issues/new/choose
423 ) to discuss your intentions with the community."""
425 @field_validator("license", mode="after")
426 @classmethod
427 def deprecated_spdx_license(
428 cls, value: LicenseId | DeprecatedLicenseId | str | None
429 ):
430 if isinstance(value, LicenseId):
431 pass
432 elif value is None:
433 issue_warning("missing", value=value, field="license")
434 elif isinstance(value, DeprecatedLicenseId):
435 issue_warning(
436 "'{value}' is a deprecated license identifier.",
437 value=value,
438 field="license",
439 )
440 elif isinstance(value, str):
441 issue_warning(
442 "'{value}' is an unknown license identifier.",
443 value=value,
444 field="license",
445 )
446 else:
447 assert_never(value)
449 return value
452ResourceDescrType = TypeVar("ResourceDescrType", bound=GenericDescrBase)
455class GenericDescr(GenericDescrBase, extra="ignore"):
456 """Specification of the fields used in a generic bioimage.io-compliant resource description file (RDF).
458 An RDF is a YAML file that describes a resource such as a model, a dataset, or a notebook.
459 Note that those resources are described with a type-specific RDF.
460 Use this generic resource description, if none of the known specific types matches your resource.
461 """
463 type: Annotated[str, LowerCase, Field(frozen=True)] = "generic"
464 """The resource type assigns a broad category to the resource."""
466 id: (
467 Annotated[ResourceId, Field(examples=["affable-shark", "ambitious-sloth"])]
468 | None
469 ) = None
470 """bioimage.io-wide unique resource identifier
471 assigned by bioimage.io; version **un**specific."""
473 source: HttpUrl | None = None
474 """The primary source of the resource"""
476 @field_validator("type", mode="after")
477 @classmethod
478 def check_specific_types(cls, value: str) -> str:
479 if value in KNOWN_SPECIFIC_RESOURCE_TYPES:
480 raise ValueError(
481 f"Use the {value} description instead of this generic description for"
482 + f" your '{value}' resource."
483 )
485 return value