refactor: declare each adapter's Service and pass get_ogc_data one Endpoint (ADR 0014, step 3)

[thodson-usgs]

Step 3 of ADR 0014 (proposed), the last step. Stacked on #448 and #449: review only the last commit, 90d5b5c6. I'll rebase as the others merge.

Problem

• Service names written as literals: each adapter wrote its service's name, such as adapter="waterdata", at every configuration, retry and fan-out call: 18 sites in 10 files, plus its Configuration class.
• URL resolution repeated: each adapter resolved its URL with its own base_url(adapter=..., default=...) call.
• Arguments passed separately: get_ogc_data took the URL, the dialect and the adapter name as three arguments that always travel together.

Change

• dataretrieval._service is a dependency-free leaf with 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.

• Each adapter declares its Service once and reads the name from it in:

  • its Configuration class;
  • its retry and fan-out adapter= arguments;
  • configuration.service_url(service), which replaces base_url(adapter=..., default=...).

  Water Data's SERVICE is in waterdata.endpoints, shared by its four APIs.

• get_ogc_data takes endpoint= in place of base_url=, dialect= and adapter=. The request builder and finalizer it binds keep their URL and dialect arguments; ADR 0014: declare how each service departs from its protocol as data #448 changed the ADR's wording to match.

• Tests:

  • New test_service_names_are_written_only_where_declared fails if a service name appears as a literal outside its declaration and the configuration roster.
  • The read-site test in configuration_test.py now looks for <declaration>.name or Endpoint(<declaration>, ...).

• CONTEXT.md defines Service declaration and Endpoint, and broadens Dialect to cover both dialect types.

Not done, by design

• Endpoint for the STAC ratings search: get_ratings uses STAC_DATES directly.
• Endpoint for WQP, NLDI, NWDC, StreamStats, Samples and Statistics: no shared protocol code reads a dialect for them. They get a Service only.

Behavior

No change.

• Offline: the suite (1336 tests) passes under UTC and America/Chicago, coverage is 99.10%, and the pre-commit gates pass.
• Live, all returned data as expected:
  • Water Data get_daily, get_continuous with an interval string, and get_ratings;
  • get_reference_table with a date in query;
  • NGWMN get_water_level with an open start;
  • WQP get_results;
  • an NgwmnConfiguration(base_url=...) redirect.

Once this merges, ADR 0014 can be marked Accepted.

🤖 Generated with Claude Code

https://claude.ai/code/session_01HBt3Ee7eneKtdKQWq2T3YK

[thodson-usgs]

Combined into #448, which now holds all three ADR 0014 steps as one commit each.