docs+tests(waterdata): apply /simplify sweep — close stale refs and consolidate sleep helpers

Doc-vs-code drift left by the recent inlining + the 01c734b transport-error fix:

- multi_value_chunked Raises (chunking.py:1716): now lists transport
  errors alongside 429/5xx — the surface the 01c734b sweep missed.
- _combine_raw docstring (chunking.py:1444): "record" → "the track
  closure in _run" since record() was inlined in c63da1b.
- track closure docstring (chunking.py:1627): "+ record +" → "+
  result-store +" for the same reason.
- _aiozero test helper docstring: tightened to "asyncio.sleep (via the
  chunking module's binding)" — chunking.asyncio IS the asyncio module.
- Test section banner: "drivers" (plural) → "driver" (only one
  remaining after the async-only collapse).

Simplifications:

- Drop the redundant 3-line comment above the inlined
  `return self.finalize(*self._combine_raw())` — partial_frame's
  docstring and the class Attributes already say the same thing twice.
- Test sleep-faker variants consolidated: replaced 3 inline
  `async def _noslept(_d): return None` blocks with the existing
  module-level `_aiozero`; replaced 2 inline `_record` closures with a
  new module-level `_recording_sleep(slept)` factory.

Net −8 lines. 296 offline tests pass; ruff clean.

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

Author: thodson-usgs

dataretrieval/waterdata/chunking.py

@@ -1441,10 +1441,11 @@ def _combine_raw(self) -> tuple[pd.DataFrame, httpx.Response]:
         Frames concatenate in sub-args *index* order (``sorted`` keys —
         deterministic, independent of parallel completion order). The
         aggregated response takes its headers from the most-recently-
-        *completed* sub-request: ``record`` is the only writer of
-        ``self._chunks`` and ``dict`` preserves insertion order, so the
-        chunks' natural order is completion order and the last one carries
-        the freshest ``x-ratelimit-remaining``.
+        *completed* sub-request: the ``track`` closure in :meth:`_run`
+        is the only writer of ``self._chunks`` and ``dict`` preserves
+        insertion order, so the chunks' natural order is completion
+        order and the last one carries the freshest
+        ``x-ratelimit-remaining``.
 
         Returns
         -------
@@ -1624,7 +1625,7 @@ async def _run(self, max_concurrent: int | None) -> tuple[pd.DataFrame, Any]:
                 async def track(
                     index: int, args: dict[str, Any]
                 ) -> tuple[pd.DataFrame, httpx.Response]:
-                    """One sub-request (with retry) + record + progress tick."""
+                    """One sub-request (with retry) + result-store + progress tick."""
                     result = await _retry(lambda: self.fetch(args), self.retry_policy)
                     self._chunks[index] = result
                     if reporter is not None:
