refactor(waterdata.xarray): move CF vocabulary maps to types

The CF lookup tables (USGS units -> UDUNITS, statistic_id -> cell_methods
operator, parameter_code -> standard_name) are plain reference data, so move
them out of the converter module into types.py as public, extensible
constants (CF_UNIT_MAP, CF_CELL_METHODS, CF_STANDARD_NAMES) alongside the
existing PROFILE_LOOKUP. They carry no xarray dependency, so types.py stays
import-light and the tables can be extended without importing the
xarray-optional converter. xarray.py imports them at the top; behavior is
unchanged.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Author: thodson-usgs

dataretrieval/waterdata/types.py

@@ -74,3 +74,47 @@
         "count",
     ],
 }
+
+
+# --- CF / xarray vocabulary mappings ---------------------------------------
+# Lookup tables used by :mod:`dataretrieval.waterdata.xarray` to translate
+# USGS terms into CF-conventions metadata. Each is intentionally partial:
+# anything not listed falls back to a sensible default (raw unit string kept
+# verbatim; no standard_name emitted) rather than guessing a wrong CF term.
+# They are plain data, so they live here rather than in the (xarray-optional)
+# converter module and can be extended without importing xarray.
+
+# USGS unit strings -> UDUNITS / CF-canonical form.
+CF_UNIT_MAP = {
+    "ft^3/s": "ft3 s-1",
+    "ft3/s": "ft3 s-1",
+    "ft": "ft",
+    "in": "in",
+    "degC": "degC",
+    "deg C": "degC",
+    "uS/cm": "uS/cm",
+    "mg/l": "mg L-1",
+    "mg/L": "mg L-1",
+    "tons/day": "short_ton day-1",
+    "%": "percent",
+}
+
+# USGS statistic_id -> the operator in a CF ``cell_methods`` string.
+CF_CELL_METHODS = {
+    "00001": "maximum",
+    "00002": "minimum",
+    "00003": "mean",
+    "00006": "sum",
+    "00008": "median",
+    "00011": "point",  # instantaneous
+}
+
+# USGS 5-digit parameter code -> CF standard_name. Deliberately conservative;
+# codes without a confident match are left without a standard_name.
+CF_STANDARD_NAMES = {
+    "00060": "water_volume_transport_in_river_channel",
+    "00010": "water_temperature",
+    "00065": "water_surface_height_above_reference_datum",
+    "63160": "water_surface_height_above_reference_datum",
+    "00045": "lwe_thickness_of_precipitation_amount",
+}

dataretrieval/waterdata/xarray.py

@@ -48,6 +48,7 @@
 
 from . import api as _api
 from .nearest import get_nearest_continuous as _get_nearest_continuous
+from .types import CF_CELL_METHODS, CF_STANDARD_NAMES, CF_UNIT_MAP
 
 __all__ = [
     "get_continuous",
@@ -62,47 +63,10 @@
 ]
 
 
-# --- CF mapping tables -----------------------------------------------------
-# Each is intentionally partial: anything not listed falls back to a sensible
-# default (raw unit string kept verbatim; no standard_name emitted) rather
-# than guessing and emitting a wrong CF term.
-
-# USGS unit strings -> UDUNITS / CF-canonical form.
-_UDUNITS = {
-    "ft^3/s": "ft3 s-1",
-    "ft3/s": "ft3 s-1",
-    "ft": "ft",
-    "in": "in",
-    "degC": "degC",
-    "deg C": "degC",
-    "uS/cm": "uS/cm",
-    "mg/l": "mg L-1",
-    "mg/L": "mg L-1",
-    "tons/day": "short_ton day-1",
-    "%": "percent",
-}
-
-# USGS statistic_id -> the operator in a CF ``cell_methods`` string. Read
-# straight from the values frame, so no metadata round-trip is needed to
-# classify the aggregation.
-_STATISTIC_CELL_METHOD = {
-    "00001": "maximum",
-    "00002": "minimum",
-    "00003": "mean",
-    "00006": "sum",
-    "00008": "median",
-    "00011": "point",  # instantaneous
-}
-
-# USGS 5-digit parameter code -> CF standard_name. Deliberately conservative;
-# codes without a confident match are left without a standard_name.
-_STANDARD_NAME = {
-    "00060": "water_volume_transport_in_river_channel",
-    "00010": "water_temperature",
-    "00065": "water_surface_height_above_reference_datum",
-    "63160": "water_surface_height_above_reference_datum",
-    "00045": "lwe_thickness_of_precipitation_amount",
-}
+# The CF vocabulary lookups (USGS units -> UDUNITS, statistic_id ->
+# cell_methods operator, parameter_code -> standard_name) are plain data and
+# live in ``types`` -- imported as CF_UNIT_MAP / CF_CELL_METHODS /
+# CF_STANDARD_NAMES at the top of this module.
 
 # Columns kept off the value pivot but surfaced as ancillary (flag) variables.
 _ANCILLARY = ("qualifier", "approval_status")
@@ -179,19 +143,17 @@ def _var_attrs(desc, *, unit, pcode, stat, default_cell_method, ancillary, name)
         attrs["long_name"] = str(long_name)
 
     if unit is not None and _pd.notna(unit):
-        attrs["units"] = _UDUNITS.get(str(unit), str(unit))
+        attrs["units"] = CF_UNIT_MAP.get(str(unit), str(unit))
 
     op = (
-        _STATISTIC_CELL_METHOD.get(str(stat))
-        if stat is not None and _pd.notna(stat)
-        else None
+        CF_CELL_METHODS.get(str(stat)) if stat is not None and _pd.notna(stat) else None
     )
     op = op or default_cell_method
     if op:
         attrs["cell_methods"] = f"time: {op}"
 
     if pcode is not None and _pd.notna(pcode):
-        sn = _STANDARD_NAME.get(str(pcode))
+        sn = CF_STANDARD_NAMES.get(str(pcode))
         if sn:
             attrs["standard_name"] = sn
         attrs["usgs_parameter_code"] = str(pcode)
@@ -289,7 +251,7 @@ def _build_timeseries(
 
         name = _slug(desc.get("parameter_name") or pcode)
         if name in used:  # same parameter, different statistic -> distinct var
-            op = _STATISTIC_CELL_METHOD.get(str(stat)) or (str(stat) if stat else None)
+            op = CF_CELL_METHODS.get(str(stat)) or (str(stat) if stat else None)
             name = f"{name}_{_slug(op)}" if op else name
         while name in used:
             name += "_x"