Merge pull request #11822 from rouault/python_user_friendly_alg_arg

Python bindings: add syntaxic sugar to get/set algorithm arguments + doc

autotest/utilities/test_gdalalg_info.py

@@ -17,8 +17,7 @@
 
 
 def get_info_alg():
-    reg = gdal.GetGlobalAlgorithmRegistry()
-    return reg.InstantiateAlg("info")
+    return gdal.GetGlobalAlgorithmRegistry()["info"]
 
 
 @pytest.mark.parametrize(
@@ -31,7 +30,7 @@ def get_info_alg():
 def test_gdalalg_info_on_raster(args):
     info = get_info_alg()
     assert info.ParseRunAndFinalize(args)
-    output_string = info.GetActualAlgorithm().GetArg("output-string").Get()
+    output_string = info["output-string"]
     assert output_string.startswith("Driver: GTiff/GeoTIFF")
 
 
@@ -57,7 +56,7 @@ def test_gdalalg_info_on_raster_invalid_arg():
 def test_gdalalg_info_on_vector(args):
     info = get_info_alg()
     assert info.ParseRunAndFinalize(args)
-    output_string = info.GetActualAlgorithm().GetArg("output-string").Get()
+    output_string = info["output-string"]
     assert output_string.startswith("INFO: Open of")
 
 
@@ -75,8 +74,7 @@ def test_gdalalg_info_invalid_arg():
 
 def test_gdalalg_info_run_cannot_be_run():
     info = get_info_alg()
-    ds = gdal.GetDriverByName("MEM").Create("", 1, 1)
-    info.GetArg("input").SetDataset(ds)
+    info["input"] = gdal.GetDriverByName("MEM").Create("", 1, 1)
     with pytest.raises(Exception, match="method should not be called directly"):
         info.Run()
 
@@ -108,6 +106,6 @@ def test_gdalalg_info_mixed_raster_vector_with_invalid_arg(tmp_vsimem):
 def test_gdalalg_info_mixed_run_without_arg(tmp_vsimem):
 
     info = get_info_alg()
-    info.GetArg("input").Get().SetName("data/utmsmall.tif")
+    info["input"] = "data/utmsmall.tif"
     with pytest.raises(Exception, match="should not be called directly"):
         assert info.Run()

autotest/utilities/test_gdalalg_pipeline.py

@@ -17,8 +17,7 @@
 
 
 def get_pipeline_alg():
-    reg = gdal.GetGlobalAlgorithmRegistry()
-    return reg.InstantiateAlg("pipeline")
+    return gdal.GetGlobalAlgorithmRegistry()["pipeline"]
 
 
 def test_gdalalg_pipeline_read_and_write(tmp_vsimem):
@@ -44,6 +43,6 @@ def my_progress(pct, msg, user_data):
 def test_gdalalg_pipeline_mixed_run_without_arg(tmp_vsimem):
 
     pipeline = get_pipeline_alg()
-    pipeline.GetArg("input").Get().SetDataset(gdal.OpenEx("../ogr/data/poly.shp"))
+    pipeline["input"] = gdal.OpenEx("../ogr/data/poly.shp")
     with pytest.raises(Exception, match="should not be called directly"):
         assert pipeline.Run()

autotest/utilities/test_gdalalg_raster_convert.py

@@ -53,7 +53,7 @@ def test_gdalalg_raster_convert_to_mem():
     convert = get_convert_alg()
     assert convert.ParseCommandLineArguments(["--of=MEM", "data/utmsmall.tif", ""])
     assert convert.Run()
-    out_ds = convert.GetArg("output").Get().GetDataset()
+    out_ds = convert["output"].GetDataset()
     assert out_ds.GetRasterBand(1).Checksum() == 50054
 
 
@@ -82,8 +82,7 @@ def test_gdalalg_raster_convert_append(tmp_vsimem):
 
 def test_gdalalg_raster_convert_error_output_already_set():
     convert = get_convert_alg()
-    ds = gdal.GetDriverByName("MEM").Create("", 1, 1)
-    convert.GetArg("output").Get().SetDataset(ds)
+    convert["output"] = gdal.GetDriverByName("MEM").Create("", 1, 1)
     assert convert.ParseCommandLineArguments(["data/utmsmall.tif"])
     with pytest.raises(
         Exception,

autotest/utilities/test_gdalalg_raster_edit.py

@@ -17,9 +17,7 @@
 
 
 def get_edit_alg():
-    reg = gdal.GetGlobalAlgorithmRegistry()
-    raster = reg.InstantiateAlg("raster")
-    return raster.InstantiateSubAlgorithm("edit")
+    return gdal.GetGlobalAlgorithmRegistry()["raster"]["edit"]
 
 
 def test_gdalalg_raster_edit_read_only(tmp_vsimem):
@@ -28,7 +26,7 @@ def test_gdalalg_raster_edit_read_only(tmp_vsimem):
     gdal.FileFromMemBuffer(tmp_filename, open("../gcore/data/byte.tif", "rb").read())
 
     pipeline = get_edit_alg()
-    pipeline.GetArg("dataset").Set(gdal.OpenEx(tmp_filename))
+    pipeline["dataset"] = gdal.OpenEx(tmp_filename)
     with pytest.raises(
         Exception, match="edit: Dataset should be opened in update mode"
     ):

autotest/utilities/test_gdalalg_raster_info.py

@@ -19,9 +19,7 @@
 
 
 def get_info_alg():
-    reg = gdal.GetGlobalAlgorithmRegistry()
-    raster = reg.InstantiateAlg("raster")
-    return raster.InstantiateSubAlgorithm("info")
+    return gdal.GetGlobalAlgorithmRegistry()["raster"]["info"]
 
 
 def test_gdalalg_raster_info_stdout():
@@ -41,7 +39,7 @@ def test_gdalalg_raster_info_stdout():
 def test_gdalalg_raster_info():
     info = get_info_alg()
     assert info.ParseRunAndFinalize(["--format=text", "data/utmsmall.tif"])
-    output_string = info.GetArg("output-string").Get()
+    output_string = info["output-string"]
     assert output_string.startswith("Driver: GTiff/GeoTIFF")
 
 
@@ -50,45 +48,45 @@ def test_gdalalg_raster_info_mm_checksum():
     assert info.ParseRunAndFinalize(
         ["--format=text", "--mm", "--checksum", "data/utmsmall.tif"]
     )
-    output_string = info.GetArg("output-string").Get()
+    output_string = info["output-string"]
     assert "   Computed Min/Max=0.000,255.000" in output_string
     assert "Checksum=" in output_string
 
 
 def test_gdalalg_raster_info_stats():
     info = get_info_alg()
     ds = gdal.Translate("", "../gcore/data/byte.tif", format="MEM")
-    info.GetArg("input").SetDataset(ds)
+    info["input"] = ds
     assert info.ParseRunAndFinalize(["--stats"])
-    output_string = info.GetArg("output-string").Get()
+    output_string = info["output-string"]
     j = json.loads(output_string)
     assert "stdDev" in j["bands"][0]
 
 
 def test_gdalalg_raster_info_approx_stats():
     info = get_info_alg()
     ds = gdal.Translate("", "../gcore/data/byte.tif", format="MEM")
-    info.GetArg("input").SetDataset(ds)
+    info["input"] = ds
     assert info.ParseRunAndFinalize(["--approx-stats"])
-    output_string = info.GetArg("output-string").Get()
+    output_string = info["output-string"]
     j = json.loads(output_string)
     assert "stdDev" in j["bands"][0]
 
 
 def test_gdalalg_raster_info_hist():
     info = get_info_alg()
     ds = gdal.Translate("", "../gcore/data/byte.tif", format="MEM")
-    info.GetArg("input").SetDataset(ds)
+    info["input"] = ds
     assert info.ParseRunAndFinalize(["--hist"])
-    output_string = info.GetArg("output-string").Get()
+    output_string = info["output-string"]
     j = json.loads(output_string)
     assert "histogram" in j["bands"][0]
 
 
 def test_gdalalg_raster_info_no_options():
     info = get_info_alg()
     ds = gdal.Translate("", "../gcore/data/byte.tif", format="MEM")
-    info.GetArg("input").SetDataset(ds)
+    info["input"] = ds
     assert info.ParseRunAndFinalize(
         ["--no-gcp", "--no-md", "--no-ct", "--no-fl", "--no-nodata", "--no-mask"]
     )
@@ -98,9 +96,9 @@ def test_gdalalg_raster_info_list_mdd():
     info = get_info_alg()
     ds = gdal.Translate("", "../gcore/data/byte.tif", format="MEM")
     ds.SetMetadataItem("foo", "bar", "MY_DOMAIN")
-    info.GetArg("input").SetDataset(ds)
+    info["input"] = ds
     assert info.ParseRunAndFinalize(["--list-mdd"])
-    output_string = info.GetArg("output-string").Get()
+    output_string = info["output-string"]
     j = json.loads(output_string)
     assert "MY_DOMAIN" in j["metadata"]["metadataDomains"]
 
@@ -109,9 +107,9 @@ def test_gdalalg_raster_info_mdd_all():
     info = get_info_alg()
     ds = gdal.Translate("", "../gcore/data/byte.tif", format="MEM")
     ds.SetMetadataItem("foo", "bar", "MY_DOMAIN")
-    info.GetArg("input").SetDataset(ds)
+    info["input"] = ds
     assert info.ParseRunAndFinalize(["--mdd=all"])
-    output_string = info.GetArg("output-string").Get()
+    output_string = info["output-string"]
     j = json.loads(output_string)
     assert j["metadata"] == {
         "": {"AREA_OR_POINT": "Area"},
@@ -128,7 +126,7 @@ def test_gdalalg_raster_info_list_subdataset():
     assert info.ParseRunAndFinalize(
         ["--input=../gcore/data/tiff_with_subifds.tif", "--subdataset=2"]
     )
-    output_string = info.GetArg("output-string").Get()
+    output_string = info["output-string"]
     j = json.loads(output_string)
     assert j["description"] == "GTIFF_DIR:2:../gcore/data/tiff_with_subifds.tif"
 
@@ -149,7 +147,7 @@ def test_gdalalg_raster_info_list_subdataset_error_cannot_open_subdataset():
     ds = gdal.GetDriverByName("MEM").Create("", 1, 1)
     ds.SetMetadataItem("SUBDATASET_1_DESC", "desc", "SUBDATASETS")
     ds.SetMetadataItem("SUBDATASET_1_NAME", "i_do_not_exist", "SUBDATASETS")
-    info.GetArg("input").SetDataset(ds)
+    info["input"] = ds
     with pytest.raises(
         Exception,
         match="i_do_not_exist",