Suppress nested deprecation warnings; pin removal date via constant

`get_record(service='iv')` calls `get_iv`, which calls `query_waterservices`
— each of which now emits a DeprecationWarning. Without suppression the user
sees three near-identical messages for one call.

Walk the call stack inside `_warn_deprecated`: if any ancestor frame is also
a deprecated nwis function, skip. Only the outermost call surfaces a
warning, regardless of how the wrappers are layered. Add a regression test
that pins this contract.

Loosen `test_warn_message_includes_replacement` to assert against the
`_NWIS_REMOVAL_DATE` constant rather than the literal "2027-05-06" so a
future date change updates one place, not two.

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

Author: thodson-usgs

dataretrieval/nwis.py

@@ -6,6 +6,7 @@
 
 from __future__ import annotations
 
+import sys
 import warnings
 from json import JSONDecodeError
 
@@ -72,7 +73,19 @@
 
 
 def _warn_deprecated(func_name: str) -> None:
-    """Emit a per-function DeprecationWarning pointing at the waterdata replacement."""
+    """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
     warnings.warn(
         f"`nwis.{func_name}` is deprecated and will be removed from "
         f"`dataretrieval` on or after {_NWIS_REMOVAL_DATE}; "

tests/nwis_test.py

@@ -1,5 +1,6 @@
 import datetime
 import json
+import warnings
 from pathlib import Path
 from unittest import mock
 
@@ -145,15 +146,15 @@ 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
+        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)
         assert replacement_substring in message
-        assert "2027-05-06" in message
+        assert _NWIS_REMOVAL_DATE in message
 
     def test_get_iv_fires_deprecation_on_call(self, requests_mock):
         """End-to-end: a real call routes through _warn_deprecated."""
@@ -164,6 +165,23 @@ def test_get_iv_fires_deprecation_on_call(self, requests_mock):
         with pytest.warns(DeprecationWarning, match="get_iv.*waterdata.get_continuous"):
             get_iv(sites="01491000")
 
+    def test_nested_calls_emit_one_warning(self, requests_mock):
+        """get_record(service='iv') wraps get_iv -> query_waterservices.
+
+        Without re-entrancy suppression the user would see 3 near-identical
+        deprecation warnings for one call; pin the outermost-only contract.
+        """
+        requests_mock.get(
+            "https://waterservices.usgs.gov/nwis/iv",
+            json={"value": {"timeSeries": []}},
+        )
+        with warnings.catch_warnings(record=True) as caught:
+            warnings.simplefilter("always", DeprecationWarning)
+            get_record(sites="01491000", service="iv")
+        deprecations = [w for w in caught if issubclass(w.category, DeprecationWarning)]
+        assert len(deprecations) == 1
+        assert "get_record" in str(deprecations[0].message)
+
 
 class TestDefunct:
     """Verify that defunct functions raise NameError."""