chore!: remove the nadp module and the deprecated samples shim (#330)

Ahead of the 1.2.0 release (which allows breaking changes), remove two
deprecated modules and every reference to them except the changelog:

- `dataretrieval.nadp` — deprecated 2026-05-01. NADP is not a USGS data source;
  retrieve NADP data directly from https://nadp.slh.wisc.edu/.
- `dataretrieval.samples` — the `get_usgs_samples` shim that only forwarded to
  `waterdata.get_samples()`. Use `waterdata.get_samples()` directly.

Deleted: both modules, `tests/nadp_test.py`, and their reference doc pages
`docs/source/reference/{nadp,samples}.rst`. Updated references: the `nadp`
API-toctree entry, the two NADP rows in the data-portals table, the
`nadp`/`samples` entries in `dataretrieval/__init__` (imports, `__all__`, the
module-list docstring), the `nadp` mentions in the shared `exceptions`/`utils`
docstrings, and the `nadp_test` note in AGENTS.md. A NEWS.md entry records the
removal.

The modern `waterdata.get_samples()` / `get_samples_summary()` and their demo
notebooks are untouched — only the deprecated `samples` shim is removed.
(Rebased onto main: the `ngwmn` module + OGC engine added in #324 are kept; the
`samples.rst` autodoc page main added for the now-removed module is dropped.)

BREAKING CHANGE: `import dataretrieval.nadp` and `import dataretrieval.samples`
now raise ModuleNotFoundError; `samples.get_usgs_samples` is gone — use
`waterdata.get_samples()`.


Claude-Session: https://claude.ai/code/session_01Sjb14HkwuCydKSKMsaXsgd

Co-authored-by: Claude Opus 4.8 <noreply@anthropic.com>

Author: thodson-usgs

AGENTS.md

@@ -22,7 +22,6 @@
 ## Testing Gotchas
 - Tests mock HTTP with `pytest-httpx`'s `httpx_mock` fixture and fixtures under `tests/data/`; keep new API tests offline. `tests/conftest.py` relaxes the fixture's strict-mode defaults (unused mocks and unmocked requests are tolerated) so rerun-on-failure works.
 - `tests/nwis_test.py::test_nwis_service_live` hits live NWIS.
-- `tests/nadp_test.py` is module-skipped (NADP deprecated).
 - `tests/waterdata_test.py` and `tests/waterdata_ratings_test.py` skip on Python <3.10, so a 3.9 run does not cover them.
 
 ## Implementation Notes

NEWS.md

@@ -1,3 +1,5 @@
+**06/23/2026:** **Breaking change (1.2.0):** removed the `nadp` module and the deprecated `samples` module ahead of the 1.2.0 release. `nadp` was deprecated on 05/01/2026 — NADP is not a USGS data source, so retrieve NADP data directly from https://nadp.slh.wisc.edu/. The `samples.get_usgs_samples` shim (a deprecated forward to the modern getter) is gone; use `waterdata.get_samples()` instead. `import dataretrieval.nadp` / `import dataretrieval.samples` now raise `ModuleNotFoundError`.
+
 **06/03/2026:** The request-error hierarchy is now unified. Every module (`nwis`, `wqp`, `nldi`, `waterdata`, `nadp`, `streamstats`) raises a subclass of `dataretrieval.DataRetrievalError` on a failed request, so a single `except dataretrieval.DataRetrievalError` spans them all. An HTTP error status surfaces as an `HTTPError` carrying `.status_code` (inspect it to branch on a specific code); the retryable 429/5xx subset is `TransientError` (`RateLimited` / `ServiceUnavailable`, carrying `.retry_after`); and a request too large to satisfy is a `RequestTooLarge` (`URLTooLong` for an over-long single request, `Unchunkable` when the Water Data chunker cannot split a call small enough). Connection-level failures (timeouts, DNS, refused connections) are wrapped as a `NetworkError`, with the underlying `httpx` exception on `__cause__`. Every `DataRetrievalError` also exposes `.status_code` (`None` when there is no HTTP status), `.retry_after`, and `.retryable`, so a single `except dataretrieval.DataRetrievalError as e` clause can branch on the status or retry transient failures without knowing the concrete subclass. **Breaking change:** these exceptions no longer multiply-inherit a built-in — code that caught request failures with `except ValueError` or `except RuntimeError` should switch to `except dataretrieval.DataRetrievalError` (or a specific subclass). A no-data result is **not** an error: the modern getters (`waterdata`, `wqp`, `nldi`) return an empty DataFrame when nothing matches. Only the deprecated `nwis` (waterservices) path still raises `NoSitesError` on no data.
 
 **05/17/2026:** The OGC `waterdata` getters (`get_daily`, `get_continuous`, `get_field_measurements`, and the rest of the multi-value-capable functions) now transparently chunk requests whose URLs would otherwise exceed the server's ~8 KB byte limit.

dataretrieval/__init__.py

@@ -11,8 +11,7 @@
     df, meta = nwis.get_dv(sites="05427718")
 
 Available service modules: ``waterdata``, ``wqp`` (Water Quality Portal),
-``nldi``, ``samples``, ``streamstats``, and the deprecated ``nwis`` and
-``nadp``.
+``nldi``, ``streamstats``, and the deprecated ``nwis``.
 
 ``nldi`` requires geopandas (``pip install dataretrieval[nldi]``) and is
 imported on demand: ``from dataretrieval import nldi``.
@@ -58,10 +57,8 @@
 
 from . import (
     exceptions,
-    nadp,
     ngwmn,
     nwis,
-    samples,
     streamstats,
     utils,
     waterdata,
@@ -70,10 +67,8 @@
 
 __all__ = [
     # service modules
-    "nadp",
     "ngwmn",
     "nwis",
-    "samples",
     "streamstats",
     "utils",
     "waterdata",

dataretrieval/exceptions.py

@@ -1,6 +1,6 @@
 """Exception taxonomy for ``dataretrieval``.
 
-Every service module (``nwis``, ``wqp``, ``nldi``, ``waterdata``, ``nadp``,
+Every service module (``nwis``, ``wqp``, ``nldi``, ``waterdata``,
 ``streamstats``) raises a subclass of :class:`DataRetrievalError` when a request
 fails, so one ``except dataretrieval.DataRetrievalError`` catches them all --
 including connection-level failures (timeouts, DNS, refused connections), which
@@ -267,7 +267,7 @@ def error_for_status(
     """Return the typed :class:`DataRetrievalError` for an HTTP error *status*.
 
     The one status-to-type mapping every request path shares (the legacy
-    ``query`` path, ``waterdata``, ``nadp`` / ``streamstats``), so a given status
+    ``query`` path, ``waterdata``, ``streamstats``), so a given status
     becomes the same type everywhere:
 
     * **413, 414** -> :class:`URLTooLong` (a :class:`RequestTooLarge`) -- the

dataretrieval/nadp.py

@@ -311,7 +311,7 @@ def _raise_for_status(response: httpx.Response) -> None:
     """Raise the typed :class:`DataRetrievalError` for an HTTP error response;
     return ``None`` on success.
 
-    Shared by the legacy :func:`query` path (and ``nadp`` / ``streamstats``).
+    Shared by the legacy :func:`query` path (and ``streamstats``).
     Delegates the status-to-type mapping to
     :func:`dataretrieval.exceptions.error_for_status`, except a too-long-URL
     status (413 / 414): that gets the same actionable "split your query"

dataretrieval/samples.py

@@ -8,11 +8,9 @@ API reference
     :maxdepth: 1
 
     exceptions
-    nadp
     ngwmn
     nldi
     nwis
-    samples
     streamstats
     utils
     waterdata