[thodson-usgs]

Summary

This removes dataretrieval.nwis before its published 2027-05-06 horizon, as part of the next major release. USGS is decommissioning the waterservices endpoints the module called, and every getter in it already has a waterdata or nwdc replacement.

Breaking:

• import dataretrieval.nwis now raises ModuleNotFoundError.
• NoSitesError is removed, both dataretrieval.NoSitesError and exceptions.NoSitesError. Only the waterservices path raised it. The modern getters return an empty DataFrame when nothing matches.

Code

• Deleted nwis.py, tests/nwis_test.py, tests/waterservices_test.py, and 9 fixtures used only by those tests.
• Deleted REMOVALS["nwis"], the "No sites/data" body check in _querying, and _validation.require_any_of, whose only caller was nwis.
• .importlinter: dropped nwis from the layers contract and deleted the nwis-quarantine contract. Also updated the pyproject comment, the pre-commit comments, and the pyscn clone baseline.
• Rewrote the generic tests that used nwis only to reach shared code (utils.query, the deprecation mechanism) so they call that code directly.
• rdb.read_rdb's HTML-response message used to tell callers to migrate to waterdata. Only waterdata.get_ratings reaches it now, so the message asks them to report the moved endpoint instead.

Notebooks and demos

• hydroshare/USGS_NWIS_WaterUse_Examples.ipynb was defunct and couldn't run. It is rewritten on nwdc.get_wateruse and renamed USGS_NWDC_WaterUse_Examples.ipynb.
• nwqn_data_pull scripts now use waterdata.get_monitoring_locations and get_daily. Approval filtering happens on the server (approval_status="Approved") instead of matching the old NWIS _cd strings.
• Copy-edited the notebooks that still called nwis current or said waterdata "will replace" it, and removed the unused nwis import from the R-vignette notebook.
• Added nblinks for the two notebooks that weren't in the docs: USGS_WaterUse_Examples and hydroshare/USGS_NLDI_Examples. Updated examples/index.rst.

Prose

• Updated README, NEWS (new 10/22/2026 entry with a migration map), CONTEXT (NWIS entry now marked retired), AGENTS, CONTRIBUTING, the architecture overview, and userguide/dataportals.rst.
• ADR 0005 is marked completed. Where an ADR's Compliance section named the deleted contract or tests, I added a short dated note and left the historical reasoning alone.

Other deprecations evaluated

None of the other published horizons is earlier than May 2027, so they all stay. They are listed in the NEWS entry:

Surface	Horizon
get_time_series_metadata v0 filters	2027-06-01 (set by the service's v0 retirement)
get_cql(service=)	2027-08-09
wateruse alias	2027-08-11
ogc.interruptions	2027-08-25

The camelCase get_samples kwargs have no horizon published.

Remaining "NWIS" mentions (intentional)

• Domain vocabulary: WQP providers=NWIS, NLDI nwissite/nwisgw, NGWMN organization_type="NWIS", the USGS NWIS time-zone code list, and docstrings saying site numbers are assigned by NWIS.
• R readNWIS* calls quoted in the R-vignette notebook comments.
• Historical record: earlier NEWS entries, ADR narrative, and the CONTEXT glossary entry.

Testing

• ruff check, ruff format --check, lint-imports (7 kept), xenon, and complexipy all pass, as do the pre-commit hooks.
• pytest: 1650 passed. Branch coverage is 99.07%, above fail_under 98.9.
• mypy --python-version 3.12 is clean. Locally, the default 3.10 target fails only inside numpy's installed stub (type statement), which is unrelated to this change. CI should confirm.
• make html succeeds and the executed notebooks render. The only cell errors are NetworkErrors on WQP calls in rvignettes and DiscreteSamples, caused by a local SSL problem that also reproduces with a bare httpx.get.
• Ran against live services: the NWDC water-use notebook, WaterData_demo, Introduction, and peak_streamflow_trends. Ran retrieve_nwqn_streamflow.map_retrieval on one site with lithops and S3 stubbed out.
• Not verified end to end: the full nwqn lithops/S3 pipeline.