refactor: hoist _default_headers into utils (neutral HTTP layer)

`_default_headers` (the token-aware USGS-API request headers) lived in
`ogc/engine.py`, but nothing about it is OGC-specific: it's consumed by the
Water Data getters, the stats client, and `wateruse`, and `waterdata/utils`
already re-exported it. The new `wateruse` module (a non-OGC CSV API) having
to reach into the OGC engine for it was an inverted dependency.

Move the definition to `dataretrieval/utils.py` — the package's neutral HTTP
foundation, alongside `_get`, `HTTPX_DEFAULTS`, `query`, and `BaseMetadata` —
and repoint the importers. `ogc.engine` and `waterdata.utils` re-import it, so
`ogc.engine._default_headers` and `waterdata.utils._default_headers` still
resolve to the same object; no behavior change. Also drops the now-unused `os`
and `__version__` imports from the engine.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01Sjb14HkwuCydKSKMsaXsgd

Author: thodson-usgs

dataretrieval/ogc/engine.py

@@ -29,7 +29,6 @@
 import json
 import logging
 import numbers
-import os
 import re
 from collections.abc import (
     AsyncIterator,
@@ -49,7 +48,6 @@
 import pandas as pd
 from anyio.from_thread import start_blocking_portal
 
-from dataretrieval import __version__
 from dataretrieval.exceptions import DataRetrievalError
 from dataretrieval.ogc import chunking
 from dataretrieval.ogc import progress as _progress
@@ -61,7 +59,13 @@
 from dataretrieval.ogc.errors import _paginated_failure_message, _raise_for_non_200
 from dataretrieval.ogc.planning import _safe_elapsed
 from dataretrieval.ogc.shaping import GEOPANDAS, _finalize_ogc, _get_resp_data
-from dataretrieval.utils import HTTPX_DEFAULTS, BaseMetadata, _get, _network_error
+from dataretrieval.utils import (
+    HTTPX_DEFAULTS,
+    BaseMetadata,
+    _default_headers,
+    _get,
+    _network_error,
+)
 
 # Set up logger for this module
 logger = logging.getLogger(__name__)
@@ -242,29 +246,6 @@ def _cql2_param(args: dict[str, Any]) -> str:
     return json.dumps(query, separators=(",", ":"))
 
 
-def _default_headers() -> dict[str, str]:
-    """
-    Generate default HTTP headers for API requests.
-
-    Returns
-    -------
-    dict
-        A dictionary containing default headers including 'Accept-Encoding',
-        'Accept', 'User-Agent', and 'lang'. If the environment variable
-        'API_USGS_PAT' is set, its value is included as the 'X-Api-Key' header.
-    """
-    headers = {
-        "Accept-Encoding": "compress, gzip",
-        "Accept": "application/json",
-        "User-Agent": f"python-dataretrieval/{__version__}",
-        "lang": "en-US",
-    }
-    token = os.getenv("API_USGS_PAT")
-    if token:
-        headers["X-Api-Key"] = token
-    return headers
-
-
 def _check_ogc_requests(endpoint: str, req_type: str = "queryables") -> dict[str, Any]:
     """
     Sends an HTTP GET request to the specified OGC endpoint and request type,

dataretrieval/utils.py

@@ -4,6 +4,7 @@
 
 from __future__ import annotations
 
+import os
 import warnings
 from collections.abc import Iterable
 from typing import Any
@@ -29,6 +30,35 @@
 }
 
 
+def _default_headers() -> dict[str, str]:
+    """Build the default HTTP headers for a USGS web-API request.
+
+    Always sets a descriptive ``User-Agent`` plus ``Accept`` /
+    ``Accept-Encoding`` and ``lang``. If the ``API_USGS_PAT`` environment
+    variable is set, its value is added as the ``X-Api-Key`` header — a USGS
+    personal access token raises the request rate limit.
+
+    Shared by the OGC engine (:mod:`dataretrieval.ogc`), the Water Data getters
+    (:mod:`dataretrieval.waterdata`), and :mod:`dataretrieval.wateruse`, so the
+    request identity is consistent across every USGS API the package talks to.
+
+    Returns
+    -------
+    dict[str, str]
+        Headers suitable for an ``httpx`` request against a USGS API.
+    """
+    headers = {
+        "Accept-Encoding": "compress, gzip",
+        "Accept": "application/json",
+        "User-Agent": f"python-dataretrieval/{dataretrieval.__version__}",
+        "lang": "en-US",
+    }
+    token = os.getenv("API_USGS_PAT")
+    if token:
+        headers["X-Api-Key"] = token
+    return headers
+
+
 def to_str(listlike: object, delimiter: str = ",") -> str | None:
     """Translates list-like objects into strings.
 

dataretrieval/waterdata/stats.py

@@ -18,7 +18,6 @@
 
 from dataretrieval.ogc.engine import (
     BASE_URL,
-    _default_headers,
     _paginate,
     _run_sync,
 )
@@ -27,7 +26,7 @@
     _attach_coordinates,
     _empty_feature_frame,
 )
-from dataretrieval.utils import BaseMetadata
+from dataretrieval.utils import BaseMetadata, _default_headers
 
 # ``_handle_nesting``'s geopandas branch calls ``gpd.GeoDataFrame.from_features``
 # directly, so this module needs its own bound ``gpd`` name. Import it under the

dataretrieval/waterdata/utils.py

@@ -37,7 +37,6 @@
     _check_ogc_requests,
     _construct_api_requests,
     _construct_cql_request,
-    _default_headers,
     _next_req_url,
     _normalize_str_iterable,
     _paginate,
@@ -65,7 +64,7 @@
 from dataretrieval.ogc.shaping import (
     _finalize_ogc as _engine_finalize_ogc,
 )
-from dataretrieval.utils import BaseMetadata
+from dataretrieval.utils import BaseMetadata, _default_headers
 from dataretrieval.waterdata.types import (
     PROFILE_LOOKUP,
     PROFILES,

dataretrieval/wateruse.py

@@ -12,7 +12,7 @@
 (:mod:`dataretrieval.ngwmn`), the NWDC is a plain CSV REST service rather than
 an OGC API Features collection, so this module talks to it directly instead of
 delegating to the shared OGC engine. It still follows the same conventions:
-shared request headers (:func:`~dataretrieval.ogc.engine._default_headers`),
+shared request headers (:func:`~dataretrieval.utils._default_headers`),
 the typed :class:`~dataretrieval.exceptions.DataRetrievalError` taxonomy, and a
 ``(DataFrame, BaseMetadata)`` return.
 
@@ -47,8 +47,13 @@
 import pandas as pd
 
 from dataretrieval.exceptions import error_for_status
-from dataretrieval.ogc.engine import _default_headers
-from dataretrieval.utils import HTTPX_DEFAULTS, BaseMetadata, _get, to_str
+from dataretrieval.utils import (
+    HTTPX_DEFAULTS,
+    BaseMetadata,
+    _default_headers,
+    _get,
+    to_str,
+)
 
 if TYPE_CHECKING:
     from collections.abc import Iterable