grass.script: add Activate and Deactivate methods to RegionManager and MaskManager (OSGeo#6268)

Author: petrasovaa

python/grass/script/raster.py

@@ -294,6 +294,18 @@ class MaskManager:
     >>> with gs.MaskManager(mask_name="state_boundary"):
     ...     gs.parse_command("r.univar", map="elevation", format="json")
 
+    Example using explicit activate and deactivate:
+
+    >>> manager = gs.MaskManager()
+    >>> manager.activate()
+    >>> try:
+    ...     # Create mask with r.mask
+    ...     gs.run_command("r.mask", raster="state_boundary")
+    ...     gs.parse_command("r.univar", map="elevation", format="json")
+    ... finally:
+    ...     manager.deactivate()
+
+
     Note the difference between using the name of an existing raster map directly
     and using *r.mask* to create a new mask. Both zeros and NULL values are used
     to represent mask resulting in NULL cells, while *r.mask*
@@ -368,20 +380,24 @@ def __init__(
         else:
             self.mask_name = mask_name
             self._remove = False if remove is None else remove
+        self._active = False
 
-    def __enter__(self):
+    def activate(self):
         """Set mask in the given environment.
 
         Sets the `GRASS_MASK` environment variable to the provided or
         generated mask name.
 
         :return: Returns the MaskManager instance.
         """
+        if self._active:
+            return None
         self._original_value = self.env.get("GRASS_MASK")
         self.env["GRASS_MASK"] = self.mask_name
+        self._active = True
         return self
 
-    def __exit__(self, exc_type, exc_val, exc_tb):
+    def deactivate(self):
         """Restore the previous mask state.
 
         Restores the original value of `GRASS_MASK` and optionally removes
@@ -391,6 +407,8 @@ def __exit__(self, exc_type, exc_val, exc_tb):
         :param exc_val: Exception value, if any.
         :param exc_tb: Traceback, if any.
         """
+        if not self._active:
+            return
         if self._original_value is not None:
             self.env["GRASS_MASK"] = self._original_value
         else:
@@ -405,6 +423,13 @@ def __exit__(self, exc_type, exc_val, exc_tb):
                 env=self.env,
                 quiet=True,
             )
+        self._active = False
+
+    def __enter__(self):
+        return self.activate()
+
+    def __exit__(self, exc_type, exc_val, exc_tb):
+        self.deactivate()
 
 
 class RegionManager:
@@ -442,6 +467,15 @@ class RegionManager:
     ...     manager.set_region(n=226000, s=222000, w=634000, e=638000)
     ...     gs.parse_command("r.univar", map="elevation", format="json")
 
+    Example using explicit activate and deactivate:
+
+    >>> manager = gs.RegionManager(raster="elevation")
+    >>> manager.activate()
+    >>> try:
+    ...     gs.run_command("r.slope.aspect", elevation="elevation", slope="slope")
+    ... finally:
+    ...     manager.deactivate()
+
     If no environment is provided, the global environment is used. When running parallel
     processes in the same mapset that modify region settings, it is useful to use a copy
     of the global environment. The following code creates the copy of the global environment
@@ -466,6 +500,7 @@ def __init__(self, env: dict[str, str] | None = None, **kwargs):
         self._original_value = None
         self.region_name = append_uuid(append_node_pid("region"))
         self._region_inputs = kwargs or {}
+        self._active = False
 
     def set_region(self, **kwargs):
         """Sets region.
@@ -474,19 +509,22 @@ def set_region(self, **kwargs):
         """
         run_command("g.region", **kwargs, env=self.env)
 
-    def __enter__(self):
+    def activate(self):
         """Sets the `WIND_OVERRIDE` environment variable to the generated region name.
 
         :return: Returns the :class:`RegionManager` instance.
         """
+        if self._active:
+            return None
         self._original_value = self.env.get("WIND_OVERRIDE")
         run_command(
             "g.region", save=self.region_name, env=self.env, **self._region_inputs
         )
         self.env["WIND_OVERRIDE"] = self.region_name
+        self._active = True
         return self
 
-    def __exit__(self, exc_type, exc_val, exc_tb):
+    def deactivate(self):
         """Restore the previous region state.
 
         Restores the original value of `WIND_OVERRIDE`.
@@ -495,6 +533,8 @@ def __exit__(self, exc_type, exc_val, exc_tb):
         :param exc_val: Exception value, if any.
         :param exc_tb: Traceback, if any.
         """
+        if not self._active:
+            return
         if self._original_value is not None:
             self.env["WIND_OVERRIDE"] = self._original_value
         else:
@@ -507,6 +547,13 @@ def __exit__(self, exc_type, exc_val, exc_tb):
                 name=self.region_name,
                 env=self.env,
             )
