enh: updates from Javier's review

Author: dshemetov

README.md

@@ -64,19 +64,19 @@ epidata.epidata_archive(
     source="nssp",
     signals="pct_ed_visits_influenza",
     geo_type="state",
-    report_time_query="<2025-10-16",
+    report_time="<2025-10-16",
 ).df()
 
-# Router: pass `report_time_query` (or `snapshot_date="*"`) for archive, `snapshot_date` for snapshot.
+# Router: pass `report_time` (or `snapshot_date="*"`) for archive, `snapshot_date` for snapshot.
 epidata.epidata(
     source="nssp",
     signals="pct_ed_visits_influenza",
     geo_type="state",
-    report_time_query=EpiRange("2025-01-01", "2025-10-16"),
+    report_time=EpiRange("2025-01-01", "2025-10-16"),
 ).df()
 ```
 
-`geo_values`, `reference_time`, and an `EpiRange` `report_time_query` lower
+`geo_values`, `reference_time`, and an `EpiRange` `report_time` lower
 bound are filtered locally after the request.
 
 ## Development

epidatpy/_endpoints.py

@@ -1534,7 +1534,7 @@ def epidata_snapshot(
         geo_values: StringParam = "*",
         reference_time: EpiRangeParam = "*",
         fill_method: str | None = None,
-        snapshot_date: str | date | None = None,
+        snapshot_date: str | date | int | None = None,
     ) -> CALL_TYPE:
         """Fetch a snapshot of CAST-API signals as they appeared on `snapshot_date`.
 
@@ -1574,16 +1574,16 @@ def epidata_archive(
         geo_values: StringParam = "*",
         reference_time: EpiRangeParam = "*",
         fill_method: str | None = None,
-        report_time_query: str | date | EpiRange | None = "*",
+        report_time: str | date | EpiRange | None = "*",
     ) -> CALL_TYPE:
         """Fetch the full report-time history of CAST-API signals.
 
-        `report_time_query` accepts an exact date, an operator-prefixed string
+        `report_time` accepts an exact date, an operator-prefixed string
         (e.g. ``"<2025-10-16"``), or an :class:`EpiRange`. ``"*"`` (default)
         requests all report times. `geo_values`, `reference_time`, and the
         EpiRange lower bound are filtered locally after the API call.
         """
-        report_time_query_str = validate_report_time_query(report_time_query)
+        report_time_str = validate_report_time_query(report_time)
 
         signal_str = signals if isinstance(signals, str) else ",".join(signals)
 
@@ -1594,14 +1594,14 @@ def epidata_archive(
                 "signal": signal_str,
                 "geo_type": geo_type,
                 "fill_method": fill_method,
-                "report_time_query": report_time_query_str,
+                "report_time": report_time_str,
             },
             _cast_signal_fields(),
             api_version="cast",
             post_filter=(
                 geo_values,
                 reference_time,
-                report_time_query if isinstance(report_time_query, EpiRange) else None,
+                report_time if isinstance(report_time, EpiRange) else None,
             ),
         )
 
@@ -1613,28 +1613,28 @@ def epidata(
         geo_values: StringParam = "*",
         reference_time: EpiRangeParam = "*",
         fill_method: str | None = None,
-        snapshot_date: str | date | None = None,
-        report_time_query: str | date | EpiRange | None = None,
+        snapshot_date: str | date | int | None = None,
+        report_time: str | date | EpiRange | None = None,
     ) -> CALL_TYPE:
         """Router for CAST-API queries.
 
-        Dispatches to :meth:`epidata_archive` when ``report_time_query`` is
+        Dispatches to :meth:`epidata_archive` when ``report_time`` is
         supplied or ``snapshot_date == "*"``; otherwise to
-        :meth:`epidata_snapshot`. ``report_time_query`` and ``snapshot_date``
+        :meth:`epidata_snapshot`. ``report_time`` and ``snapshot_date``
         are mutually exclusive.
         """
-        if report_time_query is not None and snapshot_date is not None:
-            raise InvalidArgumentException("`report_time_query` and `snapshot_date` are mutually exclusive")
+        if report_time is not None and snapshot_date is not None:
+            raise InvalidArgumentException("`report_time` and `snapshot_date` are mutually exclusive")
 
-        if report_time_query is not None or snapshot_date == "*":
+        if report_time is not None or snapshot_date == "*":
             return self.epidata_archive(
                 source=source,
                 signals=signals,
                 geo_type=geo_type,
                 geo_values=geo_values,
                 reference_time=reference_time,
                 fill_method=fill_method,
-                report_time_query=report_time_query if report_time_query is not None else "*",
+                report_time=report_time if report_time is not None else "*",
             )
         return self.epidata_snapshot(
             source=source,

epidatpy/_parse.py

@@ -77,28 +77,31 @@ def parse_user_date_or_week(
     raise ValueError(f"Cannot parse date or week from {value}")
 
 
-def validate_report_time_query(report_time_query: str | int | date | Week | EpiRange | None) -> str | None:
-    """Format the `report_time_query` argument for the CAST API `report_time_query` parameter.
+def validate_report_time_query(report_time: str | int | date | Week | EpiRange | None) -> str | None:
+    """Format the `report_time` argument for the CAST API `report_time` parameter.
 
     Accepts an exact date, an operator-prefixed string (e.g. ``"<2025-10-16"``),
     or an :class:`EpiRange` (upper bound becomes ``"<to"``; the lower bound is
     filtered locally). Returns ``None`` for ``None`` / ``"*"``.
     """
     from ._model import EpiRange  # avoid circular import
 
-    if report_time_query is None or report_time_query == "*":
+    if report_time is None or report_time == "*":
         return None
 
     operator = "="
     raw: str | int | date | Week
-    if isinstance(report_time_query, str) and report_time_query[:1] in ("<", ">", "="):
-        operator = report_time_query[0]
-        raw = report_time_query[1:]
-    elif isinstance(report_time_query, EpiRange):
+    if isinstance(report_time, str) and report_time[:2] in ("<=", ">="):
+        operator = report_time[:2]
+        raw = report_time[2:]
+    elif isinstance(report_time, str) and report_time[:1] in ("<", ">", "="):
+        operator = report_time[0]
+        raw = report_time[1:]
+    elif isinstance(report_time, EpiRange):
         operator = "<"
-        raw = report_time_query.end
+        raw = report_time.end
     else:
-        raw = report_time_query
+        raw = report_time
 
     parsed: date | None
     if isinstance(raw, date):
@@ -109,7 +112,7 @@ def validate_report_time_query(report_time_query: str | int | date | Week | EpiR
         parsed = parse_api_date(raw)
     if parsed is None:
         raise ValueError(
-            "Invalid `report_time_query` format. Must be a single date, an `EpiRange`, "
+            "Invalid `report_time` format. Must be a single date, an `EpiRange`, "
             "or a string with an operator (e.g., '<2025-10-16')."
         )
     return f"{operator}{parsed.strftime('%Y-%m-%d')}"

epidatpy/request.py

@@ -114,6 +114,10 @@ def with_base_url(self, base_url: str) -> EpiDataCall:
             self._session,
             self._endpoint,
             self._params,
+            self.meta,
+            self.only_supports_classic,
+            self.use_cache,
+            self.cache_max_age_days,
             api_version=self._api_version,
             post_filter=self._post_filter,
         )
@@ -124,6 +128,10 @@ def with_session(self, session: Session) -> EpiDataCall:
             session,
             self._endpoint,
             self._params,
+            self.meta,
+            self.only_supports_classic,
+            self.use_cache,
+            self.cache_max_age_days,
             api_version=self._api_version,
             post_filter=self._post_filter,
         )
@@ -276,15 +284,15 @@ def df(
                     except (ValueError, TypeError):
                         pass
 
-        if self._post_filter is not None:
-            geo_values, reference_time, report_time = self._post_filter
-            df = cast_filter(df, geo_values=geo_values, reference_time=reference_time, report_time=report_time)
-
         if self.use_cache:
             with Cache(CACHE_DIRECTORY) as cache:
                 cache_key = self._get_cache_key("df")
                 cache.set(cache_key, df, expire=self.cache_max_age_days * 24 * 60 * 60)
 
+        if self._post_filter is not None:
+            geo_values, reference_time, report_time = self._post_filter
+            df = cast_filter(df, geo_values=geo_values, reference_time=reference_time, report_time=report_time)
+
         return df
 
 
@@ -311,10 +319,22 @@ def __init__(
         self.cache_max_age_days = cache_max_age_days
 
     def with_base_url(self, base_url: str) -> EpiDataContext:
-        return EpiDataContext(base_url, self._session, cast_base_url=self._cast_base_url)
+        return EpiDataContext(
+            base_url,
+            self._session,
+            self.use_cache,
+            self.cache_max_age_days,
+            cast_base_url=self._cast_base_url,
+        )
 
     def with_session(self, session: Session) -> EpiDataContext:
-        return EpiDataContext(self._base_url, session, cast_base_url=self._cast_base_url)
+        return EpiDataContext(
+            self._base_url,
+            session,
+            self.use_cache,
+            self.cache_max_age_days,
+            cast_base_url=self._cast_base_url,
+        )
 
     def _create_call(
         self,

test.py

@@ -13,7 +13,7 @@ def _():
         source="nssp",
         signals="pct_ed_visits_influenza",
         geo_type="state",
-        report_time_query=EpiRange("2025-01-01", "2025-10-16"),
+        report_time=EpiRange("2025-01-01", "2025-10-16"),
     ).df()
     return (df,)
 

tests/test_cast_endpoints.py

@@ -63,7 +63,7 @@ def test_epidata_archive(self, source: str, signal: str, geo_type: str) -> None:
         assert pd.api.types.is_datetime64_any_dtype(df["report_time"])
 
     def test_epidata_router_dispatch(self) -> None:
-        # `snapshot_date="*"` routes to archive (no report_time_query sent);
+        # `snapshot_date="*"` routes to archive (no report_time sent);
         # verify the archive's `report_time` column comes back.
         ctx = EpiDataContext()
         df = ctx.epidata(
@@ -74,14 +74,14 @@ def test_epidata_router_dispatch(self) -> None:
         ).df()
         assert "report_time" in df.columns
 
-    def test_epidata_mutually_exclusive_report_time_query_and_snapshot_date(self) -> None:
+    def test_epidata_mutually_exclusive_report_time_and_snapshot_date(self) -> None:
         with pytest.raises(InvalidArgumentException):
             EpiDataContext().epidata(
                 source="nssp",
                 signals="pct_ed_visits_influenza",
                 geo_type="state",
                 snapshot_date="2025-10-16",
-                report_time_query="2025-10-16",
+                report_time="2025-10-16",
             )
 
     def test_epidata_snapshot_local_filters(self) -> None:

tests/test_parse.py

@@ -0,0 +1,43 @@
+import datetime
+
+import pytest
+from epiweeks import Week
+
+from epidatpy._model import EpiRange
+from epidatpy._parse import validate_report_time_query
+
+
+def test_validate_report_time_query_none() -> None:
+    assert validate_report_time_query(None) is None
+    assert validate_report_time_query("*") is None
+
+
+def test_validate_report_time_query_exact() -> None:
+    assert validate_report_time_query("2025-10-16") == "=2025-10-16"
+    assert validate_report_time_query(20251016) == "=2025-10-16"
+    assert validate_report_time_query(datetime.date(2025, 10, 16)) == "=2025-10-16"
+    assert validate_report_time_query("=2025-10-16") == "=2025-10-16"
+
+
+def test_validate_report_time_query_week() -> None:
+    # Week resolves to its start date.
+    assert validate_report_time_query(Week(2025, 1)) == f"={Week(2025, 1).startdate():%Y-%m-%d}"
+
+
+def test_validate_report_time_query_operators() -> None:
+    assert validate_report_time_query("<2025-10-16") == "<2025-10-16"
+    assert validate_report_time_query(">2025-10-16") == ">2025-10-16"
+    assert validate_report_time_query("<=2025-10-16") == "<=2025-10-16"
+    assert validate_report_time_query(">=2025-10-16") == ">=2025-10-16"
+
+
+def test_validate_report_time_query_epirange() -> None:
+    # EpiRange upper bound becomes "<to"; lower bound filtered locally.
+    assert validate_report_time_query(EpiRange(20251001, 20251016)) == "<2025-10-16"
+
+
+def test_validate_report_time_query_invalid() -> None:
+    with pytest.raises(ValueError):
+        validate_report_time_query("not-a-date")
+    with pytest.raises(ValueError):
+        validate_report_time_query("<garbage")