Source code for osprey_connectors.relative_time
"""Declarative relative timestamps, resolved against an anchor at load time.
Demo and seed data (simulation scenario bundles and their narratives, seed
files the generic ARIEL adapter reads) express timestamps *relative* to "now" —
``{days_ago, time}`` — rather than as absolute dates. They resolve to concrete
datetimes at the moment data enters the system (``osprey sim apply`` and the
deploy-time seed for scenario narratives; ``osprey ariel ingest``/``quickstart``
for the generic adapter), so the data always lands at a
recent, deterministic wall-clock position without ever mutating the source file
at build time.
This is the single shared primitive, living in :mod:`osprey_connectors` so
neither the simulation engine nor the ARIEL ingestion layer depends on the
other.
"""
from dataclasses import dataclass
from datetime import datetime, timedelta
from datetime import time as dtime
__all__ = [
"RelativeTimestamp",
"resolve_relative_timestamp",
]
[docs]
@dataclass(frozen=True)
class RelativeTimestamp:
"""A timestamp expressed relative to an apply-/ingest-time anchor.
``days_ago`` is a whole-day shift back from the anchor date; ``time`` pins
the resolved time-of-day (tz-naive local), so hardcoded prose clock times in
an entry body stay consistent with the resolved timestamp.
"""
days_ago: int
time: dtime
[docs]
def resolve_relative_timestamp(spec: RelativeTimestamp, now: datetime) -> datetime:
"""Resolve a relative timestamp against an anchor ``now``.
Shifts ``now`` back ``spec.days_ago`` whole calendar days and pins the
resolved time-of-day to ``spec.time``. The shift is computed on the date
component, so it is DST-safe (it counts calendar days, not 24-hour spans)
and the resolved wall-clock time is exactly ``spec.time`` regardless of any
DST transition between the two dates. The result carries ``now``'s tzinfo
(naive in, naive out).
Args:
spec: The relative timestamp (whole-day offset plus time-of-day).
now: The anchor instant. For scenario bundles this is the shared
apply-time T0 (so narrative and telemetry resolve against one clock);
for generic ingestion it is the ingest-time "now".
Returns:
The resolved timestamp, with the same tzinfo as ``now``.
"""
target_date = (now - timedelta(days=spec.days_ago)).date()
return datetime.combine(target_date, spec.time, tzinfo=now.tzinfo)