resample: add type annotations to public signature (#2544)

.claude/sweep-api-consistency-state.csv

@@ -3,4 +3,5 @@ geotiff,2026-05-18,2106,MEDIUM,3,"Sweep 2026-05-18 (deep-sweep-api-consistency-g
 polygonize,2026-05-19,2148,HIGH,1;3,"Sweep 2026-05-19 (deep-sweep-api-consistency-polygonize-2026-05-19). 1 MEDIUM Cat 3 finding fixed in this branch (#2148): polygonize() was the only public vector/raster conversion function without a return type annotation. Sieve/contours/rasterize/clip_polygon all declare one. Fix adds a Union return annotation (numpy tuple | awkward tuple | geopandas GeoDataFrame | spatialpandas GeoDataFrame | geojson dict) using TYPE_CHECKING forward refs for optional deps, and expands the docstring Returns section to enumerate the per-return_type shapes. 1 HIGH Cat 1 finding NOT fixed in this PR -- cross-module rename: polygonize uses `connectivity` (int 4|8) while sieve uses `neighborhood` (int 4|8) for the identical rook/queen pixel-connectivity concept. Industry convention (GDAL, rasterio.features.sieve) favours `connectivity`; the deprecation shim belongs in sieve.py, not polygonize, so this is out of scope for the polygonize-scoped sweep branch. Documented here for the next sieve sweep pass. 1 LOW Cat 1 cross-cutting: polygonize/sieve/clip_polygon use `raster` while contours and many older modules use `agg` for the input DataArray -- library-wide drift, not filed per-module per sweep template. Cat 2 return-shape: polygonize returns tuple/GeoDataFrame/dict by return_type; consistent with contours' tuple/GeoDataFrame dispatch. No Cat 4 (no mutable defaults; connectivity=4 default matches sieve neighborhood=4 default). No Cat 5 (polygonize re-exported in xrspatial/__init__.py; no orphan API; no __all__ but consistent with module convention). cuda-validated: cupy backend accepts identical kwargs, smoke-tested with cupy DataArray on host with CUDA_AVAILABLE."
 rasterize,2026-05-21,2250,MEDIUM,3,"Sweep 2026-05-21 (deep-sweep-api-consistency-rasterize-2026-05-21). 1 MEDIUM Cat 3 finding fixed in this branch (#2250): rasterize() was missing type annotations on geometries, columns, and merge (3 of 16 public params); the other 13 plus the return type were annotated. The docstring already declared the intended types so this was a doc-vs-signature drift. Fix annotates geometries: Any (because the accepted GeoDataFrame / dask_geopandas / iterable union spans optional deps), columns: Optional[Sequence[str]], merge: Union[str, Callable]. Regression test in test_rasterize_signature_annot_2250.py pins every param + the return annotation so a future contributor can't silently drop annotations again. Cross-module drift documented but not filed per template: clip_polygon(nodata) vs rasterize(fill) same concept different name; clip_polygon(name: Optional[str]=None) vs rasterize(name: str='rasterize') default convention; polygonize(column_name) vs rasterize(column) column selector. No Cat 1 in-module rename, no Cat 2 return drift (returns xr.DataArray as documented), no Cat 4 mutable defaults, no Cat 5 orphan API (rasterize is the only public symbol from the module and is re-exported in __init__). cuda-validated: cupy backend accepts identical kwargs, smoke-tested with use_cuda=True on host with CUDA_AVAILABLE."
 reproject,2026-05-10,1570,HIGH,2;5,"Filed cross-module attrs['vertical_crs'] type collision (string vs EPSG int) vs xrspatial.geotiff. Fixed in PR (TBD): reproject now writes EPSG int and preserves friendly token under vertical_datum. MEDIUM kwarg-order drift (transform_precision vs chunk_size) and missing type hints vs geotiff documented but not fixed (cosmetic, kwarg-only)."
+resample,2026-05-27,2544,MEDIUM,3,"Sweep 2026-05-27 (deep-sweep-api-consistency-resample-2026-05-27). 1 MEDIUM Cat 3 finding fixed in this branch (#2544): resample() was the only public symbol in xrspatial.resample without type annotations on any parameter or return; siblings slope/aspect/hillshade/curvature all annotate `agg: xr.DataArray` and `-> xr.DataArray`. Fix adds annotations matching the docstring (agg: xr.DataArray; scale_factor / target_resolution: float | tuple[float, float] | None; method: str; nodata: float | None; name: str) and a `-> xr.DataArray` return type, plus a docstring note that the @supports_dataset decorator accepts Dataset too. Regression test test_resample_signature_annot_2544.py pins every param and the return annotation. Other findings documented but not filed per template: (MEDIUM Cat 1 cross-module) `method` (resample) vs `resampling` (reproject/merge) -- same conceptual parameter, different name, cross-cutting rename, needs design issue. (LOW Cat 1 cross-cutting) first-arg `agg` (resample/slope/aspect/...) vs `raster` (reproject/rasterize/polygonize/sieve) -- library-wide drift, not per-module. (LOW Cat 5) ALL_METHODS imported by tests but not in __all__ (module has no __all__); borderline orphan but used for test parametrisation only. No Cat 2 (returns xr.DataArray as documented). No Cat 4 mutable defaults. resample is exported in xrspatial/__init__.py. cuda-validated: cupy backend smoke-tested with nearest, bilinear, and average on host with CUDA_AVAILABLE=True."
 zonal,2026-05-27,2521,HIGH,1;3;5,"Sweep 2026-05-27 (deep-sweep-api-consistency-zonal-2026-05-27). 1 HIGH Cat 1 finding fixed in this branch (#2521): crop() used zones_ids while stats/crosstab use zone_ids -- pure typo creating a TypeError trap when switching between sibling zonal functions. Fix accepts both, deprecates zones_ids with DeprecationWarning, raises if both supplied, raises if neither. All call sites in tests migrated to canonical zone_ids; legacy zones_ids paths covered by new regression tests. Other findings not fixed in this PR: (HIGH Cat 1+4) nodata vs nodata_values drift across stats/crosstab (nodata_values=None) vs apply/hypsometric_integral (nodata=0) -- different name AND different default, breaks substitutability; cross-function scope, needs a design issue. (MEDIUM Cat 3) crosstab docstring says 'layer: int, default=0' but signature is 'Optional[int] = None'. (MEDIUM Cat 3) hypsometric_integral lacks all type annotations; apply and crop lack return type annotations (siblings have them). (MEDIUM Cat 5) get_full_extent has public-style docstring with 'from xrspatial.zonal import get_full_extent' example but is not in __init__.py -- borderline orphan, but minor utility. (LOW Cat 3) apply() docstring mixes 'values' parameter name with 'agg' prose; example returns np.array shape (not DataArray) while function actually returns a DataArray. Cross-cutting: zones/raster as first-arg name varies (zonal.stats uses zones; zonal.regions/trim use raster). Regions/trim are single-array operations on the zone raster itself, so the rename arguably matches the role. Documented, not filed. cuda-validated: CUDA_AVAILABLE=True on this host."

xrspatial/resample.py

@@ -1180,23 +1180,25 @@ def _apply_nodata_mask(agg, nodata):
 
 @supports_dataset
 def resample(
-    agg,
-    scale_factor=None,
-    target_resolution=None,
-    method='nearest',
-    nodata=None,
-    name='resample',
-):
+    agg: xr.DataArray,
+    scale_factor: float | tuple[float, float] | None = None,
+    target_resolution: float | tuple[float, float] | None = None,
+    method: str = 'nearest',
+    nodata: float | None = None,
+    name: str = 'resample',
+) -> xr.DataArray:
     """Change raster resolution without changing its CRS.
 
     Exactly one of *scale_factor* or *target_resolution* must be given.
 
     Parameters
     ----------
-    agg : xarray.DataArray
+    agg : xarray.DataArray or xarray.Dataset
         Input raster. 2-D ``(y, x)`` or 3-D ``(band, y, x)``. For 3-D
         inputs each band is resampled independently and the leading
-        non-spatial coordinate is preserved.
+        non-spatial coordinate is preserved. If a Dataset is passed,
+        the operation is applied to each data variable independently
+        (via the ``@supports_dataset`` decorator).
     scale_factor : float or (float, float), optional
         Multiplicative factor applied to the number of pixels.
         ``0.5`` halves the pixel count (doubles the cell size);

xrspatial/tests/test_resample_signature_annot_2544.py

@@ -0,0 +1,47 @@
+"""Regression: resample() public signature carries type annotations on every
+parameter and on the return type.
+
+Pins the fix for issue #2544 (api-consistency sweep, Cat 3 MEDIUM). Without
+this test, future contributors can drop annotations on ``agg``,
+``scale_factor``, ``target_resolution``, ``method``, ``nodata``, or ``name``
+without surfacing the drift between docstring and signature -- IDE hints,
+mypy, and sphinx autodoc all silently lose information.
+"""
+from __future__ import annotations
+
+import inspect
+
+from xrspatial.resample import resample
+
+
+def test_resample_every_param_is_annotated():
+    sig = inspect.signature(resample)
+    unannotated = [
+        name for name, p in sig.parameters.items()
+        if p.annotation is inspect.Parameter.empty
+    ]
+    assert not unannotated, (
+        f"resample() must annotate every public parameter; "
+        f"missing annotation(s): {unannotated}"
+    )
+
+
+def test_resample_return_is_annotated():
+    sig = inspect.signature(resample)
+    assert sig.return_annotation is not inspect.Signature.empty, (
+        "resample() must declare a return annotation"
+    )
+
+
+def test_resample_2544_specific_params_annotated():
+    """Pin every public param so a future regression names them directly
+    in the failure message.
+    """
+    sig = inspect.signature(resample)
+    expected = ('agg', 'scale_factor', 'target_resolution',
+                'method', 'nodata', 'name')
+    for name in expected:
+        assert sig.parameters[name].annotation is not inspect.Parameter.empty, (
+            f"resample({name}=...) lost its type annotation; "
+            f"this regressed issue #2544"
+        )