grass.app: Add internal CLI with argparse subcommands (#5590)

This adds a CLI to grass.app subpackage using `__main__.py` and Python argparse with subcommands. At this point, this is meant as internal and experimental. The original motivation for this is testing locking in #5443. The subcommands add a lot of flexibility in what can done with argparse supporting directly several use cases and being quite stable and standardized.

Just as an example (to have this separate from #5443 while functional), this adds two subcommands, help and man, which both end up calling g.manual. These specific subcommands are not a replacement for calling g.manual inside an interactive shell, but there are a replacement for command line call with a temporary project setup.

Author: wenzeslaus

python/grass/app/Makefile

@@ -6,6 +6,8 @@ include $(MODULE_TOPDIR)/include/Make/Python.make
 DSTDIR = $(ETC)/python/grass/app
 
 MODULES = \
+	__main__ \
+	cli \
 	data \
 	runtime
 

python/grass/app/__main__.py

@@ -0,0 +1,21 @@
+##############################################################################
+# AUTHOR(S): Vaclav Petras <wenzeslaus gmail com>
+#
+# PURPOSE:   Minimal file for package execution for CLI interface
+#
+# COPYRIGHT: (C) 2025 Vaclav Petras and the GRASS Development Team
+#
+#            This program is free software under the GNU General Public
+#            License (>=v2). Read the file COPYING that comes with GRASS
+#            for details.
+##############################################################################
+
+"""Minimal file for package execution for low-level CLI interface
+
+This is not a stable part of the API. Contact developers before using it.
+"""
+
+import sys
+from .cli import main
+
+sys.exit(main())

python/grass/app/cli.py

@@ -0,0 +1,76 @@
+##############################################################################
+# AUTHOR(S): Vaclav Petras <wenzeslaus gmail com>
+#
+# PURPOSE:   Python-driven CLI interface
+#
+# COPYRIGHT: (C) 2025 Vaclav Petras and the GRASS Development Team
+#
+#            This program is free software under the GNU General Public
+#            License (>=v2). Read the file COPYING that comes with GRASS
+#            for details.
+##############################################################################
+
+"""
+Experimental low-level CLI interface for the main GRASS executable functionality
+
+This is not a stable part of the API. Contact developers before using it.
+"""
+
+import argparse
+import tempfile
+import os
+import sys
+from pathlib import Path
+
+import grass.script as gs
+
+
+def call_g_manual(**kwargs):
+    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:
+            return gs.run_command(
+                "g.manual", **kwargs, env=session.env, errors="status"
+            )
+
+
+def subcommand_show_help(args):
+    return call_g_manual(entry=args.page)
+
+
+def subcommand_show_man(args):
+    return call_g_manual(entry=args.page, flags="m")
+
+
+def main(args=None, program=None):
+    # Top-level parser
+    if program is None:
+        program = os.path.basename(sys.argv[0])
+        if program == "__main__.py":
+            program = f"{Path(sys.executable).name} -m grass.app"
+    parser = argparse.ArgumentParser(
+        description="Experimental low-level CLI interface to GRASS. Consult developers before using it.",
+        prog=program,
+    )
+    subparsers = parser.add_subparsers(
+        title="subcommands", required=True, dest="subcommand"
+    )
+
+    # Subcommand parsers
+
+    subparser = subparsers.add_parser(
+        "help", help="show HTML documentation for a tool or topic"
+    )
+    subparser.add_argument("page", type=str)
+    subparser.set_defaults(func=subcommand_show_help)
+
+    subparser = subparsers.add_parser(
+        "man", help="show man page for a tool or topic using"
+    )
+    subparser.add_argument("page", type=str)
+    subparser.set_defaults(func=subcommand_show_man)
+
+    parsed_args = parser.parse_args(args)
+    return parsed_args.func(parsed_args)

python/grass/app/tests/grass_app_cli_test.py

@@ -0,0 +1,16 @@
+import sys
+
+import pytest
+
+from grass.app.cli import main
+
+
+def test_cli_help_runs():
+    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():
+    assert main(["man", "g.region"]) == 0