Coverage for bioimageio/spec/generic/v0_3.py: 91%

1from __future__ import annotations 

2 

3import string 

4from functools import partial 

5from typing import ( 

6 TYPE_CHECKING, 

7 Any, 

8 Callable, 

9 ClassVar, 

10 Dict, 

11 List, 

12 Literal, 

13 Optional, 

14 Sequence, 

15 Type, 

16 TypeVar, 

17 Union, 

18 cast, 

19) 

20 

21import annotated_types 

22from annotated_types import Len, LowerCase, MaxLen, MinLen 

23from pydantic import Field, RootModel, ValidationInfo, field_validator, model_validator 

24from typing_extensions import Annotated 

25 

26from bioimageio.spec._internal.type_guards import is_dict 

27 

28from .._internal.common_nodes import Node, ResourceDescrBase 

29from .._internal.constants import TAG_CATEGORIES 

30from .._internal.field_validation import validate_gh_user 

31from .._internal.field_warning import as_warning, warn 

32from .._internal.io import ( 

33 BioimageioYamlContent, 

34 FileDescr, 

35 WithSuffix, 

36 is_yaml_value, 

37) 

38from .._internal.io_basics import Sha256 

39from .._internal.io_packaging import FileDescr_ 

40from .._internal.license_id import DeprecatedLicenseId, LicenseId 

41from .._internal.node_converter import Converter 

42from .._internal.types import FileSource_, NotEmpty, RelativeFilePath 

43from .._internal.url import HttpUrl 

44from .._internal.validated_string import ValidatedString 

45from .._internal.validator_annotations import ( 

46 Predicate, 

47 RestrictCharacters, 

48) 

49from .._internal.version_type import Version 

50from .._internal.warning_levels import ALERT, INFO 

51from ._v0_3_converter import convert_from_older_format 

52from .v0_2 import Author as _Author_v0_2 

53from .v0_2 import BadgeDescr, Doi, FileSource_cover, OrcidId, Uploader 

54from .v0_2 import Maintainer as _Maintainer_v0_2 

55 

56__all__ = [ 

57 "Author", 

58 "BadgeDescr", 

59 "CiteEntry", 

60 "DeprecatedLicenseId", 

61 "Doi", 

62 "FileDescr", 

63 "GenericDescr", 

64 "HttpUrl", 

65 "KNOWN_SPECIFIC_RESOURCE_TYPES", 

66 "LicenseId", 

67 "LinkedResource", 

68 "Maintainer", 

69 "OrcidId", 

70 "RelativeFilePath", 

71 "ResourceId", 

72 "Sha256", 

73 "Uploader", 

74 "VALID_COVER_IMAGE_EXTENSIONS", 

75 "Version", 

76] 

77 

78KNOWN_SPECIFIC_RESOURCE_TYPES = ( 

79 "application", 

80 "collection", 

81 "dataset", 

82 "model", 

83 "notebook", 

84) 

85VALID_COVER_IMAGE_EXTENSIONS = ( 

86 ".gif", 

87 ".jpeg", 

88 ".jpg", 

89 ".png", 

90 ".svg", 

91) 

92 

93 

94class ResourceId(ValidatedString): 

95 root_model: ClassVar[Type[RootModel[Any]]] = RootModel[ 

96 Annotated[ 

97 NotEmpty[str], 

98 RestrictCharacters(string.ascii_lowercase + string.digits + "_-/."), 

99 annotated_types.Predicate( 

100 lambda s: not (s.startswith("/") or s.endswith("/")) 

101 ), 

102 ] 

103 ] 

104 

105 

106def _has_no_slash(s: str) -> bool: 

107 return "/" not in s and "\\" not in s 

108 

109 

110class Author(_Author_v0_2): 

111 name: Annotated[str, Predicate(_has_no_slash)] 

112 github_user: Optional[str] = None 

113 

114 @field_validator("github_user", mode="after") 

115 def _validate_gh_user(cls, value: Optional[str]): 

116 if value is None: 

117 return None 

118 else: 

119 return validate_gh_user(value) 

120 

121 

122class _AuthorConv(Converter[_Author_v0_2, Author]): 

123 def _convert( 

124 self, src: _Author_v0_2, tgt: "type[Author] | type[dict[str, Any]]" 

125 ) -> "Author | dict[str, Any]": 

126 return tgt( 

127 name=src.name, 

128 github_user=src.github_user, 

129 affiliation=src.affiliation, 

130 email=src.email, 

131 orcid=src.orcid, 

132 ) 

133 

134 

135_author_conv = _AuthorConv(_Author_v0_2, Author) 

136 

137 

138class Maintainer(_Maintainer_v0_2): 

139 name: Optional[Annotated[str, Predicate(_has_no_slash)]] = None 

140 github_user: str 

141 

142 @field_validator("github_user", mode="after") 

