Enrich waterdata getter docstrings with examples adapted from R#265
Merged
thodson-usgs merged 2 commits intoDOI-USGS:mainfrom May 6, 2026
Merged
Conversation
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 "../<date>" 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) <noreply@anthropic.com>
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) <noreply@anthropic.com>
Contributor
There was a problem hiding this comment.
Pull request overview
This PR updates the dataretrieval.waterdata getter docstrings to include additional usage examples (ported/adapted from the R dataRetrieval package) that demonstrate common querying idioms such as ISO 8601 durations, half-bounded time intervals, and incremental polling via last_modified.
Changes:
- Added new Examples to
get_dailyshowingtime="P7D"and incremental polling withlast_modified="P7D", and corrected a broken multi-site example formatting. - Added new Examples to
get_latest_continuousandget_latest_dailycoveringtime="P7D", multi-site/multi-parameter queries, andlast_modified="P7D". - Added a half-bounded time interval Example to
get_field_measurements(time="1980-01-01/..") and documented the inverse form.
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
ldecicco-USGS
approved these changes
May 6, 2026
Collaborator
ldecicco-USGS
left a comment
ldecicco-USGS
left a comment
There was a problem hiding this comment.
Helpful examples that will most likely help users realize they don't need to calculate specific date ranges.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Cross-referenced each Python
waterdatagetter's Examples section against the corresponding R analogue in DOI-USGS/dataRetrieval and ported the distinctive examples that the Python docs were missing. Same rationale as the audit done forget_combined_metadatain #264 — many R example sets cover useful idioms (ISO 8601 durations, half-bounded time intervals,last_modifiedfor incremental polling, multi-value POST queries) that aren't yet shown in the Python docs.Docs only — no signature, behavior, or test changes.
Functions touched and what was added
get_dailytime="P7D") example;last_modified="P7D"example for incremental ETL polling. Also fixed a pre-existing bug where the multi-site /approval_statusexample block was missing its closing parenthesis and trailing comma.get_latest_continuoustime="P7D"example (drops sites with no recent observation); multi-site / multi-parameter +last_modified="P7D"example.get_latest_dailylast_modified="P7D"example; multi-site + multi-parameter (discharge + water-temperature) example.get_field_measurements"1980-01-01/.."for everything since 1980; documents the inverse"../<date>"form).What was deliberately skipped
get_continuous(5 examples),get_monitoring_locations(2 well-chosen ones already, R's bbox+chaining cases would duplicateget_combined_metadata's new chaining example in Add waterdata.get_combined_metadata for combined location + time-series inventory #264),get_time_series_metadata,get_stats_por,get_stats_date_range,get_samples,get_codes,get_reference_table,get_channel,get_samples_summary.no_paging,attach_request,chunk_size,convertTypeflag toggling). Filter chunking happens automatically in Python.get_daily's Rdv_postexample usingapproval_status=c("Approved", "Provisional")— Python already has anapproval_status="Approved"example.Test plan
ruff checkclean.__doc__renders correctly (verified viahelp()).P7Dduration,1980-01-01/..half-bounded interval,last_modifiedfield) that are already covered by existing tests and other functions' working examples.Related
get_combined_metadatawith the same docs philosophy applied to a single new function).