feat(ogc): accept date, datetime and Timestamp values in date arguments

[bhaskargurram-ai]

Follow-up from #441, which noted that pd.Timestamp and datetime elements fail with AttributeError or TypeError.

Problem

A datetime.date, datetime.datetime or pandas.Timestamp passed to a date argument fails inside the formatter, and the error names no argument:

• time=[pd.Timestamp("2024-01-01", tz="UTC"), None] and time=[date(2024, 1, 1), None] raise AttributeError: ... has no attribute 'endswith'
• time=datetime(2024, 1, 1) raises TypeError: 'datetime.datetime' object is not iterable

time=[df.index.min(), None] is a natural call for a pandas user, and today it hits the first case.

Change

In dataretrieval/ogc/dates.py, these values are now read like the equivalent string:

• An aware value is converted to UTC.
• A naive value is read in the local zone, the same rule a naive string follows.
• A date is midnight of that day.
• NaT is an open bound, like None.
• In date-only collections, the date part is used.

A lone value is treated as a single element, as a lone string already is. Any other type, for example a number, raises ValueError naming the argument and listing the accepted types (the minimum suggested in #441).

_format_one now delegates to a small _to_datetime helper, so each function stays under the complexity limit.

Tests

• test_format_api_dates_accepts_date_and_datetime_objects: date, date pairs, aware Timestamp and datetime (an offset converted to UTC), NaT as an open bound, and mixed string and Timestamp ranges.
• test_format_api_dates_reads_naive_objects_like_naive_strings: a naive datetime/Timestamp and its string spelling build the same filter, so this holds in any time zone.
• test_format_api_dates_rejects_other_types_naming_the_argument
• test_construct_api_requests_accepts_timestamp_bounds: request-level check that time=[Timestamp, None] produces time=2024-01-01%2F..

The full suite passes locally (1267 passed), including the new tests under TZ=UTC, America/Denver, Asia/Kolkata and America/Chicago. coverage report passes at 98.99%. ruff, mypy, lint-imports, xenon and complexipy are clean.

Open question

The public getter annotations still say str | list[str]. Should I widen them to include date objects in this PR, or leave that as a separate change?

---

Maintainer update (2026-10-12)

The branch is now three commits: the original commit above, unchanged; a merge of main; and one commit with the maintainer's edits.

• Lone values in get_ratings. get_ratings(time=...) accepts a lone date or Timestamp. Its duration check used to iterate the value and raise TypeError.
• bytes values. A bytes value is read as one element, so it gets the message naming the accepted types instead of "takes at most 2 values" over its byte codes.
• Docstring. get_ratings' time docstring names the accepted date types.
• NEWS. The entry is dated by its land and sits above fix(ogc): send Water Data list filters and CQL2 JSON filters correctly #446's. Its "a naive one is read in local time" clause is dropped, because fix(ogc): read each side of a "start/end" interval string like the list form #443 changes that rule (see below).
• Open question, answered. The getter annotations are widened in ADR 0014 (proposed): Service declarations and OGC endpoints #445 (DateArgument), not here.

Time zones: following pandas, #443 makes a naive date or time UTC rather than the machine's local time, so the "naive value is read in the local zone" line above holds only until #443 lands.

Merge this before #443. The full offline suite passes (1280 tests), and so do ruff, mypy and the pre-commit gates.

[bhaskargurram-ai]

@thodson-usgs this picks up the non-string follow-up you listed in #441. I went with accepting date/datetime/Timestamp rather than only rejecting them, since time=[df.index.min(), None] is a common call; happy to cut it back to a clear ValueError if you prefer. The "start/end" string validation from the same list would be my next one, unless you'd rather keep it.