feat(wateruse): add water-use module for the NWDC API

[thodson-usgs]

Summary

Adds a dataretrieval.wateruse module for retrieving USGS National Water
Availability Assessment Data Companion (NWDC) water-use estimates from
https://api.water.usgs.gov/nwaa-data/data. Estimates are modeled on a HUC12
grid and queryable by county, state, or hydrologic unit. This is the modern
replacement for the defunct legacy NWIS water-use service, so
nwis.get_water_use now points callers here.

It covers the same data as the R
dataRetrieval::read_waterdata_use_data
getter, but is written to the Python package's conventions rather than ported
from the R structure.

from dataretrieval import wateruse

df, md = wateruse.get_wateruse(
    model="wu-public-supply-wd",
    variable=["pswdtot", "pswdgw", "pswdsw"],
    state="RI",
    startdate="2020-01",
    timeres="monthly",
)

Design notes

The NWDC is a plain CSV REST service, not an OGC API Features collection —
it has no /collections or /conformance, and its error envelope is
{"detail": ...} rather than the OGC engine's {code, description}. So it does
not use the high-level OGC path (get_ogc_data, the CQL2 byte-chunker, the
GeoJSON pager, _raise_for_non_200). It does reuse the engine's generic
transport plumbing (extracted/cleaned up in the refactor commit below),
supplying only NWDC-specific strategies, and stays consistent with the package
where the shared pieces fit:

• Returns the conventional (DataFrame, BaseMetadata) tuple.
• Reuses utils._default_headers() for request headers, so the documented
  API_USGS_PAT token raises the NWDC rate limit just as it does for the OGC
  getters.
• Raises through the shared typed DataRetrievalError taxonomy (via
  utils._raise_for_status with an injected detail extractor), surfacing the
  NWDC detail (e.g. "Invalid model name: ...") in the message.
• Locations are idiomatic state / county / huc selectors (mirroring
  ngwmn / waterdata), each accepting a single value or a list. Since NWDC
  takes one location per request, a multi-value selector fans out — one
  request per location, run concurrently over a shared client.
• Multi-valued variable is comma-joined into a single GET (via utils.to_str).
• Pagination is real and handled transparently. Large areas paginate with
  an RFC 8288 Link: <...>; rel="next" header (verified: a huc2 → 7 pages, a
  populous state → 4; small queries → a single page). Rather than a bespoke
  loop, wateruse drives the engine's generic _paginate (with NWDC parse /
  cursor / error strategies) and concatenates the pages.
• huc12_id is parsed as a string so leading zeros survive.

Folded-in engine refactor (second commit)

Building wateruse surfaced that it could reuse the OGC engine's transport
instead of re-implementing it — and that extracting the reusable seams also
de-duplicated the engine itself. The second commit on this branch,
refactor(ogc): reuse + unify the OGC engine — pager, aggregation, ambient state, does that. Net source ≈ −66 LOC, behavior-preserving, and it reads
independently of the wateruse module (feature and refactor are split into two
commits on purpose):

• planning._merge_response — one low-level "fold N responses into one"
  behind both pagination (_paginate) and the chunked / fan-out aggregation
  (_combine_chunk_responses), replacing two near-duplicate implementations
  across modules; deletes engine._aggregate_paginated_response.
• utils.Ambient[T] — a small generic ContextVar-with-scope class that
  collapses each per-call ambient (_row_cap, _ogc_base_url, _dialect, the
  chunker's _chunked_client) from a var + hand-written @contextmanager
  setter pair into a single declaration. with _x(value): call sites are
  unchanged; readers shorten to _x.get().
• wateruse reuses _paginate / _run_sync (Jupyter-safe anyio portal) /
  _combine_chunk_* rather than a hand-rolled pager + thread bridge; its
  _resolve_locations becomes a _LOCATION_BUILDERS dispatch table.
• Smaller dedups: _paginate's verbatim per-page progress block → a
  report_page closure; a dead single-response branch dropped; _QUOTA_HEADER
  moved to the base planning module (dedups the literal and fixes a layering
  inversion); CQL2 filters built as a comprehension; the single-use
  _check_id_format helper inlined and its dead re-export removed.
• Rate-limit correctness fix: x-ratelimit-remaining now reports the
  lowest value any concurrent sub-request saw (the quota actually left after
  a fan-out) via a shared _lowest_remaining, instead of the last-by-index —
  fixing a latent inaccuracy in the OGC chunker too.

What's included

• dataretrieval/wateruse.py — the module, wired into dataretrieval/__init__.py.
• The engine refactor across ogc/{engine,planning,chunking}.py, utils.py,
  and waterdata/utils.py (second commit).
• tests/wateruse_test.py — offline pytest-httpx coverage: single-page parse,
  string huc12_id, comma-joined variables, dropped-None params, Link-header
  pagination + concatenation, bare-host normalization, shared-header reuse,
  state/county/huc selectors + fan-out, and typed-error/detail handling; plus
  updates to tests/waterdata_{chunking,utils,}_test.py for the engine changes.
• docs/source/reference/wateruse.rst + toctree entry.
• README.md — usage example and an "Available Data Services" entry.
• demos/USGS_WaterUse_Examples.ipynb — a motivating walkthrough: where
  Wisconsin's public water supply comes from (groundwater vs. surface water)
  and its summer demand peak.

Verification

• Offline suites pass — wateruse (tests/wateruse_test.py) plus the OGC
  engine / chunking / progress / utils suites the refactor touches;
  ruff check / ruff format / mypy --strict clean.
• Smoke-tested against the live API: single-page and multi-page queries,
  monthly and annual resolutions, paginated results byte-identical to the
  unpaginated equivalent, concurrent fan-out over multiple states, and the
  lowest-remaining rate-limit header confirmed. The demo notebook was executed
  end-to-end (outputs stripped on commit per the repo's nbstripout hook).

🤖 Generated with Claude Code