refactor(waterdata): coherent error handling + safe cleanups for non-OGC getters

[thodson-usgs]

Summary

Coherence pass on the non-OGC getters (Samples, codes, ratings) — the backlog split out of PR #295's review. Two themes: error-handling coherence and safe cleanups.

All public signatures, kwargs (including the Samples camelCase, which mirrors the upstream API), and return shapes are unchanged. The one behavior-affecting change is the exception type on HTTP errors — flagged below for an explicit decision.

Error coherence (behavior: exception type)

The OGC and stats paths raise the module's typed errors (RateLimited on 429, ServiceUnavailable on 5xx, with Retry-After and USGS-aware messages via _raise_for_non_200). The direct-httpx.get getters did not — they used a bare response.raise_for_status() (generic httpx.HTTPStatusError). This PR routes them through _raise_for_non_200:

• get_samples, get_samples_summary, get_codes (api.py)
• ratings._search, ratings._download_and_parse (ratings.py)

So a caller can now except RateLimited / except ServiceUnavailable across the whole module.

⚠️ Behavior change: code that caught httpx.HTTPStatusError from these getters will no longer match (the typed errors are RuntimeError subclasses). This is the deliberate coherence change — happy to gate it behind discussion, or make the typed errors also subclass httpx.HTTPStatusError if you'd prefer strict backward-compat.

Safe cleanups (behavior-preserving)

• _get_samples_csv helper — collapses the duplicated GET + read_csv + metadata tail shared by get_samples / get_samples_summary.
• get_channel docstring drift — channel_flow was described as units (it's the discharge value); channel_flow_unit was undocumented; measurement_type carried last_modified's pasted RFC-3339 block.
• _format_api_dates — resolve the local timezone only after the all-NA / duration / interval early-return guards (it was computed then discarded on those paths).

Tests

• New typed-error regression tests (429 → RateLimited, 5xx → ServiceUnavailable).
• 118 samples/ratings/utils tests pass; ruff clean.

Intentionally excluded (per scope + backward-compat)

• No kwarg renames — the Samples camelCase mirrors the upstream API; a rename would break callers.
• No get_codes return-shape change, no ssl_check additions (those were the "breaking" option).
• The _aggregate_paginated_response / _combine_chunk_responses response-merge dedup is deferred to avoid conflicting with the in-flight chunking PR fix: repair WQP_Metadata.site_info and streamstats.Watershed #295.

🤖 Generated with Claude Code