refactor(wateruse): snake_case the public date / time-resolution params

Expose idiomatic snake_case parameter names on ``get_wateruse`` and map them to
the NWDC's compact wire names when the request is built — the same user-facing
convention as ``waterdata.get_samples`` (DOI-USGS#331):

    timeres   -> time_resolution
    startdate -> start_date
    enddate   -> end_date

Only the Python-facing parameters change; the NWDC query still receives
``timeres`` / ``startdate`` / ``enddate`` on the wire. ``wateruse`` is a new,
unreleased module, so there are no prior callers to keep compatible and no
deprecation shim is needed (unlike DOI-USGS#331, which had to accept the released
camelCase aliases).

Updates the signature, docstrings, the README and demo-notebook examples, and
adds a test pinning the snake_case -> wire-name mapping.

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

Author: thodson-usgs

README.md

@@ -133,7 +133,7 @@ sites, metadata = ngwmn.get_sites(state='Wisconsin')
 
 print(f"Found {len(sites)} NGWMN sites in Wisconsin")
 
-# Pull water levels from the first twenty sites over a time window. 
+# Pull water levels from the first twenty sites over a time window.
 water_levels, metadata = ngwmn.get_water_level(
     monitoring_location_id=sites['monitoring_location_id'][:20],
     datetime=['2022-01-01', '2024-01-01']
@@ -206,8 +206,8 @@ df, metadata = wateruse.get_wateruse(
     model='wu-public-supply-wd',
     variable=['pswdtot', 'pswdgw', 'pswdsw'],
     state='RI',  # name/postal/FIPS; pass a list to fan out over several areas
-    startdate='2020-01',
-    timeres='monthly',
+    start_date='2020-01',
+    time_resolution='monthly',
 )
 
 print(f"Retrieved {len(df)} records across {df['huc12_id'].nunique()} watersheds")

dataretrieval/wateruse.py

@@ -35,8 +35,8 @@
         model="wu-public-supply-wd",
         variable=["pswdtot", "pswdgw", "pswdsw"],
         state="RI",
-        startdate="2020-01",
-        timeres="monthly",
+        start_date="2020-01",
+        time_resolution="monthly",
     )
 
 """
@@ -96,9 +96,9 @@ def get_wateruse(
     state: str | int | Iterable[str | int] | None = None,
     county: str | Iterable[str] | None = None,
     huc: str | Iterable[str] | None = None,
-    timeres: str | None = None,
-    startdate: str | None = None,
-    enddate: str | None = None,
+    time_resolution: str | None = None,
+    start_date: str | None = None,
+    end_date: str | None = None,
     intersection: str = "overlap",
     limit: int = 600,
     ssl_check: bool = True,
@@ -146,15 +146,15 @@ def get_wateruse(
 
         Provide exactly one of ``state``, ``county``, or ``huc`` (each may be a
         single value or a list).
-    timeres : string, optional
+    time_resolution : string, optional
         Temporal resolution: ``"monthly"``, ``"annualcy"`` (annual, calendar
         year), or ``"annualwy"`` (annual, water year). See
         :data:`TIME_RESOLUTIONS`.
-    startdate : string, optional
+    start_date : string, optional
         Start of the query window, formatted ``"YYYY"`` for annual data or
         ``"YYYY-MM"`` for monthly data.
-    enddate : string, optional
-        End of the query window, in the same format as ``startdate``.
+    end_date : string, optional
+        End of the query window, in the same format as ``start_date``.
     intersection : string, optional
         How to select HUC12s that straddle the queried-area boundary:
         ``"overlap"`` (any overlap, the default) or ``"envelop"`` (fully
@@ -199,18 +199,21 @@ def get_wateruse(
         ...     model="wu-public-supply-wd",
         ...     variable=["pswdtot", "pswdgw", "pswdsw"],
         ...     state="RI",
-        ...     startdate="2020-01",
-        ...     timeres="monthly",
+        ...     start_date="2020-01",
+        ...     time_resolution="monthly",
         ... )
 
     """
+    # 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.
     base_params: dict[str, Any] = {
         "format": "csv",
         "model": model,
         "variable": to_str(variable),
-        "timeres": timeres,
-        "startdate": startdate,
-        "enddate": enddate,
+        "timeres": time_resolution,
+        "startdate": start_date,
+        "enddate": end_date,
         "intersection": intersection,
         "limit": limit,
     }

demos/USGS_WaterUse_Examples.ipynb

@@ -78,9 +78,9 @@
     "    model=\"wu-public-supply-wd\",\n",
     "    variable=[\"pswdtot\", \"pswdgw\", \"pswdsw\"],\n",
     "    state=\"WI\",\n",
-    "    startdate=\"2020-01\",\n",
-    "    enddate=\"2020-12\",\n",
-    "    timeres=\"monthly\",\n",
+    "    start_date=\"2020-01\",\n",
+    "    end_date=\"2020-12\",\n",
+    "    time_resolution=\"monthly\",\n",
     ")\n",
     "\n",
     "print(f\"{len(df):,} rows across {df['huc12_id'].nunique():,} HUC12 watersheds\")\n",
@@ -194,8 +194,8 @@
     "  default) is split across pages; `get_wateruse` follows the links and returns\n",
     "  a single concatenated frame. Whole-region queries (e.g. `huc=\"04\"`)\n",
     "  may return many pages and take longer.\n",
-    "- **Annual data.** Set `timeres=\"annualcy\"` (calendar year) or `\"annualwy\"`\n",
-    "  (water year) and use four-digit years for `startdate`/`enddate`; the time\n",
+    "- **Annual data.** Set `time_resolution=\"annualcy\"` (calendar year) or `\"annualwy\"`\n",
+    "  (water year) and use four-digit years for `start_date`/`end_date`; the time\n",
     "  column comes back as `year` instead of `year_month`.\n",
     "- **Other models.** Swap `model` and `variable` to retrieve irrigation\n",
     "  (`wu-irrigation-wd`) or thermoelectric (`wu-thermoelectric`) water use. See\n",

tests/wateruse_test.py

@@ -47,8 +47,8 @@ def test_get_wateruse_single_page(httpx_mock):
         model="wu-public-supply-wd",
         variable=["pswdtot", "pswdgw", "pswdsw"],
         state="RI",
-        startdate="2020-01",
-        timeres="monthly",
+        start_date="2020-01",
+        time_resolution="monthly",
     )
 
     assert isinstance(df, pd.DataFrame)
@@ -105,6 +105,26 @@ def test_unset_params_are_dropped(httpx_mock):
     assert qs["limit"] == ["600"]
 
 
+def test_snake_case_date_params_map_to_nwdc_wire_names(httpx_mock):
+    """The public snake_case params (``start_date`` / ``end_date`` /
+    ``time_resolution``) are sent under the NWDC's compact wire names
+    (``startdate`` / ``enddate`` / ``timeres``)."""
+    httpx_mock.add_response(method="GET", url=WU_RE, text=_CSV_PAGE)
+
+    get_wateruse(
+        model="wu-public-supply-wd",
+        state="RI",
+        start_date="2020-01",
+        end_date="2020-12",
+        time_resolution="monthly",
+    )
+
+    qs = parse_qs(urlsplit(str(httpx_mock.get_requests()[0].url)).query)
+    assert qs["startdate"] == ["2020-01"]
+    assert qs["enddate"] == ["2020-12"]
+    assert qs["timeres"] == ["monthly"]
+
+
 def test_pagination_follows_link_header_and_concatenates(httpx_mock):
     """Pages are followed via the ``rel="next"`` Link header and concatenated."""
     httpx_mock.add_response(