more explicit handling of format_version arg

Author: FynnBe

src/bioimageio/spec/_description.py

@@ -100,43 +100,43 @@ def dump_description(
             {
                 "0.2": GenericDescr_v0_2,
                 "0.3": GenericDescr_v0_3,
-                None: GenericDescr,
+                "latest": GenericDescr,
             }
         ),
         "generic": MappingProxyType(
             {
                 "0.2": GenericDescr_v0_2,
                 "0.3": GenericDescr_v0_3,
-                None: GenericDescr,
+                "latest": GenericDescr,
             }
         ),
         "application": MappingProxyType(
             {
                 "0.2": ApplicationDescr_v0_2,
                 "0.3": ApplicationDescr_v0_3,
-                None: ApplicationDescr,
+                "latest": ApplicationDescr,
             }
         ),
         "dataset": MappingProxyType(
             {
                 "0.2": DatasetDescr_v0_2,
                 "0.3": DatasetDescr_v0_3,
-                None: DatasetDescr,
+                "latest": DatasetDescr,
             }
         ),
         "notebook": MappingProxyType(
             {
                 "0.2": NotebookDescr_v0_2,
                 "0.3": NotebookDescr_v0_3,
-                None: NotebookDescr,
+                "latest": NotebookDescr,
             }
         ),
         "model": MappingProxyType(
             {
                 "0.3": ModelDescr_v0_4,
                 "0.4": ModelDescr_v0_4,
                 "0.5": ModelDescr_v0_5,
-                None: ModelDescr,
+                "latest": ModelDescr,
             }
         ),
     }
@@ -184,8 +184,14 @@ def build_description(
     Args:
         content: loaded rdf.yaml file (loaded with YAML, not bioimageio.spec)
         context: validation context to use during validation
-        format_version: (optional) use this argument to load the resource and
-                        convert its metadata to a higher format_version
+        format_version:
+            (optional) use this argument to load the resource and
+            convert its metadata to a higher format_version.
+            Note:
+            - Use "latest" to convert to the latest available format version.
+            - Use "discover" to use the format version specified in the RDF.
+            - Only considers major.minor format version, ignores patch version.
+            - Conversion to lower format versions is not supported.
 
     Returns:
         An object holding all metadata of the bioimage.io resource
@@ -213,7 +219,13 @@ def validate_format(
 
     Args:
         data: Dictionary holding the raw bioimageio.yaml content.
-        format_version: Format version to (update to and) use for validation.
+        format_version:
+            Format version to (update to and) use for validation.
+            Note:
+            - Use "latest" to convert to the latest available format version.
+            - Use "discover" to use the format version specified in the RDF.
+            - Only considers major.minor format version, ignores patch version.
+            - Conversion to lower format versions is not supported.
         context: Validation context, see `bioimagieo.spec.ValidationContext`
 
     Note:

src/bioimageio/spec/_description_impl.py

@@ -26,26 +26,34 @@ def get_rd_class_impl(
         Optional[str], Mapping[Optional[str], Type[ResourceDescrT]]
     ],
 ) -> Type[ResourceDescrT]:
+    """get the resource description class for the given type and format version"""
     assert None in descriptions_map
-    assert all(None in version_map for version_map in descriptions_map.values())
+    assert all("latest" in version_map for version_map in descriptions_map.values())
     assert all(
-        fv is None or fv.count(".") == 1
+        fv == "latest" or fv.count(".") == 1
         for version_map in descriptions_map.values()
         for fv in version_map
     )
     if not isinstance(typ, str) or typ not in descriptions_map:
         typ = None
 
     format_version = str(format_version)
-    if (ndots := format_version.count(".")) == 0:
+    if format_version == "latest" or (ndots := format_version.count(".")) == 1:
+        use_format_version = format_version
+    elif ndots == 0:
         use_format_version = format_version + ".0"
-    elif ndots == 2:
-        use_format_version = format_version[: format_version.rfind(".")]
     else:
-        use_format_version = None
+        assert ndots > 1
+        use_format_version = format_version[: format_version.rfind(".")]
 
     descr_versions = descriptions_map[typ]
-    return descr_versions.get(use_format_version, descr_versions[None])
+    if use_format_version not in descr_versions:
+        raise ValueError(
+            f"Unsupported format version '{format_version}' for type '{typ}'. "
+            f"Supported format versions are: {', '.join(sorted(fv for fv in descr_versions if fv is not None))}"
+        )
+
+    return descr_versions[use_format_version]
 
 
 def build_description_impl(

src/bioimageio/spec/_io.py

@@ -65,18 +65,28 @@ def load_description(
     """load a bioimage.io resource description
 
     Args:
-        source: Path or URL to an rdf.yaml or a bioimage.io package
-                (zip-file with rdf.yaml in it).
-        format_version: (optional) Use this argument to load the resource and
-                        convert its metadata to a higher format_version.
-        perform_io_checks: Wether or not to perform validation that requires file io,
-                           e.g. downloading a remote files. The existence of local
-                           absolute file paths is still being checked.
-        known_files: Allows to bypass download and hashing of referenced files
-                     (even if perform_io_checks is True).
-                     Checked files will be added to this dictionary
-                     with their SHA-256 value.
-        sha256: Optional SHA-256 value of **source**
+        source:
+            Path or URL to an rdf.yaml or a bioimage.io package
+            (zip-file with rdf.yaml in it).
+        format_version:
+            (optional) Use this argument to load the resource and
+            convert its metadata to a higher format_version.
+            Note:
+            - Use "latest" to convert to the latest available format version.
+            - Use "discover" to use the format version specified in the RDF.
+            - Only considers major.minor format version, ignores patch version.
+            - Conversion to lower format versions is not supported.
+        perform_io_checks:
+            Wether or not to perform validation that requires file io,
+            e.g. downloading a remote files. The existence of local
+            absolute file paths is still being checked.
+        known_files:
+            Allows to bypass download and hashing of referenced files
+            (even if perform_io_checks is True).
+            Checked files will be added to this dictionary
+            with their SHA-256 value.
+        sha256:
+            Optional SHA-256 value of **source**
 
     Returns:
         An object holding all metadata of the bioimage.io resource