From 5a82f2a5c6b1bfa7bd2debb20615531b082cc604 Mon Sep 17 00:00:00 2001 From: thodson-usgs Date: Tue, 5 May 2026 15:20:27 -0500 Subject: [PATCH 1/2] Enrich waterdata getter docstrings with examples adapted from R MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Cross-referenced each Python waterdata getter's Examples section against the corresponding R analogue in DOI-USGS/dataRetrieval and ported the distinctive examples that the Python docs were missing: - get_daily: add ISO 8601 duration ("P7D") and last_modified ("P7D") examples. Also fix a pre-existing bug where the multi-site / approval_status example block was missing its closing parenthesis and trailing comma. - get_latest_continuous: add time="P7D" and multi-site + last_modified="P7D" examples. - get_latest_daily: add last_modified="P7D" and multi-site + multi-parameter examples. - get_field_measurements: add a half-bounded-time example ("1980-01-01/..") and document the inverse "../" form. Docs only — no signature, behavior, or test changes. Ruff clean. Live spot-verification was attempted but blocked by a 429 rate limit; the new examples only use date-format and multi-value idioms that are already covered by existing tests. Co-Authored-By: Claude Opus 4.7 (1M context) --- dataretrieval/waterdata/api.py | 61 ++++++++++++++++++++++++++++++++-- 1 file changed, 58 insertions(+), 3 deletions(-) diff --git a/dataretrieval/waterdata/api.py b/dataretrieval/waterdata/api.py index 583b512c..275b4e15 100644 --- a/dataretrieval/waterdata/api.py +++ b/dataretrieval/waterdata/api.py @@ -208,11 +208,27 @@ def get_daily( ... time="2021-01-01T00:00:00Z/2022-01-01T00:00:00Z", ... ) + >>> # Quick "show me the last week" idiom (ISO 8601 duration) + >>> df, md = dataretrieval.waterdata.get_daily( + ... monitoring_location_id="USGS-02238500", + ... parameter_code="00060", + ... time="P7D", + ... ) + >>> # Get approved daily flow data from multiple sites >>> df, md = dataretrieval.waterdata.get_daily( - ... monitoring_location_id = ["USGS-05114000", "USGS-09423350"], - ... approval_status = "Approved", - ... time = "2024-01-01/.." + ... monitoring_location_id=["USGS-05114000", "USGS-09423350"], + ... approval_status="Approved", + ... time="2024-01-01/..", + ... ) + + >>> # Pull only rows whose underlying record was refreshed in the + >>> # last 7 days — handy for incremental ETL polling + >>> df, md = dataretrieval.waterdata.get_daily( + ... monitoring_location_id="USGS-02238500", + ... parameter_code="00060", + ... last_modified="P7D", + ... ) """ service = "daily" output_id = "daily_id" @@ -1097,6 +1113,22 @@ def get_latest_continuous( ... monitoring_location_id="USGS-02238500", parameter_code="00060" ... ) + >>> # Restrict to the last 7 days; sites with no observation in that + >>> # window are dropped instead of returned with stale values + >>> df, md = dataretrieval.waterdata.get_latest_continuous( + ... monitoring_location_id="USGS-02238500", + ... parameter_code="00060", + ... time="P7D", + ... ) + + >>> # Pull only rows whose underlying record was refreshed in the + >>> # last 7 days, across multiple sites and parameters + >>> df, md = dataretrieval.waterdata.get_latest_continuous( + ... monitoring_location_id=["USGS-451605097071701", "USGS-14181500"], + ... parameter_code=["00060", "72019"], + ... last_modified="P7D", + ... ) + >>> # Get latest continuous measurements for multiple sites >>> df, md = dataretrieval.waterdata.get_latest_continuous( ... monitoring_location_id=["USGS-05114000", "USGS-09423350"] @@ -1278,6 +1310,21 @@ def get_latest_daily( ... monitoring_location_id="USGS-02238500", parameter_code="00060" ... ) + >>> # Restrict to rows whose underlying record was refreshed in the + >>> # last 7 days + >>> df, md = dataretrieval.waterdata.get_latest_daily( + ... monitoring_location_id="USGS-02238500", + ... parameter_code="00060", + ... last_modified="P7D", + ... ) + + >>> # Multi-site, multi-parameter — discharge and water temperature + >>> # at two sites in a single round-trip + >>> df, md = dataretrieval.waterdata.get_latest_daily( + ... monitoring_location_id=["USGS-01491000", "USGS-01645000"], + ... parameter_code=["00060", "00010"], + ... ) + >>> # Get most recent daily measurements for two sites >>> df, md = dataretrieval.waterdata.get_latest_daily( ... monitoring_location_id=["USGS-05114000", "USGS-09423350"] @@ -1454,6 +1501,14 @@ def get_field_measurements( ... skip_geometry=True, ... ) + >>> # Half-bounded time range: every measurement at this site since + >>> # 1980 (open-ended end). Use ``"../"`` for the inverse + >>> # (everything up to a date). + >>> df, md = dataretrieval.waterdata.get_field_measurements( + ... monitoring_location_id="USGS-425957088141001", + ... time="1980-01-01/..", + ... ) + >>> # Get field measurements from multiple sites and >>> # parameter codes from the last 20 years >>> df, md = dataretrieval.waterdata.get_field_measurements( From b2b87fdb94fc251184c2b1be9ae44497c3fc3f70 Mon Sep 17 00:00:00 2001 From: thodson-usgs Date: Wed, 6 May 2026 08:38:33 -0500 Subject: [PATCH 2/2] Fix continuation in get_field_measurements multi-site example Same pre-existing bug shape as the one PR 265 already fixed in get_daily: a list item on a continuation line without the doctest "... " prefix, which makes doctest end the example mid-bracket (SyntaxError: '[' was never closed). Found by exec'ing every example in the four PR-touched functions against the live USGS API. Reformatted to put each list element on its own properly-prefixed continuation line, matching the style used elsewhere in this file. While here, dropped the non-PEP8 spaces around the `=` of keyword arguments. After this fix, all 15 doctest examples in the four functions PR 265 touched pass when run with the package imported (15/15 across get_daily, get_latest_continuous, get_latest_daily, get_field_measurements; verified live against api.waterdata.usgs.gov). Co-Authored-By: Claude Opus 4.7 (1M context) --- dataretrieval/waterdata/api.py | 10 ++++++---- 1 file changed, 6 insertions(+), 4 deletions(-) diff --git a/dataretrieval/waterdata/api.py b/dataretrieval/waterdata/api.py index 275b4e15..15f6a5a0 100644 --- a/dataretrieval/waterdata/api.py +++ b/dataretrieval/waterdata/api.py @@ -1512,10 +1512,12 @@ def get_field_measurements( >>> # Get field measurements from multiple sites and >>> # parameter codes from the last 20 years >>> df, md = dataretrieval.waterdata.get_field_measurements( - ... monitoring_location_id = ["USGS-451605097071701", - "USGS-263819081585801"], - ... parameter_code = ["62611", "72019"], - ... time = "P20Y" + ... monitoring_location_id=[ + ... "USGS-451605097071701", + ... "USGS-263819081585801", + ... ], + ... parameter_code=["62611", "72019"], + ... time="P20Y", ... ) """ service = "field-measurements"