ADR 0014: declare how each service departs from its protocol as data

[thodson-usgs]

Implements ADR 0014 (proposed, added here) in three commits, one per step. Review commit by commit. This PR replaces the single-branch draft #445, which conflicted with main in 10 files after #442 and #443. It also absorbs #449 and #450, which held steps 2 and 3.

ADR 0014 records how each service departs from its protocol's standard as dialect fields, whose defaults are the standard. Shared code names no service. A date argument is read once and written by each protocol.

Commit 1: read date arguments once and write them per protocol (1b849c83)

• dataretrieval._dates (a dependency-free leaf) reads a date argument into a DateRange: an instant, a range with None for an open bound, or a duration. Every bound is UTC; a naive value is UTC, as in pandas (fix(ogc): read each side of a "start/end" interval string like the list form #443).
• dataretrieval._intervals writes a DateRange in the ISO 8601 interval grammar that OGC API Features and STAC share. A DateDialect with two fields adjusts it:
  • open_start: .. or an empty string;
  • durations: whether a lone duration is accepted, False by default.
• Dialects:
  • OgcDialect.open_start becomes OgcDialect.dates.
  • Water Data sets durations=True.
  • NGWMN sets open_start="".
  • get_ratings uses STAC_DATES and drops its separate duration check.
• Removed: ogc/dates.py.
• Behavior change: a lone duration passed to an ngwmn getter raises ValueError before sending, instead of returning HTTP 400. get_ratings still rejects one, now with the shared message.
• Otherwise unchanged: 1432 inputs compared against main's _format_api_dates under UTC and America/Chicago gave the same output and messages.

Commit 2: declare date parameters on the dialect (a5e12be8)

• OgcDialect:
  • New field date_params, defaulting to {"datetime"}.
  • New field timed_params.
  • date_only_services is renamed date_only_collections.
  • The Water Data dialect lists its seven date parameters and timed_params={"last_modified"}. Before this, the request builder and the chunk planner named those parameters.
• When dates are read: prepare_request_args(..., dialect=) reads date parameters when the getter is called. get_ogc_data reads the ones still raw in a get_reference_table(query=...) dict, and raises TypeError for a DateRange under a key the dialect doesn't list. Samples and Statistics pass no dialect.
• New architecture test: fails if a string a shipped dialect lists appears as a literal in ogc/ or _intervals.py.
• Behavior: the values sent are unchanged. An unreadable date raises when the getter is called, with the same message as before.

Commit 3: Service and Endpoint (e245f426)

• dataretrieval._service defines two values:
  • Service: the name settings are resolved by, and the default URL;
  • Endpoint: a service, the URL resolved when a call starts, and a dialect.
• Service declarations: each adapter declares its Service once. The 18 adapter="<name>" literals and each Configuration.adapter read the name from it, and configuration.service_url(service) resolves its URL.
• get_ogc_data takes endpoint= in place of base_url=, dialect= and adapter=.
• New architecture test: fails if a service name appears as a literal outside its declaration and the configuration roster.
• CONTEXT.md defines Service declaration and Endpoint.
• Behavior: no change.

Not carried over from #445

• grouping the result-shaping fields into a ShapingDialect;
• an Endpoint for the STAC search, or for adapters with no shared protocol code;
• the ADR's Protocol and Execution rows and its revision log;
• the DateArgument annotation on the getters, which could be a later follow-up.

Tests

• Live tests: one per service checks each DateDialect field against the real Water Data OGC, NGWMN and STAC services. All pass.
• Offline: the suite (1336 tests) passes under UTC, America/Chicago and Asia/Kolkata, with coverage at 99.10%. Each commit was tested on its own, and each passed CI as ADR 0014: declare how each service departs from its protocol as data #448, refactor(ogc): declare date parameters on the dialect and read them on entry (ADR 0014, step 2) #449 and refactor: declare each adapter's Service and pass get_ogc_data one Endpoint (ADR 0014, step 3) #450.
• Pre-commit: ruff, mypy, xenon, complexipy and import-linter all pass.
• Live checks on the final commit: Water Data daily, continuous, ratings and a reference-table query with a date; NGWMN water levels with an open start; WQP results; an NgwmnConfiguration(base_url=...) redirect.

NEWS is dated 10/12; I'll re-date it to the day this lands. ADR 0014 becomes Accepted when this merges.

🤖 Generated with Claude Code

https://claude.ai/code/session_01HBt3Ee7eneKtdKQWq2T3YK