first test for data inventory

.ci_helpers/check_test_data_inventory.py

@@ -0,0 +1,131 @@
+#!/usr/bin/env python3
+"""Validate the test data inventory against the Pooch test-data bundles."""
+
+from __future__ import annotations
+
+import ast
+import sys
+from pathlib import Path
+
+import yaml
+
+ROOT = Path(__file__).resolve().parents[1]
+
+CONFTST = ROOT / "echopype" / "tests" / "conftest.py"
+INVENTORY = ROOT / "docs" / "source" / "test_data_inventory.yml"
+
+
+REQUIRED_BUNDLE_KEYS = {
+    "documented_checksum",
+    "instrument",
+    "description",
+    "source",
+    "contributor",
+    "references",
+    "notes",
+    "files",
+}
+
+REQUIRED_FILE_KEYS = {
+    "instrument",
+    "description",
+    "source",
+    "contributor",
+    "references",
+    "notes",
+}
+
+
+def load_conftest_bundles_and_registry():
+    source = CONFTST.read_text(encoding="utf-8")
+    tree = ast.parse(source)
+
+    bundles = None
+    registry = None
+
+    for node in ast.walk(tree):
+        if not isinstance(node, ast.Assign):
+            continue
+
+        for target in node.targets:
+            if isinstance(target, ast.Name) and target.id == "bundles":
+                bundles = ast.literal_eval(node.value)
+            elif isinstance(target, ast.Name) and target.id == "registry":
+                registry = ast.literal_eval(node.value)
+
+    if bundles is None:
+        raise RuntimeError(f"Could not find 'bundles' in {CONFTST}")
+
+    if registry is None:
+        raise RuntimeError(f"Could not find 'registry' in {CONFTST}")
+
+    return bundles, registry
+
+
+def load_inventory():
+    with INVENTORY.open(encoding="utf-8") as f:
+        return yaml.safe_load(f)
+
+
+def main():
+    bundles, registry = load_conftest_bundles_and_registry()
+    inventory = load_inventory()
+
+    errors = []
+
+    conftest_bundles = set(bundles)
+    inventory_bundles = set(inventory)
+
+    missing = sorted(conftest_bundles - inventory_bundles)
+    if missing:
+        errors.append(
+            "Bundles listed in conftest.py but missing from inventory:\n  - "
+            + "\n  - ".join(missing)
+        )
+
+    extra = sorted(inventory_bundles - conftest_bundles)
+    if extra:
+        errors.append(
+            "Bundles listed in inventory but not in conftest.py:\n  - " + "\n  - ".join(extra)
+        )
+
+    for bundle in sorted(conftest_bundles & inventory_bundles):
+        metadata = inventory[bundle]
+
+        missing_keys = REQUIRED_BUNDLE_KEYS - set(metadata)
+        if missing_keys:
+            errors.append(
+                f"{bundle}: missing required bundle keys: " + ", ".join(sorted(missing_keys))
+            )
+
+        checksum = metadata.get("documented_checksum")
+        if checksum is not None and checksum != registry[bundle]:
+            errors.append(
+                f"{bundle}: documented_checksum does not match conftest.py registry\n"
+                f"  inventory: {checksum}\n"
+                f"  registry:  {registry[bundle]}"
+            )
+
+        files = metadata.get("files", {})
+        if files is None:
+            errors.append(f"{bundle}: files must be a mapping, not null")
+            continue
+
+        for filename, file_metadata in files.items():
+            missing_file_keys = REQUIRED_FILE_KEYS - set(file_metadata)
+            if missing_file_keys:
+                errors.append(
+                    f"{bundle} / {filename}: missing required file keys: "
+                    + ", ".join(sorted(missing_file_keys))
+                )
+
+    if errors:
+        print("\nTEST DATA INVENTORY CHECK FAILED\n")
+        print("\n\n".join(errors))
+        sys.exit(1)
+
+    print("Test data inventory is valid.")
+
+
+if __name__ == "__main__":
+    main()

docs/source/_config.yml

@@ -45,7 +45,8 @@ sphinx:
     'sphinx.ext.mathjax',
     'sphinx.ext.ifconfig',
     'sphinx.ext.githubpages',
-    'sphinxcontrib.mermaid'
+    'sphinxcontrib.mermaid',
+    'test_data_inventory_ext',
   ]
   config:
     bibtex_reference_style: label

docs/source/_toc.yml

@@ -30,6 +30,7 @@ parts:
   - file: contrib_roadmap
   - file: contrib_howto
   - file: contrib_setup
+  - file: test_data_inventory
 - caption: Help & references
   chapters:
   - file: whats-new

docs/source/contrib_test_data.md

@@ -0,0 +1,44 @@
+(contrib:test-data)=
+
+# Test data inventory
+
+echopype uses a collection of test data bundles to support unit and integration tests across different sonar models and file formats. These bundles are distributed through GitHub release assets and downloaded automatically using Pooch during testing.
+
+The test data inventory is maintained in:
+
+```text
+docs/source/test_data_inventory.yml
+```
+
+This inventory serves as the central metadata registry for the test data bundles currently used by the test suite. It includes, when available:
+
+* instrument type,
+* file descriptions,
+* data source,
+* contributor,
+* references,
+* additional notes.
+
+The inventory is validated in CI against the list of test data bundles declared in the test suite (`echopype/tests/conftest.py`). When a new test data bundle is added, the inventory should be updated accordingly.
+
+## Inventory fields
+
+| Field                 | Description                                                                     |
+| :-------------------- | :------------------------------------------------------------------------------ |
+| `documented_checksum` | SHA256 checksum of the bundle version for which the metadata has been reviewed. |
+| `instrument`          | Sonar or instrument type, when known.                                           |
+| `description`         | Short description of the bundle or file.                                        |
+| `source`              | Origin of the dataset, when known.                                              |
+| `contributor`         | Contributor or data provider, when known.                                       |
+| `references`          | Related publications, documentation, or external resources.                     |
+| `notes`               | Additional information or context.                                              |
+| `files`               | Metadata for individual files contained in the bundle.                          |
+
+## Adding a new test data bundle
+
+When adding a new test data bundle:
+
+1. Add the bundle to the Pooch registry in `echopype/tests/conftest.py`.
+2. Add a corresponding entry to `docs/source/test_data_inventory.yml`.
+3. Populate the available metadata fields as completely as possible.
+4. If the bundle metadata has been reviewed, update `documented_checksum` to match the bundle checksum in the Pooch registry.