refactor(waterdata): Untangle chunking ↔ utils — strict one-way layer

The chunker module previously had a circular dep with utils: utils
imported chunking at top level, but chunking did a lazy import of
`RateLimited` / `ServiceUnavailable` from utils inside
`_classify_chunk_error`. The lazy form existed only to defeat that
cycle. utils.py also reached across the boundary three times for
private chunker internals — `chunking._QUOTA_HEADER`,
`chunking._chunked_session.get()`, and `chunking._publish_session`.

Reasoning about the layer: `RateLimited` / `ServiceUnavailable` exist
*because of* the chunker — they're raised by utils.py's
`_raise_for_non_200` solely so `_classify_chunk_error` can dispatch
on them as resumable transient failures. The motivating consumer is
the chunker, so they belong in chunking.py.

Changes:
- Move `_RetryableTransportError`, `RateLimited`, `ServiceUnavailable`
  from utils.py → chunking.py.
- Drop the lazy `from .utils import …` inside `_classify_chunk_error`.
- Add `chunking.get_active_session()` — public accessor for the
  `_chunked_session` ContextVar so `_session()` in utils.py doesn't
  reach into a private name.
- Hoist `_QUOTA_HEADER` to a top-level explicit import in utils.py
  instead of `chunking._QUOTA_HEADER` ad-hoc.
- Update the two test files that imported `RateLimited` /
  `ServiceUnavailable` from utils.py.

After this commit, chunking.py has zero runtime dependency on utils.py
(only docstring cross-references). The dep direction is now strictly
utils → chunking.

80/80 chunker + utils unit tests pass; ruff clean.

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>

Author: thodson-usgs

dataretrieval/waterdata/chunking.py

@@ -113,8 +113,8 @@
 @contextmanager
 def _publish_session(session: requests.Session) -> Iterator[None]:
     """
-    Make ``session`` visible to :func:`dataretrieval.waterdata.utils._session`
-    for the duration of the ``with`` block via the ``_chunked_session``
+    Make ``session`` visible to :func:`get_active_session` for the
+    duration of the ``with`` block via the ``_chunked_session``
     ContextVar. Wraps the set/reset token dance so callers don't have to.
     """
     token = _chunked_session.set(session)
@@ -124,6 +124,23 @@ def _publish_session(session: requests.Session) -> Iterator[None]:
         _chunked_session.reset(token)
 
 
+def get_active_session() -> requests.Session | None:
+    """
+    Return the chunker's currently-published session, or ``None``.
+
+    Public accessor for the ``_chunked_session`` ContextVar so
+    sibling modules (notably :func:`dataretrieval.waterdata.utils._session`)
+    don't have to reach into the private ContextVar directly.
+
+    Returns
+    -------
+    requests.Session or None
+        The session published by :func:`_publish_session` if currently
+        inside a :class:`ChunkedCall` ``resume`` block; ``None`` otherwise.
+    """
+    return _chunked_session.get()
+
+
 # Separators the two axis kinds use to join their atoms back into
 # URL text. List axes comma-join values
 # (``site=USGS-A,USGS-B``); the filter axis OR-joins clauses
@@ -135,6 +152,58 @@ def _publish_session(session: requests.Session) -> Iterator[None]:
 _FetchOnce = Callable[[dict[str, Any]], tuple[pd.DataFrame, requests.Response]]
 
 
+class _RetryableTransportError(RuntimeError):
+    """
+    Base for typed HTTP transport failures the chunker recognizes as
+    transient.
+
+    Raised by :func:`dataretrieval.waterdata.utils._raise_for_non_200`
+    and walked by :func:`_classify_chunk_error`. One subclass per
+    recoverable HTTP status family (429 → :class:`RateLimited`,
+    5xx → :class:`ServiceUnavailable`); ``ChunkedCall`` wraps them as
+    resumable :class:`ChunkInterrupted` subclasses.
+
+    Parameters
+    ----------
+    message : str
+        Human-readable error message.
+    retry_after : float, optional
+        Seconds to wait before retrying, parsed from the
+        ``Retry-After`` response header.
+
+    Attributes
+    ----------
+    retry_after : float or None
+        Seconds to wait before retrying, parsed from the
+        ``Retry-After`` response header. ``None`` when the header was
+        absent or unparseable.
+    """
+
+    def __init__(self, message: str, *, retry_after: float | None = None) -> None:
+        super().__init__(message)
+        self.retry_after = retry_after
+
+
+class RateLimited(_RetryableTransportError):
+    """
+    A USGS Water Data API request was rejected with HTTP 429.
+
+    Exposed as a typed exception so callers (notably the multi-value
+    chunker) can detect rate-limit failures via ``isinstance`` instead
+    of string-matching error messages.
+    """
+
+
+class ServiceUnavailable(_RetryableTransportError):
+    """
+    A USGS Water Data API request was rejected with HTTP 5xx.
+
+    Surfaced as a typed exception (parallel to :class:`RateLimited`)
+    so ``ChunkedCall`` can treat transient server failures as
+    resumable interruptions rather than fatal programmer errors.
+    """
+
+
 class RequestTooLarge(ValueError):
     """
     No chunking plan fits the URL byte limit.
@@ -801,13 +870,7 @@ def _classify_chunk_error(
     ``RuntimeError`` with the typed transport exception linked as
     ``__cause__``, so this function must walk the chain rather than
     just ``isinstance`` the top-level exception.
-
-    The import of ``RateLimited`` / ``ServiceUnavailable`` is lazy
-    because :mod:`dataretrieval.waterdata.utils` imports this module
-    to decorate ``_fetch_once``; a top-level import would be circular.
     """
