Widen _check_monitoring_location_id to accept iterables of strings

The previous `(str, list)` isinstance check rejected legitimate inputs:
tuple, pandas.Series, pandas.Index, numpy.ndarray, generators. Pre-fix
these would round-trip through requests and either work (tuple) or
silently break the URL (numpy/pandas). Post-fix the function:

- Accepts any non-string iterable whose elements are strings
- Materializes the iterable to a list so downstream comma-join /
  POST-CQL2 logic in _construct_api_requests keeps working uniformly
- Returns the (possibly-normalized) value, so callers reassign:
    monitoring_location_id = _check_monitoring_location_id(monitoring_location_id)
- Rejects Mapping (e.g. dict) explicitly — iterating a dict yields
  keys, which is a footgun

Live-verified against api.waterdata.usgs.gov: passing tuple, pd.Series,
pd.Index, and np.ndarray of "USGS-01646500" all return 3 rows for the
2024-06-01/2024-06-03 window. Passing pd.Series([1646500]) raises
TypeError("monitoring_location_id elements must be strings, not int...")
before any network call.

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

Author: thodson-usgs

dataretrieval/waterdata/api.py

@@ -214,7 +214,7 @@ def get_daily(
         ...     approval_status = "Approved",
         ...     time = "2024-01-01/.."
     """
-    _check_monitoring_location_id(monitoring_location_id)
+    monitoring_location_id = _check_monitoring_location_id(monitoring_location_id)
     service = "daily"
     output_id = "daily_id"
 
@@ -403,7 +403,7 @@ def get_continuous(
         ...     filter_lang="cql-text",
         ... )
     """
-    _check_monitoring_location_id(monitoring_location_id)
+    monitoring_location_id = _check_monitoring_location_id(monitoring_location_id)
     service = "continuous"
     output_id = "continuous_id"
 
@@ -702,7 +702,7 @@ def get_monitoring_locations(
         ...     properties=["monitoring_location_id", "state_name", "country_name"],
         ... )
     """
-    _check_monitoring_location_id(monitoring_location_id)
+    monitoring_location_id = _check_monitoring_location_id(monitoring_location_id)
     service = "monitoring-locations"
     output_id = "monitoring_location_id"
 
@@ -926,7 +926,7 @@ def get_time_series_metadata(
         ...     begin="1990-01-01/..",
         ... )
     """
-    _check_monitoring_location_id(monitoring_location_id)
+    monitoring_location_id = _check_monitoring_location_id(monitoring_location_id)
     service = "time-series-metadata"
     output_id = "time_series_id"
 
@@ -1106,7 +1106,7 @@ def get_latest_continuous(
         ...     monitoring_location_id=["USGS-05114000", "USGS-09423350"]
         ... )
     """
-    _check_monitoring_location_id(monitoring_location_id)
+    monitoring_location_id = _check_monitoring_location_id(monitoring_location_id)
     service = "latest-continuous"
     output_id = "latest_continuous_id"
 
@@ -1288,7 +1288,7 @@ def get_latest_daily(
         ...     monitoring_location_id=["USGS-05114000", "USGS-09423350"]
         ... )
     """
-    _check_monitoring_location_id(monitoring_location_id)
+    monitoring_location_id = _check_monitoring_location_id(monitoring_location_id)
     service = "latest-daily"
     output_id = "latest_daily_id"
 
@@ -1469,7 +1469,7 @@ def get_field_measurements(
         ...     time = "P20Y"
         ... )
     """
-    _check_monitoring_location_id(monitoring_location_id)
+    monitoring_location_id = _check_monitoring_location_id(monitoring_location_id)
     service = "field-measurements"
     output_id = "field_measurement_id"
 
@@ -1925,7 +1925,7 @@ def get_stats_por(
         ... )
     """
     # Build argument dictionary, omitting None values
-    _check_monitoring_location_id(monitoring_location_id)
+    monitoring_location_id = _check_monitoring_location_id(monitoring_location_id)
     params = _get_args(locals(), exclude={"expand_percentiles"})
 
     return get_stats_data(
@@ -2055,7 +2055,7 @@ def get_stats_date_range(
         ... )
     """
     # Build argument dictionary, omitting None values
-    _check_monitoring_location_id(monitoring_location_id)
+    monitoring_location_id = _check_monitoring_location_id(monitoring_location_id)
     params = _get_args(locals(), exclude={"expand_percentiles"})
 
     return get_stats_data(
@@ -2228,7 +2228,7 @@ def get_channel(
         ...     monitoring_location_id="USGS-02238500",
         ... )
     """
-    _check_monitoring_location_id(monitoring_location_id)
+    monitoring_location_id = _check_monitoring_location_id(monitoring_location_id)
     service = "channel-measurements"
     output_id = "channel_measurements_id"
 

dataretrieval/waterdata/utils.py

@@ -4,6 +4,7 @@
 import logging
 import os
 import re
+from collections.abc import Iterable, Mapping
 from datetime import datetime
 from typing import Any, get_args
 
@@ -1155,44 +1156,53 @@ def _check_profiles(
 _MONITORING_LOCATION_ID_RE = re.compile(r"^.+-.+$")
 
 
-def _check_monitoring_location_id(
-    monitoring_location_id: str | list[str] | None,
-) -> None:
-    """Validate the format of a monitoring_location_id value.
+def _check_monitoring_location_id(monitoring_location_id):
+    """Validate and normalize a ``monitoring_location_id`` value.
 
     Parameters
     ----------
-    monitoring_location_id : str, list of str, or None
-        One or more monitoring location identifiers.
+    monitoring_location_id : None, str, or iterable of str
+        Accepts ``None``, a single string, or any non-string iterable of
+        strings (``list``, ``tuple``, ``pandas.Series``, ``pandas.Index``,
+        ``numpy.ndarray``, ...). Iterables are materialized to a ``list``
+        so downstream code that branches on ``isinstance(v, list)`` keeps
+        working.
+
+    Returns
+    -------
+    None, str, or list of str
+        ``None`` and ``str`` inputs are returned unchanged; non-string
+        iterables are returned as a ``list``.
 
     Raises
     ------
     TypeError
-        If any identifier is not a string (e.g. an integer was passed).
+        If the input is not ``None``, a string, or an iterable, or if any
+        iterable element is not a string.
     ValueError
-        If any string identifier does not follow the required
-        ``'AGENCY-ID'`` format (e.g. ``'USGS-01646500'``).
+        If any identifier doesn't contain a hyphen separator
+        (per the OGC API spec: AGENCY-ID format, e.g. ``USGS-01646500``).
     """
     if monitoring_location_id is None:
-        return
+        return None
 
-    if not isinstance(monitoring_location_id, (str, list)):
+    if isinstance(monitoring_location_id, str):
+        ids = [monitoring_location_id]
+    elif isinstance(monitoring_location_id, Iterable) and not isinstance(
+        monitoring_location_id, Mapping
+    ):
+        ids = list(monitoring_location_id)
+    else:
         raise TypeError(
-            f"monitoring_location_id must be a string or list of strings, "
+            f"monitoring_location_id must be a string or iterable of strings, "
             f"not {type(monitoring_location_id).__name__}. "
             f"Expected format: 'AGENCY-ID', e.g., 'USGS-{monitoring_location_id}'."
         )
 
-    ids = (
-        [monitoring_location_id]
-        if isinstance(monitoring_location_id, str)
-        else monitoring_location_id
-    )
-
     for id_ in ids:
         if not isinstance(id_, str):
             raise TypeError(
-                f"monitoring_location_id must be a string or list of strings, "
+                f"monitoring_location_id elements must be strings, "
                 f"not {type(id_).__name__}. "
                 f"Expected format: 'AGENCY-ID', e.g., 'USGS-{id_}'."
             )
@@ -1202,6 +1212,8 @@ def _check_monitoring_location_id(
                 f"Expected 'AGENCY-ID' format, e.g., 'USGS-01646500'."
             )
 
+    return monitoring_location_id if isinstance(monitoring_location_id, str) else ids
+
 
 def _get_args(
     local_vars: dict[str, Any], exclude: set[str] | None = None

tests/waterdata_test.py

@@ -1,6 +1,7 @@
 import datetime
 import sys
 
+import pandas as pd
 import pytest
 from pandas import DataFrame
 
@@ -389,16 +390,17 @@ class TestCheckMonitoringLocationId:
     """
 
     def test_valid_string(self):
-        """A correctly formatted string passes without error."""
-        _check_monitoring_location_id("USGS-01646500")
+        """A correctly formatted string passes and is returned unchanged."""
+        assert _check_monitoring_location_id("USGS-01646500") == "USGS-01646500"
 
     def test_valid_list(self):
         """A list of correctly formatted strings passes without error."""
-        _check_monitoring_location_id(["USGS-01646500", "USGS-02238500"])
+        ids = ["USGS-01646500", "USGS-02238500"]
+        assert _check_monitoring_location_id(ids) == ids
 
     def test_none_passes(self):
         """None is allowed (optional parameter)."""
-        _check_monitoring_location_id(None)
+        assert _check_monitoring_location_id(None) is None
 
     def test_integer_raises_type_error(self):
         """An integer ID raises TypeError with a helpful message."""
@@ -425,6 +427,52 @@ def test_get_daily_integer_id_raises(self):
         with pytest.raises(TypeError):
             get_daily(monitoring_location_id=5129115, parameter_code="00060")
 
+    def test_tuple_normalizes_to_list(self):
+        """A tuple of valid strings is accepted and normalized to list."""
+        result = _check_monitoring_location_id(("USGS-01646500", "USGS-02238500"))
+        assert result == ["USGS-01646500", "USGS-02238500"]
+        assert isinstance(result, list)
+
+    def test_pandas_series_normalizes_to_list(self):
+        """A pandas.Series of valid strings is accepted and normalized to list."""
+        s = pd.Series(["USGS-01646500", "USGS-02238500"])
+        result = _check_monitoring_location_id(s)
+        assert result == ["USGS-01646500", "USGS-02238500"]
+        assert isinstance(result, list)
+
+    def test_pandas_index_normalizes_to_list(self):
+        """A pandas.Index of valid strings is accepted and normalized to list."""
+        idx = pd.Index(["USGS-01646500", "USGS-02238500"])
+        result = _check_monitoring_location_id(idx)
+        assert result == ["USGS-01646500", "USGS-02238500"]
+        assert isinstance(result, list)
+
+    def test_numpy_array_normalizes_to_list(self):
+        """A numpy.ndarray of valid strings is accepted and normalized to list."""
+        import numpy as np
+
+        arr = np.array(["USGS-01646500", "USGS-02238500"])
+        result = _check_monitoring_location_id(arr)
+        assert result == ["USGS-01646500", "USGS-02238500"]
+        assert isinstance(result, list)
+
+    def test_numpy_int_array_raises_type_error(self):
+        """An iterable whose elements aren't strings (numpy int array) raises."""
+        import numpy as np
+
+        with pytest.raises(TypeError, match="elements must be strings"):
+            _check_monitoring_location_id(np.array([1, 2, 3]))
+
+    def test_pandas_series_of_ints_raises_type_error(self):
+        """An iterable whose elements aren't strings (Series of ints) raises."""
+        with pytest.raises(TypeError, match="elements must be strings"):
+            _check_monitoring_location_id(pd.Series([1, 2, 3]))
+
+    def test_dict_raises_type_error(self):
+        """Mappings are rejected — iterating a dict yields keys, which is a footgun."""
+        with pytest.raises(TypeError, match="not dict"):
+            _check_monitoring_location_id({"USGS-01646500": "site"})
+
     def test_get_daily_malformed_id_raises(self):
         """get_daily raises ValueError for a malformed string ID."""
         with pytest.raises(ValueError):