fix(codes): reconcile time-zone table with USGS and WQX code lists (#456)

* fix(codes): reconcile the time-zone table with the USGS and WQX code lists

Samples writes American Samoa as ZP-11, which the table lacked, so every
timed American Samoa row from get_samples() had a NaT datetime. Follow the
USGS NWIS list (Samples) and the WQX TimeZone domain (WQP); where they
disagree (SST, BST), WQX wins. Snapshots of both lists back an offline
test, and live tests watch the published lists and responses for Pacific
monitoring locations.

* docs(codes): note that WQP passes USGS time-zone codes through

A live sweep of every state and territory found ZP-11 in WQP responses for
USGS American Samoa records, so the USGS list governs part of WQP too.

Author: thodson-usgs

NEWS.md

@@ -1,3 +1,5 @@
+**10/16/2026:** **Bug fix:** the time-zone table behind the `*DateTime` columns that `waterdata.get_samples()` and `wqp.get_results()` append, and behind `utils.format_datetime()`, now follows the code lists those services use: the USGS NWIS time-zone list (Samples, and the USGS records that the Water Quality Portal passes through) and the WQX TimeZone domain (Water Quality Portal). USGS records write American Samoa as `ZP-11`, which was missing, so every timed American Samoa row from `get_samples()`, and every timed USGS American Samoa row from `get_results()`, had a `NaT` datetime; it is now UTC-11. 39 other codes from the two lists that used to become `NaT` now resolve, among them the remaining `ZP*` offsets, `IDLW`, `IDLE`, `NZT`, `SWT`, and the retired WQX codes `AHST` and `YST`. **Behavior change:** codes that the table read with a different meaning from the USGS list now take the USGS meaning: `CAST` (+9:30), `CCT` (+8), `EASST` (+11), `EAST` (+10), `NFT` (-3:30), `NZDT` (+13), `WAST` (+7), and `WAT` (-1). `FJST` is now UTC+13. Where the two lists disagree, WQX wins: `SST` stays American Samoa (UTC-11), the meaning the Water Quality Portal returns, and `BST` is UTC-11.
+
 **10/15/2026:** **Bug fix:** the `ActivityStartDateTime` and `Activity_StartDateTime` columns that `wqp.get_results()` and `waterdata.get_samples()` append, and the `datetime` column of `utils.format_datetime()`, read the time-zone code `GST` as Gulf Standard Time (UTC+4). The USGS time-zone codes and the WQX TimeZone domain both define `GST` as Guam Standard Time (UTC+10), so a sample collected on Guam at 10:00 local time was placed at 06:00 UTC instead of 00:00 UTC. `GST` is now UTC+10, and `HDT` (Hawaii-Aleutian Daylight Time, UTC-9), a USGS code that was missing from the table, now resolves instead of becoming `NaT`.
 
 **10/13/2026:** Twenty columns that the Water Data OGC collections return are now named, documented parameters of the getter that returns them; before, they could be passed only through `**queryables`. `get_field_measurements()`: `control_condition`, `day`, `field_measurements_series_id`, `measurement_rated`, `month`, `reading_type`, `time_of_day`, `year`. `get_peaks()`: `qualifier`, `time_of_day`, `value`. `get_monitoring_locations()`: `revision_created`, `revision_modified`, `revision_note`. `get_combined_metadata()`: `data_gap_interval`, `reading_type`. `get_time_series_metadata()`: `data_gap_interval`, `parameter_description`. `get_field_measurements_metadata()`: `reading_type`. `get_channel()`: `channel_location_direction`. They are keyword-only, so every existing call, including one that passes arguments by position, sends the same request as before; `sublocation_identifier` (10/07) is keyword-only too. **Behavior change:** `statistics_begin` in `get_time_series_metadata()` and `method_category` in `get_continuous()`, added in 1.4.0, are now keyword-only too, so a call that passed either by position, or passed a later argument by position (from `thresholds` in `get_time_series_metadata()` and from `value` in `get_continuous()`), must pass it by name.

dataretrieval/codes/timezones.py

@@ -1,50 +1,61 @@
 """Time zone information.
 
 Maps the time-zone abbreviations that services put beside a local date and
-time to UTC offsets. Several abbreviations name more than one zone worldwide.
-``GST`` follows the USGS time-zone codes and the WQX TimeZone domain, which
-both define it as Guam Standard Time (UTC+10), not Gulf Standard Time. Other
-entries that differ from the USGS list (``CCT``, ``EAST``, ``NFT``, ``NZDT``,
-``SST``, ``WAT``) have not been reconciled, and the two lists disagree with
-each other on ``SST``.
+time to UTC offsets. Several abbreviations name more than one zone worldwide,
+so the table follows the code lists the services draw from rather than common
+usage:
+
+* the WQX TimeZone domain, used by the Water Quality Portal
+  (``tests/data/wqx_timezones.csv``), and
+* the USGS NWIS time-zone list, used by the USGS Samples database and by the
+  USGS records the Water Quality Portal passes through
+  (``tests/data/usgs_timezones.xml``).
+
+Where the two lists disagree -- ``SST`` (American Samoa in WQX, Swedish Summer
+Time in USGS) and ``BST`` (retired Bering Standard Time in WQX, British Summer
+Time in USGS) -- WQX wins: the Water Quality Portal returns ``SST`` for American
+Samoa, and USGS records write that zone as ``ZP-11``. Abbreviations in
+neither list keep their common meaning. ``tests/timezones_test.py`` checks the
+table against both lists.
 """
 
-tz_str = """-1200 Y
--1100 X NUT SST
--1000 W CKT HAST HST TAHT TKT
--0900 V AKST GAMT GIT HADT HDT HNY
+tz_str = """-1200 Y IDLW
+-1100 X BST NUT SST ZP-11
+-1000 W AHST CKT HAST HST TAHT TKT
+-0900 V AKST GAMT GIT HADT HDT HNY YST
 -0800 U AKDT CIST HAY HNP PST PT
 -0700 T HAP HNR MST PDT
--0600 S CST EAST GALT HAR HNC MDT
--0500 R CDT COT EASST ECT EST ET HAC HNE PET
+-0600 S CST GALT HAR HNC MDT
+-0500 R CDT COT ECT EST ET HAC HNE PET
 -0400 Q AST BOT CLT COST EDT FKT GYT HAE HNA PYT
--0300 P ADT ART BRT CLST FKST GFT HAA PMST PYST SRT UYT WGT
--0200 O BRST FNT PMDT UYST WGST
--0100 N AZOT CVT EGT
+-0300 P ADT ART BRT CLST FKST GFT HAA PMST PYST SRT UYT WGT ZP-3
+-0200 O BRST FNT PMDT UYST WGST ZP-2
+-0100 N AZOT CVT EGT WAT
 +0000 Z EGST GMT UTC WET WT
-+0100 A CET DFT WAT WEDT WEST
-+0200 B CAT CEDT CEST EET SAST WAST
-+0300 C EAT EEDT EEST IDT MSK
-+0400 D AMT AZT GET KUYT MSD MUT RET SAMT SCT
-+0500 E AMST AQTT AZST HMT MAWT MVT PKT TFT TJT TMT UZT YEKT
-+0600 F ALMT BIOT BTT IOT KGT NOVT OMST YEKST
-+0700 G CXT DAVT HOVT ICT KRAT NOVST OMSST THA WIB
-+0800 H ACT AWST BDT BNT CAST HKT IRKT KRAST MYT PHT SGT ULAT WITA WST
-+0900 I AWDT IRKST JST KST PWT TLT WDT WIT YAKT
-+1000 K AEST ChST GST PGT VLAT YAKST YAPT
-+1100 L AEDT LHDT MAGT NCT PONT SBT VLAST VUT
-+1200 M ANAST ANAT FJT GILT MAGST MHT NZST PETST PETT TVT WFT
-+1330 FJST NZDT
-+1130 NFT
-+1030 ACDT LHST
-+0930 ACST
-+0630 CCT MMT
++0100 A CET DFT DNT DST FST MET MEWT MEZ NOR SET SWT WEDT WEST WETDST
++0200 B CAT CEDT CEST CETDST EET FWT IST MEST METDST SAST
++0300 C BT EAT EEDT EEST EETDST IDT MSK
++0400 D AMT AZT GET KUYT MSD MUT RET SAMT SCT ZP4
++0500 E AMST AQTT AZST HMT MAWT MVT PKT TFT TJT TMT UZT YEKT ZP5
++0600 F ALMT BIOT BTT IOT KGT NOVT OMST YEKST ZP6
++0700 G CXT DAVT HOVT ICT KRAT NOVST OMSST THA WAST WIB
++0800 H ACT AWST BDT BNT CCT HKT IRKT KRAST MYT PHT SGT ULAT WADT WITA WST
++0900 I AWDT AWSST IRKST JST KST PWT TLT WDT WIT YAKT
++1000 K AEST ChST EAST GST LIGT PGT VLAT YAKST YAPT
++1100 L AEDT AESST EASST LHDT MAGT NCT PONT SBT VLAST VUT ZP11
++1200 M ANAST ANAT FJT GILT IDLE MAGST MHT NZST NZT PETST PETT TVT WFT
++1300 FJST NZDT
++1030 ACDT ACSST CADT LHST SADT
++0930 ACST CAST SAT
++0830 MT
++0730 JT
++0630 MMT
 +0545 NPT
 +0530 SLT
 +0430 AFT IRDT
-+0330 IRST
++0330 IRST IT
 -0230 HAT NDT
--0330 HNT NST NT
+-0330 HNT NFT NST NT
 -0430 HLV VET
 -0930 MART MIT"""
 

tests/contracts/README.md

@@ -10,7 +10,8 @@ The suite uses four dependency-oriented layers without moving established tests:
   response parsing, and documented protocol behavior.
 - **Component** (`transport_test.py`, `waterdata_chunking_test.py`,
   `waterdata_queryables_test.py`, `waterdata_endpoints_test.py`,
-  `waterdata_properties_test.py`, `rdb_test.py`, `_csv_test.py`): one internal
+  `waterdata_properties_test.py`, `rdb_test.py`, `_csv_test.py`,
+  `timezones_test.py`): one internal
   responsibility in isolation.
 - **Cross-component** (`architecture_test.py`, `headers_host_scoping_test.py`,
   `waterdata_progress_test.py`): dependency fitness functions and behavior that