Skip to content

Commit ead1c09

Browse files
thodson-usgsclaude
andcommitted
docs(waterdata): final editorial pass on chunking.py
- Retry-defaults comment: drop the hardcoded numbers (4 / 0.5s / 30s / 60s) — they live in the constants below and were drifting from them. - _publish docstring: drop the 'set/reset token dance' mechanism leak; state the contract. - get_active_client docstring: drop the 'public accessor / private ContextVar' justification paragraph; keep the one-liner + the paginated-loop usage cue. - combined(): drop the 'terminal success result' paragraph that duplicated the Returns section; move the finalize return-shape detail into Returns where it belongs. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
1 parent bbabf50 commit ead1c09

1 file changed

Lines changed: 18 additions & 23 deletions

File tree

dataretrieval/waterdata/chunking.py

Lines changed: 18 additions & 23 deletions
Original file line numberDiff line numberDiff line change
@@ -153,10 +153,9 @@ def _read_concurrency_env() -> int | None:
153153

154154

155155
# Retry-with-backoff defaults for transient sub-request failures (429 /
156-
# 5xx / connect-read timeouts): 4 retries, 0.5s base doubling under full
157-
# jitter up to a 30s per-attempt ceiling, and honor a server
158-
# ``Retry-After`` up to 60s before escalating to a resumable interruption
159-
# instead.
156+
# 5xx / connect-read timeouts): exponential backoff with full jitter, and
157+
# honor a server ``Retry-After`` up to the cap below before escalating
158+
# to a resumable interruption instead.
160159
_RETRIES_ENV = "API_USGS_RETRIES"
161160
_RETRIES_DEFAULT = 4
162161
_RETRY_BASE_BACKOFF = 0.5
@@ -322,15 +321,14 @@ def backoff(self, attempt: int, retry_after: float | None) -> float:
322321
@contextmanager
323322
def _publish(client: httpx.AsyncClient) -> Iterator[None]:
324323
"""
325-
Bind ``client`` to the ``_chunked_client`` ContextVar for the
326-
duration of the ``with`` block (wrapping the set/reset token dance),
327-
so the paginated-loop helpers can borrow the chunker's shared client
328-
via :func:`get_active_client`.
324+
Publish ``client`` on the ``_chunked_client`` ContextVar so the
325+
paginated-loop helpers can borrow it via :func:`get_active_client`
326+
for the duration of the ``with`` block.
329327
330328
Parameters
331329
----------
332330
client : httpx.AsyncClient
333-
The client to publish on ``_chunked_client``.
331+
The client to publish.
334332
335333
Yields
336334
------
@@ -348,11 +346,9 @@ def get_active_client() -> httpx.AsyncClient | None:
348346
"""
349347
Return the chunker's currently-published client, or ``None``.
350348
351-
Public accessor for the ``_chunked_client`` ContextVar so
352-
sibling modules (notably
353-
:func:`dataretrieval.waterdata.utils._client_for`) don't have
354-
to reach into the private ContextVar directly. Used by the
355-
paginated-loop helpers to reuse the per-call connection pool.
349+
Used by the paginated-loop helpers (e.g.
350+
:func:`dataretrieval.waterdata.utils._client_for`) to reuse the
351+
per-call connection pool.
356352
357353
Returns
358354
-------
@@ -1493,19 +1489,18 @@ def combined(self) -> tuple[pd.DataFrame, Any]:
14931489
"""
14941490
Combine every recorded sub-request and apply :attr:`finalize`.
14951491
1496-
The terminal *success* result: :meth:`_run` returns this, so a
1497-
completed call (first run or resume) yields the same shape
1498-
``finalize`` produces — a raw ``(frame, httpx.Response)`` by
1499-
default, or the OGC getters' type-coerced / column-arranged frame
1500-
plus ``BaseMetadata``. The ``partial_*`` accessors deliberately do
1501-
NOT go through here — they return the raw :meth:`_combine_raw`
1502-
snapshot to stay cheap and side-effect-free.
1492+
Returned by :meth:`_run` on a completed call (first run or
1493+
resume). The ``partial_*`` accessors deliberately do NOT route
1494+
through here — they return the raw :meth:`_combine_raw` snapshot
1495+
to stay cheap and side-effect-free.
15031496
15041497
Returns
15051498
-------
15061499
tuple of (pandas.DataFrame, finalized response)
1507-
The combined frame and the finalized aggregate response /
1508-
metadata that :attr:`finalize` produces.
1500+
The combined frame and whatever :attr:`finalize` produces —
1501+
a raw :class:`httpx.Response` by default, or the OGC
1502+
getters' type-coerced / column-arranged frame plus
1503+
``BaseMetadata``.
15091504
"""
15101505
return self.finalize(*self._combine_raw())
15111506

0 commit comments

Comments
 (0)