Coverage for src / bioimageio / spec / _io.py: 89%

1from typing import Dict, Literal, Optional, TextIO, Union, cast, overload 

2from zipfile import ZipFile 

3 

4from loguru import logger 

5from pydantic import FilePath, NewPath 

6 

7from ._description import ( 

8 DISCOVER, 

9 InvalidDescr, 

10 LatestResourceDescr, 

11 ResourceDescr, 

12 build_description, 

13 dump_description, 

14 ensure_description_is_dataset, 

15 ensure_description_is_model, 

16) 

17from ._internal.common_nodes import ResourceDescrBase 

18from ._internal.io import BioimageioYamlContent, YamlValue 

19from ._internal.io_basics import Sha256 

20from ._internal.io_utils import open_bioimageio_yaml, write_yaml 

21from ._internal.types import FormatVersionPlaceholder, PermissiveFileSource 

22from ._internal.validation_context import get_validation_context 

23from .dataset import AnyDatasetDescr, DatasetDescr 

24from .model import AnyModelDescr, ModelDescr 

25from .summary import ValidationSummary 

26 

27 

28@overload 

29def load_description( 

30 source: Union[PermissiveFileSource, ZipFile], 

31 /, 

32 *, 

33 format_version: Literal["latest"], 

34 perform_io_checks: Optional[bool] = None, 

35 known_files: Optional[Dict[str, Optional[Sha256]]] = None, 

36 sha256: Optional[Sha256] = None, 

37) -> Union[LatestResourceDescr, InvalidDescr]: ... 

38 

39 

40@overload 

41def load_description( 

42 source: Union[PermissiveFileSource, ZipFile], 

43 /, 

44 *, 

45 format_version: Union[FormatVersionPlaceholder, str] = DISCOVER, 

46 perform_io_checks: Optional[bool] = None, 

47 known_files: Optional[Dict[str, Optional[Sha256]]] = None, 

48 sha256: Optional[Sha256] = None, 

49) -> Union[ResourceDescr, InvalidDescr]: ... 

50 

51 

52def load_description( 

53 source: Union[PermissiveFileSource, ZipFile], 

54 /, 

55 *, 

56 format_version: Union[FormatVersionPlaceholder, str] = DISCOVER, 

57 perform_io_checks: Optional[bool] = None, 

58 known_files: Optional[Dict[str, Optional[Sha256]]] = None, 

59 sha256: Optional[Sha256] = None, 

60) -> Union[ResourceDescr, InvalidDescr]: 

61 """load a bioimage.io resource description 

62 

63 Args: 

64 source: 

65 Path or URL to an rdf.yaml or a bioimage.io package 

66 (zip-file with rdf.yaml in it). 

67 format_version: 

68 (optional) Use this argument to load the resource and 

69 convert its metadata to a higher format_version. 

70 Note: 

71 - Use "latest" to convert to the latest available format version. 

72 - Use "discover" to use the format version specified in the RDF. 

73 - Only considers major.minor format version, ignores patch version. 

74 - Conversion to lower format versions is not supported. 

75 perform_io_checks: 

76 Wether or not to perform validation that requires file io, 

77 e.g. downloading a remote files. The existence of local 

78 absolute file paths is still being checked. 

79 known_files: 

80 Allows to bypass download and hashing of referenced files 

81 (even if perform_io_checks is True). 

82 

83 Keys should be file paths or URL strings as they appear in the 

84 bioimageio.yaml file. 

85 

86 Values are Sha256 values compared to hash values in the description. 

87 For `None` values no hash value comparison is performed. 

88 

89 If `perfrom_io_checks` is True, checked files will be added to 

90 this dictionary with their SHA-256 value. 

91 

92 If `perform_io_checks` is False and `known_files` is not empty, 

93 missing, 'unknown' file references are considered invalid. 

94 sha256: 

95 Optional SHA-256 value of **source** 

96 

97 Returns: 

98 An object holding all metadata of the bioimage.io resource 

99 

100 """ 

101 if isinstance(source, ResourceDescrBase): 

102 name = getattr(source, "name", f"{str(source)[:10]}...") 

103 logger.warning("returning already loaded description '{}' as is", name) 

104 return source # pyright: ignore[reportReturnType] 

105 

106 opened = open_bioimageio_yaml(source, sha256=sha256) 

107 

108 context = get_validation_context().replace( 

109 root=opened.original_root, 

110 file_name=opened.original_file_name, 

111 original_source_name=opened.original_source_name, 

112 perform_io_checks=perform_io_checks, 

113 known_files=known_files, 

114 ) 

115 

116 return build_description( 

117 opened.content, 

118 context=context, 

119 format_version=format_version, 

120 ) 

121 

122 

123@overload 

124def load_model_description( 

125 source: Union[PermissiveFileSource, ZipFile], 

126 /, 

127 *, 

128 format_version: Literal["latest"], 

129 perform_io_checks: Optional[bool] = None, 

130 known_files: Optional[Dict[str, Optional[Sha256]]] = None, 

131 sha256: Optional[Sha256] = None, 

132) -> ModelDescr: ... 

133 

