Merge pull request #281 from tlambert03/cli

feat: Add CLI validate/info

Author: d-v-b

pyproject.toml

@@ -32,6 +32,9 @@ docs = [
     "fsspec[http]",
 ]
 
+[project.scripts]
+ome-zarr-models = "ome_zarr_models._cli:main"
+
 [tool.hatch.version]
 source = "vcs"
 

src/ome_zarr_models/__init__.py

@@ -1,5 +1,5 @@
 from importlib.metadata import PackageNotFoundError, version
-from typing import Any
+from typing import TYPE_CHECKING, Any, Literal
 
 import zarr
 
@@ -22,6 +22,8 @@
 except PackageNotFoundError:  # pragma: no cover
     __version__ = "uninstalled"
 
+if TYPE_CHECKING:
+    from collections.abc import Sequence
 
 _V04_groups: list[type[BaseGroupv04[Any]]] = [
     ome_zarr_models.v04.hcs.HCS,
@@ -48,7 +50,9 @@
 ]
 
 
-def open_ome_zarr(group: zarr.Group) -> BaseGroup:
+def open_ome_zarr(
+    group: zarr.Group, *, version: Literal["0.4", "0.5"] | None = None
+) -> BaseGroup:
     """
     Create an ome-zarr-models object from an existing OME-Zarr group.
 
@@ -63,6 +67,10 @@ def open_ome_zarr(group: zarr.Group) -> BaseGroup:
     ----------
     group : zarr.Group
         Zarr group containing OME-Zarr data.
+    version : Literal['0.4', '0.5'], optional
+        If you know which version of OME-Zarr your data is, you can
+        specify it here. If not specified, all versions will be tried.
+        The default is None, which means all versions will be tried.
 
     Raises
     ------
@@ -76,17 +84,31 @@ def open_ome_zarr(group: zarr.Group) -> BaseGroup:
     take a long time. It will be quicker to directly use the OME-Zarr group class if you
     know which version and group you expect.
     """
-    group_cls: type[BaseGroup]
-    for group_cls in _V05_groups + _V04_groups:
+    # because 'from_zarr' isn't defined on a shared super-class, list all variants here
+    groups: Sequence[type[BaseGroupv05[Any] | BaseGroupv04[Any]]]
+    match version:
+        case None:
+            groups = [*_V05_groups, *_V04_groups]
+        case "0.4":
+            groups = _V04_groups
+        case "0.5":
+            groups = _V05_groups
+        case _:
+            _versions = ("0.4", "0.5")  # type: ignore[unreachable]
+            raise ValueError(
+                f"Unsupported version '{version}', must be one of {_versions}, or None"
+            )
+
+    errors: list[Exception] = []
+    for group_cls in groups:
         try:
             return group_cls.from_zarr(group)
-        except Exception:
-            continue
+        except Exception as e:
+            errors.append(e)
 
     raise RuntimeError(
-        f"Could not successfully validate {group} with any OME-Zarr group models.\n"
+        f"Could not successfully validate {group} against any OME-Zarr group model.\n"
         "\n"
-        "If you know what type of group you are trying to open, using the "
-        "<group class>.from_zarr() method will give you a more informative "
-        "error message explaining why validation failed."
+        "The following errors were encountered while trying to validate:\n\n"
+        + "\n\n".join(f"- {type(e).__name__}: {e}" for e in errors)
     )

src/ome_zarr_models/_cli.py

@@ -0,0 +1,115 @@
+from __future__ import annotations
+
+import argparse
+import sys
+from typing import TYPE_CHECKING
+
+from ome_zarr_models import __version__, open_ome_zarr
+
+if TYPE_CHECKING:
+    from zarr.storage import StoreLike
+
+
+def main() -> None:
+    """Main entry point for the ome-zarr-models CLI."""
+    parser = argparse.ArgumentParser(
+        prog="ome-zarr-models",
+        description="OME-Zarr Models CLI",
+    )
+    parser.add_argument(
+        "--version",
+        action="version",
+        version=f"ome-zarr-models version {__version__}",
+    )
+    subparsers = parser.add_subparsers(
+        dest="command", help="Available commands", metavar="COMMAND"
+    )
+
+    # validate sub-command
+    validate_cmd = subparsers.add_parser("validate", help="Validate an OME-Zarr")
+    validate_cmd.add_argument(
+        "path", type=str, help="Path to OME-Zarr group to validate"
+    )
+
+    # info sub-command
+    info_cmd = subparsers.add_parser(
+        "info", help="Get information about an OME-Zarr group"
+    )
+    info_cmd.add_argument(
+        "path", type=str, help="Path to OME-Zarr group to get information about"
+    )
+
+    args = parser.parse_args()
+
+    # Execute the appropriate command
+    match args.command:
+        case "validate":
+            validate(args.path)
+        case "info":
+            info(args.path)
+        case None:
+            parser.print_help()
+            sys.exit(1)
+
+
+def validate(path: StoreLike, version: str | None = None) -> None:
+    """Validate an OME-Zarr at the given path.
+
+    Parameters
+    ----------
+    path : str
+        Path to the OME-Zarr group to validate.  May be
+    version : str | None, optional
+        OME-Zarr version to validate against. If `None`, the version will be
+        inferred from the metadata, by default `None`.
+
+    Examples
+    --------
+    ```bash
+    ome-zarr-models validate https://uk1s3.embassy.ebi.ac.uk/idr/zarr/v0.5/idr0066/ExpD_chicken_embryo_MIP.ome.zarr
+    ```
+    """
+    import zarr
+
+    group = zarr.open_group(path, mode="r")
+    try:
+        open_ome_zarr(group, version=version)  # type: ignore[arg-type]
+    except Exception as e:
+        print(f"{e}\n")
+        print(f"❌ Invalid OME-Zarr: {path}")
+        sys.exit(1)
+    print("✅ Valid OME-Zarr")
+
+
+def info(path: StoreLike) -> None:
+    """Print information about an OME-Zarr at the given path.
+
+    Examples
+    --------
+    ```bash
+    ome-zarr-models info https://uk1s3.embassy.ebi.ac.uk/idr/zarr/v0.5/idr0066/ExpD_chicken_embryo_MIP.ome.zarr
+    ome-zarr-models info https://uk1s3.embassy.ebi.ac.uk/idr/zarr/v0.5/idr0062A/6001240_labels.zarr
+    ome-zarr-models info https://uk1s3.embassy.ebi.ac.uk/idr/zarr/v0.5/idr0083/9822152.zarr
+    ome-zarr-models info https://uk1s3.embassy.ebi.ac.uk/idr/zarr/v0.5/idr0010/76-45.ome.zarr
+    ```
+    """
+    import zarr
+
+    try:
+        from rich import print
+    except ImportError:
+        from builtins import print
+
+    try:
+        group = zarr.open_group(path, mode="r")
+        obj = open_ome_zarr(group)
+    except Exception as e:
+        print(f"{e}\n")
+        print(f"❌ Invalid OME-Zarr: {path}")
+        sys.exit(1)
+    else:
+        print(obj)
+
+
+if __name__ == "__main__":
+    main()

