test(python): RS_SetBandNoDataValue null value clears the band's nodata

Author: james-willis

docs/reference/sql/rs_setbandnodatavalue.qmd

@@ -19,17 +19,19 @@
 title: RS_SetBandNoDataValue
 description: >
   Sets the nodata value of the specified band, packing the value into the band's
-  native data type. A null raster, band, or nodata value yields a null raster.
-  This is metadata-only: raster cell values are not modified.
+  native data type. A null raster or band yields a null raster; a null nodata
+  value instead clears the addressed band's nodata. This is metadata-only:
+  raster cell values are not modified.
 kernels:
   - returns: raster
     args:
     - raster
     - name: nodata
       type: float64
       description: >
-        Nodata value to set. The raster must be single-band; for a multiband
-        raster, specify the band with the three-argument form below.
+        Nodata value to set, or null to clear the band's nodata. The raster must
+        be single-band; for a multiband raster, specify the band with the
+        three-argument form below.
   - returns: raster
     args:
     - raster
@@ -38,7 +40,7 @@ kernels:
       description: Band index (1-based).
     - name: nodata
       type: float64
-      description: Nodata value to set on the band.
+      description: Nodata value to set on the band, or null to clear it.
 ---
 
 ## Examples
@@ -50,3 +52,9 @@ SELECT RS_BandNoDataValue(RS_SetBandNoDataValue(RS_Example(), 1, 0), 1);
 ```sql
 SELECT RS_BandNoDataValue(RS_SetBandNoDataValue(RS_Example(), 2, 255), 2);
 ```
+
+A null nodata value clears the band's existing nodata, so the getter reads back null:
+
+```sql
+SELECT RS_BandNoDataValue(RS_SetBandNoDataValue(RS_Example(), 1, CAST(NULL AS DOUBLE)), 1);
+```

python/sedonadb/tests/functions/test_raster_functions.py

@@ -278,9 +278,10 @@ def test_rs_setgeoreference_esri_skewed_roundtrips():
         # Three-arg form targets a specific band; read it back with the getter.
         ("RS_BandNoDataValue(RS_SetBandNoDataValue(RS_Example(), 1, 0), 1)", 0.0),
         ("RS_BandNoDataValue(RS_SetBandNoDataValue(RS_Example(), 2, 255), 2)", 255.0),
-        # A null nodata value yields a null raster, so the getter returns null.
+        # A null nodata value clears the addressed band's nodata (band 1 starts
+        # at 127), so the getter then reads back null for that band.
         (
-            "RS_BandNoDataValue(RS_SetBandNoDataValue(RS_Example(), CAST(NULL AS DOUBLE)), 1)",
+            "RS_BandNoDataValue(RS_SetBandNoDataValue(RS_Example(), 1, CAST(NULL AS DOUBLE)), 1)",
             None,
         ),
     ],
@@ -289,12 +290,15 @@ def test_rs_setbandnodatavalue(expr, expected):
     SedonaDB().assert_query_result(f"SELECT {expr}", expected)
 
 
-def test_rs_setbandnodatavalue_two_arg_requires_single_band():
+@pytest.mark.parametrize("value", ["0", "CAST(NULL AS DOUBLE)"])
+def test_rs_setbandnodatavalue_two_arg_requires_single_band(value):
     # The 2-arg form is ambiguous on a multiband raster (RS_Example has multiple
-    # bands), so it errors rather than silently setting only band 1.
+    # bands), so it errors rather than silently setting only band 1. A null value
+    # clears the band's nodata rather than short-circuiting to a null raster, so
+    # it hits the same ambiguity and errors too.
     with pytest.raises(Exception, match="specify which band"):
         SedonaDB().assert_query_result(
-            "SELECT RS_SetBandNoDataValue(RS_Example(), 0)", None
+            f"SELECT RS_SetBandNoDataValue(RS_Example(), {value})", None
         )