grass.tools: Add API to access tools as functions

python/grass/CMakeLists.txt

@@ -21,6 +21,7 @@ set(PYDIRS
     semantic_label
     temporal
     temporal/ply
+    tools
     utils)
 
 set(PYDIR_GRASS ${GRASS_INSTALL_PYDIR}/grass)

python/grass/Makefile

@@ -19,6 +19,7 @@ SUBDIRS = \
 	script \
 	semantic_label \
 	temporal \
+	tools \
 	utils
 
 default: $(PYDIR)/__init__.py

python/grass/app/cli.py

@@ -20,10 +20,48 @@
 import tempfile
 import os
 import sys
+import subprocess
 from pathlib import Path
 
+
 import grass.script as gs
 from grass.app.data import lock_mapset, unlock_mapset, MapsetLockingException
+from grass.tools import Tools
+
+# Special flags supported besides help and --json which does not need special handling:
+SPECIAL_FLAGS = [
+    "--interface-description",
+    "--md-description",
+    "--wps-process-description",
+    "--script",
+]
+# To make this list shorter, we don't support outdated special flags:
+# --help-text --html-description --rst-description
+
+
+def subcommand_run_tool(args, tool_args: list, print_help: bool):
+    command = [args.tool, *tool_args]
+    with tempfile.TemporaryDirectory() as tmp_dir_name:
+        project_name = "project"
+        project_path = Path(tmp_dir_name) / project_name
+        gs.create_project(project_path)
+        with gs.setup.init(project_path) as session:
+            tools = Tools(session=session, capture_output=False)
+            try:
+                # From here, we return the subprocess return code regardless of its
+                # value. Error states are handled through exceptions.
+                if print_help:
+                    # We consumed the help flag, so we need to add it explicitly.
+                    return tools.call_cmd([*command, "--help"]).returncode
+                if any(item in command for item in SPECIAL_FLAGS):
+                    # This is here basically because of how --json behaves,
+                    # two JSON flags are accepted, but --json currently overridden by
+                    # other special flags, so later use of --json in tools will fail
+                    # with the other flags active.
+                    return tools.call_cmd(command).returncode
+                return tools.run_cmd(command).returncode
+            except subprocess.CalledProcessError as error:
+                return error.returncode
 
 
 def subcommand_lock_mapset(args):
@@ -73,10 +111,22 @@ def main(args=None, program=None):
         description="Experimental low-level CLI interface to GRASS. Consult developers before using it.",
         prog=program,
     )
-    subparsers = parser.add_subparsers(title="subcommands", required=True)
+    subparsers = parser.add_subparsers(
+        title="subcommands", dest="subcommand", required=True
+    )
 
     # Subcommand parsers
 
