Accept target_values=None in the surface_* trio like the proximity trio (#3712)

surface_distance, surface_allocation and surface_direction declared
target_values: list = [] while proximity, allocation, direction and
cost_distance declare None and normalise it in the body. Passing None
therefore reached np.asarray(None, dtype=float64) and blew up inside the
_seed_sources numba kernel with a type-inference error that never
mentioned target_values.

Switch the three defaults to None, normalise in _compute, and update the
docstring. Not a breaking change: None and [] both mean 'every non-zero
finite pixel is a source'.

Author: brendancol

xrspatial/surface_distance.py

@@ -1297,6 +1297,8 @@ def _chunk_func(source_block, elev_block):
 def _compute(raster, elevation, x, y, target_values, max_distance,
              connectivity, method, mode):
     """Core dispatcher for surface_distance / allocation / direction."""
+    if target_values is None:
+        target_values = []
     _validate_raster(raster, func_name='surface_distance', name='raster')
     _validate_raster(elevation, func_name='surface_distance',
                      name='elevation')
@@ -1421,7 +1423,7 @@ def surface_distance(
     elevation: xr.DataArray,
     x: str = "x",
     y: str = "y",
-    target_values: list = [],
+    target_values: list = None,
     max_distance: float = np.inf,
     connectivity: int = 8,
     method: str = 'planar',
@@ -1445,9 +1447,9 @@ def surface_distance(
         Name of the x coordinate.
     y : str, default='y'
         Name of the y coordinate.
-    target_values : list, optional
+    target_values : list, default=None
         Specific pixel values in *raster* to treat as sources.
-        If empty, all non-zero finite pixels are sources.
+        If ``None`` or empty, all non-zero finite pixels are sources.
     max_distance : float, default=np.inf
         Maximum surface distance.  Pixels beyond this budget are NaN.
         A finite value enables efficient Dask parallelisation.
@@ -1482,7 +1484,7 @@ def surface_allocation(
     elevation: xr.DataArray,
     x: str = "x",
     y: str = "y",
-    target_values: list = [],
+    target_values: list = None,
     max_distance: float = np.inf,
     connectivity: int = 8,
     method: str = 'planar',
@@ -1524,7 +1526,7 @@ def surface_direction(
     elevation: xr.DataArray,
     x: str = "x",
     y: str = "y",
-    target_values: list = [],
+    target_values: list = None,
     max_distance: float = np.inf,
     connectivity: int = 8,
     method: str = 'planar',

xrspatial/tests/test_surface_distance.py

@@ -359,6 +359,42 @@ def test_target_values():
     assert sd[0, 1] == pytest.approx(2.0, abs=1e-5)
 
 
+@pytest.mark.parametrize("backend",
+                         ['numpy', 'cupy', 'dask+numpy', 'dask+cupy'])
+@pytest.mark.parametrize("func",
+                         [surface_distance, surface_allocation,
+                          surface_direction])
+def test_target_values_none_matches_empty_list(backend, func):
+    """target_values=None means the same thing as [] on every backend.
+
+    The proximity trio and cost_distance already accept None; issue #3712
+    reported that the surface_* trio raised a numba TypingError instead.
+    """
+    source = np.zeros((6, 6), dtype=np.float64)
+    source[0, 0] = 1.0
+    source[5, 5] = 3.0
+    elev = np.arange(36, dtype=np.float64).reshape(6, 6) * 0.5
+
+    raster = _make_raster(source, backend)
+    elevation = _make_raster(elev, backend)
+
+    with_none = _compute(func(raster, elevation, target_values=None,
+                              max_distance=2.0))
+    with_empty = _compute(func(raster, elevation, target_values=[],
+                               max_distance=2.0))
+
+    np.testing.assert_allclose(with_none, with_empty, equal_nan=True)
+
+
+def test_target_values_default_is_not_mutable():
+    """The public signatures must not carry a mutable default."""
+    import inspect
+
+    for func in (surface_distance, surface_allocation, surface_direction):
+        default = inspect.signature(func).parameters['target_values'].default
+        assert default is None, f"{func.__name__} has a mutable default"
+
+
 # ---------------------------------------------------------------------------
 # Tests — connectivity
 # ---------------------------------------------------------------------------