grass.experimental: Add object to access tools as functions

python/grass/app/cli.py

@@ -20,10 +20,47 @@
 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.experimental.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, 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:
+                if help:
+                    # We consumed the help flag, so we need to add it explicitly.
+                    tools.no_nonsense_run_from_list([*command, "--help"])
+                elif 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.
+                    tools.no_nonsense_run_from_list(command)
+                else:
+                    tools.run_from_list(command)
+            except subprocess.CalledProcessError as error:
+                return error.returncode
 
 
 def subcommand_lock_mapset(args):
@@ -73,10 +110,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 it 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 +169,12 @@ 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
+        return parsed_args.func(parsed_args, other_args, help=parsed_args.help)
     return parsed_args.func(parsed_args)

python/grass/experimental/Makefile

@@ -1,18 +1,21 @@
 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
 
+SUBDIRS = \
+	tools
+
 MODULES = \
 	create \
 	mapset
 
 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
@@ -69,3 +69,41 @@ def xy_mapset_non_permament(xy_session):  # pylint: disable=redefined-outer-name
         "test1", create=True, env=xy_session.env
     ) as session:
         yield session
+
+
+@pytest.fixture
+def rows_raster_file3x3(tmp_path):
+    project = tmp_path / "xy_test3x3"
+    gs.create_project(project)
+    with gs.setup.init(project, env=os.environ.copy()) as session:
+        gs.run_command("g.region", rows=3, cols=3, env=session.env)
+        gs.mapcalc("rows = row()", env=session.env)
+        output_file = tmp_path / "rows3x3.grass_raster"
+        gs.run_command(
+            "r.pack",
+            input="rows",
+            output=output_file,
+            flags="c",
+            superquiet=True,
+            env=session.env,
+        )
+    return output_file
+
+
+@pytest.fixture
+def rows_raster_file4x5(tmp_path):
+    project = tmp_path / "xy_test4x5"
+    gs.create_project(project)
+    with gs.setup.init(project, env=os.environ.copy()) as session:
+        gs.run_command("g.region", rows=4, cols=5, env=session.env)
+        gs.mapcalc("rows = row()", env=session.env)
+        output_file = tmp_path / "rows4x5.grass_raster"
+        gs.run_command(
+            "r.pack",
+            input="rows",
+            output=output_file,
+            flags="c",
+            superquiet=True,
+            env=session.env,
+        )
+    return output_file

python/grass/experimental/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/experimental/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/experimental/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