+    run_subparser = subparsers.add_parser(
+        "run",
+        help="run a tool",
+        add_help=False,
+        epilog="Tool name is followed by its parameters.",
+    )
+    run_subparser.add_argument("tool", type=str, nargs="?", help="name of a tool")
+    run_subparser.add_argument("--help", action="store_true")
+    run_subparser.set_defaults(func=subcommand_run_tool)
+
     subparser = subparsers.add_parser("lock", help="lock a mapset")
     subparser.add_argument("mapset_path", type=str)
     subparser.add_argument(
@@ -120,5 +170,16 @@ def main(args=None, program=None):
     subparser.add_argument("page", type=str)
     subparser.set_defaults(func=subcommand_show_man)
 
-    parsed_args = parser.parse_args(args)
+    # Parsing
+    parsed_args, other_args = parser.parse_known_args(args)
+    # Standard help already exited, but we need to handle tools separately.
+    if parsed_args.subcommand == "run":
+        if parsed_args.tool is None and parsed_args.help:
+            run_subparser.print_help()
+            return 0
+        if parsed_args.tool is None:
+            run_subparser.print_usage()
+            # argparse gives 2 without parameters, so we behave the same.
+            return 2
+        return parsed_args.func(parsed_args, other_args, print_help=parsed_args.help)
     return parsed_args.func(parsed_args)

python/grass/app/tests/grass_app_cli_test.py

@@ -6,11 +6,50 @@
 
 
 def test_cli_help_runs():
+    """Check help of the main command"""
     with pytest.raises(SystemExit) as exception:
         main(["--help"])
     assert exception.value.code == 0
 
 
 @pytest.mark.skipif(sys.platform.startswith("win"), reason="No man on Windows")
 def test_man_subcommand_runs():
+    """Check that man subcommand runs without an error"""
     assert main(["man", "g.region"]) == 0
+
+
+def test_subcommand_man_no_page():
+    """argparse gives 2 without parameters"""
+    with pytest.raises(SystemExit) as exception:
+        main(["man"])
+    assert exception.value.code == 2
+
+
+def test_subcommand_run_help():
+    """Check help of a subcommand"""
+    assert main(["run", "--help"]) == 0
+
+
+def test_subcommand_run_no_tool():
+    """argparse gives 2 without parameters"""
+    assert main(["run"]) == 2
+
+
+def test_subcommand_run_tool_help():
+    """Check help of a tool"""
+    assert main(["run", "g.region", "--help"]) == 0
+
+
+def test_subcommand_run_tool_special_flag():
+    """Check that a special flag is supported"""
+    assert main(["run", "g.region", "--interface-description"]) == 0
+
+
+def test_subcommand_run_tool_regular_run():
+    """Check that a tool runs without error"""
+    assert main(["run", "g.region", "-p"]) == 0
+
+
+def test_subcommand_run_tool_failure_run():
+    """Check that a tool produces non-zero return code"""
+    assert main(["run", "g.region", "raster=does_not_exist"]) == 1

python/grass/experimental/Makefile

@@ -1,7 +1,7 @@
 MODULE_TOPDIR = ../../..
 
-include $(MODULE_TOPDIR)/include/Make/Other.make
 include $(MODULE_TOPDIR)/include/Make/Python.make
+include $(MODULE_TOPDIR)/include/Make/Dir.make
 
 DSTDIR = $(ETC)/python/grass/experimental
 
@@ -12,7 +12,7 @@ MODULES = \
 PYFILES := $(patsubst %,$(DSTDIR)/%.py,$(MODULES) __init__)
 PYCFILES := $(patsubst %,$(DSTDIR)/%.pyc,$(MODULES) __init__)
 
-default: $(PYFILES) $(PYCFILES)
+default: subdirs $(PYFILES) $(PYCFILES)
 
 $(DSTDIR):
 	$(MKDIR) $@

python/grass/experimental/tests/conftest.py

@@ -1,4 +1,4 @@
-"""Fixtures for grass.script"""
+"""Fixtures for grass.experimental"""
 
 import uuid
 import os

python/grass/tools/Makefile

@@ -0,0 +1,21 @@
+MODULE_TOPDIR = ../../..
+
+include $(MODULE_TOPDIR)/include/Make/Other.make
+include $(MODULE_TOPDIR)/include/Make/Python.make
+
+DSTDIR = $(ETC)/python/grass/tools
+
+MODULES = \
+	session_tools \
+	support
+
+PYFILES := $(patsubst %,$(DSTDIR)/%.py,$(MODULES) __init__)
+PYCFILES := $(patsubst %,$(DSTDIR)/%.pyc,$(MODULES) __init__)
+
+default: $(PYFILES) $(PYCFILES)
+
+$(DSTDIR):
+	$(MKDIR) $@
+
+$(DSTDIR)/%: % | $(DSTDIR)
+	$(INSTALL_DATA) $< $@

python/grass/tools/__init__.py

@@ -0,0 +1,10 @@
+def __getattr__(name):
+    if name == "Tools":
+        from .session_tools import Tools
+
+        return Tools
+    msg = f"module {__name__} has no attribute {name}"
+    raise AttributeError(msg)
+
+
+__all__ = ["Tools"]  # pylint: disable=undefined-all-variable