Make isschecker a package

[xylar]

Package the compliance checker so it installs cleanly and runs from anywhere

Summary

The checker was a standalone script that had to be run from the repository root, because it resolved its criteria CSVs relative to the working directory. This PR turns it into an installed package — ismip7-compliance-checker on the PATH, criteria and grid definitions bundled as package data, no assumptions about where it is run from — and then does the work that makes that safe to hand to ice sheet modelers: bounded dependency versions, an install that cannot silently pull from PyPI, and CI that tests the package it ships rather than the source tree.

The conversion itself is @aaschwanden's work (#9). This PR carries his commits and replaces the earlier PR for it, adding the version constraints, the packaging fixes that only surface once the checker really is run from elsewhere, and the tests to keep them fixed.

The requirement driving the rest is that a modeler running the checker on their own machine and OS should get the same answer we do from the same files. That is now tested rather than intended: the log produced under python 3.11 / numpy 2.1 / pandas 2.2 / xarray 2025.1.2 is byte-identical to the log produced under python 3.14 / numpy 2.5 / pandas 3.0 / xarray 2026.7.

What changes for users

	Before	After
Install	conda env create -f isschecker_env.yml	same, then python -m pip install --no-deps --no-build-isolation .
Run the checker	python compliance_checker.py ..., from the repository root only	ismip7-compliance-checker ... (or python -m isschecker ...), from any directory
Generate test files	python generate/generate_test_files.py ...	ismip7-generate-test-files ...
Import name	import compliance_checker	import isschecker
Criteria files	conventions/ISMIP7_variable_request.csv, experiments_ismip7.csv, read relative to the working directory	bundled package data under isschecker/data/, found wherever the package is installed
Log provenance line	Commit Number: <git log in your working directory>	isschecker version: 0.1.0

Deliberately unchanged, because modelers depend on them: the ismip7-compliance-checker command name, the compliance_checker_log.txt filename and its contents, and all check logic. The version is not bumped — no version of this software has ever been tagged, so 0.1.0 still stands.

The package

compliance_checker.py becomes isschecker/checker.py with a thin __init__.py re-exporting main, run_checker and __version__, plus a __main__.py so python -m isschecker works. The criteria CSVs and the grid definitions move into isschecker/data/ and are located with importlib.resources, which is what frees the checker from the working directory. pyproject.toml declares two console scripts, ismip7-compliance-checker and ismip7-generate-test-files.

The import package is isschecker, matching the distribution name rather than the compliance_checker the script grew up as. That is not just tidiness: compliance_checker is precisely the import name of IOOS compliance-checker, a CF/ACDD netCDF compliance tool published on both conda-forge and PyPI and squarely in our users' domain. Installing both in one environment would give whichever came first on the path.

The test-file generator moves into the package too (isschecker/generate.py, with the grid definitions as package data). It is a test dependency, and while it sat outside the package the suite loaded it by file path after inserting the repository root into sys.path — which meant the tests exercised the source tree no matter what was installed, and is exactly what let the defects listed below go unnoticed. As a bonus, modelers now get the generator, which is useful for producing sample output.

Dependency constraints

isschecker_env.yml previously pinned every package to an exact version, which is unmaintainable and eventually fails to solve on some platforms; the conversion commit dropped constraints entirely, which reproduces nothing. It now carries bounded ranges, and CI verifies both ends of every one of them.

Package	Constraint	Why
python	>=3.11,<3.15	str | None annotations need 3.10; 3.10 is EOL in Oct 2026
numpy	>=2.1,<3	what recent pandas and xarray are built against
pandas	>=2.2,<4	reads the criteria CSVs; 3.0 changed the default string dtype, so both lines are exercised
xarray	>=2025.1.2,<2027	hard requirement: xarray.coders.CFDatetimeCoder, which the time checks use, only became public API in 2025.01.1 (the release that deprecated bare use_cftime); 2025.01.2 added the non-nanosecond datetime decoding the code is written against
cftime	>=1.6.4,<2	date arithmetic in the start/end/duration checks
netCDF4	>=1.7,<2	_FillValue checks compare against netCDF4.default_fillvals
tqdm	>=4.66	progress bar only; never reaches the log

Upper bounds exclude the next major — or, for xarray's CalVer, the next year — so raising a ceiling is a deliberate act with a CI run behind it. That is the release line that bit us before, via the use_cftime deprecation.

Two additions that have nothing to do with versions but everything to do with reproducibility: nodefaults in the channel list, so a modeler whose ~/.condarc includes defaults cannot silently solve against different builds; and setuptools, which conda-forge python no longer vendors and without which the documented install fails outright.

pyproject.toml mirrors these ranges exactly. Every dependency is on PyPI, so nothing had to be dropped from the metadata. It also gains PEP 639 license metadata, project URLs, and a requires-python that matches the environment file.

Install instructions

pip install . is the wrong instruction for a conda environment: pip is free to satisfy dependencies from PyPI, and a PyPI netCDF4 wheel brings its own copy of the netCDF C library, which is a direct route to two people getting different results from the same files. Build isolation is a second, independent path to PyPI, since it downloads a build backend even when nothing else needs fetching. The README documents python -m pip install --no-deps --no-build-isolation ., explains why, and mentions --no-index for anyone who wants a hard failure on any network access. The dependency table above is in the README as well, so the docs and the environment file cannot drift apart.

