Add scheduled refresh for tables that change at a fixed time of day

src/sqlmem/spec.py

@@ -10,6 +10,7 @@ kwargs keep working; ``tables=`` is converted to the same internal config.
 from dataclasses import dataclass, field
 
 from .delta import DeltaConfig
+from .schedule import ScheduleSpec, parse_schedule
 
 # Friendly alias for the declarative API; ``Delta`` and ``DeltaConfig`` are the
 # same type (``change_column`` + ``key_columns``), so either may be used as a
@@ -24,6 +25,22 @@ class TTL:
     seconds: int
 
 
+@dataclass(frozen=True)
+class Schedule:
+    """Time-of-day refresh strategy: full-reload the table at fixed times of day.
+
+    *times* is one time of day or a list of them (``"HH:MM"``/``"HH:MM:SS"``
+    strings or :class:`datetime.time`), interpreted in the local timezone.
+    Validated eagerly so a typo surfaces at construction, not at the first
+    refresh tick.
+    """
+
+    times: ScheduleSpec
+
+    def __post_init__(self) -> None:
+        parse_schedule("<Schedule>", self.times)  # eager validation; table name unknown yet
+
+
 @dataclass(frozen=True)
 class TableSpec:
     """Declarative specification of one cached table.
@@ -33,8 +50,9 @@ class TableSpec:
     a query asking for a column outside the list raises
     :class:`~sqlmem.exceptions.UndeclaredError`.
 
-    *refresh* is a :class:`Delta` (change-column incremental sync) or :class:`TTL`
-    (time-based full reload), or ``None`` for a static table loaded once.
+    *refresh* is a :class:`Delta` (change-column incremental sync), :class:`TTL`
+    (time-based full reload) or :class:`Schedule` (full reload at fixed times of
+    day), or ``None`` for a static table loaded once.
 
     *preload=True* loads the table at startup (in the background by default) so the
     first query is a cache hit instead of paying a cold load; a copy already fresh
@@ -44,6 +62,6 @@ class TableSpec:
     name: str
     columns: list[str] | None = None
     indexes: list[str | list[str]] = field(default_factory=list)
-    refresh: DeltaConfig | TTL | None = None
+    refresh: DeltaConfig | TTL | Schedule | None = None
     datetime_columns: list[str] = field(default_factory=list)
     preload: bool = False