docs(waterdata): Add retry-loop example for resume_from

Worked example in get_daily's docstring showing the canonical
PartialResult catch / accumulate-partials / sleep-and-retry pattern,
capped at a one-hour deadline matched to the API's hourly rate-limit
window so structural failures surface rather than spin forever.

Module-level multi_value_chunked docstring and the per-getter
resume_from parameter doc now point to get_daily for the example.

Author: thodson-usgs

dataretrieval/waterdata/api.py

@@ -195,7 +195,8 @@ def get_daily(
         ``QuotaExhausted``) exception from a previous call. The chunker
         consults its ``chunk_manifest`` to skip already-completed
         sub-requests and fetch only the remainder. Pass the same other
-        kwargs as the original call.
+        kwargs as the original call. See ``get_daily`` for a worked
+        retry-loop example.
 
     Returns
     -------
@@ -252,6 +253,51 @@ def get_daily(
         ...     parameter_code="00060",
         ...     time="P7D",
         ... )
+
+        >>> # Resume loop: a heavy chunked query may exhaust the hourly
+        >>> # rate-limit budget partway through or hit a transient upstream
+        >>> # error. Catch ``PartialResult``, accumulate the partial frames,
+        >>> # and re-call with ``resume_from=`` to fetch only the
+        >>> # outstanding chunks. The USGS API rate-limit window is one
+        >>> # hour, so a total retry window of one hour is a sensible
+        >>> # ceiling — anything longer means the failure is structural,
+        >>> # not transient, and the loop should surface the error.
+        >>> import time
+        >>> import pandas as pd
+        >>> from dataretrieval import waterdata
+        >>> from dataretrieval.waterdata.chunking import PartialResult
+        >>>
+        >>> sites = sites_df["monitoring_location_id"].tolist()
+        >>> deadline = time.monotonic() + 3600  # one hour cap
+        >>> partials = []
+        >>> md = None  # carries the latest chunk_manifest between attempts
+        >>> attempt = 0
+        >>> while True:
+        ...     try:
+        ...         df, md = waterdata.get_daily(
+        ...             monitoring_location_id=sites,
+        ...             parameter_code="00060",
+        ...             time="P7D",
+        ...             resume_from=md,  # ``None`` on the first attempt
+        ...         )
+        ...         break  # full result fetched
+        ...     except PartialResult as exc:
+        ...         partials.append(exc.partial_frame)
+        ...         md = exc.partial_metadata
+        ...         if time.monotonic() >= deadline:
+        ...             raise TimeoutError(
+        ...                 f"Could not complete chunked query within one hour "
+        ...                 f"({md.chunk_manifest.completed}/"
+        ...                 f"{md.chunk_manifest.total} chunks done)."
+        ...             ) from exc
+        ...         attempt += 1
+        ...         # Exponential backoff, capped at 10 minutes. Quota-
+        ...         # reset failures benefit from a longer wait; transient
+        ...         # transport errors clear quickly. ``min(...)`` ensures
+        ...         # a tight cap; the outer deadline ensures we never wait
+        ...         # past one hour total.
+        ...         time.sleep(min(60 * 2 ** (attempt - 1), 600))
+        >>> full = pd.concat([*partials, df], ignore_index=True)
     """
     service = "daily"
     output_id = "daily_id"
@@ -412,7 +458,8 @@ def get_continuous(
         ``QuotaExhausted``) exception from a previous call. The chunker
         consults its ``chunk_manifest`` to skip already-completed
         sub-requests and fetch only the remainder. Pass the same other
-        kwargs as the original call.
+        kwargs as the original call. See ``get_daily`` for a worked
+        retry-loop example.
 
     Returns
     -------
@@ -727,7 +774,8 @@ def get_monitoring_locations(
         ``QuotaExhausted``) exception from a previous call. The chunker
         consults its ``chunk_manifest`` to skip already-completed
         sub-requests and fetch only the remainder. Pass the same other
-        kwargs as the original call.
+        kwargs as the original call. See ``get_daily`` for a worked
+        retry-loop example.
 
     Returns
     -------
@@ -957,7 +1005,8 @@ def get_time_series_metadata(
         ``QuotaExhausted``) exception from a previous call. The chunker
         consults its ``chunk_manifest`` to skip already-completed
         sub-requests and fetch only the remainder. Pass the same other
-        kwargs as the original call.
+        kwargs as the original call. See ``get_daily`` for a worked
+        retry-loop example.
 
     Returns
     -------
@@ -1161,7 +1210,8 @@ def get_combined_metadata(
         ``QuotaExhausted``) exception from a previous call. The chunker
         consults its ``chunk_manifest`` to skip already-completed
         sub-requests and fetch only the remainder. Pass the same other
-        kwargs as the original call.
+        kwargs as the original call. See ``get_daily`` for a worked
+        retry-loop example.
 
     Returns
     -------
@@ -1385,7 +1435,8 @@ def get_latest_continuous(
         ``QuotaExhausted``) exception from a previous call. The chunker
         consults its ``chunk_manifest`` to skip already-completed
         sub-requests and fetch only the remainder. Pass the same other
-        kwargs as the original call.
+        kwargs as the original call. See ``get_daily`` for a worked
+        retry-loop example.
 
     Returns
     -------
@@ -1589,7 +1640,8 @@ def get_latest_daily(
         ``QuotaExhausted``) exception from a previous call. The chunker
         consults its ``chunk_manifest`` to skip already-completed
         sub-requests and fetch only the remainder. Pass the same other
-        kwargs as the original call.
+        kwargs as the original call. See ``get_daily`` for a worked
+        retry-loop example.
 
     Returns
     -------
@@ -1784,7 +1836,8 @@ def get_field_measurements(
         ``QuotaExhausted``) exception from a previous call. The chunker
         consults its ``chunk_manifest`` to skip already-completed
         sub-requests and fetch only the remainder. Pass the same other
-        kwargs as the original call.
+        kwargs as the original call. See ``get_daily`` for a worked
+        retry-loop example.
 
     Returns
     -------
@@ -1909,7 +1962,8 @@ def get_field_measurements_metadata(
         ``QuotaExhausted``) exception from a previous call. The chunker
         consults its ``chunk_manifest`` to skip already-completed
         sub-requests and fetch only the remainder. Pass the same other
-        kwargs as the original call.
+        kwargs as the original call. See ``get_daily`` for a worked
+        retry-loop example.
 
     Returns
     -------
@@ -2040,7 +2094,8 @@ def get_peaks(
         ``QuotaExhausted``) exception from a previous call. The chunker
         consults its ``chunk_manifest`` to skip already-completed
         sub-requests and fetch only the remainder. Pass the same other
-        kwargs as the original call.
+        kwargs as the original call. See ``get_daily`` for a worked
+        retry-loop example.
 
     Returns
     -------
@@ -2899,7 +2954,8 @@ def get_channel(
         ``QuotaExhausted``) exception from a previous call. The chunker
         consults its ``chunk_manifest`` to skip already-completed
         sub-requests and fetch only the remainder. Pass the same other
-        kwargs as the original call.
+        kwargs as the original call. See ``get_daily`` for a worked
+        retry-loop example.
 
     Returns
     -------

dataretrieval/waterdata/chunking.py

@@ -617,7 +617,9 @@ def multi_value_chunked(
     the caller's kwargs. The wrapper pops it before planning (so it
     never reaches the underlying HTTP request), validates the saved
     plan matches the fresh plan, and skips the already-completed
-    cartesian-product combinations.
+    cartesian-product combinations. See ``get_daily``'s docstring for
+    a worked retry-loop example using a one-hour deadline matched to
+    the API's rate-limit window.
     """
 
     def decorator(fetch_once: _FetchOnce) -> _FetchOnce: