Merge pull request #66 from climate-resource/42-html-errors-output

Add support dumping caught errors as HTML

changelog/66.deprecation.md

@@ -0,0 +1,6 @@
+Deprecated
+[`validate_database_file_entry`][input4mips_validation.validation.database.validate_database_file_entry],
+[`validate_ds_to_write_to_disk`][input4mips_validation.validation.datasets_to_write_to_disk.validate_ds_to_write_to_disk],
+[`validate_file`][input4mips_validation.validation.file.validate_file]
+and [`validate_tree`][input4mips_validation.validation.tree.validate_tree].
+See the docs for each function and deprecation warnings for recommended alternatives.

changelog/66.feature.md

@@ -0,0 +1,3 @@
+Added the `--output-html` flag to `input4mips-validation validate-tree`.
+This allows you to output the results of the validation as HTML,
+which provides easier exploration of the failures.

docs/gen_doc_stubs.py

@@ -27,6 +27,7 @@
     "cvs": "CVs",
     "drs": "DRS",
     "upload_ftp": "Upload FTP",
+    "datasets_to_write_to_disk": "Datasets to write to disk",
     "input4mips_validation": "input4mips_validation",
 }
 

mkdocs.yml

@@ -100,6 +100,7 @@ plugins:
 
 markdown_extensions:
   - attr_list
+  - pymdownx.blocks.admonition
   # Code highlighting handiness
   - pymdownx.highlight:
       anchor_linenums: true

pyproject.toml

@@ -66,6 +66,7 @@ tests = [
     "pytest>=8.2.2",
     "coverage>=7.6.0",
     "pytest-cov>=5.0.0",
+    "pytest-regressions>=2.5",
 ]
 
 [project.scripts]

src/input4mips_validation/cli/__init__.py

@@ -29,12 +29,8 @@
 from input4mips_validation.inference.from_data import infer_time_start_time_end
 from input4mips_validation.logging import setup_logging
 from input4mips_validation.upload_ftp import upload_ftp
-from input4mips_validation.validation import (
-    InvalidFileError,
-    InvalidTreeError,
-    validate_file,
-    validate_tree,
-)
+from input4mips_validation.validation.file import get_validate_file_result
+from input4mips_validation.validation.tree import get_validate_tree_result
 from input4mips_validation.xarray_helpers.iris import ds_from_iris_cubes
 
 app = typer.Typer()
@@ -157,16 +153,11 @@ def validate_file_command(  # noqa: PLR0913
     because some validation can only be performed if we have the entire file tree.
     See the ``validate-tree`` command for this validation.
     """
-    try:
-        validate_file(
-            file,
-            cv_source=cv_source,
-            allow_cf_checker_warnings=allow_cf_checker_warnings,
-        )
-    except InvalidFileError as exc:
-        logger.debug(f"{type(exc).__name__}: {exc}")
-
-        raise typer.Exit(code=1) from exc
+    get_validate_file_result(
+        file,
+        cv_source=cv_source,
+        allow_cf_checker_warnings=allow_cf_checker_warnings,
+    ).raise_if_errors()
 
     if write_in_drs:
         cvs = load_cvs(cv_source=cv_source)
@@ -229,27 +220,34 @@ def validate_tree_command(  # noqa: PLR0913
     time_dimension: TIME_DIMENSION_OPTION = "time",
     rglob_input: RGLOB_INPUT_OPTION = "*.nc",
     allow_cf_checker_warnings: ALLOW_CF_CHECKER_WARNINGS_TYPE = False,
+    output_html: Annotated[
+        Optional[Path],
+        typer.Option(
+            "--output-html", help="Output the result as HTML to this file too."
+        ),
+    ] = None,
 ) -> None:
     """
     Validate a tree of files
 
     This checks things like whether all external variables are also provided
     and all tracking IDs are unique.
     """
-    try:
-        validate_tree(
-            root=tree_root,
-            cv_source=cv_source,
-            frequency_metadata_key=frequency_metadata_key,
-            no_time_axis_frequency=no_time_axis_frequency,
-            time_dimension=time_dimension,
-            rglob_input=rglob_input,
-            allow_cf_checker_warnings=allow_cf_checker_warnings,
-        )
-    except InvalidTreeError as exc:
-        logger.debug(f"{type(exc).__name__}: {exc}")
+    vtrs = get_validate_tree_result(
+        root=tree_root,
+        cv_source=cv_source,
+        frequency_metadata_key=frequency_metadata_key,
+        no_time_axis_frequency=no_time_axis_frequency,
+        time_dimension=time_dimension,
+        rglob_input=rglob_input,
+        allow_cf_checker_warnings=allow_cf_checker_warnings,
+    )
+
+    if output_html is not None:
+        with open(output_html, "w") as fh:
+            fh.write(vtrs.to_html())
 
-        raise typer.Exit(code=1) from exc
+    vtrs.raise_if_errors()
 
 
 @app.command(name="upload-ftp")

src/input4mips_validation/deprecation.py

@@ -0,0 +1,33 @@
+"""
+Deprecation support
+"""
+
+from __future__ import annotations
+
+import warnings
+
+
+def raise_deprecation_warning(
+    name: str, removed_in: str, use_instead: str, stacklevel: int = 3
+) -> None:
+    """
+    Raise a deprecation warning
+
+    Parameters
+    ----------
+    name
+        Name of the callable being deprecated
+
+    removed_in
+        Version in which the callable will be removed
+
+    use_instead
+        Instructions on what to use instead of the deprecated callable
+
+    stacklevel
+        Stack level to show with the warning
+    """
+    message = (
+        f"{name} will be removed in {removed_in}. Instead, please use {use_instead}."
+    )
+    warnings.warn(message, DeprecationWarning, stacklevel=stacklevel)

src/input4mips_validation/io.py

@@ -16,7 +16,7 @@
 from input4mips_validation.cvs import Input4MIPsCVs
 from input4mips_validation.validation.creation_date import CREATION_DATE_FORMAT
 from input4mips_validation.validation.datasets_to_write_to_disk import (
-    validate_ds_to_write_to_disk,
+    get_ds_to_write_to_disk_validation_result,
 )
 
 iris.FUTURE.save_split_attrs = True
@@ -60,7 +60,10 @@ def write_ds_to_disk(
     # As part of https://github.com/climate-resource/input4mips_validation/issues/14
     # add final validation here for bullet proofness
     # - tracking ID, creation date, comparison with DRS from cvs etc.
-    validate_ds_to_write_to_disk(ds=ds, out_path=out_path, cvs=cvs)
+    validation_result = get_ds_to_write_to_disk_validation_result(
+        ds=ds, out_path=out_path, cvs=cvs
+    )
+    validation_result.raise_if_errors()
 
     # Having validated, make the target directory and write
     out_path.parent.mkdir(parents=True, exist_ok=True)