@@ -1667,9 +1668,6 @@ async def track(
                     interrupted, exc = first_transient
                     raise interrupted from exc
 
-        # Apply the injected ``finalize`` to the raw combined result.
-        # ``partial_frame`` / ``partial_response`` deliberately bypass
-        # ``finalize`` to stay cheap and side-effect-free.
         return self.finalize(*self._combine_raw())
 
 
@@ -1713,9 +1711,9 @@ def multi_value_chunked(
     RequestTooLarge
         If no plan can fit ``url_limit``.
     ChunkInterrupted
-        On a mid-execution 429 (:class:`QuotaExhausted`) or 5xx
-        (:class:`ServiceInterrupted`). See :class:`ChunkedCall` for
-        the resume semantics.
+        On a mid-execution transient — 429, 5xx, or a bare transport
+        error: :class:`QuotaExhausted` for 429, :class:`ServiceInterrupted`
+        for the rest. See :class:`ChunkedCall` for the resume semantics.
 
     See Also
     --------

tests/waterdata_chunking_test.py

@@ -60,15 +60,26 @@
 
 
 def _aiozero(_d):
-    """An async no-op sleep — monkeypatched over the ``chunking`` module's
-    ``asyncio.sleep`` so retry backoff doesn't actually wait in tests."""
+    """An async no-op sleep — monkeypatched over ``asyncio.sleep`` (via
+    the chunking module's binding) so retry backoff doesn't wait in tests."""
 
     async def _noop():
         return None
 
     return _noop()
 
 
+def _recording_sleep(slept):
+    """An ``_aiozero`` variant that appends each requested delay to ``slept``
+    before resolving — for tests that need to assert what would have been waited."""
+
+    def _record(delay):
+        slept.append(delay)
+        return _aiozero(delay)
+
+    return _record
+
+
 class _FakeReq:
     """Stand-in for ``httpx.Request`` whose ``_request_bytes`` shape
     is ``len(str(url)) + len(content)``."""
@@ -1487,7 +1498,7 @@ def test_combine_chunk_responses_does_not_mutate_input_urls():
 
 
 # ---------------------------------------------------------------------------
-# Retry-with-backoff: RetryPolicy + _retryable + drivers + decorator wiring.
+# Retry-with-backoff: RetryPolicy + _retryable + driver + decorator wiring.
 # Conftest pins API_USGS_RETRIES=0, so these tests opt in explicitly and
 # patch the chunking module's ``asyncio.sleep`` to a no-op (no real backoff).
 # ---------------------------------------------------------------------------
@@ -1631,11 +1642,7 @@ async def afn():
 def test_retry_non_retryable_not_retried(monkeypatch):
     slept: list[float] = []
 
-    def _record(delay):
-        slept.append(delay)
-        return _aiozero(delay)
-
-    monkeypatch.setattr(_chunking.asyncio, "sleep", _record)
+    monkeypatch.setattr(_chunking.asyncio, "sleep", _recording_sleep(slept))
     calls = {"n": 0}
 
     async def afn():
@@ -1650,11 +1657,7 @@ async def afn():
 def test_retry_long_retry_after_escalates(monkeypatch):
     slept: list[float] = []
 
-    def _record(delay):
-        slept.append(delay)
-        return _aiozero(delay)
-
-    monkeypatch.setattr(_chunking.asyncio, "sleep", _record)
+    monkeypatch.setattr(_chunking.asyncio, "sleep", _recording_sleep(slept))
     calls = {"n": 0}
 
     async def afn():
@@ -1670,10 +1673,7 @@ async def afn():
 
 
 def test_retry_transient_then_success(monkeypatch):
-    async def _noslept(_d):
-        return None
-
-    monkeypatch.setattr(_chunking.asyncio, "sleep", _noslept)
+    monkeypatch.setattr(_chunking.asyncio, "sleep", _aiozero)
     calls = {"n": 0}
 
     async def afn():
@@ -1734,10 +1734,7 @@ def test_async_fan_out_retries_transient_then_completes(monkeypatch):
     """The parallel path retries a transient sub-request and completes."""
     monkeypatch.setenv("API_USGS_RETRIES", "3")
 
-    async def _noslept(_d):
-        return None
-
-    monkeypatch.setattr(_chunking.asyncio, "sleep", _noslept)
+    monkeypatch.setattr(_chunking.asyncio, "sleep", _aiozero)
     state = {"failed": False}
 
     async def fetch_async(args):
@@ -1756,10 +1753,7 @@ def test_async_fan_out_surfaces_fatal_over_transient(monkeypatch):
     being masked behind a resumable interruption from a transient sibling."""
     monkeypatch.setenv("API_USGS_RETRIES", "2")
 
-    async def _noslept(_d):
-        return None
-
-    monkeypatch.setattr(_chunking.asyncio, "sleep", _noslept)
+    monkeypatch.setattr(_chunking.asyncio, "sleep", _aiozero)
 
     async def fetch_async(args):
         # One chunk carries a deterministic programmer error; the rest are