Defects fixed along the way

Each of these is invisible while the checker is run from its own checkout, and breaks the moment it is not:

• python -m compliance_checker was documented but raised. The conversion deleted the if __name__ == "__main__" block without adding a __main__.py.
• The log's provenance line described the wrong thing. _get_commit_number() ran git log in the process's working directory, so a modeler running the checker from their data directory would get the commit of whatever unrelated repository they happened to be standing in, or a placeholder. The header now reports the installed version, with the git commit appended only when running from a checkout. Incidentally, the old --pretty=format:'%h' was passed through str.split(), so the shell quotes survived into the recorded string.
• The generator wrote into site-packages. create_netcdf_file defaulted its output to Path(__file__).parent.parent / 'Models', which for an installed package is a Models directory inside site-packages. It now defaults to ./Models, matching the checker's own --source-path default.
• get_available_grids ignored its conventions_dir argument, always reading a hard-coded repository path, so --conventions-dir silently did nothing for grids.
• All 1516 lines lived in __init__.py, so importing the package pulled in the whole CLI.
• isschecker/data/ had no __init__.py, so it resolved as a namespace package and importlib.resources.files() returned a MultiplexedPath spanning every same-named portion on the path.
• Synthetic test data was unseeded, using the legacy global np.random. Every run produced different values — the wrong default for this project, and one unlucky draw away from a value close enough to a min/max bound to flip a numerical check. Now drawn from a seeded np.random.Generator, with --seed.

Also added: --version, so there is something exact to quote in a problem report.

Testing

CI previously created the environment and ran pytest from the checkout, never installing the package; combined with the sys.path insertion in the tests, it tested the source tree. Every defect above would have passed it indefinitely. CI now installs with the same flags the README gives modelers, and runs the entry-point smoke checks and pytest from runner.temp, outside the checkout, so the tests import what was installed. The matrix covers {ubuntu, macos} × {latest ranges, pinned floors from ci/isschecker_env_floor.yml}, which is what makes both ends of every range verified rather than asserted. Environment caching is enabled only for the floor job, since caching the "latest" solve would hide the day a new release breaks the open end of a range — the thing that job exists to catch.

New in tests/test_golden_log.py: the checker runs over a fixed, seeded dataset (27 files, scalars and x,y,t, all five check categories) and its log is compared line by line against a stored reference, with the version, date, and source path masked out. This is what turns "results should agree across machines" into something CI can check, and it is the payoff for seeding the generator — without fixed input data there is nothing stable to compare. When a change is meant to change the log, ISSCHECKER_UPDATE_GOLDEN_LOG=1 pytest tests/test_golden_log.py regenerates the reference for review alongside it.

Verification

• Both ends of every range were solved and the suite run in each: floor (python 3.11.15, numpy 2.1.3, pandas 2.2.3, xarray 2025.1.2, cftime 1.6.4, netCDF4 1.7.4, tqdm 4.66.6) and latest (python 3.14.6, numpy 2.5.1, pandas 3.0.3, xarray 2026.7.0, cftime 1.6.5, netCDF4 1.7.4, tqdm 4.69.0). 7 passed in both, run from outside the checkout against the installed package.
• Those two environments produce identical logs, which is the reproducibility claim this PR exists to support.
• End to end from an empty directory with no checkout in sight: ismip7-generate-test-files wrote files under ./Models, and ismip7-compliance-checker reported no errors with the version in the log header.
• The golden test is not vacuous: reinstalling with a single log message reworded fails with exactly that diff.
• The CI arrangement earns its keep: with the criteria CSV temporarily resolved relative to the working directory — the bug class this conversion exists to eliminate — pytest from the checkout reports 6 passed while pytest from a temporary directory reports 6 errors.
• The wheel builds with no setuptools deprecation warnings, carries License-Expression: MIT and the six Requires-Dist lines, and bundles the criteria CSVs and grid definitions.

Not verified: the workflow file itself, which can only run on push; in particular, whether the floor pins solve on macos-arm64 is untested. I also did not install IOOS compliance-checker alongside ours to demonstrate the collision, since it would drag conflicting pins into the environment; the fix is verified structurally instead (top_level.txt is isschecker, and import compliance_checker now raises).

Notes for review

• One gotcha worth knowing while reviewing locally: setuptools reuses a stale build/ directory, so after the rename an install can keep resolving import compliance_checker from files that no longer exist in the tree. rm -rf build fixes it; the README says so.
• The tests import the installed package, so during development use the editable install (-e) or edits will not affect a test run until you reinstall.
• Each commit is independently reviewable and leaves the suite green; the commit messages carry the per-change rationale and verification.
• Follow-up worth doing separately: publish isschecker on conda-forge so modelers can conda create -n isschecker isschecker=X.Y and skip the pip step entirely. That, with a tag, is the real fix for cross-machine reproducibility; the ranges here are the best available substitute until then.

Closes #9

[xylar]

@hgoelzer, as nice as it would be to have your review, I'm going to go ahead with this since you're away.

@aaschwanden, thanks for getting the ball rolling!