Add waterdata.get_samples_summary for per-location sample inventory

[thodson-usgs]

Closes #261.

Summary

Adds waterdata.get_samples_summary(monitoringLocationIdentifier=...) — a wrapper around the Samples database /summary/{monitoringLocationIdentifier} endpoint. The endpoint returns one row per (characteristic group, characteristic, user-supplied characteristic) combination with result and activity counts plus first / most recent activity dates, which makes it convenient for taking inventory of what discrete-sample data exists at a site before pulling the underlying observations with get_samples.

This mirrors the R package's summarize_waterdata_samples (read_waterdata_samples.R) feature requested in #261.

The Samples summary endpoint accepts only a single monitoring location per request, so the parameter is typed as str (not str | list[str]).

Live API example

from dataretrieval.waterdata import get_samples_summary

df, md = get_samples_summary(monitoringLocationIdentifier="USGS-04183500")

print(md.url)
# https://api.waterdata.usgs.gov/samples-data/summary/USGS-04183500?mimeType=text%2Fcsv

print(df.columns.tolist())
# ['monitoringLocationIdentifier', 'characteristicGroup', 'characteristic',
#  'characteristicUserSupplied', 'resultCount', 'activityCount',
#  'firstActivity', 'mostRecentActivity']

print(len(df))
# 110

Test plan

• New test_mock_get_samples_summary covers the happy path against a recorded response (tests/data/samples_summary.txt): URL composition, column names, single-location filter.
• Live verification: get_samples_summary(monitoringLocationIdentifier="USGS-04183500") returns 110 rows with the expected schema.
• Full tests/waterdata_test.py suite (27 tests) passes.

[Copilot]

Pull request overview

This PR adds a new public waterdata.get_samples_summary() helper to the waterdata module so users can inspect the discrete-sample inventory available for a single monitoring location before requesting full sample records. It fits the module’s role as the Python wrapper around modern USGS Water Data APIs and mirrors the corresponding R-package capability requested in #261.

Changes:

• Added waterdata.get_samples_summary(monitoringLocationIdentifier=...) to wrap the Samples /summary/{monitoringLocationIdentifier} CSV endpoint.
• Exported the new helper from dataretrieval.waterdata and added a recorded-response unit test plus fixture data.
• Documented the new API addition in NEWS.md.

Reviewed changes

Copilot reviewed 5 out of 5 changed files in this pull request and generated 2 comments.

Show a summary per file

File	Description
dataretrieval/waterdata/api.py	Adds the new Samples summary API wrapper and docstring.
dataretrieval/waterdata/__init__.py	Re-exports the new helper as part of the public waterdata API.
tests/waterdata_test.py	Adds a mock-based test for URL composition, metadata, and returned columns.
tests/data/samples_summary.txt	Provides recorded CSV fixture data for the new test.
NEWS.md	Announces the new get_samples_summary capability for users.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[ldecicco-USGS]

Looks good. I'm not entirely sure I follow the "quote" discussion, but seems imply it's the easiest way to test for 1 monitoring location id.

[thodson-usgs]

@ldecicco-USGS Thanks for the review! Quick clarification on the quote discussion since the Copilot phrasing was a bit indirect: urllib.parse.quote(monitoringLocationIdentifier, safe='') is just URL-path-segment escaping — it percent-encodes any /, ?, #, or whitespace so user input can't break URL composition. It doesn't validate the shape of the input. The single-site enforcement is the separate isinstance(..., str) guard a few lines above, which raises TypeError("...accepts exactly one monitoring location per request...") for a list (the symptom Copilot was actually pointing at). The two are independent — quote is for URL safety, the type check is for the API constraint.