Merge branch 'OSGeo:main' into main

Author: echoix

doc/interfaces_overview.md

@@ -35,13 +35,15 @@ r.slope.aspect elevation=elevation slope=slope aspect=aspect
 
 ## Python
 
-GRASS Python interface provides libraries to create GRASS scripts and access
-the internal data structures of GRASS. The Python interface consists of
-two main libraries:
-*[grass.script](https://grass.osgeo.org/grass-stable/manuals/libpython/script_intro.html)*
-provides a Python interface to GRASS tools
+GRASS Python interface provides libraries to use GRASS tools, create scripts,
+and access the GRASS data structures. The Python interface consists of
+three main libraries:
+*[grass.tools](https://grass.osgeo.org/grass-stable/manuals/libpython/tools_index.html)*
+provides a Python interface to GRASS tools,
+*[grass.script](https://grass.osgeo.org/grass-stable/manuals/libpython/grass.script_intro.html)*
+handles GRASS projects and sessions in Python,
 and *[grass.pygrass](https://grass.osgeo.org/grass-stable/manuals/libpython/pygrass_index.html)*
-enables access to the internal data structures of GRASS.
+enables a fine-grained access to the GRASS data structures.
 
 To get started with scripting, create a new project with `gs.create_project` and
 start a GRASS session with the `gs.setup.init` function to initialize the
@@ -57,6 +59,7 @@ sys.path.append(
 )
 
 import grass.script as gs
+from grass.tools import Tools
 
 # Create a new project
 gs.create_project(path="path/to/my_project", epsg="3358")
@@ -65,9 +68,10 @@ gs.create_project(path="path/to/my_project", epsg="3358")
 with gs.setup.init("path/to/my_project") as session:
 
     # Run GRASS tools
-    gs.run_command("r.import", input="/path/to/elevation.tif", output="elevation")
-    gs.run_command("g.region", raster="elevation")
-    gs.run_command("r.slope.aspect", elevation="elevation", slope="slope")
+    tools = Tools(session=session)
+    tools.r_import_(input="/path/to/elevation.tif", output="elevation")
+    tools.g_region(raster="elevation")
+    tools.r_slope_aspect(elevation="elevation", slope="slope")
 ```
 
 [Learn more :material-arrow-right-bold:](python_intro.md){ .md-button }

doc/jupyter_intro.md

@@ -85,9 +85,13 @@ features you can refer to the [Cartography](topic_cartography.md) topic page.
 For example, let's add a legend, barscale, and shaded relief to the map:
 
 ```python
+from grass.tools import Tools
+
+# Create an object to access tools
+tools = Tools()
 
 # Compute shaded relief
-gs.run_command("r.relief", input="elevation", output="relief")
+tools.r_relief(input="elevation", output="relief")
 
 # Create a new map
 m = gj.Map()
@@ -176,10 +180,10 @@ maps and play a continuous loop.
 # Create a series of relief maps with different angles
 directions = [0, 90, 180, 270]
 for azimuth in directions:
-    gs.run_command("r.relief",
-                   input="elevation",
-                   output=f"relief_{azimuth}",
-                   azimuth=azimuth)
+    tools.r_relief(
+        input="elevation",
+        output=f"relief_{azimuth}",
+        azimuth=azimuth)
 m = gj.SeriesMap()
 m.add_rasters(f"relief_{azimuth}" for azimuth in directions)
 m.d_vect(map="roads")
@@ -199,30 +203,30 @@ series map of overland water flow:
 
 ```python
 # Zoom in to the study area
-gs.run_command("g.region", n=226040, s=223780, e=639170, w=636190)
+tools.g_region(n=226040, s=223780, e=639170, w=636190)
 # Compute topography dx and dy derivatives
-gs.run_command("r.slope.aspect",
-               elevation="elevation",
-               dx="dx",
-               dy="dy")
+tools.r_slope_aspect(elevation="elevation", dx="dx", dy="dy")
 # Compute overland flow
-gs.run_command("r.sim.water",
-               flags="t",
-               elevation="elevation",
-               dx="dx",
-               dy="dy",
-               depth="depth",
-               niterations=30)
+tools.r_sim_water(
+    flags="t",
+    elevation="elevation",
+    dx="dx",
+    dy="dy",
+    depth="depth",
+    niterations=30)
 
 # Create a time series
-gs.run_command("t.create",
-               output="depth",
-               temporaltype="relative",
-               title="Overland flow depth",
-               description="Overland flow depth")
+tools.t_create(
+    output="depth",
+    temporaltype="relative",
+    title="Overland flow depth",
+    description="Overland flow depth")
 # Register the time series
-maps = gs.list_strings(type="raster", pattern="depth*")
-gs.run_command("t.register", input="depth", maps=maps)
+maps = [
+    item["fullname"]
+    for item in tools.g_list(type="raster", pattern="depth*", format="json")
+]
+tools.t_register(input="depth", maps=maps)
 
 # Create a time series map
 flow_map = gj.TimeSeriesMap()
@@ -253,6 +257,10 @@ For complete documentation on the `grass.jupyter` package, see the
 [grass.jupyter](https://grass.osgeo.org/grass-stable/manuals/libpython/grass.jupyter.html)
 library documentation page.
 
+For complete documentation on the `grass.tools` package, see the
+[grass.tools](https://grass.osgeo.org/grass-stable/manuals/libpython/grass.tools.html)
+library documentation page.
+
 For complete documentation on the `grass.script` package, see the
 [grass.script](https://grass.osgeo.org/grass-stable/manuals/libpython/script_intro.html)
 library documentation page.