134 

135@overload 

136def load_model_description( 

137 source: Union[PermissiveFileSource, ZipFile], 

138 /, 

139 *, 

140 format_version: Union[FormatVersionPlaceholder, str] = DISCOVER, 

141 perform_io_checks: Optional[bool] = None, 

142 known_files: Optional[Dict[str, Optional[Sha256]]] = None, 

143 sha256: Optional[Sha256] = None, 

144) -> AnyModelDescr: ... 

145 

146 

147def load_model_description( 

148 source: Union[PermissiveFileSource, ZipFile], 

149 /, 

150 *, 

151 format_version: Union[FormatVersionPlaceholder, str] = DISCOVER, 

152 perform_io_checks: Optional[bool] = None, 

153 known_files: Optional[Dict[str, Optional[Sha256]]] = None, 

154 sha256: Optional[Sha256] = None, 

155) -> AnyModelDescr: 

156 """same as `load_description`, but addtionally ensures that the loaded 

157 description is valid and of type 'model'. 

158 

159 Raises: 

160 ValueError: for invalid or non-model resources 

161 """ 

162 rd = load_description( 

163 source, 

164 format_version=format_version, 

165 perform_io_checks=perform_io_checks, 

166 known_files=known_files, 

167 sha256=sha256, 

168 ) 

169 return ensure_description_is_model(rd) 

170 

171 

172@overload 

173def load_dataset_description( 

174 source: Union[PermissiveFileSource, ZipFile], 

175 /, 

176 *, 

177 format_version: Literal["latest"], 

178 perform_io_checks: Optional[bool] = None, 

179 known_files: Optional[Dict[str, Optional[Sha256]]] = None, 

180 sha256: Optional[Sha256] = None, 

181) -> DatasetDescr: ... 

182 

183 

184@overload 

185def load_dataset_description( 

186 source: Union[PermissiveFileSource, ZipFile], 

187 /, 

188 *, 

189 format_version: Union[FormatVersionPlaceholder, str] = DISCOVER, 

190 perform_io_checks: Optional[bool] = None, 

191 known_files: Optional[Dict[str, Optional[Sha256]]] = None, 

192 sha256: Optional[Sha256] = None, 

193) -> AnyDatasetDescr: ... 

194 

195 

196def load_dataset_description( 

197 source: Union[PermissiveFileSource, ZipFile], 

198 /, 

199 *, 

200 format_version: Union[FormatVersionPlaceholder, str] = DISCOVER, 

201 perform_io_checks: Optional[bool] = None, 

202 known_files: Optional[Dict[str, Optional[Sha256]]] = None, 

203 sha256: Optional[Sha256] = None, 

204) -> AnyDatasetDescr: 

205 """same as `load_description`, but addtionally ensures that the loaded 

206 description is valid and of type 'dataset'. 

207 """ 

208 rd = load_description( 

209 source, 

210 format_version=format_version, 

211 perform_io_checks=perform_io_checks, 

212 known_files=known_files, 

213 sha256=sha256, 

214 ) 

215 return ensure_description_is_dataset(rd) 

216 

217 

218def save_bioimageio_yaml_only( 

219 rd: Union[ResourceDescr, BioimageioYamlContent, InvalidDescr], 

220 /, 

221 file: Union[NewPath, FilePath, TextIO], 

222 *, 

223 exclude_unset: bool = True, 

224 exclude_defaults: bool = False, 

225): 

226 """write the metadata of a resource description (`rd`) to `file` 

227 without writing any of the referenced files in it. 

228 

229 Args: 

230 rd: bioimageio resource description 

231 file: file or stream to save to 

232 exclude_unset: Exclude fields that have not explicitly be set. 

233 exclude_defaults: Exclude fields that have the default value (even if set explicitly). 

234 

235 Note: To save a resource description with its associated files as a package, 

236 use `save_bioimageio_package` or `save_bioimageio_package_as_folder`. 

237 """ 

238 if isinstance(rd, ResourceDescrBase): 

239 content = dump_description( 

240 rd, exclude_unset=exclude_unset, exclude_defaults=exclude_defaults 

241 ) 

242 else: 

243 content = rd 

244 

245 write_yaml(cast(YamlValue, content), file) 

246 

247 

248def load_description_and_validate_format_only( 

249 source: Union[PermissiveFileSource, ZipFile], 

250 /, 

251 *, 

252 format_version: Union[FormatVersionPlaceholder, str] = DISCOVER, 

253 perform_io_checks: Optional[bool] = None, 

254 known_files: Optional[Dict[str, Optional[Sha256]]] = None, 

255 sha256: Optional[Sha256] = None, 

256) -> ValidationSummary: 

257 """same as `load_description`, but only return the validation summary. 

258 

259 Returns: 

260 Validation summary of the bioimage.io resource found at `source`. 

261 

262 """ 

263 rd = load_description( 

264 source, 

265 format_version=format_version, 

266 perform_io_checks=perform_io_checks, 

267 known_files=known_files, 

268 sha256=sha256, 

269 ) 

270 assert rd.validation_summary is not None 

271 return rd.validation_summary