Deprecate the remaining active nwis functions ahead of 2027-05-06 removal

The module-level "use waterdata instead" warning has been firing on
import for a while; this PR makes the migration guidance actionable
by emitting a per-function DeprecationWarning that names the specific
waterdata replacement the user should switch to.

Once peaks (DOI-USGS#267) and ratings (DOI-USGS#269) land, every active nwis function
has a waterdata replacement, so all nine of them are deprecated here:

  nwis.get_dv               -> waterdata.get_daily()
  nwis.get_iv               -> waterdata.get_continuous()
  nwis.get_info             -> waterdata.get_monitoring_locations()
  nwis.what_sites           -> waterdata.get_monitoring_locations()
  nwis.get_stats            -> waterdata.get_stats_por() /
                              waterdata.get_stats_date_range()
  nwis.get_discharge_peaks  -> waterdata.get_peaks()
  nwis.get_ratings          -> waterdata.get_ratings()
  nwis.get_record           -> the appropriate waterdata.get_*()
  nwis.query_waterdata      -> a high-level waterdata.get_*() helper
  nwis.query_waterservices  -> a high-level waterdata.get_*() helper

(get_qwdata, get_discharge_measurements, get_gwlevels, get_pmcodes,
and get_water_use are already defunct and raise NameError.)

Implementation follows the nadp deprecation template (DOI-USGS#243): a small
_REPLACEMENTS dict + a _warn_deprecated(func_name) helper called as
the first line of each public function. stacklevel=3 makes the
warning point at the caller's code, not the helper's frame.

11 new parametrized tests pin the warning text — that the function
name appears, the replacement helper appears, and the removal date
appears — plus one end-to-end test that get_iv() actually fires
its warning when called.

Removal date is set to 2027-05-06, one full year out (vs. the six
months used for nadp), since nwis is much more widely used and most
users will need migration time. Maintainer can adjust if desired.

This depends on DOI-USGS#267 (waterdata.get_peaks) and DOI-USGS#269 (waterdata.get_ratings)
being merged: until then the deprecation messages for get_discharge_peaks
and get_ratings point at functions users can't yet call. Hold this PR
draft until those land.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Author: thodson-usgs

NEWS.md

@@ -1,3 +1,5 @@
+**05/06/2026:** Each remaining active function in `dataretrieval.nwis` now emits a per-function `DeprecationWarning` that names its `waterdata` replacement (`get_dv` → `get_daily`, `get_iv` → `get_continuous`, `get_info` / `what_sites` → `get_monitoring_locations`, `get_stats` → `get_stats_por` / `get_stats_date_range`, `get_discharge_peaks` → `get_peaks`, `get_ratings` → `get_ratings`, `get_record` / `query_waterdata` / `query_waterservices` → the appropriate `waterdata.get_*()` helper). The `nwis` module is scheduled for removal on or after **2027-05-06**.
+
 **05/06/2026:** Added `waterdata.get_ratings(...)` — wraps the new Water Data STAC catalog (`api.waterdata.usgs.gov/stac/v0/search`) for USGS stage-discharge rating curves. Returns parsed `exsa` / `base` / `corr` rating tables as a dict of DataFrames keyed by feature ID, or just the list of available STAC features when `download_and_parse=False`. Mirrors R's `read_waterdata_ratings`.
 
 **05/06/2026:** Added `waterdata.get_field_measurements_metadata(...)` — wraps the OGC `field-measurements-metadata` collection. Returns one row per (location, parameter) field-measurement series describing its period of record, units, etc., without the underlying observations. Discrete-measurement analogue to `get_time_series_metadata`. Mirrors R's `read_waterdata_field_meta`.

dataretrieval/nwis.py

@@ -53,6 +53,35 @@
 }
 
 
+# Per-function deprecation. The module-level warning above tells users that
+# `nwis` overall is being phased out; these replacements tell them which
+# `waterdata` function to migrate each call to. Scheduled removal: 2027-05-06.
+_NWIS_REMOVAL_DATE = "2027-05-06"
+_REPLACEMENTS = {
+    "get_dv": "`waterdata.get_daily()`",
+    "get_iv": "`waterdata.get_continuous()`",
+    "get_info": "`waterdata.get_monitoring_locations()`",
+    "what_sites": "`waterdata.get_monitoring_locations()`",
+    "get_stats": "`waterdata.get_stats_por()` or `waterdata.get_stats_date_range()`",
+    "get_discharge_peaks": "`waterdata.get_peaks()`",
+    "get_ratings": "`waterdata.get_ratings()`",
+    "get_record": "the appropriate `waterdata.get_*()` for the service you need",
+    "query_waterdata": "a high-level `waterdata.get_*()` helper",
+    "query_waterservices": "a high-level `waterdata.get_*()` helper",
+}
+
+
+def _warn_deprecated(func_name: str) -> None:
+    """Emit a per-function DeprecationWarning pointing at the waterdata replacement."""
+    warnings.warn(
+        f"`nwis.{func_name}` is deprecated and will be removed from "
+        f"`dataretrieval` on or after {_NWIS_REMOVAL_DATE}; "
+        f"use {_REPLACEMENTS[func_name]} instead.",
+        DeprecationWarning,
+        stacklevel=3,
+    )
+
+
 def _parse_json_or_raise(response: requests.Response) -> pd.DataFrame:
     """Parse a JSON NWIS response, raising a helpful error on HTML responses."""
     try:
@@ -216,6 +245,7 @@ def get_discharge_peaks(
         ... )
 
     """
+    _warn_deprecated("get_discharge_peaks")
     _check_sites_value_types(sites)
 
     kwargs["site_no"] = kwargs.pop("site_no", sites)
@@ -292,6 +322,7 @@ def get_stats(
         ... )
 
     """
+    _warn_deprecated("get_stats")
     _check_sites_value_types(sites)
 
     response = query_waterservices(
@@ -322,6 +353,7 @@ def query_waterdata(
     request: ``requests.models.Response``
         The response object from the API request to the web service
     """
+    _warn_deprecated("query_waterdata")
     major_params = ["site_no", "state_cd"]
     bbox_params = [
         "nw_longitude_va",
@@ -391,6 +423,7 @@ def query_waterservices(
         The response object from the API request to the web service
 
     """
+    _warn_deprecated("query_waterservices")
     if not any(
         key in kwargs for key in ["sites", "stateCd", "bBox", "huc", "countyCd"]
     ):
@@ -467,6 +500,7 @@ def get_dv(
         >>> df, md = dataretrieval.nwis.get_dv(sites="01646500")
 
     """
+    _warn_deprecated("get_dv")
     _check_sites_value_types(sites)
 
     kwargs["startDT"] = kwargs.pop("startDT", start)
@@ -572,6 +606,7 @@ def get_info(ssl_check: bool = True, **kwargs) -> tuple[pd.DataFrame, BaseMetada
         >>> df, md = dataretrieval.nwis.get_info(sites=["05114000", "09423350"])
 
     """
+    _warn_deprecated("get_info")
     seriesCatalogOutput = kwargs.pop("seriesCatalogOutput", None)
     if seriesCatalogOutput in ["True", "TRUE", "true", True]:
         warnings.warn(
@@ -650,6 +685,7 @@ def get_iv(
         ... )
 
     """
+    _warn_deprecated("get_iv")
     _check_sites_value_types(sites)
 
     kwargs["startDT"] = kwargs.pop("startDT", start)
@@ -719,6 +755,7 @@ def get_ratings(
         >>> df, md = dataretrieval.nwis.get_ratings(site="01594440")
 
     """
+    _warn_deprecated("get_ratings")
     site = kwargs.pop("site_no", site)
 
     payload = {}
@@ -767,6 +804,7 @@ def what_sites(ssl_check: bool = True, **kwargs) -> tuple[pd.DataFrame, BaseMeta
         ... )
 
     """
+    _warn_deprecated("what_sites")
 
     response = query_waterservices(service="site", ssl_check=ssl_check, **kwargs)
 
@@ -863,6 +901,7 @@ def get_record(
         ... )
 
     """
+    _warn_deprecated("get_record")
     _check_sites_value_types(sites)
 
     defunct_replacements = {

tests/nwis_test.py

@@ -118,6 +118,53 @@ def test_preformat_peaks_response():
 # Removed defunct gwlevels tests.
 
 
+class TestDeprecationWarnings:
+    """Verify per-function DeprecationWarning fires with the right replacement.
+
+    The module-level "use waterdata instead" warning fires on import; these
+    tests pin the function-specific replacements so users see actionable
+    migration guidance the first time they call each NWIS getter.
+    """
+
+    @pytest.mark.parametrize(
+        "func_name, replacement_substring",
+        [
+            ("get_dv", "waterdata.get_daily"),
+            ("get_iv", "waterdata.get_continuous"),
+            ("get_info", "waterdata.get_monitoring_locations"),
+            ("what_sites", "waterdata.get_monitoring_locations"),
+            ("get_stats", "waterdata.get_stats_por"),
+            ("get_discharge_peaks", "waterdata.get_peaks"),
+            ("get_ratings", "waterdata.get_ratings"),
+            ("get_record", "waterdata.get_*"),
+            ("query_waterdata", "waterdata.get_*"),
+            ("query_waterservices", "waterdata.get_*"),
+        ],
+    )
+    def test_warn_message_includes_replacement(
+        self, func_name, replacement_substring, requests_mock
+    ):
+        """Each deprecated function emits a warning naming the right replacement."""
+        from dataretrieval.nwis import _warn_deprecated
+
+        # Test the helper directly so we don't need to spin up a fake response
+        # for every function. The integration is checked once below.
+        with pytest.warns(DeprecationWarning, match=func_name) as record:
+            _warn_deprecated(func_name)
+        message = str(record[0].message)
+        assert replacement_substring in message
+        assert "2027-05-06" in message
+
+    def test_get_iv_fires_deprecation_on_call(self, requests_mock):
+        """End-to-end: a real call routes through _warn_deprecated."""
+        requests_mock.get(
+            "https://waterservices.usgs.gov/nwis/iv",
+            json={"value": {"timeSeries": []}},
+        )
+        with pytest.warns(DeprecationWarning, match="get_iv.*waterdata.get_continuous"):
+            get_iv(sites="01491000")
+
+
 class TestDefunct:
     """Verify that defunct functions raise NameError."""