Use ISO 8601 duration as the window default

Switch the default from "00:07:30" to "PT7M30S" so the user-visible
contract points at an actual international standard (ISO 8601
duration) rather than a pandas-specific colon form.

``pandas.Timedelta`` still accepts all the other forms users may
already have typed — ISO 8601, HH:MM:SS, shorthand ("7min30s",
"450s"), or a ``pd.Timedelta`` directly — and a parametrized test
now exercises each shape to lock in the "whatever ``pd.Timedelta``
takes" contract.

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

Author: thodson-usgs

dataretrieval/waterdata/api.py

@@ -445,7 +445,7 @@ def get_nearest_continuous(
     monitoring_location_id: str | list[str] | None = None,
     parameter_code: str | list[str] | None = None,
     *,
-    window: str | pd.Timedelta = "00:07:30",
+    window: str | pd.Timedelta = "PT7M30S",
     on_tie: Literal["first", "last", "mean"] = "first",
     **kwargs,
 ) -> tuple[pd.DataFrame, BaseMetadata]:
@@ -472,14 +472,21 @@ def get_nearest_continuous(
         Forwarded to ``get_continuous``.
     parameter_code : string or list of strings, optional
         Forwarded to ``get_continuous``.
-    window : string or ``pandas.Timedelta``, default ``"00:07:30"``
-        Half-window around each target, in ``HH:MM:SS`` form (or any
-        ``pandas.Timedelta``-parseable string: ``"7min30s"``,
-        ``"450s"``, etc.). Must be small enough that every target's
-        window captures roughly one observation at the service cadence.
-        The ``"00:07:30"`` default matches a 15-minute continuous gauge;
-        use a larger value (e.g. ``"00:15:00"``) when the gauge cadence
-        is longer or you need more resilience to data gaps.
+    window : string or ``pandas.Timedelta``, default ``"PT7M30S"``
+        Half-window around each target, as an ISO 8601 duration
+        (``"PT7M30S"``, ``"PT15M"``, ``"PT1H"``, etc.). Also accepts
+        any other form ``pandas.Timedelta`` parses — ``HH:MM:SS``
+        (``"00:07:30"``), pandas shorthand (``"7min30s"``,
+        ``"450s"``), or a ``pd.Timedelta`` directly. See the
+        `pandas.Timedelta docs
+        <https://pandas.pydata.org/docs/reference/api/pandas.Timedelta.html>`_
+        for the full grammar.
+
+        Must be small enough that every target's window captures
+        roughly one observation at the service cadence. The default
+        matches a 15-minute continuous gauge; widen (e.g.
+        ``"PT15M"``) for irregular cadences or resilience to data
+        gaps.
     on_tie : {"first", "last", "mean"}, default ``"first"``
         How to resolve ties when two observations are exactly equidistant
         from a target (which happens when the target falls at the midpoint
@@ -549,7 +556,7 @@ def get_nearest_continuous(
         ...     targets,
         ...     monitoring_location_id="USGS-02238500",
         ...     parameter_code="00060",
-        ...     window="00:30:00",
+        ...     window="PT30M",
         ...     on_tie="mean",
         ... )
     """

tests/waterdata_nearest_test.py

@@ -58,7 +58,7 @@ def test_builds_one_or_clause_per_target(patch_get_continuous):
         targets,
         monitoring_location_id="USGS-02238500",
         parameter_code="00060",
-        window="00:07:30",
+        window="PT7M30S",
     )
     _, kwargs = patch_get_continuous.call_args
     filter_expr = kwargs["filter"]
@@ -89,7 +89,7 @@ def test_tie_first_keeps_earlier(patch_get_continuous):
         targets,
         monitoring_location_id="USGS-02238500",
         on_tie="first",
-        window="00:07:30",
+        window="PT7M30S",
     )
     assert len(result) == 1
     assert result.iloc[0]["value"] == 22.0
@@ -111,7 +111,7 @@ def test_tie_last_keeps_later(patch_get_continuous):
         targets,
         monitoring_location_id="USGS-02238500",
         on_tie="last",
-        window="00:07:30",
+        window="PT7M30S",
     )
     assert result.iloc[0]["value"] == 22.4
     assert result.iloc[0]["time"] == pd.Timestamp("2023-06-15T10:30:00Z")
@@ -132,7 +132,7 @@ def test_tie_mean_averages_numeric_and_uses_target_time(patch_get_continuous):
         targets,
         monitoring_location_id="USGS-02238500",
         on_tie="mean",
-        window="00:07:30",
+        window="PT7M30S",
     )
     assert result.iloc[0]["value"] == pytest.approx(22.2)
     # Time is set to the target since no real observation sits at the midpoint
@@ -232,23 +232,28 @@ def test_accepts_list_of_strings(patch_get_continuous):
     assert len(result) == 1
 
 
-def test_window_accepts_hhmmss_and_shorthand_equivalently(patch_get_continuous):
-    """``window="00:07:30"`` and ``window="7min30s"`` are the same duration
-    as far as ``pandas.Timedelta`` is concerned, so the two forms must
-    produce identical CQL filters."""
+@pytest.mark.parametrize(
+    "window",
+    [
+        "00:07:30",  # HH:MM:SS
+        "7min30s",  # pandas shorthand
+        "450s",  # seconds shorthand
+        "PT7M30S",  # ISO 8601 duration
+        pd.Timedelta(minutes=7, seconds=30),  # Timedelta object
+    ],
+)
+def test_window_accepts_any_pandas_timedelta_form(patch_get_continuous, window):
+    """Every representation ``pandas.Timedelta`` parses must produce the
+    same CQL filter. Documents the public contract: ``window`` is
+    whatever ``pd.Timedelta(window)`` returns."""
     targets = pd.to_datetime(["2023-06-15T10:30:00Z"], utc=True)
     patch_get_continuous.return_value = (_fake_df([]), mock.Mock())
 
-    get_nearest_continuous(targets, monitoring_location_id="USGS-1", window="00:07:30")
-    filter_hhmmss = patch_get_continuous.call_args.kwargs["filter"]
-
-    get_nearest_continuous(targets, monitoring_location_id="USGS-1", window="7min30s")
-    filter_shorthand = patch_get_continuous.call_args.kwargs["filter"]
-
-    assert filter_hhmmss == filter_shorthand
-    # And the bounds should be 7:30 away from the target
-    assert "'2023-06-15T10:22:30Z'" in filter_hhmmss
-    assert "'2023-06-15T10:37:30Z'" in filter_hhmmss
+    get_nearest_continuous(targets, monitoring_location_id="USGS-1", window=window)
+    filter_expr = patch_get_continuous.call_args.kwargs["filter"]
+    # Bounds are 7:30 away from the target regardless of input spelling
+    assert "'2023-06-15T10:22:30Z'" in filter_expr
+    assert "'2023-06-15T10:37:30Z'" in filter_expr
 
 
 def test_forwards_kwargs_to_get_continuous(patch_get_continuous):