Switch to @_deprecated decorator; drop sys._getframe walk

Replaces nine `_warn_deprecated("name")` first-line calls with `@_deprecated`
above the function definition. The decorator does three things:

  1. Validates `func.__name__ in _REPLACEMENTS` at import time, so a missing
     mapping fails loudly instead of producing a KeyError on the first user
     call.
  2. Drops the stringly-typed `_warn_deprecated("get_iv")` call sites — the
     name now flows from `func.__name__`, so a typo can't drift from the
     real symbol.
  3. Replaces the `sys._getframe` stack walk with a thread-local re-entrancy
     flag. Because the decorator wraps the whole function call (not just the
     warn line), the flag's lifetime spans nested wrapper invocations
     correctly. No CPython implementation detail required.

Tighten the NEWS.md entry and drop the unused `requests_mock` fixture from
`test_warn_message_includes_replacement` (it never made an HTTP request).

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

Author: thodson-usgs

NEWS.md

@@ -1,4 +1,4 @@
-**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:** Each remaining active function in `dataretrieval.nwis` now emits a per-function `DeprecationWarning` naming the `waterdata` replacement to migrate to (visible the first time users call each getter). The `nwis` module is scheduled for removal on or after **2027-05-06**.
 
 **05/05/2026:** Added `waterdata.get_combined_metadata(...)` — wraps the Water Data API's `combined-metadata` collection, which joins the monitoring-locations catalog with the time-series-metadata catalog and returns one row per (location, parameter, statistic) inventory entry. This is the most flexible "what data is available" endpoint in the API: any location attribute (state, HUC, site type, drainage area, well-construction depth, …) can be combined with any time-series attribute (parameter code, statistic, data type, period of record, …) in a single query. Mirrors R's `read_waterdata_combined_meta`.
 

dataretrieval/nwis.py

@@ -6,7 +6,8 @@
 
 from __future__ import annotations
 
-import sys
+import functools
+import threading
 import warnings
 from io import StringIO
 from json import JSONDecodeError
@@ -46,9 +47,6 @@
 _CRS = "EPSG:4269"
 
 
-# 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()`",
@@ -63,21 +61,11 @@
     "query_waterservices": "a high-level `waterdata.get_*()` helper",
 }
 
+_deprecation_state = threading.local()
 
-def _warn_deprecated(func_name: str) -> None:
-    """Emit a per-function DeprecationWarning pointing at the waterdata replacement.
 
-    Suppresses the warning when invoked from another deprecated nwis function so
-    that wrappers like ``get_record`` -> ``get_iv`` -> ``query_waterservices``
-    surface only the outermost call (otherwise one user call produces three
-    near-identical messages).
-    """
-    module_globals = globals()
-    frame = sys._getframe(2) if hasattr(sys, "_getframe") else None
-    while frame is not None:
-        if frame.f_globals is module_globals and frame.f_code.co_name in _REPLACEMENTS:
-            return
-        frame = frame.f_back
+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}; "
@@ -87,6 +75,33 @@ def _warn_deprecated(func_name: str) -> None:
     )
 
 
+def _deprecated(func):
+    """Mark an nwis function as deprecated.
+
+    Wrappers like ``get_record`` -> ``get_iv`` -> ``query_waterservices`` would
+    otherwise emit one warning per layer; the thread-local sentinel ensures the
+    user sees only the outermost call's warning.
+    """
+    if func.__name__ not in _REPLACEMENTS:
+        raise RuntimeError(
+            f"_REPLACEMENTS missing entry for {func.__name__!r}; "
+            "add a `waterdata` replacement before applying @_deprecated."
+        )
+
+    @functools.wraps(func)
+    def wrapper(*args, **kwargs):
+        if getattr(_deprecation_state, "active", False):
+            return func(*args, **kwargs)
+        _deprecation_state.active = True
+        try:
+            _warn_deprecated(func.__name__)
+            return func(*args, **kwargs)
+        finally:
+            _deprecation_state.active = False
+
+    return wrapper
+
+
 def _parse_json_or_raise(response: requests.Response) -> pd.DataFrame:
     """Parse a JSON NWIS response, raising a helpful error on HTML responses."""
     try:
@@ -197,6 +212,7 @@ def get_discharge_measurements(**kwargs):
     )
 
 
