Skip to content

grass.script: new RegionManager context manager #5628

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
wants to merge 2 commits into
base: main
Choose a base branch
from

Conversation

petrasovaa
Copy link
Contributor

Similarly to MaskManager, this adds a context manager for temporary changes of computational region.

Example with explicit region parameters:

>>> with gs.RegionManager(n=226000, s=222000, w=634000, e=638000):
...     gs.parse_command("r.univar", map="elevation", format="json")

Example matching a raster map's region:

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

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 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 modifying a copy of environment (e.g. for parallelization):

>>> with gs.RegionManager(raster="elevation", env=os.environ.copy()) as manager:
...     gs.run_command("r.univar", map="elevation", env=manager.env)

This introduces 2 classes, the primary-to-be-used-one RegionManager, which uses the same implementation as gs. use_temp_region with WIND_OVERRIDE variable. It saves a region and points the variable to the name of that region. Then there is RegionManagerEnv (not sure about the name), which uses GRASS_REGION variable. The advantage of RegionManagerEnv is no files are written to disk, so it's more lightweight.
The disadvantage is that simply calling g.region within the context will not affect the temporary region, but the global one, which can be confusing:

# this won't work
>>> with gs.RegionManagerEnv():
        gs.run_command("g.region", raster="elevation")
...     gs.run_command("r.univar", map="elevation", env=manager.env)

Hence, RegionManager should probably be the primary implementation.

@github-actions github-actions bot added Python Related code is in Python libraries docs markdown Related to markdown, markdown files notebook labels May 8, 2025
@github-actions github-actions bot added the tests Related to Test Suite label May 9, 2025
Comment on lines +538 to +541
This is *incorrect* usage (calling `g.region`):
>>> with gs.RegionManagerEnv():
gs.run_command("g.region", raster="elevation")
... gs.run_command("r.univar", map="elevation", env=manager.env)
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

To make sure web scraping/AI scraping doesn't take this as a valid example, is the text outside the code block enough? When I'm reading Microsoft docs on C# stuff, I'm kinda getting used to have a code comment note in the code block and skip a bit the text of the page, when just looking for something.

It's a minor thing, I'm not blocking the PR for this

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I would prefer addressing the concerns, e.g. by making that text rather than code.

@landam landam added this to the 8.5.0 milestone May 24, 2025
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
docs libraries markdown Related to markdown, markdown files notebook Python Related code is in Python tests Related to Test Suite
Projects
None yet
Development

Successfully merging this pull request may close these issues.

4 participants