Polish PR 233: module-level constant, fix misleading comment, add 3 unit tests

Style alignment with the rest of `waterdata/utils.py`:

- Hoist `_cql2_required_services` from a function-local lowercase `set`
  to a module-level `_CQL2_REQUIRED_SERVICES = frozenset(...)` to match
  the convention of `_DATE_RANGE_PARAMS`, `_NO_NORMALIZE_PARAMS`,
  `_MONITORING_LOCATION_ID_RE`, etc.
- Drop the "Legacy path:" prefix in the inline comment. POST/CQL2 is
  still the current and required path for monitoring-locations — the
  API team hasn't promised to add comma-GET there. Rephrased the two
  branches symmetrically ("POST with CQL2 JSON" / "GET with comma-
  separated values") so neither reads as deprecated.

New unit tests:

- `test_construct_api_requests_single_value_stays_get` — confirms a
  scalar `monitoring_location_id="USGS-..."` still produces a clean GET
  with no `%2C`, i.e. existing single-site callers see no change.
- `test_construct_api_requests_numeric_list_joins_with_str` — pins down
  that `water_year=[2020, 2021]` reaches the URL as `water_year=2020%2C2021`,
  exercising the `str(x) for x in v` generator that exists specifically
  to handle non-string list params (without it, `",".join` on a list of
  ints would TypeError).
- `test_construct_api_requests_two_element_date_list_becomes_interval` —
  pins down the contract that a two-element date list (`time=["2024-01-01",
  "2024-01-31"]`) is interpreted as start/end of an OGC datetime interval
  (joined with `/`), NOT as two discrete dates. The OGC `datetime`
  parameter doesn't support "these N specific dates" — that would
  require a CQL filter. Test exists so this semantic choice can't be
  silently changed.

Author: thodson-usgs

dataretrieval/waterdata/utils.py

@@ -153,6 +153,10 @@ def _switch_properties_id(properties: list[str] | None, id_name: str, service: s
     {"datetime", "last_modified", "begin", "begin_utc", "end", "end_utc", "time"}
 )
 
+# Services that don't support comma-separated values for multi-value GET
+# parameters and require POST with CQL2 JSON instead.
+_CQL2_REQUIRED_SERVICES = frozenset({"monitoring-locations"})
+
 
 def _parse_datetime(value: str) -> datetime | None:
     """Parse a single datetime string against the supported formats.
@@ -450,10 +454,6 @@ def _construct_api_requests(
     """
     service_url = f"{OGC_API_URL}/collections/{service}/items"
 
-    # The monitoring-locations endpoint does not support comma-separated values
-    # for multi-value GET parameters; CQL2 POST is required for that service.
-    _cql2_required_services = {"monitoring-locations"}
-
     # Format date/time parameters to ISO8601 first — both routing paths need it.
     for key in _DATE_RANGE_PARAMS:
         if key in kwargs:
@@ -462,8 +462,8 @@ def _construct_api_requests(
                 date=(service == "daily" and key != "last_modified"),
             )
 
-    if service in _cql2_required_services:
-        # Legacy path: POST with CQL2 for multi-value params
+    if service in _CQL2_REQUIRED_SERVICES:
+        # POST with CQL2 JSON: multi-value params go in the request body.
         post_params = {
             k: v
             for k, v in kwargs.items()
@@ -473,7 +473,7 @@ def _construct_api_requests(
         }
         params = {k: v for k, v in kwargs.items() if k not in post_params}
     else:
-        # Join list/tuple values with commas for multi-value GET parameters.
+        # GET with comma-separated values: join list/tuple values into one string.
         post_params = {}
         params = {
             k: ",".join(str(x) for x in v) if isinstance(v, (list, tuple)) else v

tests/waterdata_test.py

@@ -134,6 +134,47 @@ def test_construct_api_requests_monitoring_locations_post():
     assert req.body is not None
 
 
+def test_construct_api_requests_single_value_stays_get():
+    """A length-1 list (or scalar) reaches the URL as a plain value, not a
+    comma-separated form, so existing single-site callers see no change."""
+    req = _construct_api_requests(
+        "daily",
+        monitoring_location_id="USGS-05427718",
+        parameter_code="00060",
+    )
+    assert req.method == "GET"
+    assert "monitoring_location_id=USGS-05427718" in req.url
+    assert "%2C" not in req.url  # no comma-encoded multi-value
+
+
+def test_construct_api_requests_numeric_list_joins_with_str():
+    """Numeric-list params (e.g. ``water_year=[2020, 2021]`` on get_peaks)
+    must reach the URL as a comma-joined string, not crash on ``",".join``
+    of ints. The generator-of-``str(x)`` exists exactly for this case."""
+    req = _construct_api_requests(
+        "peaks",
+        monitoring_location_id="USGS-05427718",
+        water_year=[2020, 2021],
+    )
+    assert req.method == "GET"
+    assert "water_year=2020%2C2021" in req.url
+
+
+def test_construct_api_requests_two_element_date_list_becomes_interval():
+    """A two-element date list is interpreted as start/end of an OGC datetime
+    interval (joined with '/'), NOT as two discrete dates. The OGC `datetime`
+    parameter does not support "these N specific dates" — that would require
+    a CQL filter. Verifying so this contract is locked in."""
+    req = _construct_api_requests(
+        "daily",
+        monitoring_location_id="USGS-05427718",
+        time=["2024-01-01", "2024-01-31"],
+    )
+    assert req.method == "GET"
+    # `/` URL-encodes to %2F. Confirms _format_api_dates ran before the join.
+    assert "time=2024-01-01%2F2024-01-31" in req.url
+
+
 def test_samples_results():
     """Test results call for proper columns"""
     df, _ = get_samples(