temporal: add parameter to skip creation of TGIS DB in current mapset on tgis.init (#7645)

* enable DB creation skip on tgis.init()

* add test for tgis.init(skip_db_init=True)

Author: ninsbl

python/grass/temporal/core.py

@@ -543,14 +543,15 @@ def get_available_temporal_mapsets():
 ###############################################################################
 
 
-def init(raise_fatal_error: bool = False, skip_db_version_check: bool = False):
-    """This function set the correct database backend from GRASS environmental
-    variables and creates the grass temporal database structure for raster,
-    vector and raster3d maps as well as for the space-time datasets strds,
-    str3ds and stvds in case it does not exist.
+def init(
+    raise_fatal_error: bool = False,
+    skip_db_version_check: bool = False,
+    skip_db_init: bool = False,
+):
+    """Initialize the temporal GIS system.
 
-    Several global variables are initiated and the messenger and C-library
-    interface subprocesses are spawned.
+    This function sets several global variables and spawns the messenger and
+    C-library interface subprocesses.
 
     Re-run this function in case the following GRASS variables change while
     the process runs:
@@ -572,7 +573,14 @@ def init(raise_fatal_error: bool = False, skip_db_version_check: bool = False):
     - GRASS_TGIS_PROFILE (True, False, 1, 0)
     - GRASS_TGIS_RAISE_ON_ERROR (True, False, 1, 0)
 
-    .. warning::
+    If not otherwise requested (skip_db_init), this function will check for
+    the existence of a temporal database and its version in the current mapset.
+    If the database does not exist, it will be created, using the database
+    backend from GRASS environment variables, with the GRASS temporal database
+    structure for raster, vector and raster3d maps as well as for the space-time
+    dataset types strds, str3ds and stvds.
+
+        .. warning::
 
         This functions must be called before any spatio-temporal processing
         can be started
@@ -588,6 +596,14 @@ def init(raise_fatal_error: bool = False, skip_db_version_check: bool = False):
                                    database version check.
                                    Recommended to be used only for
                                    upgrade_temporal_database().
+    :param skip_db_init: Set this True to allow init() to complete
+                         without initializing, (version) checking or creating
+                         a temporal database in the current mapset.
+                         Use this when the calling process only needs the
+                         global TGIS state (backend, mapset, interfaces)
+                         but does not require a temporal database in the
+                         current mapset for operations (like listing
+                         datasets, getting metainformation, ...).
     """
     # We need to set the correct database backend and several global variables
     # from the GRASS mapset specific environment variables of g.gisenv and t.connect
@@ -600,9 +616,6 @@ def init(raise_fatal_error: bool = False, skip_db_version_check: bool = False):
 
     raise_on_error = raise_fatal_error
 
-    # We must run t.connect at first to create the temporal database and to
-    # get the environmental variables
-    gs.run_command("t.connect", flags="c")
     grassenv = gs.gisenv()
 
     new_mapset = grassenv["MAPSET"]
@@ -647,14 +660,11 @@ def init(raise_fatal_error: bool = False, skip_db_version_check: bool = False):
     # Start the C-library interface server
     _init_tgis_c_library_interface()
     msgr = get_tgis_message_interface()
-    msgr.debug(1, "Initiate the temporal database")
 
     msgr.debug(1, ("Raise on error id: %s" % str(raise_on_error)))
 
     ciface = get_tgis_c_library_interface()
     current_mapset = decode(gs.gisenv().get("MAPSET"))
-    driver_string = ciface.get_driver_name(current_mapset)
-    database_string = ciface.get_database_name(current_mapset)
 
     # Set the mapset check and the timestamp write
     if "TGIS_DISABLE_MAPSET_CHECK" in grassenv:
@@ -673,6 +683,17 @@ def init(raise_fatal_error: bool = False, skip_db_version_check: bool = False):
             enable_timestamp_write = False
             msgr.warning("TGIS_DISABLE_TIMESTAMP_WRITE is True")
 
+    if skip_db_init:
+        return
+
+    msgr.debug(1, "Initiate the temporal database")
+    # We must run t.connect at first to create the temporal database and to
+    # get the environmental variables
+    gs.run_command("t.connect", flags="c")
+
+    driver_string = ciface.get_driver_name(current_mapset)
+    database_string = ciface.get_database_name(current_mapset)
+
     if driver_string is not None and driver_string != "":
         driver_string = decode(driver_string)
         if driver_string == "sqlite":

python/grass/temporal/tests/grass_temporal_core_init_skip_db_test.py

@@ -0,0 +1,76 @@
+"""Regression test for tgis.init() with and without TGIS DB initialization.
+
+tgis.init() creates a TGIS database in the current mapset by default.
+For several tools that is not needed. This test checks if tgis.init()
+can be called with and without TGIS DB initialization and that the
+required files are created or not created accordingly.
+"""
+
+import pytest
+
+from pathlib import Path
+
+import sqlite3
+
+from grass.grassdb.create import create_mapset
+import grass.script as gs
+import grass.temporal as tgis
+
+
+@pytest.fixture
+def simple_mapset(tmp_path):
+    """Create a simple mapset and yield its path."""
+    project_c = tmp_path / "c"
+    gs.create_project(project_c)
+    create_mapset(project_c / "c")
+    return project_c / "c"
+
+
+def test_init_creates_tgis_db_if_not_skipped(simple_mapset):
+    """tgis.init() creates a DB and connection entry in VAR if not skipped."""
+    project_c = simple_mapset
+    var_file = Path(project_c) / "VAR"
+    tgis_db = Path(project_c) / "tgis" / "sqlite.db"
+    with gs.setup.init(project_c):
+        tgis.init()
+        ciface = tgis.get_tgis_c_library_interface()
+        assert ciface.available_mapsets() == ["c", "PERMANENT"]
+        assert tgis.get_tgis_version() == 2
+        assert tgis.get_tgis_backend() == "sqlite"
+        assert tgis.get_enable_mapset_check() is True
+        assert tgis.get_enable_timestamp_write() is True
+        assert tgis.get_sql_template_path().endswith("sql")
+        # Test if the VAR file with the TGIS connection info is created
+        assert var_file.exists()
+        varfile_content = var_file.read_text(encoding="utf-8")
+        assert "TGISDB_DRIVER" in varfile_content
+        assert "TGISDB_DATABASE" in varfile_content
+        # Test if the TGIS DB is created with content
+        assert tgis_db.parent.exists()
+        assert tgis_db.exists()
+        assert (
+            sqlite3.connect(tgis_db)
+            .execute(
+                "SELECT name FROM sqlite_master WHERE type='table' AND name LIKE '%strds%';"
+            )
+            .fetchall()
+            != []
+        )
+
+
+def test_init_succeeds_without_db_creation(simple_mapset):
+    """tgis.init(skip_db_init=True) does not create a DB or connection entry in VAR."""
+    project_c = simple_mapset
+    var_file = Path(project_c) / "VAR"
+    tgis_db = Path(project_c) / "tgis"
+    with gs.setup.init(project_c):
+        tgis.init(skip_db_init=True)
+        first_ciface = tgis.get_tgis_c_library_interface()
+        assert first_ciface.available_mapsets() == ["c", "PERMANENT"]
+        assert tgis.get_tgis_version() == 2
+        assert tgis.get_tgis_backend() == "sqlite"
+        assert tgis.get_enable_mapset_check() is True
+        assert tgis.get_enable_timestamp_write() is True
+        assert tgis.get_sql_template_path().endswith("sql")
+        assert not var_file.exists()
+        assert not tgis_db.exists()