diff --git a/python/grass/script/raster.py b/python/grass/script/raster.py index 47f9d7f2542..c2d114325f0 100644 --- a/python/grass/script/raster.py +++ b/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. diff --git a/python/grass/script/tests/grass_script_raster_region_test.py b/python/grass/script/tests/grass_script_raster_region_test.py index 6428842d24e..c2b63ffb593 100644 --- a/python/grass/script/tests/grass_script_raster_region_test.py +++ b/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, + )