feat: add NGWMN getters as an ogc sibling; extract a shared OGC engine

[thodson-usgs]

Ports the NGWMN functions from the R dataRetrieval PR (DOI-USGS/dataRetrieval#904) and, per review, refactors the Water Data OGC machinery into a shared engine so NGWMN and Water Data are sibling layers on top of it — NGWMN does not depend on Water Data.

Architecture

dataretrieval/
  ogc/                   generic, API-agnostic OGC engine (no service-specific config)
    engine.py            request build · paginate · parse · finalize · get_ogc_data
    chunking.py          URL-byte multi-value chunker   (moved from waterdata/)
    filters.py           CQL `filter` splitting         (moved from waterdata/)
    progress.py          self-updating status line      (moved from waterdata/_progress.py)
  waterdata/             Water Data layer on the engine
    api.py               typed OGC getters: monitoring-locations, daily, continuous, peaks,
                         time-series/combined metadata, field/channel measurements, samples, …
    stats.py             Statistics API client (get_stats_por / get_stats_date_range)
    ratings.py           rating-curve retrieval via the Water Data STAC catalog
    nearest.py           get_nearest_continuous convenience on top of the getters
    utils.py             service→id map · WATERDATA_DIALECT · get_ogc_data wrapper · engine re-exports
    types.py             service/profile Literals + lookup tables
  ngwmn.py               sibling getters (imports only dataretrieval.ogc):
                         get_sites / get_water_level / get_lithology /
                         get_well_construction / get_providers
  codes/states.py        to_state(): shared name/postal/FIPS state normalizer used by both layers

Layering / import rules (the organization a reviewer can check):

• ogc/* is fully API-agnostic — it imports no dataretrieval.waterdata or dataretrieval.ngwmn.
• waterdata/* and ngwmn.py are siblings on the engine; ngwmn.py imports only dataretrieval.ogc (+ codes.states), never dataretrieval.waterdata.
• api.py / stats.py / ratings.py / nearest.py are thin getter layers; the shared Water-Data state (service→id map, dialect, the get_ogc_data wrapper) lives once in utils.py.

The engine is parameterized, not branched: get_ogc_data(args, service, output_id, *, base_url, extra_id_cols, dialect). An OgcDialect(cql2_services, date_only_services, …) (threaded via a context variable, like the base-url context) carries per-API quirks — Water Data POSTs CQL2 for monitoring-locations and renders daily time args date-only; NGWMN needs neither. Adding a sibling API is a new dialect + base URL, not engine edits.

from dataretrieval import ngwmn

df, md = ngwmn.get_sites(state="Wisconsin")      # name, postal ("WI"), or FIPS ("55")
df, md = ngwmn.get_water_level(
    monitoring_location_id="USGS-272838082142201",
    datetime=["2022-01-01", "2024-01-01"],
)
df, md = ngwmn.get_water_level(                   # NGWMN ids aren't all USGS-prefixed
    monitoring_location_id=["USGS-272838082142201", "MBMG-702934"]
)
df, md = ngwmn.get_providers(state="WI")

The multi-value chunker (recently fixed in #322) is generic and applies to NGWMN unchanged — verified that a forced-small-budget multi-site NGWMN query chunks and unions correctly.

Unified state parameter

A single, canonical state parameter spans the modern getters and accepts a full name ("Wisconsin"), a two-letter postal code ("WI"), or a two-digit ANSI/FIPS code ("55"). It is normalized once by codes.states.to_state() (50 states + DC; fails fast on a typo) and resolved at the getter layer into whatever native queryable each endpoint wants — state_name for the OGC getters, US:XX state_code for stats, the per-collection queryable for NGWMN. The native state_code / state_name parameters remain as an escape hatch (e.g. non-US FIPS codes); passing state together with either raises.

Engine fixes (NGWMN's API differs from the main one)

• Key the empty-result short-circuit off features rather than the numberReturned that NGWMN omits (otherwise pages with data were silently dropped).
• Tolerate observation features with no geometry key (GeoDataFrame.from_features can't index a missing key).

PEP naming

The engine snake_cases any non-snake column in finalize, so the package always returns PEP-8 column names regardless of the upstream API — a no-op today (both APIs are already snake_case) but enforced going forward.

Tests & checks

Live NGWMN tests for all five getters (tests/ngwmn_test.py); unit tests for to_state, the _with_state / getter-layer state resolution, and _to_snake_case; mock.patch sites repointed to ogc.engine; a module fixture activates WATERDATA_DIALECT for the direct _construct_api_requests unit tests. The unit suite passes and mypy --strict + ruff are clean. A pre-commit mypy hook (pinned to the same mypy<2 major as CI, with httpx/anyio in the hook env) now mirrors the CI type-check locally.

Note

CI will show 3 pre-existing failures (test_get_daily_properties/_id, test_get_continuous) — the live-API drift fixed by #323, not introduced here (branch is off main). They go green once #323 merges.

🤖 Generated with Claude Code

[thodson-usgs]

@ehinman,
Besides adding the NGWMN module, this PR will create a shared OGC engine used by NGWMN and WaterData. In the architecture outlined above, ngwmn and waterdata would become sibling modules, whereas ratings and stats would still live within waterdata. The logical distinction is a little murky, but I believe that's better than putting everything within waterdata. What organization makes most sense to you?