143 def validate_gh_user(cls, value: str): 

144 return validate_gh_user(value) 

145 

146 

147class _MaintainerConv(Converter[_Maintainer_v0_2, Maintainer]): 

148 def _convert( 

149 self, src: _Maintainer_v0_2, tgt: "type[Maintainer | dict[str, Any]]" 

150 ) -> "Maintainer | dict[str, Any]": 

151 return tgt( 

152 name=src.name, 

153 github_user=src.github_user, 

154 affiliation=src.affiliation, 

155 email=src.email, 

156 orcid=src.orcid, 

157 ) 

158 

159 

160_maintainer_conv = _MaintainerConv(_Maintainer_v0_2, Maintainer) 

161 

162 

163class CiteEntry(Node): 

164 """A citation that should be referenced in work using this resource.""" 

165 

166 text: str 

167 """free text description""" 

168 

169 doi: Optional[Doi] = None 

170 """A digital object identifier (DOI) is the prefered citation reference. 

171 See https://www.doi.org/ for details. 

172 Note: 

173 Either **doi** or **url** have to be specified. 

174 """ 

175 

176 url: Optional[HttpUrl] = None 

177 """URL to cite (preferably specify a **doi** instead/also). 

178 Note: 

179 Either **doi** or **url** have to be specified. 

180 """ 

181 

182 @model_validator(mode="after") 

183 def _check_doi_or_url(self): 

184 if not self.doi and not self.url: 

185 raise ValueError("Either 'doi' or 'url' is required") 

186 

187 return self 

188 

189 

190class LinkedResourceBase(Node): 

191 

192 @model_validator(mode="before") 

193 def _remove_version_number(cls, value: Any): 

194 if is_dict(value): 

195 vn = value.pop("version_number", None) 

196 if vn is not None and value.get("version") is None: 

197 value["version"] = vn 

198 

199 return value 

200 

201 version: Optional[Version] = None 

202 """The version of the linked resource following SemVer 2.0.""" 

203 

204 

205class LinkedResource(LinkedResourceBase): 

206 """Reference to a bioimage.io resource""" 

207 

208 id: ResourceId 

209 """A valid resource `id` from the official bioimage.io collection.""" 

210 

211 

212class BioimageioConfig(Node, extra="allow"): 

213 """bioimage.io internal metadata.""" 

214 

215 

216class Config(Node, extra="allow"): 

217 """A place to store additional metadata (often tool specific). 

218 

219 Such additional metadata is typically set programmatically by the respective tool 

220 or by people with specific insights into the tool. 

221 If you want to store additional metadata that does not match any of the other 

222 fields, think of a key unlikely to collide with anyone elses use-case/tool and save 

223 it here. 

224 

225 Please consider creating [an issue in the bioimageio.spec repository](https://github.com/bioimage-io/spec-bioimage-io/issues/new?template=Blank+issue) 

226 if you are not sure if an existing field could cover your use case 

227 or if you think such a field should exist. 

228 """ 

229 

230 bioimageio: BioimageioConfig = Field(default_factory=BioimageioConfig) 

231 """bioimage.io internal metadata.""" 

232 

233 @model_validator(mode="after") 

234 def _validate_extra_fields(self): 

235 if self.model_extra: 

236 for k, v in self.model_extra.items(): 

237 if not isinstance(v, Node) and not is_yaml_value(v): 

238 raise ValueError( 

239 f"config.{k} is not a valid YAML value or `Node` instance" 

240 ) 

241 

242 return self 

243 

244 def __getitem__(self, key: str) -> Any: 

245 """Allows to access the config as a dictionary.""" 

246 return getattr(self, key) 

247 

248 def __setitem__(self, key: str, value: Any) -> None: 

249 """Allows to set the config as a dictionary.""" 

250 setattr(self, key, value) 

251 

252 

253class GenericModelDescrBase(ResourceDescrBase): 

254 """Base for all resource descriptions including of model descriptions""" 

255 

256 name: Annotated[ 

257 Annotated[ 

258 str, RestrictCharacters(string.ascii_letters + string.digits + "_+- ()") 

259 ], 

260 MinLen(5), 

261 MaxLen(128), 

262 warn(MaxLen(64), "Name longer than 64 characters.", INFO), 

263 ] 

264 name: Annotated[NotEmpty[str], MaxLen(128)] 

265 """A human-friendly name of the resource description. 

266 May only contains letters, digits, underscore, minus, parentheses and spaces.""" 

267 

268 description: Annotated[ 

269 str, MaxLen(1024), warn(MaxLen(512), "Description longer than 512 characters.") 

270 ] 

271 """A string containing a brief description.""" 

272 

