feat(wateruse): warn that the module is experimental on each call

The USGS NWDC water-use service is new and still changing, so flag `wateruse` as
experimental: a `FutureWarning` (in the spirit of `pandas.DataFrame.attrs`'
experimental notice) plus a `.. warning::` admonition in the `get_wateruse`
docstring.

Emitted per call rather than on import: `dataretrieval` imports `wateruse`
eagerly (`from . import wateruse`), so an import-time warning would fire for
every `import dataretrieval` user; firing inside `get_wateruse` reaches only
callers who actually request water-use data. The tests silence the warning
module-wide and assert it once explicitly.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01Sjb14HkwuCydKSKMsaXsgd

Author: thodson-usgs

dataretrieval/wateruse.py

@@ -45,6 +45,7 @@
 
 import asyncio
 import io
+import warnings
 from collections.abc import Callable, Iterable
 from typing import Any
 
@@ -105,6 +106,13 @@ def get_wateruse(
 ) -> tuple[pd.DataFrame, BaseMetadata]:
     """Get USGS water-use data from the NWDC web service.
 
+    .. warning::
+
+       ``dataretrieval.wateruse`` is **experimental**. The USGS NWDC water-use
+       service is new and still changing, so this function's parameters and
+       returned columns may change without warning. Pin a ``dataretrieval``
+       version if you need a stable interface.
+
     Retrieves modeled water-use estimates from the USGS National Water
     Availability Assessment Data Companion. The area is given as exactly one of
     ``state``, ``county``, or ``huc``; results are always returned on a HUC12
@@ -204,6 +212,18 @@ def get_wateruse(
         ... )
 
     """
+    # Experimental-status notice. Emitted per call rather than on import
+    # because ``dataretrieval`` imports this module eagerly, so an import-time
+    # warning would fire for every ``import dataretrieval`` user; firing here
+    # reaches only callers who actually request water-use data.
+    warnings.warn(
+        "dataretrieval.wateruse is experimental: the USGS NWDC water-use "
+        "service is new and still changing, so this function's parameters and "
+        "returned columns may change without warning. Pin a dataretrieval "
+        "version if you need a stable interface.",
+        FutureWarning,
+        stacklevel=2,
+    )
     # The public parameters are idiomatic snake_case (consistent with
     # ``waterdata.get_samples``); the NWDC service expects compact lowercase
     # query names, so map to those here as the request is built.

tests/wateruse_test.py

@@ -15,6 +15,10 @@
 from dataretrieval.utils import BaseMetadata
 from dataretrieval.wateruse import _next_page_url, _resolve_locations, get_wateruse
 
+# ``get_wateruse`` emits an experimental-status FutureWarning on every call; the
+# dedicated test below asserts it explicitly, so silence it for the rest.
+pytestmark = pytest.mark.filterwarnings("ignore::FutureWarning")
+
 # Match the NWDC endpoint regardless of query string, so assertions can drill
 # into the captured params without coupling registration to param order.
 WU_RE = re.compile(r"^https://api\.water\.usgs\.gov/nwaa-data/data(\?.*)?$")
@@ -63,6 +67,15 @@ def test_get_wateruse_single_page(httpx_mock):
     assert len(df) == 3
 
 
+def test_get_wateruse_warns_experimental(httpx_mock):
+    """``get_wateruse`` emits a ``FutureWarning`` flagging the module as
+    experimental (the NWDC service and this interface are still settling)."""
+    httpx_mock.add_response(method="GET", url=WU_RE, text=_CSV_PAGE)
+
+    with pytest.warns(FutureWarning, match="experimental"):
+        get_wateruse(model="wu-public-supply-wd", state="RI")
+
+
 def test_huc12_id_kept_as_string_with_leading_zero(httpx_mock):
     """The HUC12 identifier must not be coerced to int (leading zeros matter)."""
     httpx_mock.add_response(method="GET", url=WU_RE, text=_CSV_PAGE)