Extract _DATE_RANGE_PARAMS; trim docstrings/comments from /simplify

Three small follow-ups to the centralization:

1. Extract `_DATE_RANGE_PARAMS = frozenset({"datetime", "last_modified",
   "begin", "end", "time"})` once at module level. `_construct_api_requests`
   previously defined the same set twice (`single_params` for POST/GET
   routing, `time_periods` for the `_format_api_dates` call); the new
   `_NO_NORMALIZE_PARAMS` overlapped on the same five names. All three
   now reuse `_DATE_RANGE_PARAMS`. A future date param means one edit,
   not three. `_NO_NORMALIZE_PARAMS = _DATE_RANGE_PARAMS | {"monitoring_location_id"}`.

2. Trim `_normalize_str_iterable` docstring from ~37 lines to ~20: drop
   the over-narration of callers and downstream branching; keep the
   contract (accepted shapes, return shape, raises).

3. Tighten the `_NO_NORMALIZE_PARAMS` comment to one short paragraph
   (was 11 lines) and inline the four-branch pass-through cascade in
   `_get_args` into a single boolean `if ... or ... or ... or ...:` so
   the per-branch noise comments drop away. Behavior unchanged.

26 normalizer/validator + 22 waterdata_utils tests pass; full suite
267 passed + 2 skipped + 4 deselected (flaky live-API 502s); ruff lint
+ format clean.

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

Author: thodson-usgs

dataretrieval/waterdata/utils.py

