feat(programs): add programs module and database (#243)

Rehome the programs database and related module from pymake. Also create MANIFEST.in referencing data files to include them in the published package.

Metadata creation (code.json) and related capabilities coming separately

Author: wpbonelli

MANIFEST.in

@@ -0,0 +1,2 @@
+include modflow_devtools/programs/*.csv
+include modflow_devtools/registry/*.toml

autotest/test_programs.py

@@ -0,0 +1,34 @@
+import pytest
+
+from modflow_devtools.programs import get_program, get_programs, load_programs
+
+
+def test_load_programs():
+    programs = get_programs()
+    assert isinstance(programs, dict)
+    assert "mf6" in programs
+    mf6 = get_program("mf6")
+    assert mf6 == programs["mf6"]
+    assert isinstance(mf6.version, str)
+    assert isinstance(mf6.current, bool)
+    assert isinstance(mf6.url, str)
+    assert isinstance(mf6.dirname, str)
+    assert isinstance(mf6.srcdir, str)
+    assert isinstance(mf6.standard_switch, bool)
+    assert isinstance(mf6.double_switch, bool)
+    assert isinstance(mf6.shared_object, bool)
+
+
+def test_strict_unrecognized_keys(function_tmpdir):
+    tmp_path = function_tmpdir / "programs.csv"
+    with tmp_path.open("w") as f:
+        f.write(
+            "target,version,current,url,dirname,srcdir,standard_switch,double_switch,shared_object,garbage\n"
+        )
+        f.write(
+            "mf6,6.6.3,True,https://github.com/MODFLOW-ORG/modflow6/releases/download/6.6.3/mf6.6.3_linux.zip,mf6.6.3_linux,src,True,False,False,garbage\n"
+        )
+
+    with pytest.raises(ValueError) as e:
+        load_programs(tmp_path, strict=True)
+        assert "Unrecognized keys in program data: {'unrecognized_key'}" in e.message

docs/md/programs.md

@@ -0,0 +1,13 @@
+# MODFLOW and related programs
+
+The `modflow_devtools.programs` module provides a database of programs in the MODFLOW ecosystem. This has previously been housed in [`pymake`](https://github.com/modflowpy/pymake).
+
+The database is accessible as a dictionary of programs:
+
+```python
+from modflow_devtools.programs import get_programs, get_program
+
+programs = get_programs()
+mf6 = programs["mf6"]
+mf6 = get_program("mf6") # equivalent
+```

modflow_devtools/programs/__init__.py

@@ -0,0 +1,74 @@
+"""Utilities for accessing the program database"""
+
+from csv import DictReader
+from dataclasses import dataclass
+from os import PathLike
+from pathlib import Path
+
+from modflow_devtools.misc import try_literal_eval
+
+DB_NAME = "programs.csv"
+DB_PATH = Path(__file__).parent / DB_NAME
+
+
+@dataclass
+class Program:
+    target: str
+    version: str
+    current: bool
+    url: str
+    dirname: str
+    srcdir: str
+    standard_switch: bool
+    double_switch: bool
+    shared_object: bool
+
+    @classmethod
+    def from_dict(cls, d: dict, strict: bool = False) -> "Program":
+        """
+        Create a Program instance from a dictionary.
+
+        Parameters
+        ----------
+        d : dict
+            Dictionary containing program data
+        strict : bool, optional
+            If True, raise ValueError if dict contains unrecognized keys.
+            If False (default), ignore unrecognized keys.
+        """
+        keys = set(cls.__annotations__.keys())
+        if strict:
+            dkeys = {k.strip() for k in d.keys()}
+            if extra_keys := dkeys - keys:
+                raise ValueError(f"Unrecognized keys in program data: {extra_keys}")
+        return cls(
+            **{
+                k.strip(): try_literal_eval(v.strip())
+                for k, v in d.items()
+                if k.strip() in keys
+            }
+        )
+
+
+def load_programs(path: str | PathLike, strict: bool = False) -> dict[str, Program]:
+    """Load the program database from the CSV file."""
+
+    path = Path(path).expanduser().resolve()
+    with path.open() as csvfile:
+        # assumes the first row is the header!
+        reader = DictReader(csvfile, skipinitialspace=True)
+        programs = [Program.from_dict(row, strict) for row in reader]
+        return {program.target: program for program in programs}
+
+
+PROGRAMS = load_programs(DB_PATH, strict=True)
+
+
+def get_programs() -> dict[str, Program]:
+    """Get the program database."""
+    return PROGRAMS
+
+
+def get_program(name: str) -> Program:
+    """Get a specific program by name."""
+    return PROGRAMS[name]

modflow_devtools/programs/programs.csv

@@ -0,0 +1,26 @@
+target     ,  version    ,  current, url                                                                                           , dirname                  , srcdir              ,    standard_switch, double_switch, shared_object
+mf6        ,  6.6.3      ,  True   , https://github.com/MODFLOW-ORG/modflow6/releases/download/6.6.3/mf6.6.3_linux.zip             , mf6.6.3_linux            , src                 ,    True           , False        , False
+zbud6      ,  6.6.3      ,  True   , https://github.com/MODFLOW-ORG/modflow6/releases/download/6.6.3/mf6.6.3_linux.zip             , mf6.6.3_linux            , utils/zonebudget/src,    True           , False        , False
+libmf6     ,  6.6.3      ,  True   , https://github.com/MODFLOW-ORG/modflow6/releases/download/6.6.3/mf6.6.3_linux.zip             , mf6.6.3_linux            , srcbmi              ,    True           , False        , True
+mp7        ,  7.2.001    ,  True   , https://water.usgs.gov/water-resources/software/MODPATH/modpath_7_2_001.zip                   , modpath_7_2_001          , source              ,    True           , False        , False
+mt3dms     ,  5.3.0      ,  True   , https://github.com/MODFLOW-ORG/mt3dms/releases/download/2.0/mt3dms-2.0.zip                    , mt3dms-2.0               , true-binary         ,    True           , False        , False
+mt3dusgs   ,  1.1.0      ,  True   , https://github.com/MODFLOW-ORG/mt3d-usgs/releases/download/1.1.0/mt3dusgs1.1.0.zip            , mt3dusgs1.1.0            , src                 ,    True           , False        , False
+vs2dt      ,  3.3        ,  True   , https://water.usgs.gov/water-resources/software/VS2DI/vs2dt3_3.zip                            , vs2dt3_3                 , include             ,    True           , False        , False
+triangle   ,  1.6        ,  True   , https://github.com/MODFLOW-ORG/triangle/releases/download/1.0/triangle-1.0.zip                , triangle-1.0             , src                 ,    True           , False        , False
+gridgen    ,  1.0.02     ,  True   , https://github.com/MODFLOW-ORG/gridgen/releases/download/1.0.02/gridgen-1.0.02.zip            , gridgen-1.0.02           , src                 ,    True           , False        , False
+crt        ,  1.3.1      ,  True   , https://water.usgs.gov/ogw/CRT/CRT_1.3.1.zip                                                  , CRT_1.3.1                , SOURCE              ,    True           , False        , False
+sutra      ,  4.0        ,  True   , https://water.usgs.gov/water-resources/software/sutra/4.0/SUTRA_4_0_0.zip                     , SutraSuite               , SUTRA_4_0/source    ,    True           , False        , False
+mf2000     ,  1.19.01    ,  True   , https://water.usgs.gov/nrp/gwsoftware/modflow2000/mf2k1_19_01.tar.gz                          , mf2k.1_19                , src                 ,    True           , False        , False
+mf2005     ,  1.12.00    ,  True   , https://github.com/MODFLOW-ORG/mf2005/releases/download/v.1.12.00/MF2005.1_12u.zip            , MF2005.1_12u             , src                 ,    True           , False        , False
+mfusg      ,  1.5        ,  True   , https://github.com/MODFLOW-ORG/mfusg/releases/download/v1.5.00/mfusg1_5.zip                   , mfusg1_5                 , src                 ,    True           , False        , False
+zonbudusg  ,  1.5        ,  True   , https://github.com/MODFLOW-ORG/mfusg/releases/download/v1.5.00/mfusg1_5.zip                   , mfusg1_5                 , src/zonebudusg      ,    True           , False        , False
+swtv4      ,  4.00.05    ,  True   , https://water.usgs.gov/water-resources/software/SEAWAT/swt_v4_00_05.zip                       , swt_v4_00_05             , source              ,    False          , True         , False
+mp6        ,  6.0.1      ,  True   , https://water.usgs.gov/water-resources/software/MODPATH/modpath.6_0_01.zip                    , modpath.6_0              , src                 ,    True           , False        , False
+mflgr      ,  2.0.0      ,  True   , https://water.usgs.gov/ogw/modflow-lgr/modflow-lgr-v2.0.0/mflgrv2_0_00.zip                    , mflgr.2_0                , src                 ,    True           , False        , False
+zonbud3    ,  3.01       ,  True   , https://water.usgs.gov/water-resources/software/ZONEBUDGET/zonbud3_01.exe                     , Zonbud.3_01              , Src                 ,    True           , False        , False
+mfnwt1.1.4 ,  1.1.4      ,  False  , https://water.usgs.gov/water-resources/software/MODFLOW-NWT/MODFLOW-NWT_1.1.4.zip             , MODFLOW-NWT_1.1.4        , src                 ,    True           , False        , False
+mfnwt      ,  1.3.0      ,  True   , https://water.usgs.gov/water-resources/software/MODFLOW-NWT/MODFLOW-NWT_1.3.0.zip             , MODFLOW-NWT              , src                 ,    True           , False        , False
+mfusg_gsi  ,  2.5.0      ,  True   , https://www.gsienv.com/wp-content/uploads/2025/04/USG_T_Version-2.5.0-2.zip                   , USGT_V2-5-0_Source_Code  , .                   ,    True           , False        , False
+mf6dev     ,  6.7.0.dev3 ,  False  , https://github.com/MODFLOW-ORG/modflow6/archive/refs/heads/develop.zip                        , modflow6-develop         , src                 ,    True           , False        , False
+zbud6dev   ,  6.7.0.dev3 ,  False  , https://github.com/MODFLOW-ORG/modflow6/archive/refs/heads/develop.zip                        , modflow6-develop         , utils/zonebudget/src,    True           , False        , False
+libmf6dev  ,  6.7.0.dev3 ,  False  , https://github.com/MODFLOW-ORG/modflow6/archive/refs/heads/develop.zip                        , modflow6-develop         , srcbmi              ,    True           , False        , True