273 covers: List[FileSource_cover] = Field( 

274 default_factory=cast(Callable[[], List[FileSource_cover]], list), 

275 description=( 

276 "Cover images. Please use an image smaller than 500KB and an aspect" 

277 " ratio width to height of 2:1 or 1:1.\nThe supported image formats" 

278 f" are: {VALID_COVER_IMAGE_EXTENSIONS}" 

279 ), 

280 examples=[["cover.png"]], 

281 ) 

282 """Cover images.""" 

283 

284 id_emoji: Optional[ 

285 Annotated[str, Len(min_length=1, max_length=2), Field(examples=["🦈", "🦥"])] 

286 ] = None 

287 """UTF-8 emoji for display alongside the `id`.""" 

288 

289 authors: NotEmpty[List[Author]] 

290 """The authors are the creators of this resource description and the primary points of contact.""" 

291 

292 attachments: List[FileDescr_] = Field( 

293 default_factory=cast(Callable[[], List[FileDescr_]], list) 

294 ) 

295 """file attachments""" 

296 

297 cite: NotEmpty[List[CiteEntry]] 

298 """citations""" 

299 

300 license: Annotated[ 

301 Annotated[ 

302 Union[LicenseId, DeprecatedLicenseId], Field(union_mode="left_to_right") 

303 ], 

304 warn( 

305 LicenseId, 

306 "{value} is deprecated, see https://spdx.org/licenses/{value}.html", 

307 ), 

308 Field(examples=["CC0-1.0", "MIT", "BSD-2-Clause"]), 

309 ] 

310 """A [SPDX license identifier](https://spdx.org/licenses/). 

311 We do not support custom license beyond the SPDX license list, if you need that please 

312 [open a GitHub issue](https://github.com/bioimage-io/spec-bioimage-io/issues/new/choose) 

313 to discuss your intentions with the community.""" 

314 

315 git_repo: Annotated[ 

316 Optional[HttpUrl], 

317 Field( 

318 examples=[ 

319 "https://github.com/bioimage-io/spec-bioimage-io/tree/main/example_descriptions/models/unet2d_nuclei_broad" 

320 ], 

321 ), 

322 ] = None 

323 """A URL to the Git repository where the resource is being developed.""" 

324 

325 icon: Union[Annotated[str, Len(min_length=1, max_length=2)], FileSource_, None] = ( 

326 None 

327 ) 

328 """An icon for illustration, e.g. on bioimage.io""" 

329 

330 links: Annotated[ 

331 List[str], 

332 Field( 

333 examples=[ 

334 ( 

335 "ilastik/ilastik", 

336 "deepimagej/deepimagej", 

337 "zero/notebook_u-net_3d_zerocostdl4mic", 

338 ) 

339 ], 

340 ), 

341 ] = Field(default_factory=list) 

342 """IDs of other bioimage.io resources""" 

343 

344 uploader: Optional[Uploader] = None 

345 """The person who uploaded the model (e.g. to bioimage.io)""" 

346 

347 maintainers: List[Maintainer] = Field( # pyright: ignore[reportUnknownVariableType] 

348 default_factory=list 

349 ) 

350 """Maintainers of this resource. 

351 If not specified, `authors` are maintainers and at least some of them has to specify their `github_user` name""" 

352 

353 @partial(as_warning, severity=ALERT) 

354 @field_validator("maintainers", mode="after") 

355 @classmethod 

356 def check_maintainers_exist( 

357 cls, maintainers: List[Maintainer], info: ValidationInfo 

358 ) -> List[Maintainer]: 

359 if not maintainers and "authors" in info.data: 

360 authors: List[Author] = info.data["authors"] 

361 if all(a.github_user is None for a in authors): 

362 raise ValueError( 

363 "Missing `maintainers` or any author in `authors` with a specified" 

364 + " `github_user` name." 

365 ) 

366 

367 return maintainers 

368 

369 tags: Annotated[ 

370 List[str], 

371 Field(examples=[("unet2d", "pytorch", "nucleus", "segmentation", "dsb2018")]), 

372 ] = Field(default_factory=list) 

373 """Associated tags""" 

374 

375 @as_warning 

376 @field_validator("tags") 

377 @classmethod 

378 def warn_about_tag_categories( 

379 cls, value: List[str], info: ValidationInfo 

380 ) -> List[str]: 

381 categories = TAG_CATEGORIES.get(info.data["type"], {}) 

382 missing_categories: List[Dict[str, Sequence[str]]] = [] 

383 for cat, entries in categories.items(): 

384 if not any(e in value for e in entries): 

385 missing_categories.append({cat: entries}) 

386 

387 if missing_categories: 

388 raise ValueError( 

389 f"Missing tags from bioimage.io categories: {missing_categories}" 

390 ) 

391 

392 return value 

393 

394 version: Optional[Version] = None 

395 """The version of the resource following SemVer 2.0.""" 

396 

397 @model_validator(mode="before") 

398 def _remove_version_number(cls, value: Any): 

