feat(python): support datetime inputs for replay

Author: thaaddeus

README.md

@@ -6,7 +6,9 @@
 
 <br/>
 
-Python `tardis-dev` package provides convenient access to tick-level historical cryptocurrency market data in exchange-native format. It focuses on two primary workflows: replaying historical market data and downloading CSV datasets. If you need normalized replay or real-time streaming, use the Node.js client or Tardis Machine.
+Python `tardis-dev` package provides convenient access to tick-level historical cryptocurrency market data in exchange-native format. It focuses on two primary workflows: replaying historical market data and downloading historical market data as CSV files. If you need normalized replay or real-time streaming, use the Node.js client or Tardis Machine.
+
+`replay()` accepts ISO date strings or Python `datetime` values. Naive datetimes are treated as UTC.
 
 <br/>
 
@@ -37,7 +39,7 @@ asyncio.run(main())
 
 <br/>
 
-- [CSV dataset downloads](https://docs.tardis.dev/downloadable-csv-files/overview)
+- [historical market data downloads as CSV files](https://docs.tardis.dev/python-client/quickstart#csv-dataset-downloads)
 
 <br/>
 
@@ -64,7 +66,7 @@ pip install tardis-dev
 
 - [Quickstart](https://docs.tardis.dev/python-client/quickstart)
 - [Replaying Historical Data](https://docs.tardis.dev/python-client/replaying-historical-data)
-- [Downloadable CSV files](https://docs.tardis.dev/downloadable-csv-files/overview)
+- [CSV Dataset Downloads](https://docs.tardis.dev/python-client/quickstart#csv-dataset-downloads)
 - [Migration Notice](https://docs.tardis.dev/python-client/migration-notice)
 
 <br/>

tardis_dev/replay.py

@@ -29,8 +29,8 @@ class Response(NamedTuple):
 
 async def replay(
     exchange: str,
-    from_date: str,
-    to_date: str,
+    from_date: Union[str, datetime],
+    to_date: Union[str, datetime],
     filters: Optional[Sequence[Channel]] = None,
     *,
     api_key: str = "",
@@ -310,20 +310,28 @@ def _validate_replay_args(
             raise ValueError(f"Invalid 'symbols[]' argument: {channel.symbols}. Please provide list of symbol strings.")
 
 
-def _parse_date(name: str, value: str) -> datetime:
+def _parse_date(name: str, value: Union[str, datetime]) -> datetime:
     if value is None:
         raise ValueError(
             f"Invalid '{name}' argument: {value}. Please provide valid ISO date string. "
             "https://docs.python.org/3/library/datetime.html#datetime.date.fromisoformat"
         )
 
-    try:
-        return dateutil.parser.isoparse(value)
-    except (TypeError, ValueError) as exc:
-        raise ValueError(
-            f"Invalid '{name}' argument: {value}. Please provide valid ISO date string. "
-            "https://docs.python.org/3/library/datetime.html#datetime.date.fromisoformat"
-        ) from exc
+    if isinstance(value, datetime):
+        parsed = value
+    else:
+        try:
+            parsed = dateutil.parser.isoparse(value)
+        except (TypeError, ValueError) as exc:
+            raise ValueError(
+                f"Invalid '{name}' argument: {value}. Please provide valid ISO date string. "
+                "https://docs.python.org/3/library/datetime.html#datetime.date.fromisoformat"
+            ) from exc
+
+    if parsed.tzinfo is None:
+        return parsed.replace(tzinfo=timezone.utc)
+
+    return parsed.astimezone(timezone.utc)
 
 
 def _get_slice_cache_path(

tests/test_replay.py

@@ -1,6 +1,6 @@
 import importlib
 import gzip
-from datetime import datetime
+from datetime import datetime, timedelta, timezone
 from pathlib import Path
 
 import pytest
@@ -128,6 +128,82 @@ def test_replay_formats_query_date_as_utc_z():
     assert _format_replay_query_date(datetime.fromisoformat("2019-05-01T00:00:00+00:00")) == "2019-05-01T00:00:00.000Z"
 
 
+@pytest.mark.asyncio
+async def test_replay_accepts_naive_datetime_inputs_as_utc(monkeypatch, tmp_path: Path):
+    cache_dir = tmp_path / "cache"
+    filters = _live_replay_filters()
+    captured = {}
+
+    slice_path = Path(
+        _get_slice_cache_path(
+            str(cache_dir),
+            LIVE_REPLAY_EXCHANGE,
+            datetime(2019, 5, 1, 0, 0, tzinfo=timezone.utc),
+            filters,
+        )
+    )
+    slice_path.parent.mkdir(parents=True, exist_ok=True)
+
+    with gzip.open(slice_path, "wb") as file:
+        file.write(b'2019-05-01T00:00:00.0000000Z {"table":"trade","action":"partial","data":[{"symbol":"BTCUSD"}]}\n')
+
+    async def fake_fetch_data_to_replay(**kwargs):
+        captured.update(kwargs)
+        return None
+
+    monkeypatch.setattr(replay_module, "_fetch_data_to_replay", fake_fetch_data_to_replay)
+
+    results = []
+    async for item in replay(
+        exchange=LIVE_REPLAY_EXCHANGE,
+        from_date=datetime(2019, 5, 1, 0, 0),
+        to_date=datetime(2019, 5, 1, 0, 1),
+        filters=filters,
+        cache_dir=str(cache_dir),
+    ):
+        results.append(item)
+
+    assert len(results) == 1
+    assert captured["from_date"] == datetime(2019, 5, 1, 0, 0, tzinfo=timezone.utc)
+    assert captured["to_date"] == datetime(2019, 5, 1, 0, 1, tzinfo=timezone.utc)
+
+
+@pytest.mark.asyncio
+async def test_replay_converts_timezone_aware_datetime_inputs_to_utc(monkeypatch, tmp_path: Path):
+    cache_dir = tmp_path / "cache"
+    filters = _live_replay_filters()
+    captured = {}
+
+    utc_from_date = datetime(2019, 5, 1, 0, 0, tzinfo=timezone.utc)
+    utc_to_date = datetime(2019, 5, 1, 0, 1, tzinfo=timezone.utc)
+
+    slice_path = Path(_get_slice_cache_path(str(cache_dir), LIVE_REPLAY_EXCHANGE, utc_from_date, filters))
+    slice_path.parent.mkdir(parents=True, exist_ok=True)
+
+    with gzip.open(slice_path, "wb") as file:
+        file.write(b'2019-05-01T00:00:00.0000000Z {"table":"trade","action":"partial","data":[{"symbol":"BTCUSD"}]}\n')
+
+    async def fake_fetch_data_to_replay(**kwargs):
+        captured.update(kwargs)
+        return None
+
+    monkeypatch.setattr(replay_module, "_fetch_data_to_replay", fake_fetch_data_to_replay)
+
+    results = []
+    async for item in replay(
+        exchange=LIVE_REPLAY_EXCHANGE,
+        from_date=datetime(2019, 5, 1, 2, 0, tzinfo=timezone(timedelta(hours=2))),
+        to_date=datetime(2019, 5, 1, 2, 1, tzinfo=timezone(timedelta(hours=2))),
+        filters=filters,
+        cache_dir=str(cache_dir),
+    ):
+        results.append(item)
+
+    assert len(results) == 1
+    assert captured["from_date"] == utc_from_date
+    assert captured["to_date"] == utc_to_date
+
+
 @pytest.mark.asyncio
 async def test_replay_raw_mode_returns_bytes(monkeypatch, tmp_path: Path):
     cache_dir = tmp_path / "cache"