feat: add command line interface (#72)

<!-- This is an auto-generated comment: release notes by coderabbit.ai
-->
## Summary by CodeRabbit

- **New Features**
- Introduced a command-line interface (CLI) for argument checking in
Python programs.
  - Added a script entry point for the CLI in project configuration.
  - Enhanced documentation with a new section on CLI usage.

- **Bug Fixes**
- Updated type annotations and added default arguments to improve the
robustness of the `check` function.

- **Documentation**
  - Added CLI module documentation.
  - Updated module references for better documentation rendering.

- **Tests**
  - Added test cases to validate the new CLI functionality.
  - Introduced new unit tests for CLI command verification.
<!-- end of auto-generated comment: release notes by coderabbit.ai -->

---------

Signed-off-by: Jinzhe Zeng <[email protected]>
Co-authored-by: pre-commit-ci[bot] <66853113+pre-commit-ci[bot]@users.noreply.github.com>

Author: njzjz

dargs/__main__.py

@@ -0,0 +1,6 @@
+from __future__ import annotations
+
+from dargs.cli import main
+
+if __name__ == "__main__":
+    main()

dargs/_test.py

@@ -0,0 +1,25 @@
+from __future__ import annotations
+
+from typing import List
+
+from dargs.dargs import Argument
+
+
+def test_arguments() -> list[Argument]:
+    """Returns a list of arguments."""
+    return [
+        Argument(name="test1", dtype=int, doc="Argument 1"),
+        Argument(name="test2", dtype=[float, None], doc="Argument 2"),
+        Argument(
+            name="test3",
+            dtype=List[str],
+            default=["test"],
+            optional=True,
+            doc="Argument 3",
+        ),
+    ]
+
+
+__all__ = [
+    "test_arguments",
+]

dargs/check.py

@@ -0,0 +1,35 @@
+from __future__ import annotations
+
+from dargs.dargs import Argument
+
+
+def check(
+    arginfo: Argument | list[Argument] | tuple[Argument, ...],
+    data: dict,
+    strict: bool = True,
+    trim_pattern: str = "_*",
+) -> dict:
+    """Check and normalize input data.
+
+    Parameters
+    ----------
+    arginfo : Union[Argument, List[Argument], Tuple[Argument, ...]]
+        Argument object
+    data : dict
+        data to check
+    strict : bool, optional
+        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 "_*"
+
+    Returns
+    -------
+    dict
+        normalized data
+    """
+    if isinstance(arginfo, (list, tuple)):
+        arginfo = Argument("base", dtype=dict, sub_fields=arginfo)
+
+    data = arginfo.normalize_value(data, trim_pattern=trim_pattern)
+    arginfo.check_value(data, strict=strict)
+    return data

dargs/cli.py

@@ -0,0 +1,107 @@
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+from typing import IO
+
+from dargs._version import __version__
+from dargs.check import check
+
+
+def main_parser() -> argparse.ArgumentParser:
+    """Create the main parser for the command line interface.
+
+    Returns
+    -------
+    argparse.ArgumentParser
+        The main parser
+    """
+    parser = argparse.ArgumentParser(
+        description="dargs: Argument checking for Python programs"
+    )
+    subparsers = parser.add_subparsers(help="Sub-commands")
+    parser_check = subparsers.add_parser(
+        "check",
+        help="Check a JSON file against an Argument",
+        epilog="Example: dargs check -f dargs._test.test_arguments test_arguments.json",
+    )
+    parser_check.add_argument(
+        "-f",
+        "--func",
+        type=str,
+        help="Function that returns an Argument object. E.g., `dargs._test.test_arguments`",
+        required=True,
+    )
+    parser_check.add_argument(
+        "jdata",
+        type=argparse.FileType("r"),
+        default=[sys.stdin],
+        nargs="*",
+        help="Path to the JSON file. If not given, read from stdin.",
+    )
+    parser_check.add_argument(
+        "--no-strict",
+        action="store_false",
+        dest="strict",
+        help="Do not raise an error if the key is not pre-defined",
+    )
+    parser_check.add_argument(
+        "--trim-pattern",
+        type=str,
+        default="_*",
+        help="Pattern to trim the key",
+    )
+    parser_check.set_defaults(entrypoint=check_cli)
+
+    # --version
+    parser.add_argument("--version", action="version", version=__version__)
+    return parser
+
+
+def main():
+    """Main entry point for the command line interface."""
+    parser = main_parser()
+    args = parser.parse_args()
+
+    args.entrypoint(**vars(args))
+
+
+def check_cli(
+    *,
+    func: str,
+    jdata: list[IO],
+    strict: bool,
+    **kwargs,
+) -> None:
+    """Normalize and check input data.
+
+    Parameters
+    ----------
+    func : str
+        Function that returns an Argument object. E.g., `dargs._test.test_arguments`
+    jdata : IO
+        File object that contains the JSON data
+    strict : bool
+        If True, raise an error if the key is not pre-defined
+
+    Returns
+    -------
+    dict
+        normalized data
+    """
+    module_name, attr_name = func.rsplit(".", 1)
+    try:
+        mod = __import__(module_name, globals(), locals(), [attr_name])
+    except ImportError as e:
+        raise RuntimeError(
+            f'Failed to import "{attr_name}" from "{module_name}".\n{sys.exc_info()[1]}'
+        ) from e
+
+    if not hasattr(mod, attr_name):
+        raise RuntimeError(f'Module "{module_name}" has no attribute "{attr_name}"')
+    func_obj = getattr(mod, attr_name)
+    arginfo = func_obj()
+    for jj in jdata:
+        data = json.load(jj)
+        check(arginfo, data, strict=strict)

dargs/sphinx.py

@@ -57,10 +57,10 @@ def run(self):
 
         try:
             mod = __import__(module_name, globals(), locals(), [attr_name])
-        except ImportError:
+        except ImportError as e:
             raise self.error(
                 f'Failed to import "{attr_name}" from "{module_name}".\n{sys.exc_info()[1]}'
-            )
+            ) from e
 
         if not hasattr(mod, attr_name):
             raise self.error(
@@ -217,18 +217,3 @@ def _test_argument() -> Argument:
             ),
         ],
     )
