grass.script: Add support for named saved regions in RegionManager

python/grass/script/raster.py

@@ -465,8 +465,9 @@ class RegionManager:
     settings are automatically restored. This is useful in scripts or functions that need to
     work with a specific region without permanently altering the user's working environment.
 
-    The new region can be defined by passing *g.region* parameters when initializing the context,
-    or by calling *g.region* directly within the context.
+    The new region can be defined either by passing *g.region* parameters as keyword
+    arguments when initializing the context or by calling *g.region* directly within
+    the context.
 
     The original region is saved at the beginning of the context and restored at the end.
 
@@ -480,18 +481,29 @@ class RegionManager:
     >>> with gs.RegionManager(raster="elevation"):
     ...     gs.run_command("r.slope.aspect", elevation="elevation", slope="slope")
 
+    Example using a saved region:
+
+    >>> with gs.RegionManager(region="study_area"):
+    ...     gs.parse_command("r.univar", map="elevation", format="json")
+
     Example using g.region:
 
     >>> with gs.RegionManager():
     ...     gs.run_command("g.region", n=226000, s=222000, w=634000, e=638000)
     ...     gs.parse_command("r.univar", map="elevation", format="json")
 
-    Example using :py:func:`~grass.script.raster.RegionManager.set_region`:
+    Example using :py:meth:`~grass.script.raster.RegionManager.set_region`:
 
     >>> with gs.RegionManager() as manager:
     ...     manager.set_region(n=226000, s=222000, w=634000, e=638000)
     ...     gs.parse_command("r.univar", map="elevation", format="json")
 
+    Example using :py:meth:`~grass.script.raster.RegionManager.save` to store the current
+    region under a persistent name so it can be reused after the context exits:
+
+    >>> with gs.RegionManager(raster="elevation") as manager:
+    ...     manager.save("elevation_region", overwrite=True)
+
     Example using explicit activate and deactivate:
 
     >>> manager = gs.RegionManager(raster="elevation")
@@ -534,6 +546,14 @@ def set_region(self, **kwargs):
         """
         run_command("g.region", **kwargs, env=self.env)
 
+    def save(self, name, overwrite=False):
+        """Save the current region under a persistent name.
+
+        :param name: Name of the region to save.
+        :param overwrite: Whether to overwrite an existing saved region.
+        """
+        run_command("g.region", save=name, overwrite=overwrite, env=self.env)
+
     def activate(self):
         """Sets the `WIND_OVERRIDE` environment variable to the generated region name.
 

python/grass/script/tests/grass_script_raster_region_test.py

@@ -163,3 +163,25 @@ def test_region_manager_env_activate_deactivate(session_2x2):
     # Deactivate twice is harmless
     manager.deactivate()
     assert "GRASS_REGION" not in session_2x2.env
+
+
+def test_region_manager_save(session_2x2):
+    """Test RegionManager can persist the current region explicitly."""
+
+    with gs.RegionManager(n=6, s=0, e=6, w=0, res=1, env=session_2x2.env) as manager:
+        manager.save("saved_region", overwrite=True)
+
+    try:
+        with gs.RegionManager(region="saved_region", env=session_2x2.env):
+            region = gs.region(env=session_2x2.env)
+            assert region["rows"] == 6
+            assert region["cols"] == 6
+    finally:
+        gs.run_command(
+            "g.remove",
+            flags="f",
+            type="region",
+            name="saved_region",
+            env=session_2x2.env,
+            quiet=True,
+        )