refactor(waterdata): decompose the 2033-LOC utils.py god-module into cohesive modules

[thodson-usgs]

Why

dataretrieval/waterdata/utils.py had grown to 2033 LOC spanning ~6 unrelated domains — request building, response parsing, result finalization, pagination/async, stats post-processing, and validation — plus constants and the public engines. It was the package's one genuine god-module: changing how requests are built means navigating the same file as type coercion, datetime parsing, and the async driver.

(An architecture review concluded the package's OO is otherwise appropriate — the chunker is well-factored, the modern getters are cleanly delegated — so this is a modularization, not an OO-pattern refactor.)

What

Split it into six cohesive private modules under dataretrieval/waterdata/, moving every definition verbatim (no signature/logic changes):

module	holds
_constants.py	URLs, _OUTPUT_ID_BY_SERVICE, regexes, param sets (dependency-free)
_http.py	headers, _error_body, _raise_for_non_200, retry-after
_validate.py	arg normalization/validation (_get_args, _check_*)
_requests.py	request building (_construct_api_requests, CQL2, dates)
_responses.py	geometry-agnostic parsing / finalization / stats shaping
_engine.py	pagination/async driver (_paginate, _run_sync, …)

utils.py (2033 → 651 LOC) becomes a thin façade that re-exports the internal API (explicit __all__, 56 names), so every existing from dataretrieval.waterdata.utils import … and mock.patch("dataretrieval.waterdata.utils.<name>") keeps working — no import sites or tests were touched.

Seven functions remain physically defined in the façade (get_ogc_data, _fetch_once, get_stats_data, _get_resp_data, _ogc_parse_response, _walk_pages, _handle_stats_nesting) because the test suite monkeypatches them (or gpd) by their module-global name: a function's global lookups resolve in its defining module, so they must stay in utils.py for the patches to take effect. The geopandas import probe stays with them, and the pagination logger keeps the name dataretrieval.waterdata.utils (a caplog test pins it).

Behavior-preserving

• 56 top-level definitions moved AST-identically — none lost, none duplicated (verified mechanically).
• 469 tests pass, 2 skipped; ruff clean; all 6 modules import without cycles; chunking.py untouched.

Note

Overlaps with the in-flight error-taxonomy (#313) and namespace (#315) PRs on waterdata/ imports — sequence on merge (rebasing each surfaces any conflict, as we've done for the others).

🤖 Generated with Claude Code