+        self._active = False
+
+    def __enter__(self):
+        return self.activate()
+
+    def __exit__(self, exc_type, exc_val, exc_tb):
+        self.deactivate()
 
 
 class RegionManagerEnv:
@@ -534,6 +581,17 @@ class RegionManagerEnv:
             manager.env["GRASS_REGION"] = gs.region_env()
     ...     gs.parse_command("r.univar", map="elevation", format="json")
 
+
+    Example using explicit activate and deactivate:
+
+    >>> manager = gs.RegionManagerEnv(raster="elevation")
+    >>> manager.activate()
+    >>> try:
+    ...     manager.set_region(n=226000, s=222000, w=634000, e=638000)
+    ...     gs.parse_command("r.univar", map="elevation", format="json")
+    ... finally:
+    ...     manager.deactivate()
+
     .. caution::
 
         To set region within the context, do not call `g.region`,
@@ -551,6 +609,7 @@ def __init__(self, env: dict[str, str] | None = None, **kwargs):
         self.env = env if env is not None else os.environ
         self._original_value = None
         self._region_inputs = kwargs or {}
+        self._active = False
 
     def set_region(self, **kwargs):
         """Sets region.
@@ -559,16 +618,19 @@ def set_region(self, **kwargs):
         """
         self.env["GRASS_REGION"] = region_env(**kwargs, env=self.env)
 
-    def __enter__(self):
+    def activate(self):
         """Sets the `GRASS_REGION` environment variable to the generated region name.
 
         :return: Returns the :class:`RegionManagerEnv` instance.
         """
+        if self._active:
+            return None
         self._original_value = self.env.get("GRASS_REGION")
         self.env["GRASS_REGION"] = region_env(**self._region_inputs, env=self.env)
+        self._active = True
         return self
 
-    def __exit__(self, exc_type, exc_val, exc_tb):
+    def deactivate(self):
         """Restore the previous region state.
 
         Restores the original value of `WIND_OVERRIDE`.
@@ -577,7 +639,16 @@ def __exit__(self, exc_type, exc_val, exc_tb):
         :param exc_val: Exception value, if any.
         :param exc_tb: Traceback, if any.
         """
+        if not self._active:
+            return
         if self._original_value is not None:
             self.env["GRASS_REGION"] = self._original_value
         else:
             self.env.pop("GRASS_REGION", None)
+        self._active = False
+
+    def __enter__(self):
+        return self.activate()
+
+    def __exit__(self, exc_type, exc_val, exc_tb):
+        self.deactivate()

python/grass/script/tests/grass_script_raster_mask_test.py

@@ -223,3 +223,38 @@ def test_mask_manager_provided_name_remove_false(session_2x2):
     assert status["name"].startswith(DEFAULT_MASK_NAME)
     assert not status["present"]
     assert raster_sum("ones", env=session_2x2.env) == 4
