Parse Date/Time/TimeZone triplets in samples and WQP

[thodson-usgs]

Summary

Closes #266.

• Adds dataretrieval.utils._attach_datetime_columns(df) — a private helper that scans a CSV-derived DataFrame for <prefix>Date / <prefix>Time / <prefix>TimeZone triplets and appends a derived <prefix>DateTime UTC column for each one. Recognizes both the WQX3 / Samples shape (Activity_StartDate, Activity_StartTime, Activity_StartTimeZone) and the legacy WQP shape (ActivityStartDate, ActivityStartTime/Time, ActivityStartTime/TimeZoneCode).
• Wires the helper into waterdata.get_samples() and wqp.get_results() (per the issue title's "samples/WQP" scope). Users do not call the helper directly; the <prefix>DateTime columns simply appear on the returned DataFrame.
• Original triplet columns are preserved; an existing <prefix>DateTime column on the response is never overwritten. Unknown timezone abbreviations resolve to NaT.
• Timezone abbreviations are resolved via the existing dataretrieval.codes.tz mapping (EST/EDT/CST/CDT/MST/MDT/PST/PDT/AKST/AKDT/HST/UTC/GMT and many more), the same source the existing format_datetime() helper uses. Mirrors R dataRetrieval's create_dateTime in importWQP.R.
• Also bumps requires-python from >=3.8 to >=3.9 (and the ruff target similarly) to match what CI was already testing. Called out in NEWS.

The worked example in the issue (no API change — the new column just appears):

>>> df, md = waterdata.get_samples(
...     monitoringLocationIdentifier="USGS-11455508",
...     usgsPCode="00631",
...     activityStartDateLower="2024-01-01",
...     activityStartDateUpper="2024-06-01",
...     profile="basicphyschem",
... )
>>> df["Activity_StartDate"][0],   df["Activity_StartTime"][0], df["Activity_StartTimeZone"][0]
('2024-01-09', '10:00:00', 'PST')
>>> df["Activity_StartDateTime"][0]
Timestamp('2024-01-09 18:00:00+0000', tz='UTC')

Test plan

• New unit tests in tests/utils_test.py::Test_attach_datetime_columns cover: WQX3 triplet → UTC, legacy WQP triplet → UTC, unknown TZ → NaT, partial-row missing time/tz → NaT, existing target column not overwritten, multiple triplets in one frame, lone *Date column without time/tz left alone.
• tests/waterdata_test.py::test_mock_get_samples updated to assert the new Activity_StartDateTime column appears with the correct UTC timestamp on the samples_results.txt fixture.
• tests/wqp_test.py::test_get_results (legacy) and test_get_results_WQX3 updated to assert the appropriate *DateTime column appears and parses on each fixture.
• tests/waterdata_test.py::test_samples_activity (live) column-count assertion bumped from 95 → 97 to account for Activity_StartDateTime and Activity_EndDateTime.
• Full mocked test suite: 283 passed locally (no regressions). Full CI matrix (Ubuntu + Windows × 3.9, 3.13, 3.14) passes.

🤖 Generated with Claude Code

[Copilot]

Pull request overview

This PR adds a utility to derive UTC Timestamp columns from <prefix>Date / <prefix>Time / <prefix>TimeZone triplets returned by Samples and WQP CSV endpoints, and wires it into waterdata.get_samples() and wqp.get_results() to address #266.

Changes:

• Added dataretrieval.utils.attach_datetime_columns(df) to detect WQX3 and legacy WQP triplet naming patterns and append <prefix>DateTime (UTC) columns without overwriting existing ones.
• Integrated the helper into dataretrieval.waterdata.api.get_samples() and dataretrieval.wqp.get_results().
• Updated unit/integration tests and NEWS entry to reflect the new derived columns.

Reviewed changes

Copilot reviewed 7 out of 7 changed files in this pull request and generated 1 comment.

Show a summary per file

File	Description
dataretrieval/utils.py	Introduces attach_datetime_columns() and supporting parsing helpers for Date/Time/TimeZone triplets.
dataretrieval/waterdata/api.py	Applies attach_datetime_columns() to Samples CSV responses returned by get_samples().
dataretrieval/wqp.py	Applies attach_datetime_columns() to WQP CSV responses returned by get_results() and documents the behavior.
tests/utils_test.py	Adds unit tests covering triplet detection, UTC conversion, and edge cases (unknown TZ, missing values, no overwrite).
tests/waterdata_test.py	Updates Samples mocked/live tests to account for new derived datetime columns and validate a fixture timestamp.
tests/wqp_test.py	Updates WQP mocked tests to account for new columns and asserts derived datetime presence.
NEWS.md	Documents the new derived datetime behavior for Samples and WQP.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Copilot]

Pull request overview

Copilot reviewed 11 out of 11 changed files in this pull request and generated 5 comments.

[Copilot]

Pull request overview

Copilot reviewed 11 out of 11 changed files in this pull request and generated 1 comment.

Comments suppressed due to low confidence (1)

tests/waterdata_test.py:9

• This module is still skipped entirely on Python < 3.10, but the project now declares requires-python >= 3.9 and CI includes a 3.9 job. As a result, waterdata behavior (including the new Activity_*DateTime derivation asserted below) is not tested on one of the declared supported versions. Consider either removing/relaxing the module-level skip or updating the declared minimum Python version to match the versions that can run the waterdata test suite.

import pandas as pd
import pytest
from pandas import DataFrame

if sys.version_info < (3, 10):
    pytest.skip("Skip entire module on Python < 3.10", allow_module_level=True)

[Copilot]

Pull request overview

Copilot reviewed 11 out of 11 changed files in this pull request and generated 1 comment.

[Copilot]

Pull request overview

Copilot reviewed 11 out of 11 changed files in this pull request and generated 1 comment.

[thodson-usgs]

@ldecicco-USGS, this modifies get_samples and wqp to return an additional datetime We also bump the minimum Python version to 3.9. The CI already tested 3.9+, but I still had 3.8+ in the package config.

[ldecicco-USGS]

Looks good. The only thing I see that is still different between R and Python for this is that the returned table in R sorts by either Activity_StartDateTime (which comes back from WQX3), ActivityStartDateTime (from legacy), or the first set of triple Time/Date/Zone columns (just in case...).

    if ("Activity_StartDateTime" %in% names(retval)) {
      #WQX 3
      retval <- retval[order(retval$Activity_StartDateTime), ]
    } else if ("ActivityStartDateTime" %in% names(retval)) {
      #legacy
      retval <- retval[order(retval$ActivityStartDateTime), ]
    } else {
      retval <- retval[order(retval[[dateCols[1]]]), ]
    }

Otherwise the order coming back from both samples and WQP can get pretty funky.

Not sure if you want to consider that in another PR or add it to this one.