From 03d708cedfe61b962fb9c699a2cce915b75c62dc Mon Sep 17 00:00:00 2001
From: nick-gorman <n.gorman305@gmail.com>
Date: Tue, 26 May 2026 10:55:41 +1000
Subject: [PATCH] Document start_time / end_time input forms

Replaces the single-line mention of accepted input forms with a
proper subsection under Dynamic data compiler. Documents all three
forms (string, datetime.datetime, datetime.date) with a concrete
code example for each, and calls out the date-expansion edge case
(end_time as a bare date is inclusive of the whole day, because
parse_datetime_py expands it to 00:00:00 of the next day).

Also switches the two existing datetime() examples in the
headline Dynamic data compiler example and the Accessing
additional table columns example to string literals, since strings
are the simplest form and don't require a datetime import.

Added TOC entry for the new subsection.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
---
 README.md | 34 ++++++++++++++++++++++++++++------
 1 file changed, 28 insertions(+), 6 deletions(-)

diff --git a/README.md b/README.md
index 1bb9828..52fa341 100644
--- a/README.md
+++ b/README.md
@@ -16,6 +16,7 @@ A Python package for downloading historical data published by the Australian Ene
   - [Data from dynamic tables](#data-from-dynamic-tables)
     - [Workflows](#workflows)
       - [Dynamic data compiler](#dynamic-data-compiler)
+        - [Start and end time](#start-and-end-time)
         - [Filter options](#filter-options)
         - [Caching options](#caching-options)
       - [Cache compiler](#cache-compiler)
@@ -100,10 +101,9 @@ Your workflow may determine how you use NEMOSIS. Because the GUI relies on data
 
 ```python
 from nemosis import dynamic_data_compiler
-from datetime import datetime
 
-start_time = datetime(2017, 1, 1, 0, 0)
-end_time = datetime(2017, 1, 1, 0, 5)
+start_time = '2017/01/01 00:00:00'
+end_time = '2017/01/01 00:05:00'
 table = 'DISPATCHPRICE'
 raw_data_cache = 'C:/Users/your_data_storage'
 
@@ -114,7 +114,29 @@ Using the default settings of `dynamic_data_compiler` will download zip archives
 
 A number of options are available to configure filtering (i.e. what data NEMOSIS returns as a pandas DataFrame) and caching.
 
-For `start_time` and `end_time` you can pass a datetime (timezone unaware), a `date`, or a string of the form "YYYY/MM/DD HH:MM:SS", e.g. `2017/01/01 00:00:00`.
+###### Start and end time
+
+`start_time` and `end_time` accept three forms:
+
+- A string in `"YYYY/MM/DD HH:MM:SS"` form, e.g. `"2017/01/01 00:00:00"`.
+- A `datetime.datetime` (timezone unaware). Timezone-aware datetimes are rejected — NEMOSIS treats all timestamps as AEMO market time.
+- A `datetime.date`. As `start_time` it expands to 00:00:00 of that day; as `end_time` it expands to 00:00:00 of the next day (so `end_time=date(2018, 5, 1)` is inclusive of all of 2018-05-01).
+
+```python
+from datetime import date, datetime
+from nemosis import dynamic_data_compiler
+
+# string
+data = dynamic_data_compiler('2017/01/01 00:00:00', '2017/01/01 00:05:00', table, raw_data_cache)
+
+# datetime
+data = dynamic_data_compiler(datetime(2017, 1, 1, 0, 0), datetime(2017, 1, 1, 0, 5), table, raw_data_cache)
+
+# date (covers all of 2017-01-01)
+data = dynamic_data_compiler(date(2017, 1, 1), date(2017, 1, 1), table, raw_data_cache)
+```
+
+The same forms are accepted by `cache_compiler`.
 
 ###### Filter options
 
@@ -234,8 +256,8 @@ from nemosis import defaults
 
 defaults.table_columns['BIDPEROFFER_D'] += ['PASAAVAILABILITY']
 
-start_time = datetime(2017, 1, 1, 0, 0)
-end_time = datetime(2017, 1, 1, 0, 5)
+start_time = '2017/01/01 00:00:00'
+end_time = '2017/01/01 00:05:00'
 table = 'BIDPEROFFER_D'
 raw_data_cache = 'C:/Users/your_data_storage'