-
-
-def _test_arguments() -> list[Argument]:
-    """Returns a list of arguments."""
-    return [
-        Argument(name="test1", dtype=int, doc="Argument 1"),
-        Argument(name="test2", dtype=[float, None], doc="Argument 2"),
-        Argument(
-            name="test3",
-            dtype=List[str],
-            default=["test"],
-            optional=True,
-            doc="Argument 3",
-        ),
-    ]

docs/cli.rst

@@ -0,0 +1,9 @@
+.. _cli:
+
+Command line interface
+======================
+
+.. argparse::
+   :module: dargs.cli
+   :func: main_parser
+   :prog: dargs

docs/conf.py

@@ -49,6 +49,7 @@
     "numpydoc",
     "myst_nb",
     "dargs.sphinx",
+    "sphinxarg.ext",
 ]
 
 # Add any paths that contain templates here, relative to this directory.

docs/index.rst

@@ -11,6 +11,7 @@ Welcome to dargs's documentation!
    :caption: Contents:
 
    intro
+   cli
    sphinx
    dpgui
    nb

docs/requirements.txt

@@ -3,3 +3,4 @@ numpydoc
 deepmodeling_sphinx>=0.1.1
 myst-nb
 sphinx_rtd_theme
+sphinx-argparse

docs/sphinx.rst

@@ -15,20 +15,20 @@ Then `dargs` directive will be enabled:
 .. code-block:: rst
 
     .. dargs::
-       :module: dargs.sphinx
-       :func: _test_argument
+       :module: dargs._test
+       :func: test_argument
 
-where `_test_argument` returns an :class:`Argument <dargs.Argument>`. The documentation will be rendered as:
+where `test_argument` returns an :class:`Argument <dargs.Argument>`. The documentation will be rendered as:
 
 .. dargs::
-   :module: dargs.sphinx
-   :func: _test_argument
+   :module: dargs._test
+   :func: test_argument
 
 A :class:`list` of :class:`Argument <dargs.Argument>` is also accepted.
 
 .. dargs::
-   :module: dargs.sphinx
-   :func: _test_arguments
+   :module: dargs._test
+   :func: test_arguments
 
 Cross-referencing Arguments
 ---------------------------