Tighten _legacy_only_url and clean up test imports

Per /simplify review on PR #256:
- Unify the two `wqp_url(service)` returns in `_legacy_only_url` into a
  single return inside `warnings.catch_warnings()`, gating the warn and
  filter on `not legacy`.
- Document the asymmetric `stacklevel=3` in `_warn_wqx3_unavailable`.
- Hoist `import warnings` from inside the new regression test to the
  module-level imports in `tests/wqp_test.py`.
- Compress the regression test's docstring.

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

Author: thodson-usgs

dataretrieval/wqp.py

@@ -691,6 +691,7 @@ def _warn_legacy_use():
 
 
 def _warn_wqx3_unavailable():
+    # stacklevel=3: warn -> _warn_wqx3_unavailable -> _legacy_only_url -> what_*
     warnings.warn(
         "WQX3.0 profile not available, returning legacy profile.",
         UserWarning,
@@ -707,9 +708,8 @@ def _legacy_only_url(service: str, legacy: bool) -> str:
     message claims setting ``legacy=False`` removes the warning, which is
     a lie for endpoints that have no WQX3.0 alternative.
     """
-    if not legacy:
-        _warn_wqx3_unavailable()
-        with warnings.catch_warnings():
+    with warnings.catch_warnings():
+        if not legacy:
+            _warn_wqx3_unavailable()
             warnings.simplefilter("ignore", DeprecationWarning)
-            return wqp_url(service)
-    return wqp_url(service)
+        return wqp_url(service)

tests/wqp_test.py

@@ -1,4 +1,5 @@
 import datetime
+import warnings
 
 import pytest
 from pandas import DataFrame
@@ -219,13 +220,8 @@ def test_check_kwargs():
 
 
 def test_what_organizations_legacy_false_warns(requests_mock):
-    """legacy=False on a legacy-only helper:
-    - emits the WQX3.0-unavailable UserWarning
-    - suppresses the redundant legacy DeprecationWarning, whose text would
-      misleadingly tell the user that setting legacy=False removes it.
-    """
-    import warnings
-
+    """legacy=False on a legacy-only helper warns and suppresses the
+    misleading legacy DeprecationWarning."""
     request_url = (
         "https://www.waterqualitydata.us/data/Organization/Search?statecode=US%3A34"
         "&characteristicName=Chloride&mimeType=csv"