Mark attach_datetime_columns as private and add type hints

The helper is purely an internal post-processing step inside
get_samples / get_results — users have no reason to call it directly,
and dataretrieval/__init__.py's `from dataretrieval.utils import *`
was leaking it into the public API surface as
`dataretrieval.attach_datetime_columns`. Underscore-prefix it and
update the two call sites plus the unit tests.

Also annotate _attach_datetime_columns and _build_utc_datetime with
pd.DataFrame / pd.Series / pd.Series → pd.Series signatures, matching
the typing style already used in dataretrieval/waterdata/utils.py.

Addresses self-review of PR #272.

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

Author: thodson-usgs

dataretrieval/utils.py

@@ -99,7 +99,9 @@ def format_datetime(df, date_field, time_field, tz_field):
 _TIME_TZ_SUFFIXES = (("Time", "TimeZone"), ("Time/Time", "Time/TimeZoneCode"))
 
 
-def _build_utc_datetime(date_series, time_series, tz_series):
+def _build_utc_datetime(
+    date_series: pd.Series, time_series: pd.Series, tz_series: pd.Series
+) -> pd.Series:
     """Combine date + time + tz-abbreviation columns into a UTC pandas Series.
 
     Unknown timezone codes (and rows missing any of the three values) yield
@@ -118,7 +120,7 @@ def _build_utc_datetime(date_series, time_series, tz_series):
     )
 
 
-def attach_datetime_columns(df):
+def _attach_datetime_columns(df: pd.DataFrame) -> pd.DataFrame:
     """Add ``<prefix>DateTime`` UTC columns for any Date/Time/TimeZone triplets.
 
     Detects two naming patterns that appear in USGS Samples and Water Quality

dataretrieval/waterdata/api.py

@@ -16,7 +16,7 @@
 import requests
 from requests.models import PreparedRequest
 
-from dataretrieval.utils import BaseMetadata, attach_datetime_columns, to_str
+from dataretrieval.utils import BaseMetadata, _attach_datetime_columns, to_str
 from dataretrieval.waterdata.filters import FILTER_LANG
 from dataretrieval.waterdata.types import (
     CODE_SERVICES,
@@ -2329,7 +2329,7 @@ def get_samples(
     response.raise_for_status()
 
     df = pd.read_csv(StringIO(response.text), delimiter=",")
-    df = attach_datetime_columns(df)
+    df = _attach_datetime_columns(df)
 
     return df, BaseMetadata(response)
 

dataretrieval/wqp.py

@@ -17,7 +17,7 @@
 
 import pandas as pd
 
-from .utils import BaseMetadata, attach_datetime_columns, query
+from .utils import BaseMetadata, _attach_datetime_columns, query
 
 if TYPE_CHECKING:
     from pandas import DataFrame
@@ -152,7 +152,7 @@ def get_results(
     response = query(url, kwargs, delimiter=";", ssl_check=ssl_check)
 
     df = pd.read_csv(StringIO(response.text), delimiter=",", low_memory=False)
-    df = attach_datetime_columns(df)
+    df = _attach_datetime_columns(df)
     return df, WQP_Metadata(response)
 
 

tests/utils_test.py

@@ -100,7 +100,7 @@ def test_to_str_non_iterable(self):
 
 
 class Test_attach_datetime_columns:
-    """Tests of attach_datetime_columns, which derives <prefix>DateTime UTC
+    """Tests of _attach_datetime_columns, which derives <prefix>DateTime UTC
     columns from Date/Time/TimeZone triplets in Samples and WQP CSVs."""
 
     def test_wqx3_triplet_resolves_to_utc(self):
@@ -111,7 +111,7 @@ def test_wqx3_triplet_resolves_to_utc(self):
                 "Activity_StartTimeZone": ["PST", "EST"],
             }
         )
-        df = utils.attach_datetime_columns(df)
+        df = utils._attach_datetime_columns(df)
         assert df["Activity_StartDateTime"][0] == pd.Timestamp(
             "2024-01-09 18:00:00", tz="UTC"
         )
@@ -128,7 +128,7 @@ def test_legacy_wqp_triplet_resolves_to_utc(self):
                 "ActivityStartTime/TimeZoneCode": ["PST"],
             }
         )
-        df = utils.attach_datetime_columns(df)
+        df = utils._attach_datetime_columns(df)
         assert df["ActivityStartDateTime"][0] == pd.Timestamp(
             "2024-01-09 18:00:00", tz="UTC"
         )
@@ -141,7 +141,7 @@ def test_unknown_timezone_is_NaT(self):
                 "Activity_StartTimeZone": ["BOGUS"],
             }
         )
-        df = utils.attach_datetime_columns(df)
+        df = utils._attach_datetime_columns(df)
         assert df["Activity_StartDateTime"].isna().all()
 
     def test_missing_time_or_tz_is_NaT(self):
@@ -152,7 +152,7 @@ def test_missing_time_or_tz_is_NaT(self):
                 "Activity_StartTimeZone": ["PST", "EST"],
             }
         )
-        df = utils.attach_datetime_columns(df)
+        df = utils._attach_datetime_columns(df)
         assert df["Activity_StartDateTime"][0] == pd.Timestamp(
             "2024-01-09 18:00:00", tz="UTC"
         )
@@ -167,7 +167,7 @@ def test_existing_datetime_column_not_overwritten(self):
                 "Activity_StartDateTime": ["preexisting"],
             }
         )
-        df = utils.attach_datetime_columns(df)
+        df = utils._attach_datetime_columns(df)
         assert df["Activity_StartDateTime"].tolist() == ["preexisting"]
 
     def test_multiple_triplets_handled(self):
@@ -181,11 +181,11 @@ def test_multiple_triplets_handled(self):
                 "LabInfo_AnalysisStartTimeZone": ["EST"],
             }
         )
-        df = utils.attach_datetime_columns(df)
+        df = utils._attach_datetime_columns(df)
         assert "Activity_StartDateTime" in df.columns
         assert "LabInfo_AnalysisStartDateTime" in df.columns
 
     def test_lone_date_column_left_alone(self):
         df = pd.DataFrame({"LastChangeDate": ["2024-01-09"]})
-        df = utils.attach_datetime_columns(df)
+        df = utils._attach_datetime_columns(df)
         assert list(df.columns) == ["LastChangeDate"]