+@_deprecated
 def get_discharge_peaks(
     sites: list[str] | str | None = None,
     start: str | None = None,
@@ -250,7 +266,6 @@ def get_discharge_peaks(
         ... )
 
     """
-    _warn_deprecated("get_discharge_peaks")
     _check_sites_value_types(sites)
 
     kwargs["site_no"] = kwargs.pop("site_no", sites)
@@ -275,6 +290,7 @@ def get_gwlevels(**kwargs):
     )
 
 
+@_deprecated
 def get_stats(
     sites: list[str] | str | None = None, ssl_check: bool = True, **kwargs
 ) -> tuple[pd.DataFrame, BaseMetadata]:
@@ -327,7 +343,6 @@ def get_stats(
         ... )
 
     """
-    _warn_deprecated("get_stats")
     _check_sites_value_types(sites)
 
     response = query_waterservices(
@@ -337,6 +352,7 @@ def get_stats(
     return _read_rdb(response.text), NWIS_Metadata(response, **kwargs)
 
 
+@_deprecated
 def query_waterdata(
     service: str, ssl_check: bool = True, **kwargs
 ) -> requests.models.Response:
@@ -358,7 +374,6 @@ 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",
@@ -383,6 +398,7 @@ def query_waterdata(
     return query(url, payload=kwargs, ssl_check=ssl_check)
 
 
+@_deprecated
 def query_waterservices(
     service: str, ssl_check: bool = True, **kwargs
 ) -> requests.models.Response:
@@ -428,7 +444,6 @@ 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"]
     ):
@@ -447,6 +462,7 @@ def query_waterservices(
     return query(url, payload=kwargs, ssl_check=ssl_check)
 
 
+@_deprecated
 def get_dv(
     sites: list[str] | str | None = None,
     start: str | None = None,
@@ -505,7 +521,6 @@ 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)
@@ -519,6 +534,7 @@ def get_dv(
     return format_response(df, **kwargs), NWIS_Metadata(response, **kwargs)
 
 
+@_deprecated
 def get_info(ssl_check: bool = True, **kwargs) -> tuple[pd.DataFrame, BaseMetadata]:
     """
     Get site description information from NWIS.
@@ -611,7 +627,6 @@ 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(
@@ -635,6 +650,7 @@ def get_info(ssl_check: bool = True, **kwargs) -> tuple[pd.DataFrame, BaseMetada
     return _read_rdb(response.text), NWIS_Metadata(response, **kwargs)
 
 
+@_deprecated
 def get_iv(
     sites: list[str] | str | None = None,
     start: str | None = None,
@@ -690,7 +706,6 @@ def get_iv(
         ... )
 
     """
-    _warn_deprecated("get_iv")
     _check_sites_value_types(sites)
 
     kwargs["startDT"] = kwargs.pop("startDT", start)
@@ -719,6 +734,7 @@ def get_water_use(**kwargs):
     raise NameError("`nwis.get_water_use` is defunct.")
 
 
+@_deprecated
 def get_ratings(
     site: str | None = None,
     file_type: str = "base",
@@ -760,7 +776,6 @@ def get_ratings(
         >>> df, md = dataretrieval.nwis.get_ratings(site="01594440")
 
     """
-    _warn_deprecated("get_ratings")
     site = kwargs.pop("site_no", site)
 
     payload = {}
@@ -777,6 +792,7 @@ def get_ratings(
     return _read_rdb(response.text), NWIS_Metadata(response, site_no=site)
 
 
+@_deprecated
 def what_sites(ssl_check: bool = True, **kwargs) -> tuple[pd.DataFrame, BaseMetadata]:
     """
     Search NWIS for sites within a region with specific data.
@@ -809,15 +825,14 @@ 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)
 
     df = _read_rdb(response.text)
 
     return df, NWIS_Metadata(response, **kwargs)
 
 
+@_deprecated
 def get_record(
     sites: list[str] | str | None = None,
     start: str | None = None,
@@ -906,7 +921,6 @@ def get_record(
         ... )
 
     """
-    _warn_deprecated("get_record")
     _check_sites_value_types(sites)
 
     defunct_replacements = {

tests/nwis_test.py

@@ -142,14 +142,10 @@ class TestDeprecationWarnings:
             ("query_waterservices", "waterdata.get_*"),
         ],
     )
-    def test_warn_message_includes_replacement(
-        self, func_name, replacement_substring, requests_mock
-    ):
+    def test_warn_message_includes_replacement(self, func_name, replacement_substring):
         """Each deprecated function emits a warning naming the right replacement."""
         from dataretrieval.nwis import _NWIS_REMOVAL_DATE, _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)