@@ -144,6 +144,13 @@ def _switch_properties_id(properties: list[str] | None, id_name: str, service: s
 # admits time-only forms like ``PT36H``.
 _DURATION_RE = re.compile(r"^[Pp]T?\d")
 
+# OGC API parameters that carry a date/datetime value (single string,
+# two-element range, or interval/duration string) rather than a multi-value
+# string list. Used by ``_construct_api_requests`` to keep them out of the
+# POST/CQL2 multi-value path and to route them through ``_format_api_dates``,
+# and by ``_NO_NORMALIZE_PARAMS`` to bypass string-iterable normalization.
+_DATE_RANGE_PARAMS = frozenset({"datetime", "last_modified", "begin", "end", "time"})
+
 
 def _parse_datetime(value: str) -> datetime | None:
     """Parse a single datetime string against the supported formats.
@@ -418,14 +425,11 @@ def _construct_api_requests(
     """
     service_url = f"{OGC_API_URL}/collections/{service}/items"
 
-    # Single parameters can only have one value
-    single_params = {"datetime", "last_modified", "begin", "end", "time"}
-
     # Identify which parameters should be included in the POST content body
     post_params = {
         k: v
         for k, v in kwargs.items()
-        if k not in single_params and isinstance(v, (list, tuple)) and len(v) > 1
+        if k not in _DATE_RANGE_PARAMS and isinstance(v, (list, tuple)) and len(v) > 1
     }
 
     # Everything else goes into the params dictionary for the URL
@@ -441,8 +445,7 @@ def _construct_api_requests(
     POST = bool(post_params)
 
     # Convert dates to ISO08601 format
-    time_periods = {"last_modified", "datetime", "time", "begin", "end"}
-    for i in time_periods:
+    for i in _DATE_RANGE_PARAMS:
         if i in params:
             dates = service == "daily" and i != "last_modified"
             params[i] = _format_api_dates(params[i], date=dates)
@@ -1160,63 +1163,35 @@ def _check_profiles(
 _MONITORING_LOCATION_ID_RE = re.compile(r"[^-\s]+-[^-\s]+")
 
 
-# Parameter names skipped by ``_get_args``'s string-iterable normalization.
-# Scalar non-string knobs (``limit``, ``ssl_check``, …) and ``list[float]``
-# params (``bbox``, ``boundingBox``) are detected by *runtime type* and pass
-# through automatically. The names below need explicit listing because their
-# values *are* string-iterables but have separate handling downstream:
-#
-#   * ``monitoring_location_id`` — validated by
-#     ``_check_monitoring_location_id`` at the public-function entry.
-#   * Date-range params (``time``, ``last_modified``, ``begin``, ``end``,
-#     ``datetime``) — support ``pd.NaT``/``None`` half-bounded endpoints and
-#     interval/duration strings; parsing happens in ``_format_api_dates``.
-_NO_NORMALIZE_PARAMS = frozenset(
-    {
-        "monitoring_location_id",
-        "time",
-        "last_modified",
-        "begin",
-        "end",
-        "datetime",
-    }
-)
+# Param names that ``_get_args`` must NOT push through ``_normalize_str_iterable``.
+# Scalar non-string knobs and ``list[float]`` params are detected by runtime
+# type; only string-iterable-shaped params with special handling need to be
+# named here: ``monitoring_location_id`` (validated separately) and the date-
+# range params (which may contain ``pd.NaT``/None or interval strings).
+_NO_NORMALIZE_PARAMS = _DATE_RANGE_PARAMS | {"monitoring_location_id"}
 
 
 def _normalize_str_iterable(
     value: str | Iterable[str] | None,
     param_name: str = "value",
 ) -> str | list[str] | None:
-    """Validate and normalize a parameter that accepts a string or iterable of strings.
-
-    Called from ``_get_args`` for every multi-value string parameter on
-    every waterdata getter that uses ``_get_args`` (every OGC/Samples
-    function in ``dataretrieval/waterdata/api.py``). Accepts ``list``,
-    ``tuple``, ``pandas.Series``, ``pandas.Index``, ``numpy.ndarray``,
-    generators — anything iterable whose elements are strings. The
-    downstream ``_construct_api_requests`` branches on ``isinstance(v,
-    (list, tuple))``, so iterables are materialized to a ``list`` here.
-    ``Mapping`` types are rejected because iterating a mapping yields
-    keys, which would be a footgun.
-
-    Date-range params (``time``, ``last_modified``, ``begin``, ``end``,
-    ``datetime``, ...) deliberately bypass this helper via
-    ``_NO_NORMALIZE_PARAMS``; their single-string-or-two-element-range
-    semantics (including ``pd.NaT``/``None`` half-bounded endpoints) are
-    handled by ``_format_api_dates`` inside ``_construct_api_requests``.
+    """Validate that ``value`` is None, a string, or an iterable of strings.
+
+    Non-string iterables (``list``, ``tuple``, ``pandas.Series``,
+    ``pandas.Index``, ``numpy.ndarray``, generators) are materialized to a
+    ``list`` so downstream code that branches on ``isinstance(v, (list,
+    tuple))`` keeps working. ``Mapping`` types are rejected because
+    iterating a mapping yields keys, not values.
 
     Parameters
     ----------
     value : None, str, or iterable of str
     param_name : str, optional
-        Name of the parameter, used in error messages. Defaults to
-        ``"value"``.
+        Used in error messages. Defaults to ``"value"``.
 
     Returns
     -------
     None, str, or list of str
-        ``None`` and ``str`` are returned unchanged; non-string iterables
-        are returned as a ``list``.
 
     Raises
     ------
@@ -1330,17 +1305,13 @@ def _get_args(
     for k, v in local_vars.items():
         if k in to_exclude or v is None:
             continue
-        if k in _NO_NORMALIZE_PARAMS or isinstance(v, str):
-            args[k] = v
-            continue
-        if not isinstance(v, Iterable):
-            # Scalar non-string knob (bool / int / float) — pass through.
+        if (
+            k in _NO_NORMALIZE_PARAMS
+            or isinstance(v, str)
+            or not isinstance(v, Iterable)
+            or (isinstance(v, (list, tuple)) and v and not isinstance(v[0], str))
+        ):
             args[k] = v
-            continue
-        if isinstance(v, (list, tuple)) and v and not isinstance(v[0], str):
-            # list[float] / list[int] (e.g. bbox) — pass through.
-            args[k] = v
-            continue
-        # String-iterable: validate elements and materialize to list.
-        args[k] = _normalize_str_iterable(v, k)
+        else:
+            args[k] = _normalize_str_iterable(v, k)
     return args