modflow-devtools 1.7.0__tar.gz → 1.9.0__tar.gz

{modflow_devtools-1.7.0 → modflow_devtools-1.9.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: modflow-devtools
-Version: 1.7.0
+Version: 1.9.0
 Summary: Python tools for MODFLOW development
 Project-URL: Documentation, https://modflow-devtools.readthedocs.io/en/latest/
 Project-URL: Bug Tracker, https://github.com/MODFLOW-ORG/modflow-devtools/issues
@@ -37,6 +37,7 @@ Requires-Dist: ninja; extra == 'dev'
 Requires-Dist: numpy; extra == 'dev'
 Requires-Dist: pandas; extra == 'dev'
 Requires-Dist: pooch; extra == 'dev'
+Requires-Dist: pydantic; extra == 'dev'
 Requires-Dist: pytest!=8.1.0; extra == 'dev'
 Requires-Dist: pytest-cov; extra == 'dev'
 Requires-Dist: pytest-dotenv; extra == 'dev'
@@ -45,17 +46,26 @@ Requires-Dist: pyyaml; extra == 'dev'
 Requires-Dist: ruff; extra == 'dev'
 Requires-Dist: sphinx; extra == 'dev'
 Requires-Dist: sphinx-rtd-theme; extra == 'dev'
-Requires-Dist: syrupy; extra == 'dev'
+Requires-Dist: syrupy<5.0.0; extra == 'dev'
 Requires-Dist: tomli; extra == 'dev'
 Requires-Dist: tomli-w; extra == 'dev'
 Provides-Extra: dfn
 Requires-Dist: boltons; extra == 'dfn'
+Requires-Dist: pooch; extra == 'dfn'
+Requires-Dist: pydantic; extra == 'dfn'
 Requires-Dist: tomli; extra == 'dfn'
 Requires-Dist: tomli-w; extra == 'dfn'
 Provides-Extra: docs
 Requires-Dist: myst-parser; extra == 'docs'
 Requires-Dist: sphinx; extra == 'docs'
 Requires-Dist: sphinx-rtd-theme; extra == 'docs'
+Provides-Extra: ecosystem
+Requires-Dist: boltons; extra == 'ecosystem'
+Requires-Dist: filelock; extra == 'ecosystem'
+Requires-Dist: pooch; extra == 'ecosystem'
+Requires-Dist: pydantic; extra == 'ecosystem'
+Requires-Dist: tomli; extra == 'ecosystem'
+Requires-Dist: tomli-w; extra == 'ecosystem'
 Provides-Extra: lint
 Requires-Dist: codespell[toml]; extra == 'lint'
 Requires-Dist: mypy; extra == 'lint'
@@ -64,6 +74,7 @@ Provides-Extra: models
 Requires-Dist: boltons; extra == 'models'
 Requires-Dist: filelock; extra == 'models'
 Requires-Dist: pooch; extra == 'models'
+Requires-Dist: pydantic; extra == 'models'
 Requires-Dist: tomli; extra == 'models'
 Requires-Dist: tomli-w; extra == 'models'
 Provides-Extra: test
@@ -82,7 +93,7 @@ Requires-Dist: pytest-dotenv; extra == 'test'
 Requires-Dist: pytest-xdist; extra == 'test'
 Requires-Dist: pyyaml; extra == 'test'
 Requires-Dist: ruff; extra == 'test'
-Requires-Dist: syrupy; extra == 'test'
+Requires-Dist: syrupy<5.0.0; extra == 'test'
 Description-Content-Type: text/markdown
 
 # MODFLOW developer tools
@@ -130,11 +141,10 @@ Python development tools for MODFLOW 6 and related projects.
 
 Python3.10+, dependency-free by default.
 
-Several optional dependency groups are available, oriented around specific use cases:
+Two main dependency groups are available, oriented around specific use cases:
 
-- `dfn`: MF6 definition file parsing
-- `test`: pytest fixtures/extensions
-- `models`: example model access
+- `test`: pytest fixtures, markers, and extensions
+- `ecosystem`: program/model management, definition file utilities
 
 ## Installation
 

{modflow_devtools-1.7.0 → modflow_devtools-1.9.0}/README.md

@@ -43,11 +43,10 @@ Python development tools for MODFLOW 6 and related projects.
 
 Python3.10+, dependency-free by default.
 
-Several optional dependency groups are available, oriented around specific use cases:
+Two main dependency groups are available, oriented around specific use cases:
 
-- `dfn`: MF6 definition file parsing
-- `test`: pytest fixtures/extensions
-- `models`: example model access
+- `test`: pytest fixtures, markers, and extensions
+- `ecosystem`: program/model management, definition file utilities
 
 ## Installation
 

{modflow_devtools-1.7.0 → modflow_devtools-1.9.0}/modflow_devtools/__init__.py

@@ -1,6 +1,6 @@
 __author__ = "Joseph D. Hughes"
-__date__ = "Jun 23, 2025"
-__version__ = "1.7.0"
+__date__ = "Feb 25, 2026"
+__version__ = "1.9.0"
 __maintainer__ = "Joseph D. Hughes"
 __email__ = "jdhughes@usgs.gov"
 __status__ = "Production"

modflow_devtools-1.9.0/modflow_devtools/cli.py

@@ -0,0 +1,63 @@
+"""
+Root CLI for modflow-devtools.
+
+Usage:
+    mf models sync
+    mf models info
+    mf models list
+    mf models copy <model> <workspace>
+    mf models cp <model> <workspace>  # cp is an alias for copy
+    mf programs sync
+    mf programs info
+    mf programs list
+    mf programs install <program>
+    mf programs uninstall <program>
+    mf programs history
+"""
+
+import argparse
+import sys
+
+
+def main():
+    """Main entry point for the mf CLI."""
+    parser = argparse.ArgumentParser(
+        prog="mf",
+        description="MODFLOW development tools",
+    )
+    subparsers = parser.add_subparsers(dest="subcommand", help="Available commands")
+
+    # Models subcommand
+    subparsers.add_parser("models", help="Manage MODFLOW model registries")
+
+    # Programs subcommand
+    subparsers.add_parser("programs", help="Manage MODFLOW program registries")
+
+    # Parse only the first level to determine which submodule to invoke
+    args, remaining = parser.parse_known_args()
+
+    if not args.subcommand:
+        parser.print_help()
+        sys.exit(1)
+
+    # Dispatch to the appropriate module CLI with remaining args
+    if args.subcommand == "models":
+        from modflow_devtools.models.__main__ import main as models_main
+
+        # Replace sys.argv to make it look like we called the submodule directly
+        sys.argv = ["mf models", *remaining]
+        models_main()
+    elif args.subcommand == "programs":
+        import warnings
+
+        # Suppress experimental warning for official CLI
+        with warnings.catch_warnings():
+            warnings.filterwarnings("ignore", message=".*modflow_devtools.programs.*experimental.*")
+            from modflow_devtools.programs.__main__ import main as programs_main
+
+        sys.argv = ["mf programs", *remaining]
+        programs_main()
+
+
+if __name__ == "__main__":
+    main()

{modflow_devtools-1.7.0 → modflow_devtools-1.9.0}/modflow_devtools/dfn.py

@@ -185,6 +185,29 @@ class Dfn(TypedDict):
     `str` to `Field`, and metadata, of which only a
     limited set of keys are allowed. Block names and
     metadata keys may not overlap.
+
+    Attributes
+    ----------
+    name : str
+        Component name.
+    advanced : bool
+        Whether this is an advanced package.
+    multi : bool
+        Whether this is a multi-package.
+    ref : Ref | None
+        Metadata if this component is a subpackage (child's perspective).
+        Populated from: # flopy subpackage <key> <abbr> <param> <val>
+    sln : Sln | None
+        Solution package metadata.
+    fkeys : Dfns | None
+        Field-level foreign key references to other components.
+        Maps field names to Ref objects. Populated from flopy subpackage
+        metadata when specific fields reference other components.
+    subcomponents : list[str] | None
+        Allowed child component types (schema-level constraint).
+        Populated from: # mf6 subpackage <abbr>
+        Example: ['UTL-NCF'] means this component can have utl-ncf children.
+        Distinct from fkeys, which are field-level references.
     """
 
     name: str
@@ -193,6 +216,7 @@ class Dfn(TypedDict):
     ref: Ref | None = None
     sln: Sln | None = None
     fkeys: Dfns | None = None
+    subcomponents: list[str] | None = None
 
     @staticmethod
     def _load_v1_flat(f, common: dict | None = None) -> tuple[Mapping, list[str]]:
@@ -220,6 +244,11 @@ class Dfn(TypedDict):
                 _, sep, tail = line.partition("package-type")
                 if sep == "package-type":
                     meta.append(f"package-type {tail.strip()}")
+                # Parse mf6 subpackage declarations (schema-level composition constraints).
+                # Distinct from flopy subpackage (field-level foreign keys, parsed above).
+                _, sep, tail = line.partition("mf6 subpackage")
+                if sep == "mf6 subpackage":
+                    meta.append(f"mf6-subpackage {tail.strip()}")
                 continue
 
             # if we hit a newline and the parameter dict
@@ -249,16 +278,11 @@ class Dfn(TypedDict):
                     subs = literal_eval(subs)
                     cmmn = common.get(key, None)
                     if cmmn is None:
-                        warn(
-                            "Can't substitute description text, "
-                            f"common variable not found: {key}"
-                        )
+                        warn(f"Can't substitute description text, common variable not found: {key}")
                     else:
                         descr = cmmn.get("description", "")
                         if any(subs):
-                            descr = descr.replace("\\", "").replace(
-                                "{#1}", subs["{#1}"]
-                            )
+                            descr = descr.replace("\\", "").replace("{#1}", subs["{#1}"])
                 field["description"] = descr
 
         # add the final parameter
@@ -331,8 +355,7 @@ class Dfn(TypedDict):
 
                     # explicit record
                     if n_item_names == 1 and (
-                        item_types[0].startswith("record")
-                        or item_types[0].startswith("keystring")
+                        item_types[0].startswith("record") or item_types[0].startswith("keystring")
                     ):
                         return _convert_field(next(iter(flat.getlist(item_names[0]))))
 
@@ -343,9 +366,7 @@ class Dfn(TypedDict):
                             type="record",
                             block=block,
                             fields=_fields(),
-                            description=description.replace(
-                                "is the list of", "is the record of"
-                            ),
+                            description=description.replace("is the list of", "is the record of"),
                             reader=reader,
                             **field,
                         )
@@ -358,19 +379,13 @@ class Dfn(TypedDict):
                     }
                     first = next(iter(fields.values()))
                     single = len(fields) == 1
-                    item_type = (
-                        "keystring"
-                        if single and "keystring" in first["type"]
-                        else "record"
-                    )
+                    item_type = "keystring" if single and "keystring" in first["type"] else "record"
                     return Field(
                         name=first["name"] if single else _name,
                         type=item_type,
                         block=block,
                         fields=first["fields"] if single else fields,
-                        description=description.replace(
-                            "is the list of", f"is the {item_type} of"
-                        ),
+                        description=description.replace("is the list of", f"is the {item_type} of"),
                         reader=reader,
                         **field,
                     )
@@ -390,11 +405,7 @@ class Dfn(TypedDict):
                     fields = {}
                     for name in names:
                         v = flat.get(name, None)
-                        if (
-                            not v
-                            or not v.get("in_record", False)
-                            or v["type"].startswith("record")
-                        ):
+                        if not v or not v.get("in_record", False) or v["type"].startswith("record"):
                             continue
                         fields[name] = v
                     return fields
@@ -490,11 +501,7 @@ class Dfn(TypedDict):
 
         def _sln() -> Sln | None:
             sln = next(
-                iter(
-                    m
-                    for m in meta
-                    if isinstance(m, str) and m.startswith("solution_package")
-                ),
+                iter(m for m in meta if isinstance(m, str) and m.startswith("solution_package")),
                 None,
             )
             if sln:
@@ -505,9 +512,7 @@ class Dfn(TypedDict):
         def _sub() -> Ref | None:
             def _parent():
                 line = next(
-                    iter(
-                        m for m in meta if isinstance(m, str) and m.startswith("parent")
-                    ),
+                    iter(m for m in meta if isinstance(m, str) and m.startswith("parent")),
                     None,
                 )
                 if not line:
@@ -517,9 +522,7 @@ class Dfn(TypedDict):
 
             def _rest():
                 line = next(
-                    iter(
-                        m for m in meta if isinstance(m, str) and m.startswith("subpac")
-                    ),
+                    iter(m for m in meta if isinstance(m, str) and m.startswith("subpac")),
                     None,
                 )
                 if not line:
@@ -548,6 +551,22 @@ class Dfn(TypedDict):
                 return Ref(parent=parent, **rest)
             return None
 
+        def _subcomponents() -> list[str] | None:
+            """
+            Extract allowed child component types from mf6 subpackage metadata.
+
+            This parses '# mf6 subpackage <abbr>' declarations to determine
+            schema-level composition constraints (which component types can be
+            children). Distinct from fkeys, which are field-level foreign keys
+            populated from '# flopy subpackage ...' declarations.
+            """
+            result = []
+            for m in meta:
+                if m.startswith("mf6-subpackage "):
+                    abbr = m.removeprefix("mf6-subpackage ").strip().upper()
+                    result.append(abbr)
+            return result if result else None
+
         return cls(
             name=name,
             fkeys=fkeys,
@@ -555,6 +574,7 @@ class Dfn(TypedDict):
             multi=_multi(),
             sln=_sln(),
             ref=_sub(),
+            subcomponents=_subcomponents(),
             **blocks,
         )
 
@@ -586,13 +606,11 @@ class Dfn(TypedDict):
 
     @staticmethod
     def _load_all_v1(dfndir: PathLike) -> Dfns:
-        paths: list[Path] = [
-            p for p in dfndir.glob("*.dfn") if p.stem not in ["common", "flopy"]
-        ]
+        paths: list[Path] = [p for p in dfndir.glob("*.dfn") if p.stem not in ["common", "flopy"]]
 
         # load common variables
         common_path: Path | None = dfndir / "common.dfn"
-        if not common_path.is_file:
+        if not common_path.is_file():
             common = None
         else:
             with common_path.open() as f:
@@ -618,9 +636,7 @@ class Dfn(TypedDict):
 
     @staticmethod
     def _load_all_v2(dfndir: PathLike) -> Dfns:
-        paths: list[Path] = [
-            p for p in dfndir.glob("*.toml") if p.stem not in ["common", "flopy"]
-        ]
+        paths: list[Path] = [p for p in dfndir.glob("*.toml") if p.stem not in ["common", "flopy"]]
         dfns: Dfns = {}
         for path in paths:
             with path.open(mode="rb") as f:
@@ -640,9 +656,7 @@ class Dfn(TypedDict):
             raise ValueError(f"Unsupported version, expected one of {version.__args__}")
 
 
-def get_dfns(
-    owner: str, repo: str, ref: str, outdir: str | PathLike, verbose: bool = False
-):
+def get_dfns(owner: str, repo: str, ref: str, outdir: str | PathLike, verbose: bool = False):
     """Fetch definition files from the MODFLOW 6 repository."""
     url = f"https://github.com/{owner}/{repo}/archive/{ref}.zip"
     if verbose:
@@ -655,6 +669,4 @@ def get_dfns(
             raise ValueError(f"Missing proj dir in {dl_path}, found {contents}")
         if verbose:
             print("Copying dfns from download dir to output dir")
-        shutil.copytree(
-            proj_path / "doc" / "mf6io" / "mf6ivar" / "dfn", outdir, dirs_exist_ok=True
-        )
+        shutil.copytree(proj_path / "doc" / "mf6io" / "mf6ivar" / "dfn", outdir, dirs_exist_ok=True)

modflow_devtools-1.9.0/modflow_devtools/dfn2toml.py

@@ -0,0 +1,126 @@
+"""Convert DFNs to TOML."""
+
+import argparse
+import sys
+import textwrap
+from dataclasses import asdict
+from os import PathLike
+from pathlib import Path
+
+import tomli_w as tomli
+from boltons.iterutils import remap
+
+from modflow_devtools.dfns import Dfn, is_valid, load, load_flat, map, to_flat, to_tree
+from modflow_devtools.dfns.schema.block import block_sort_key
+from modflow_devtools.misc import drop_none_or_empty
+
+# mypy: ignore-errors
+
+
+def convert(inpath: PathLike, outdir: PathLike, schema_version: str = "2") -> None:
+    """
+    Convert DFN files in `inpath` to TOML files in `outdir`.
+    By default, convert the definitions to schema version 2.
+    """
+    inpath = Path(inpath).expanduser().absolute()
+    outdir = Path(outdir).expanduser().absolute()
+    outdir.mkdir(exist_ok=True, parents=True)
+
+    if inpath.is_file():
+        if inpath.name == "common.dfn":
+            raise ValueError("Cannot convert common.dfn as a standalone file")
+
+        common_path = inpath.parent / "common.dfn"
+        if common_path.exists():
+            with common_path.open() as f:
+                from modflow_devtools.dfn import parse_dfn
+
+                common, _ = parse_dfn(f)
+        else:
+            common = {}
+
+        with inpath.open() as f:
+            dfn = load(f, name=inpath.stem, common=common, format="dfn")
+
+        dfn = map(dfn, schema_version=schema_version)
+        _convert(dfn, outdir / f"{inpath.stem}.toml")
+    else:
+        dfns = {
+            name: map(dfn, schema_version=schema_version) for name, dfn in load_flat(inpath).items()
+        }
+        tree = to_tree(dfns)
+        flat = to_flat(tree)
+        for dfn_name, dfn in flat.items():
+            _convert(dfn, outdir / f"{dfn_name}.toml")
+
+
+def _convert(dfn: Dfn, outpath: Path) -> None:
+    with Path.open(outpath, "wb") as f:
+        # TODO if we start using c/attrs, swap out
+        # all this for a custom unstructuring hook
+        dfn_dict = asdict(dfn)
+        dfn_dict["schema_version"] = str(dfn_dict["schema_version"])
+        if blocks := dfn_dict.pop("blocks", None):
+            for block_name, block_fields in blocks.items():
+                if block_name not in dfn_dict:
+                    dfn_dict[block_name] = {}
+                for field_name, field_data in block_fields.items():
+                    dfn_dict[block_name][field_name] = field_data
+
+        tomli.dump(
+            dict(
+                sorted(
+                    remap(dfn_dict, visit=drop_none_or_empty).items(),
+                    key=block_sort_key,
+                )
+            ),
+            f,
+        )
+
+
+if __name__ == "__main__":
+    """
+    Convert DFN files in the original format and schema version 1
+    to TOML files, by default also converting to schema version 2.
+    """
+
+    parser = argparse.ArgumentParser(
+        description="Convert DFN files to TOML.",
+        epilog=textwrap.dedent(
+            """\
+Convert DFN files in the original format and schema version 1
+to TOML files, by default also converting to schema version 2.
+"""
+        ),
+    )
+    parser.add_argument(
+        "--indir",
+        "-i",
+        type=str,
+        help="Directory containing DFN files, or a single DFN file.",
+    )
+    parser.add_argument(
+        "--outdir",
+        "-o",
+        help="Output directory.",
+    )
+    parser.add_argument(
+        "--schema-version",
+        "-s",
+        type=str,
+        default="2",
+        help="Schema version to convert to.",
+    )
+    parser.add_argument(
+        "--validate",
+        "-v",
+        action="store_true",
+        help="Validate DFN files without converting them.",
+    )
+    args = parser.parse_args()
+
+    if args.validate:
+        if not is_valid(args.indir):
+            sys.exit(1)
+    else:
+        convert(args.indir, args.outdir, args.schema_version)