399 if is_dict(value): 

400 vn = value.pop("version_number", None) 

401 if vn is not None and value.get("version") is None: 

402 value["version"] = vn 

403 

404 return value 

405 

406 

407FileSource_documentation = Annotated[ 

408 FileSource_, 

409 WithSuffix(".md", case_sensitive=True), 

410 Field( 

411 examples=[ 

412 "https://raw.githubusercontent.com/bioimage-io/spec-bioimage-io/main/example_descriptions/models/unet2d_nuclei_broad/README.md", 

413 "README.md", 

414 ], 

415 ), 

416] 

417 

418 

419class GenericDescrBase(GenericModelDescrBase): 

420 """Base for all resource descriptions except for the model descriptions""" 

421 

422 implemented_format_version: ClassVar[Literal["0.3.0"]] = "0.3.0" 

423 if TYPE_CHECKING: 

424 format_version: Literal["0.3.0"] = "0.3.0" 

425 else: 

426 format_version: Literal["0.3.0"] 

427 """The **format** version of this resource specification""" 

428 

429 @model_validator(mode="before") 

430 @classmethod 

431 def _convert_from_older_format( 

432 cls, data: BioimageioYamlContent, / 

433 ) -> BioimageioYamlContent: 

434 cls.convert_from_old_format_wo_validation(data) 

435 return data 

436 

437 @classmethod 

438 def convert_from_old_format_wo_validation(cls, data: BioimageioYamlContent) -> None: 

439 """Convert metadata following an older format version to this classes' format 

440 without validating the result. 

441 """ 

442 convert_from_older_format(data) 

443 

444 documentation: Optional[FileSource_documentation] = None 

445 """URL or relative path to a markdown file encoded in UTF-8 with additional documentation. 

446 The recommended documentation file name is `README.md`. An `.md` suffix is mandatory.""" 

447 

448 badges: List[BadgeDescr] = Field( # pyright: ignore[reportUnknownVariableType] 

449 default_factory=list 

450 ) 

451 """badges associated with this resource""" 

452 

453 config: Config = Field(default_factory=Config) 

454 """A field for custom configuration that can contain any keys not present in the RDF spec. 

455 This means you should not store, for example, a GitHub repo URL in `config` since there is a `git_repo` field. 

456 Keys in `config` may be very specific to a tool or consumer software. To avoid conflicting definitions, 

457 it is recommended to wrap added configuration into a sub-field named with the specific domain or tool name, 

458 for example: 

459 ```yaml 

460 config: 

461 giraffe_neckometer: # here is the domain name 

462 length: 3837283 

463 address: 

464 home: zoo 

465 imagej: # config specific to ImageJ 

466 macro_dir: path/to/macro/file 

467 ``` 

468 If possible, please use [`snake_case`](https://en.wikipedia.org/wiki/Snake_case) for keys in `config`. 

469 You may want to list linked files additionally under `attachments` to include them when packaging a resource. 

470 (Packaging a resource means downloading/copying important linked files and creating a ZIP archive that contains 

471 an altered rdf.yaml file with local references to the downloaded files.)""" 

472 

473 

474ResourceDescrType = TypeVar("ResourceDescrType", bound=GenericDescrBase) 

475 

476 

477class GenericDescr(GenericDescrBase, extra="ignore"): 

478 """Specification of the fields used in a generic bioimage.io-compliant resource description file (RDF). 

479 

480 An RDF is a YAML file that describes a resource such as a model, a dataset, or a notebook. 

481 Note that those resources are described with a type-specific RDF. 

482 Use this generic resource description, if none of the known specific types matches your resource. 

483 """ 

484 

485 implemented_type: ClassVar[Literal["generic"]] = "generic" 

486 if TYPE_CHECKING: 

487 type: Annotated[str, LowerCase] = "generic" 

488 """The resource type assigns a broad category to the resource.""" 

489 else: 

490 type: Annotated[str, LowerCase] 

491 """The resource type assigns a broad category to the resource.""" 

492 

493 id: Optional[ 

494 Annotated[ResourceId, Field(examples=["affable-shark", "ambitious-sloth"])] 

495 ] = None 

496 """bioimage.io-wide unique resource identifier 

497 assigned by bioimage.io; version **un**specific.""" 

498 

499 parent: Optional[ResourceId] = None 

500 """The description from which this one is derived""" 

501 

502 source: Optional[HttpUrl] = None 

503 """The primary source of the resource""" 

504 

505 @field_validator("type", mode="after") 

506 @classmethod 

507 def check_specific_types(cls, value: str) -> str: 

508 if value in KNOWN_SPECIFIC_RESOURCE_TYPES: 

509 raise ValueError( 

510 f"Use the {value} description instead of this generic description for" 

511 + f" your '{value}' resource." 

512 ) 

513 

514 return value