feat: Support $ref to load from external JSON/YAML file

.github/workflows/type-check.yml

@@ -10,4 +10,4 @@ jobs:
       contents: read
     steps:
     - uses: actions/checkout@v6
-    - run: pipx run uv tool run --with .[typecheck] ty check
+    - run: pipx run uv tool run --with .[typecheck,yaml] ty check

README.md

@@ -31,3 +31,4 @@ Please refer to test files for detailed usage.
 - Native integration with [Sphinx](https://github.com/sphinx-doc/sphinx), [DP-GUI](https://github.com/deepmodeling/dpgui), and [Jupyter Notebook](https://jupyter.org/)
 - JSON encoder for `Argument` and `Variant` classes
 - Generate [JSON schema](https://json-schema.org/) from an `Argument`, which can be further integrated with JSON editors such as [Visual Studio Code](https://code.visualstudio.com/)
+- Load dict values from external JSON/YAML files via the `$ref` key

dargs/check.py

@@ -10,6 +10,7 @@ def check(
     data: dict,
     strict: bool = True,
     trim_pattern: str = "_*",
+    allow_ref: bool = False,
 ) -> dict:
     """Check and normalize input data.
 
@@ -23,6 +24,9 @@ def check(
         If True, raise an error if the key is not pre-defined, by default True
     trim_pattern : str, optional
         Pattern to trim the key, by default "_*"
+    allow_ref : bool, optional
+        If True, allow loading from external files via the ``$ref`` key,
+        by default False.
 
     Returns
     -------
@@ -34,6 +38,6 @@ def check(
             "base", dtype=dict, sub_fields=cast("list[Argument]", arginfo)
         )
 
-    data = arginfo.normalize_value(data, trim_pattern=trim_pattern)
-    arginfo.check_value(data, strict=strict)
+    data = arginfo.normalize_value(data, trim_pattern=trim_pattern, allow_ref=allow_ref)
+    arginfo.check_value(data, strict=strict, allow_ref=allow_ref)
     return data

dargs/cli.py

@@ -52,6 +52,12 @@ def main_parser() -> argparse.ArgumentParser:
         default="_*",
         help="Pattern to trim the key",
     )
+    parser_check.add_argument(
+        "--allow-ref",
+        action="store_true",
+        dest="allow_ref",
+        help="Allow loading from external files via the $ref key",
+    )
     parser_check.set_defaults(entrypoint=check_cli)
 
     # doc subcommand
@@ -92,6 +98,7 @@ def check_cli(
     func: str,
     jdata: list[IO],
     strict: bool,
+    allow_ref: bool = False,
     **kwargs: Any,
 ) -> None:
     """Normalize and check input data.
@@ -104,6 +111,8 @@ def check_cli(
         File object that contains the JSON data
     strict : bool
         If True, raise an error if the key is not pre-defined
+    allow_ref : bool, optional
+        If True, allow loading from external files via the ``$ref`` key
 
     Returns
     -------
@@ -124,7 +133,7 @@ def check_cli(
     arginfo = func_obj()
     for jj in jdata:
         data = json.load(jj)
-        check(arginfo, data, strict=strict)
+        check(arginfo, data, strict=strict, allow_ref=allow_ref)
 
 
 def doc_cli(