+
+
+def test_mask_manager_activate_deactivate(session_2x2):
+    """Test MaskManager with explicit activate/deactivate."""
+    assert "GRASS_MASK" not in session_2x2.env
+
+    manager = gs.MaskManager(env=session_2x2.env)
+    manager.activate()
+    assert "GRASS_MASK" in session_2x2.env
+    assert session_2x2.env["GRASS_MASK"] == manager.mask_name
+
+    # Create mask using r.mask
+    gs.run_command("r.mask", raster="nulls_and_one_1_1", env=session_2x2.env)
+    assert raster_exists(manager.mask_name, env=session_2x2.env)
+    status = gs.parse_command("r.mask.status", format="json", env=session_2x2.env)
+    assert status["name"].startswith(manager.mask_name)
+    assert status["present"]
+    assert raster_sum("ones", env=session_2x2.env) == 1
+
+    # Deactivate restores state
+    manager.deactivate()
+    assert "GRASS_MASK" not in session_2x2.env
+    assert not raster_exists(manager.mask_name, env=session_2x2.env)
+    status = gs.parse_command("r.mask.status", format="json", env=session_2x2.env)
+    assert status["name"].startswith(DEFAULT_MASK_NAME)
+    assert not status["present"]
+    assert raster_sum("ones", env=session_2x2.env) == 4
+
+    # Calling again is harmless
+    manager.deactivate()
+    assert "GRASS_MASK" not in session_2x2.env
+    manager.activate()
+    manager.activate()
+    assert "GRASS_MASK" in session_2x2.env
+    manager.deactivate()

python/grass/script/tests/grass_script_raster_region_test.py

@@ -104,3 +104,62 @@ def test_region_manager_env_problem_with_g_region(session_2x2):
     region = gs.region(env=session_2x2.env)
     assert region["rows"] == 5
     assert region["cols"] == 5
+
+
+def test_region_manager_activate_deactivate(session_2x2):
+    """Test RegionManager with explicit activate/deactivate."""
+    assert "WIND_OVERRIDE" not in session_2x2.env
+
+    manager = gs.RegionManager(env=session_2x2.env)
+    manager.activate()
+    assert "WIND_OVERRIDE" in session_2x2.env
+    assert session_2x2.env["WIND_OVERRIDE"] == manager.region_name
+    region = gs.region(env=session_2x2.env)
+    assert region["rows"] == 2
+    assert region["cols"] == 2
+
+    # Change region inside manager
+    manager.set_region(n=4, s=0, e=4, w=0, res=1)
+    region = gs.region(env=session_2x2.env)
+    assert region["rows"] == 4
+    assert region["cols"] == 4
+
+    # Deactivate restores original
+    manager.deactivate()
+    assert "WIND_OVERRIDE" not in session_2x2.env
+    region = gs.region(env=session_2x2.env)
+    assert region["rows"] == 2
+    assert region["cols"] == 2
+
+    # Deactivate twice is harmless
+    manager.deactivate()
+    assert "WIND_OVERRIDE" not in session_2x2.env
+
+
+def test_region_manager_env_activate_deactivate(session_2x2):
+    """Test RegionManagerEnv with explicit activate/deactivate."""
+    assert "GRASS_REGION" not in session_2x2.env
+
+    manager = gs.RegionManagerEnv(env=session_2x2.env)
+    manager.activate()
+    assert "GRASS_REGION" in session_2x2.env
+    region = gs.region(env=session_2x2.env)
+    assert region["rows"] == 2
+    assert region["cols"] == 2
+
+    # Change region inside manager
+    manager.set_region(n=5, s=0, e=5, w=0, res=1)
+    region = gs.region(env=session_2x2.env)
+    assert region["rows"] == 5
+    assert region["cols"] == 5
+
+    # Deactivate restores original
+    manager.deactivate()
+    assert "GRASS_REGION" not in session_2x2.env
+    region = gs.region(env=session_2x2.env)
+    assert region["rows"] == 2
+    assert region["cols"] == 2
+
+    # Deactivate twice is harmless
+    manager.deactivate()
+    assert "GRASS_REGION" not in session_2x2.env