tests/test_cli.py

@@ -0,0 +1,110 @@
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, cast
+
+import pytest
+import zarr
+from zarr.storage import LocalStore
+
+from ome_zarr_models._cli import main
+
+from .conftest import Version, json_to_zarr_group
+
+if TYPE_CHECKING:
+    from collections.abc import Mapping, Sequence
+    from pathlib import Path
+    from typing import Any
+
+
+def populate_fake_data(
+    zarr_group: zarr.Group,
+    default_dtype: str = "uint8",
+) -> None:
+    # Get the ome metadata from the group attributes
+    # version 0.4 uses the root attributes, version 0.5 uses the "ome" attribute
+    ome_attrs = cast("Mapping[str, Any]", zarr_group.attrs.get("ome", zarr_group.attrs))
+    multiscales = ome_attrs.get("multiscales")
+    if isinstance(multiscales, list):
+        create_multiscales_data(zarr_group, multiscales, default_dtype)
+        return
+
+    # TODO?  could support fake data for other node types
+
+
+def create_multiscales_data(
+    zarr_group: zarr.Group,
+    multiscales: Sequence[Mapping[str, Any]],
+    default_dtype: str = "uint8",
+) -> None:
+    # Use the first multiscale (most common case)
+    for multiscale in multiscales:
+        if not (axes := multiscale.get("axes")):
+            raise ValueError(
+                f"No axes found in multiscale metadata from {zarr_group.store_path}"
+            )
+        if not (datasets := multiscale.get("datasets")):
+            raise ValueError(
+                f"No datasets found in multiscale metadata from {zarr_group.store_path}"
+            )
+
+        dimension_names = [axis["name"] for axis in axes]
+        shape = (1,) * len(dimension_names)
+        kwargs = {}
+        if zarr_group.metadata.zarr_format >= 3:
+            kwargs.update({"dimension_names": dimension_names})
+
+        # Create arrays for each dataset path
+        for dataset in datasets:
+            if path := dataset.get("path"):
+                zarr_group.create_array(
+                    path,
+                    shape=shape,
+                    dtype=default_dtype,
+                    **kwargs,  # type: ignore[arg-type]
+                )
+
+
+@pytest.mark.parametrize(
+    "version,json_fname",
+    [
+        ("0.4", "multiscales_example.json"),
+        ("0.5", "image_example.json"),
+        ("0.5", "image_label_example.json"),
+        ("0.5", "plate_example_1.json"),
+    ],
+)
+@pytest.mark.parametrize("cmd", ["validate", "info"])
+def test_cli_validate(
+    version: Version,
+    json_fname: str,
+    cmd: str,
+    monkeypatch: pytest.MonkeyPatch,
+    tmp_path: Path,
+    capsys: pytest.CaptureFixture[str],
+) -> None:
+    """Test the CLI commands."""
+
+    zarr_group = json_to_zarr_group(
+        version=version, json_fname=json_fname, store=LocalStore(root=tmp_path)
+    )
+    populate_fake_data(zarr_group)
+    monkeypatch.setattr("sys.argv", ["ome-zarr-models", cmd, str(tmp_path)])
+    main()
+    if cmd == "validate":
+        assert "Valid OME-Zarr" in capsys.readouterr().out
+
+
+@pytest.mark.parametrize("cmd", ["validate", "info"])
+def test_cli_invalid(
+    tmp_path: Path,
+    cmd: str,
+    monkeypatch: pytest.MonkeyPatch,
+    capsys: pytest.CaptureFixture[str],
+) -> None:
+    """Test the CLI with no command."""
+    zarr.create_group(tmp_path)
+    monkeypatch.setattr("sys.argv", ["ome-zarr-models", cmd, str(tmp_path)])
+    with pytest.raises(SystemExit) as excinfo:
+        main()
+    assert excinfo.value.code == 1
+    assert "Invalid OME-Zarr" in capsys.readouterr().out

tests/test_root.py

@@ -25,7 +25,6 @@ def test_load_ome_zarr_group_bad(tmp_path: Path) -> None:
         RuntimeError,
         match=re.escape(
             f"Could not successfully validate <Group file://{tmp_path / 'test'}> "
-            "with any OME-Zarr group models."
         ),
     ):
         open_ome_zarr(hcs_group)