refactor(waterdata)!: snake_case get_samples params (camelCase kept via shim)

[thodson-usgs]

What

Ahead of the breaking 1.2.0 release, standardize the modern waterdata getter surface on snake_case parameter names. get_samples and get_samples_summary were the last outliers — they exposed the Samples API's native camelCase param names, while every other OGC waterdata getter already uses snake_case.

Only names change. Semantics are unchanged: state_code maps straight to the same stateFips FIPS code the API expects, bbox to boundingBox, etc. The function still sends the Samples API its native camelCase query parameters.

Param mapping (old camelCase -> new snake_case)

Old (Samples API camelCase)	New (snake_case)
activityMediaName	activity_media_name
activityStartDateLower	activity_start_date_lower
activityStartDateUpper	activity_start_date_upper
activityTypeCode	activity_type_code
characteristicGroup	characteristic_group
characteristic	characteristic (unchanged)
characteristicUserSupplied	characteristic_user_supplied
boundingBox	bbox
countryFips	country_code
stateFips	state_code
countyFips	county_code
siteTypeCode	site_type_code
siteTypeName	site_type_name
usgsPCode	usgs_pcode
hydrologicUnit	hydrologic_unit
monitoringLocationIdentifier	monitoring_location_id
organizationIdentifier	organization_id
pointLocationLatitude	point_location_latitude
pointLocationLongitude	point_location_longitude
pointLocationWithinMiles	point_location_within_miles
projectIdentifier	project_id
recordIdentifierUserSupplied	record_identifier_user_supplied

get_samples_summary: monitoringLocationIdentifier -> monitoring_location_id. service/profile/ssl_check are unchanged.

The chosen names follow get_monitoring_locations (country_code/state_code/county_code/bbox/monitoring_location_id), matching the convention already used across the OGC getters.

How the back-compat shim works

A new generic, testable decorator _accept_legacy_kwargs(mapping) (in dataretrieval/waterdata/utils.py) wraps both getters. If a caller passes a deprecated camelCase keyword, the wrapper:

1. renames it to the new snake_case parameter,
2. emits a DeprecationWarning that names the replacement, and
3. raises TypeError if both the old and new name are supplied for the same argument.

Callers using the new snake_case names see no warning. Internally, a module-level _SAMPLES_PARAM_TO_API dict maps each public snake_case param back to its camelCase wire name just before the request is built (mirroring how the OGC getters map e.g. skipGeometry/bbox). The legacy-kwargs mapping is derived from _SAMPLES_PARAM_TO_API, so the two can't drift apart. The demo notebooks use camelCase and are left untouched — the shim keeps them working.

Tests

• Updated the existing get_samples / get_samples_summary tests (offline, pytest-httpx) to the new snake_case names.
• Added tests that the legacy camelCase names still work, emit a DeprecationWarning naming the new param, and produce the same camelCase request URL.
• Added a test that passing both the old and new name raises TypeError, and that snake_case-only calls emit no warning.

Verification

• ruff check / ruff format --check: clean.
• mypy --strict dataretrieval/: no new errors (the 3 remaining errors are pre-existing on main and unrelated to this change; the decorator is typed to preserve the wrapped function's return type so samples.py's get_usgs_samples wrapper stays precisely typed).
• Offline samples tests pass (9 passed).

🤖 Generated with Claude Code