Accept datetime / date for start_time and end_time (#44, #53)

[nick-gorman]

Summary

Cherry-picks Matt's two PR-#67 commits that taught the public NEMOSIS API to accept datetime.datetime and datetime.date for start_time / end_time, not just "YYYY/MM/DD HH:MM:SS" strings. Closes #44 and #53.

Public API after this PR:

• str — legacy "YYYY/MM/DD HH:MM:SS" format, unchanged
• datetime (timezone-naive) — used verbatim; tz-aware datetimes raise ValueError (the conversion isn't implemented since the contract is "treated as market time")
• date — converted to midnight. end_time resolves to midnight at the start of the next day so a request bounded by a date covers the whole of that date

Commits

1. bad82bc Allow start_date to be dt.datetime — Matt's 34fecd4, cherry-picked with Matt's authorship preserved
2. 691bbb1 Allow passing date as start_time and end_time — Matt's 539670b, cherry-picked with Matt's authorship preserved
3. 8f11360 Fix dispatch_date_setup / dispatch_half_hour_setup to accept datetime inputs, and add end-to-end coverage — my follow-up

Conflict resolutions during cherry-pick

• src/nemosis/data_fetch_methods.py: kept HEAD's underscore-aliased module imports (project convention), but adopted Matt's direct _filter_on_column_value import since both call sites changed. Kept HEAD's static_downloader_map with download_xlsx (PR Rename download_xl → download_xlsx, drop dead dict keys #84 rename) and no _downloader.download_xml dead key (PR Rename download_xl → download_xlsx, drop dead dict keys #84 cleanup).
• src/nemosis/custom_tables.py (twice): kept Matt's parse_datetime_py call with midnight='start' / midnight='end' but retained HEAD's pandas freq='5min' (PR Small fixes: 1-sec FCAS columns, Excel close, Pandas deprecations #81 deprecation fix).
• tests/test_data_fetch_methods.py: dropped — the file was deleted by PR Port test suite to offline fixture-based architecture #72 in favour of the offline-fixture suite. Matt's two test_dt_not_string tests were re-implemented in offline-fixture style in tests/end_to_end_table_tests/test_datetime_inputs.py (see below).

Bug Matt's PR didn't catch (fixed here)

dispatch_date_setup and dispatch_half_hour_setup in query_wrappers.py are setup-function wrappers used by _set_up_dynamic_compilers. They run BEFORE _parse_datetime_py is called in the compilers, and both still called datetime.strptime(start_time, ...) directly — so passing a datetime or date to any table that routes through them (BIDDAYOFFER_D, BIDPEROFFER_D, MNSP_DAYOFFER, MNSP_PEROFFER, MNSP_INTERCONNECTOR) raised TypeError: strptime() argument 1 must be str, not datetime.datetime. Both wrappers now route through parse_datetime_py at the start, so they accept any of the three input shapes.

Departures from Matt's design

• Kept the _downloader.X module reference in static_downloader_map rather than switching to direct function imports. The rest of the file uses underscore-aliased module imports throughout.
• Dropped the "_downloader.download_xml": download_xml key — PR Rename download_xl → download_xlsx, drop dead dict keys #84 already removed it as dead.
• Did not pull in Matt's net-hitting test_dt_not_string tests in tests/test_data_fetch_methods.py. That whole file was deleted by PR Port test suite to offline fixture-based architecture #72. Offline-fixture replacements in tests/end_to_end_table_tests/test_datetime_inputs.py cover the same behaviour without hitting real AEMO.

Tests

tests/test_date_generators.py::TestParseDatetimePy — Matt's unit tests, 5 cases (datetime, tz-aware datetime, valid string, invalid string, date with midnight='start' and midnight='end').

tests/end_to_end_table_tests/test_datetime_inputs.py — 5 new offline-fixture tests:

• test_dynamic_data_compiler_accepts_datetime
• test_dynamic_data_compiler_accepts_date — verifies date end_time resolves to start-of-next-day
• test_cache_compiler_accepts_datetime
• test_cache_compiler_accepts_date
• test_dispatch_date_setup_path_accepts_datetime — regression test for the bug above

Part of the PR #67 breakdown (#9 of ~10).

Test plan

• uv run pytest tests/test_date_generators.py tests/end_to_end_table_tests/test_datetime_inputs.py — 33 pass
• uv run pytest — full suite 399 passed / 1 skipped (no regressions)
• CI matrix (3.10–3.14 × ubuntu/windows/macos)

🤖 Generated with Claude Code