fix(waterdata.xarray): accurate stats docstring; pin wrapper->_fetch routing

Addresses two review gaps:

- The shared wrapper docstring promised "a CF-conventions Dataset with series
  metadata populated", which is false for the stats wrappers -- _build_stats
  emits a flat, preliminary Dataset with only dataset-level provenance.
  Parametrize _xr_doc(cf_metadata=...) so get_stats_por/get_stats_date_range
  describe their actual output.

- The include_hash strip was only tested on _fetch in isolation; nothing
  pinned the wrappers to route through it. Add a test that monkeypatches
  _fetch and asserts every public wrapper delegates to it (and forwards
  include_hash for _fetch to drop), guarding against a wrapper reverting to a
  direct getter call.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Author: thodson-usgs

dataretrieval/waterdata/xarray.py

@@ -340,14 +340,25 @@ def _fetch(func, args, kwargs):
     return func(*args, **kwargs)
 
 
-def _xr_doc(func):
-    """Prepend an xarray note to the wrapped getter's docstring."""
+def _xr_doc(func, *, cf_metadata=True):
+    """Prepend an xarray note to the wrapped getter's docstring.
+
+    ``cf_metadata=False`` describes the preliminary stats path, which emits a
+    flat Dataset without per-variable CF attributes.
+    """
+    returns = (
+        "a CF-conventions ``xarray.Dataset`` with series metadata populated"
+        if cf_metadata
+        else (
+            "a preliminary, flat ``xarray.Dataset`` (dataset-level provenance "
+            "only; per-variable CF metadata is not yet populated)"
+        )
+    )
     note = (
         "    xarray wrapper: same arguments as "
-        f"``dataretrieval.waterdata.{func.__name__}``, but returns a\n"
-        "    CF-conventions ``xarray.Dataset`` with series metadata populated.\n"
-        "    Hash-valued ID columns are always omitted here; the\n"
-        "    ``include_hash`` flag does not apply.\n\n"
+        f"``dataretrieval.waterdata.{func.__name__}``, but returns\n"
+        f"    {returns}. Hash-valued ID columns are always omitted here;\n"
+        "    the ``include_hash`` flag does not apply.\n\n"
     )
     return note + (func.__doc__ or "")
 
@@ -391,7 +402,7 @@ def wrapper(*args, **kwargs):
         df, base_meta = _fetch(func, args, kwargs)
         return _build_stats(df, base_meta, service)
 
-    wrapper.__doc__ = _xr_doc(func)
+    wrapper.__doc__ = _xr_doc(func, cf_metadata=False)
     return wrapper
 
 

tests/waterdata_xarray_test.py

@@ -195,3 +195,24 @@ def fake_getter(*args, **kwargs):
     assert (df, meta) == ("df", "meta")
     assert "include_hash" not in captured
     assert captured == {"parameter_code": "00060"}
+
+
+def test_every_wrapper_routes_through_fetch(monkeypatch):
+    # Pin the wiring: each public wrapper must delegate the underlying fetch to
+    # _fetch (which is what strips include_hash). Guards against a wrapper
+    # quietly reverting to calling the getter directly and leaking the flag.
+    seen = []
+
+    def spy(func, args, kwargs):
+        seen.append(dict(kwargs))
+        return pd.DataFrame(), SimpleNamespace(url=None)  # empty -> no network
+
+    monkeypatch.setattr(wdx, "_fetch", spy)
+    for name in wdx.__all__:
+        seen.clear()
+        ds = getattr(wdx, name)(monitoring_location_id="USGS-1", include_hash=True)
+        assert isinstance(ds, xr.Dataset)
+        assert len(seen) == 1, f"{name} did not route through _fetch"
+        # the wrapper hands include_hash to _fetch; _fetch is what drops it
+        # (asserted in test_fetch_strips_include_hash)
+        assert seen[0].get("include_hash") is True