docs(snapshots): warn about numpy version compatibility (#310)

Snapshots created by the modflow_devtools.snapshots module fixtures may be tied to specific NumPy versions. Warn about this in the docs, and show a warning if a different NumPy version is detected than was used to create the snapshots.

Author: wpbonelli

docs/md/snapshots.md

@@ -22,4 +22,18 @@ Snapshot comparisons can be disabled by invoked `pytest` with the `--snapshot-di
 
 ## Caveats & gotchas
 
-NumPy major versions may introduce changes to `np.save()`'s binary format, causing binary array snapshot failures for arrays with object dtypes. To avoid this, check object (e.g. string) columns explicitly and then omit them from the comparison array.
+### NumPy version compatibility
+
+Snapshot files are tied to the NumPy major version used to generate them. Upgrading NumPy may cause snapshot failures.
+
+- **`array_snapshot` (binary)**: `np.save()` uses `.npy` format version 3.0 in NumPy 2.0+ for arrays whose dtype description cannot be encoded as Latin-1 (e.g. structured arrays with unicode field names). Snapshots generated with NumPy 1.x will not match bytes produced by NumPy 2.x for these arrays. For plain numeric dtypes (`float64`, `int32`, etc.) the format is stable across versions.
+- **`readable_array_snapshot` (text)**: `np.array2string()` array printing is stable across NumPy major versions. However, scalar `__repr__` changed in NumPy 2.0 (e.g. `np.float64(1.1)` instead of `1.1`), which does not affect array element printing but may affect snapshot output if scalars are passed directly rather than as arrays.
+- **`text_array_snapshot` (text)**: `np.savetxt()` output is stable across NumPy versions and is the safest choice when version-portability matters.
+
+As such, snapshot fixtures should ideally be used in a dependency-locked environment. At minimum, NumPy should be pinned, and after upgrading NumPy, all snapshots regenerated:
+
+```shell
+pytest --snapshot-update
+```
+
+To make NumPy version mismatches easier to notice, a warning will be emitted at the start of a test session if the NumPy major version differs from the one used to create the snapshots. This mechanism works by storing a `.numpy_snapshot_version` file in the `__snapshots__` directory. This file should be committed alongside snapshot files.

modflow_devtools/misc.py

@@ -362,8 +362,8 @@ def is_github_rate_limited() -> bool | None:
         return None
 
 
-_has_exe_cache = {}
-_has_pkg_cache = {}
+_has_exe_cache = {}  # type: ignore
+_has_pkg_cache = {}  # type: ignore
 
 
 def has_exe(exe):

modflow_devtools/snapshots.py

@@ -1,4 +1,6 @@
+import warnings
 from io import BytesIO, StringIO
+from pathlib import Path
 from typing import Optional, Union
 
 from modflow_devtools.imports import import_optional_dependency
@@ -137,6 +139,47 @@ def readable_array_snapshot(snapshot, snapshot_disable):
 
 # pytest config hooks
 
+_NUMPY_VERSION_FILENAME = ".numpy_snapshot_version"
+
+
+def _find_snapshot_dirs(rootdir: Path) -> list:
+    return [p for p in rootdir.rglob("__snapshots__") if p.is_dir()]
+
+
+def pytest_sessionstart(session):
+    if np is None:
+        return
+    current_major = int(np.__version__.split(".")[0])
+    rootdir = Path(session.config.rootdir)
+    for snap_dir in _find_snapshot_dirs(rootdir):
+        version_file = snap_dir / _NUMPY_VERSION_FILENAME
+        if not version_file.exists():
+            continue
+        stored = version_file.read_text().strip()
+        try:
+            stored_major = int(stored.split(".")[0])
+        except (ValueError, IndexError):
+            continue
+        if stored_major != current_major:
+            warnings.warn(
+                f"NumPy major version changed from {stored_major} to {current_major}. "
+                "Array snapshots may no longer match. "
+                "Regenerate them with: pytest --snapshot-update",
+                UserWarning,
+                stacklevel=2,
+            )
+            break
+
+
+def pytest_sessionfinish(session, exitstatus):
+    if np is None:
+        return
+    if not getattr(session.config.option, "update_snapshots", False):
+        return
+    rootdir = Path(session.config.rootdir)
+    for snap_dir in _find_snapshot_dirs(rootdir):
+        (snap_dir / _NUMPY_VERSION_FILENAME).write_text(np.__version__ + "\n")
+
 
 def pytest_addoption(parser):
     parser.addoption(