grass.script: RegionManager/RegionManagerEnv: Add support for storing current region under a persistent name

[lindakarlovska]

This PR adds a new region_name parameter to RegionManager, enabling users to work with saved regions:

• If region_name refers to an existing saved region and no additional g.region parameters are provided, the saved region is used directly without modification.

  Example:

  >>> with gs.RegionManager(region_name="study_area"):
  ...     gs.parse_command("r.univar", map="elevation", format="json")
  

• If region_name is provided together with additional g.region parameters, the region is saved under that name and persists after the context exits, allowing for reuse in future operations.

  Example:

  >>> with gs.RegionManager(region_name="my_region", raster="elevation"):
  ...     gs.run_command("r.slope.aspect", elevation="elevation", slope="slope")
  

Existing usage without region_name remains the same as it was:
E.g.:

>>> with gs.RegionManager(raster="elevation"):
...     gs.run_command("r.slope.aspect", elevation="elevation", slope="slope")

EDIT:
This PR introduces a new save() method that stores the current region under a persistent name, allowing it to be reused after the context exits. This method was added to the RegionManager and RegionManagerEnv classes. It also adds more docstring examples to clarify that saved regions were already supported through the standard g.region region= parameter.

[petrasovaa]

Wouldn't region= work?

>>> gs.run_command("g.region", n=228000)
>>> with gs.RegionManager(region="aaa"):
...     print(gs.read_command("g.region", flags="p"))
...
north:      228500
...

>>> print(gs.read_command("g.region", flags="p"))
...
north:      228000
...

[lindakarlovska]

Wouldn't region= work?

>>> gs.run_command("g.region", n=228000)
>>> with gs.RegionManager(region="aaa"):
...     print(gs.read_command("g.region", flags="p"))
...
north:      228500
...

>>> print(gs.read_command("g.region", flags="p"))
...
north:      228000
...

You are right @petrasovaa, this works normally. I intuitively expected an interface similar to MaskManager (so that there would be a region_name parameter, like mask_name), and then I didn’t see any example for region= in the docstring, so I didn’t realize that it’s already covered by **kwargs.

I think we don’t necessarily need to add a region_name parameter to the API then, adding an example to the docstring should be enough. At the same time, I added a save method, which makes it possible to save the contextual region for later use (it’s basically what I originally implemented via region_name, but now I moved it into a method, which I think makes more sense overall).

[petrasovaa]

It would be good if RegionManagerEnv has the same API.

[wenzeslaus]

Try-finally does not look right in a test and the cleanup should be done by the testing harness, i.e., the fixture. Specifically, the project will be deleted because it is in a temporary directory. No need to take care of it here.

[wenzeslaus]

The save method disrupts the context here. It needs to be a separate note.

[wenzeslaus]

This is implementation detail.

[petrasovaa]

These 2 example don't make much sense together, I would split it as it was before and add:

gs.run_command("g.region", save="study_area", s=1000, n=1100, w=1000, e=1100)

[petrasovaa]

Why try/finally here? If it fails, that's the point of the test, no? The removal is probabaly unnecessary, it's temporary session anyway.