-    from .utils import RateLimited, ServiceUnavailable
-
     cur: BaseException | None = exc
     while cur is not None:
         if isinstance(cur, RateLimited):

dataretrieval/waterdata/utils.py

@@ -16,6 +16,12 @@
 from dataretrieval import __version__
 from dataretrieval.utils import BaseMetadata
 from dataretrieval.waterdata import chunking
+from dataretrieval.waterdata.chunking import (
+    _QUOTA_HEADER,
+    RateLimited,
+    ServiceUnavailable,
+    get_active_session,
+)
 from dataretrieval.waterdata.types import (
     PROFILE_LOOKUP,
     PROFILES,
@@ -442,58 +448,6 @@ def _parse_retry_after(value: str | None) -> float | None:
         return None
 
 
-class _RetryableTransportError(RuntimeError):
-    """
-    Base for typed transport failures recognized as transient by
-    :func:`dataretrieval.waterdata.chunking._classify_chunk_error`.
-
-    One subclass per recoverable HTTP status family (429 →
-    :class:`RateLimited`, 5xx → :class:`ServiceUnavailable`);
-    ``ChunkedCall`` wraps them as resumable ``ChunkInterrupted``
-    subclasses.
-
-    Parameters
-    ----------
-    message : str
-        Human-readable error message (typically built by
-        :func:`_error_body`).
-    retry_after : float, optional
-        Seconds to wait before retrying, parsed from the
-        ``Retry-After`` response header.
-
-    Attributes
-    ----------
-    retry_after : float or None
-        Seconds to wait before retrying, parsed from the
-        ``Retry-After`` response header. ``None`` when the header was
-        absent or unparseable.
-    """
-
-    def __init__(self, message: str, *, retry_after: float | None = None) -> None:
-        super().__init__(message)
-        self.retry_after = retry_after
-
-
-class RateLimited(_RetryableTransportError):
-    """
-    A USGS Water Data API request was rejected with HTTP 429.
-
-    Exposed as a typed exception so callers (notably the multi-value
-    chunker) can detect rate-limit failures via ``isinstance`` instead
-    of string-matching error messages.
-    """
-
-
-class ServiceUnavailable(_RetryableTransportError):
-    """
-    A USGS Water Data API request was rejected with HTTP 5xx.
-
-    Surfaced as a typed exception (parallel to :class:`RateLimited`)
-    so ``ChunkedCall`` can treat transient server failures as
-    resumable interruptions rather than fatal programmer errors.
-    """
-
-
 def _raise_for_non_200(resp: requests.Response) -> None:
     """
     Raise a typed exception for any non-200 response.
@@ -716,7 +670,7 @@ def _next_req_url(
     if os.getenv("API_USGS_PAT", ""):
         logger.info(
             "Remaining requests this hour: %s",
-            header_info.get(chunking._QUOTA_HEADER, ""),
+            header_info.get(_QUOTA_HEADER, ""),
         )
     for link in body.get("links", []):
         if link.get("rel") == "next":
@@ -794,8 +748,8 @@ def _session(client: requests.Session | None) -> Iterator[requests.Session]:
     1. ``client`` if the caller supplied one (borrowed; not closed
        here — the caller owns its lifecycle).
     2. The chunker's shared session if we're inside a ``ChunkedCall``
-       fan-out (published via :func:`chunking._publish_session`).
-       Borrowed; ``ChunkedCall.resume`` closes it on exit.
+       fan-out (per :func:`chunking.get_active_session`). Borrowed;
+       ``ChunkedCall.resume`` closes it on exit.
     3. A fresh short-lived ``requests.Session`` opened here and closed
        on context exit.
 
@@ -813,7 +767,7 @@ def _session(client: requests.Session | None) -> Iterator[requests.Session]:
     if client is not None:
         yield client
         return
-    shared = chunking._chunked_session.get()
+    shared = get_active_session()
     if shared is not None:
         yield shared
         return

tests/waterdata_chunking_test.py

@@ -34,19 +34,17 @@
     ChunkInterrupted,
     ChunkPlan,
     QuotaExhausted,
+    RateLimited,
     RequestExceedsQuota,
     RequestTooLarge,
     ServiceInterrupted,
+    ServiceUnavailable,
     _chunked_session,
     _extract_axes,
     _read_remaining,
     multi_value_chunked,
 )
-from dataretrieval.waterdata.utils import (
-    RateLimited,
-    ServiceUnavailable,
-    _construct_api_requests,
-)
+from dataretrieval.waterdata.utils import _construct_api_requests
 
 
 class _FakeReq:

tests/waterdata_utils_test.py

@@ -6,9 +6,8 @@
 import requests
 
 import dataretrieval.waterdata.utils as _utils_module
+from dataretrieval.waterdata.chunking import RateLimited, ServiceUnavailable
 from dataretrieval.waterdata.utils import (
-    RateLimited,
-    ServiceUnavailable,
     _arrange_cols,
     _error_body,
     _format_api_dates,