grass.app: Add project create subcommand (#6441)

The create_project function is readily available for CLI use especially with the new crs parameter (added in #6415), so this is adding the functionality under as `project create` subcommand. All create_project parameters are exposed, so the user is not limited to what crs parameter can currently handle.

This will be useful in tests of the subcommand CLI itself if we want to use the other subcommands rather than the Python functions in the tests (of subcommands). It is used for lock and unlock tests in #6437.

A --project parameter is added to the run subcommand which now can use existing project instead of creating a new one. This makes subcommand `run --project project/path ...` roughly equivalent to `grass project/path --exec ...`. The functionality is used in the test to check the resulting project CRS.

Example subcomands:
project create --crs EPSG:3358 /tmp/project_1
run --project /tmp/project_1 g.mapset -p

Adds missing documentation for crs parameter of create_project. Also, this uses the description parameter from #6440 not desc.

Implementation of the subcommand now uses StackExit context manager to handle the only-sometimes-needed temporary directory.

Author: wenzeslaus

python/grass/app/cli.py

@@ -21,11 +21,13 @@
 import os
 import sys
 import subprocess
+from contextlib import ExitStack
 from pathlib import Path
 
 
 import grass.script as gs
 from grass.app.data import lock_mapset, unlock_mapset, MapsetLockingException
+from grass.exceptions import ScriptError
 from grass.tools import Tools
 
 # Special flags supported besides help and --json which does not need special handling:
@@ -39,12 +41,16 @@
 # --help-text --html-description --rst-description
 
 
-def subcommand_run_tool(args, tool_args: list, print_help: bool):
+def subcommand_run_tool(args, tool_args: list, print_help: bool) -> int:
     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, crs=args.crs)
+    with ExitStack() as stack:
+        if args.project:
+            project_path = Path(args.project)
+        else:
+            tmp_dir_name = stack.enter_context(tempfile.TemporaryDirectory())
+            project_name = "project"
+            project_path = Path(tmp_dir_name) / project_name
+            gs.create_project(project_path, crs=args.crs)
         with gs.setup.init(project_path) as session:
             tools = Tools(
                 session=session, capture_output=False, consistent_return_value=True
@@ -66,6 +72,25 @@ def subcommand_run_tool(args, tool_args: list, print_help: bool):
                 return error.returncode
 
 
+def subcommand_create_project(args) -> int:
+    """Translates args to function parameters"""
+    try:
+        gs.create_project(
+            path=args.path,
+            crs=args.crs,
+            proj4=args.proj4,
+            wkt=args.wkt,
+            datum=args.datum,
+            datum_trans=args.datum_trans,
+            description=args.description,
+            overwrite=args.overwrite,
+        )
+    except ScriptError as error:
+        print(_("Error creating project: {}").format(error), file=sys.stderr)
+        return 1
+    return 0
+
+
 def subcommand_lock_mapset(args):
     gs.setup.setup_runtime_env()
     try:
@@ -103,6 +128,48 @@ def subcommand_show_man(args):
     return call_g_manual(entry=args.page, flags="m")
 
 
+def add_project_subparser(subparsers):
+    project_parser = subparsers.add_parser("project", help="project operations")
+    project_subparsers = project_parser.add_subparsers(dest="project_command")
+
+    create_parser = project_subparsers.add_parser("create", help="create project")
+    create_parser.add_argument("path", help="path to the new project")
+    create_parser.add_argument(
+        "--crs",
+        help="CRS for the project",
+    )
+    create_parser.add_argument(
+        "--proj4",
+        help="if given, create new project based on Proj4 definition",
+    )
+    create_parser.add_argument(
+        "--wkt",
+        help=(
+            "if given, create new project based on WKT definition "
+            "(can be path to PRJ file or WKT string)"
+        ),
+    )
+    create_parser.add_argument(
+        "--datum",
+        help="GRASS format datum code",
+    )
+    create_parser.add_argument(
+        "--datum-trans",
+        dest="datum_trans",
+        help="datum transformation parameters (used for epsg and proj4)",
+    )
+    create_parser.add_argument(
+        "--description",
+        help="description of the project",
+    )
+    create_parser.add_argument(
+        "--overwrite",
+        action="store_true",
+        help="overwrite existing project",
+    )
+    create_parser.set_defaults(func=subcommand_create_project)
+
+
 def main(args=None, program=None):
     # Top-level parser
     if program is None:
@@ -128,8 +195,13 @@ def main(args=None, program=None):
     run_subparser.add_argument("tool", type=str, nargs="?", help="name of a tool")
     run_subparser.add_argument("--help", action="store_true")
     run_subparser.add_argument("--crs", type=str, help="CRS to use for computations")
+    run_subparser.add_argument(
+        "--project", type=str, help="project to use for computations"
+    )
     run_subparser.set_defaults(func=subcommand_run_tool)
 
+    add_project_subparser(subparsers)
+
     subparser = subparsers.add_parser("lock", help="lock a mapset")
     subparser.add_argument("mapset_path", type=str)
     subparser.add_argument(

python/grass/app/tests/grass_app_cli_test.py

@@ -127,3 +127,35 @@ def test_subcommand_run_with_crs_as_pack_subprocess(pack_raster_file4x5_rows, ca
         check=True,
     )
     assert json.loads(result.stdout)["srid"] == "EPSG:3358"
+
+
+def test_create_overwrite(tmp_path):
+    """Check that creating when project exists fails unless overwrite is True"""
+    project = tmp_path / "test_1"
+    assert main(["project", "create", str(project)]) == 0
+    assert main(["project", "create", str(project)]) == 1
+    assert main(["project", "create", "--overwrite", str(project)]) == 0
+
+
+@pytest.mark.parametrize("crs", ["EPSG:4326", "EPSG:3358"])
+def test_create_crs_epsg(tmp_path, crs):
+    """Check that created project has the requested EPSG"""
+    project = tmp_path / "test_1"
+    assert main(["project", "create", str(project), "--crs", crs]) == 0
+    result = subprocess.run(
+        [
+            sys.executable,
+            "-m",
+            "grass.app",
+            "run",
+            "--project",
+            str(project),
+            "g.proj",
+            "-p",
+            "format=json",
+        ],
+        capture_output=True,
+        text=True,
+        check=True,
+    )
+    assert json.loads(result.stdout)["srid"] == crs

python/grass/script/core.py

@@ -1962,6 +1962,7 @@ def create_project(
     :param str path: path to GRASS database or project; if path to database, project
                      name must be specified with name parameter
     :param str name: project name to create
+    :param crs: CRS of the new project EPSG or filename (defaults to 'XY')
     :param epsg: if given create new project based on EPSG code
     :param proj4: if given create new project based on Proj4 definition
     :param str filename: if given create new project based on georeferenced file