mostlyright.core.temporal

mostlyright.core.temporal

mostlyright.core.temporal — temporal-safety primitives.

Public exports:

• TimePoint (UTC-aware timestamp wrapper with DST + ns truncation handling)
• KnowledgeView (filter DataFrame by knowledge_time <= as_of; plain class with __slots__)
• LeakageDetector + assert_no_leakage (loud as-of cutoff enforcement)

class mostlyright.core.temporal.KnowledgeView(df, as_of)

Bases: object

A filtered, knowledge-time-bounded view over a DataFrame.

Construction validates the shape of the input DataFrame. After construction, dataframe() returns a defensive copy of the rows where knowledge_time <= as_of.

Examples

Build a 3-row DataFrame with a tz-aware UTC knowledge_time column and view only the rows knowable as of 2025-01-02T12:00:00Z:

>>> import pandas as pd
>>> from mostlyright.core import KnowledgeView, TimePoint
>>> df = pd.DataFrame({
...     "knowledge_time": pd.to_datetime([
...         "2025-01-01T00:00:00Z",
...         "2025-01-02T00:00:00Z",
...         "2025-01-03T00:00:00Z",
...     ], utc=True),
...     "value": [10, 20, 30],
... })
>>> view = KnowledgeView(df, TimePoint("2025-01-02T12:00:00Z"))
>>> len(view.dataframe())
2

• Parameters:
  • df (pd.DataFrame | MostlyRightResult)
  • as_of (TimePoint)

property as_of : TimePoint

The as-of cutoff supplied at construction.

dataframe()

Return a defensive copy of the rows where knowledge_time <= as_of.

• Return type: DataFrame

class mostlyright.core.temporal.LeakageDetector(as_of)

Bases: object

Convenience wrapper for repeated detection against a fixed as_of.

• Parameters: as_of (TimePoint)

property as_of : TimePoint

check(df)

Run assert_no_leakage() against the bound as_of.

Accepts either a raw DataFrame or a MostlyRightResult wrapper (unwrapped inside assert_no_leakage()).

• Return type: None
• Parameters: df (DataFrame | MostlyRightResult)

check_issued_at(df)

Raise IssuedAtMissingError if any row has null issued_at.

Phase 20 OM-04 extension. Independent of as_of — the bound cutoff is irrelevant when the row carries no model-run time at all.

• Return type: None
• Parameters: df (DataFrame | MostlyRightResult)

class mostlyright.core.temporal.TimePoint(value)

Bases: object

A UTC-aware timestamp normalized to UTC for storage.

Construction accepts:

• datetime.datetime with tzinfo set (converted to UTC)
• pandas.Timestamp with tz set (converted to UTC)
• ISO 8601 string with a timezone (parsed and converted to UTC)

Rejects:

• naive datetime / pd.Timestamp (tzinfo / tz is None)
• date-only ISO strings (no time component, e.g. "2026-05-21")

Storage is a datetime with tzinfo=timezone.utc and microsecond precision preserved.

• Parameters: value (TimePointInput)

as_zone(tz)

Convert to a different IANA zone via zoneinfo.ZoneInfo.

Display helper only — the canonical storage stays UTC. Raises zoneinfo.ZoneInfoNotFoundError if tz is not a known IANA timezone.

• Return type: datetime
• Parameters: tz (str)

classmethod from_pandas(ts)

Construct from a tz-aware pandas.Timestamp.

Explicit alternative to passing a Timestamp to TimePoint(...) — useful when the caller wants the pandas-specific dispatch path to be unambiguous.

Raises ValueError if ts is pd.NaT (missing-data sentinel).

• Return type: TimePoint
• Parameters: ts (Timestamp)

iso()

Return an ISO 8601 UTC string.

Includes microseconds only when non-zero, matching standard datetime.isoformat() behavior (e.g. "2026-05-21T14:30:00+00:00" or "2026-05-21T14:30:00.123456+00:00").

• Return type: str

classmethod now()

Return a TimePoint for the current UTC time.

• Return type: TimePoint

to_utc()

Return the underlying UTC datetime (microseconds preserved).

• Return type: datetime

mostlyright.core.temporal.assert_no_leakage(df, as_of)

Raise LeakageError if any row’s knowledge_time > as_of.

Phase 6 W0-T6: accepts either a raw DataFrame or a MostlyRightResult; wrapped polars frames are converted to pandas via MostlyRightResult.frame_as_pandas() because the body of this function uses pd.Timestamp + iterrows semantics.

• Parameters:
  • df (DataFrame | MostlyRightResult) – DataFrame with a tz-aware UTC knowledge_time column, OR a MostlyRightResult wrapping such a frame.
  • as_of (TimePoint) – The as-of cutoff. Rows with strictly greater knowledge_time count as leakage.
• Raises:
  • SchemaValidationError – if knowledge_time is missing or not tz-aware UTC.
  • TypeError – if as_of is not a TimePoint.
  • LeakageError – if ≥1 rows have knowledge_time > as_of. Payload carries violating_count and a sample (≤10) of violations.
• Return type: None

Examples

• Return type: None
• Parameters:
  • df (DataFrame | MostlyRightResult)
  • as_of (TimePoint)

A leak-free frame passes silently:

>>> import pandas as pd
>>> from mostlyright.core import TimePoint, assert_no_leakage
>>> df = pd.DataFrame({
...     "knowledge_time": pd.to_datetime(["2025-01-01T00:00:00Z"], utc=True),
...     "value": [10],
... })
>>> assert_no_leakage(df, TimePoint("2025-01-02T00:00:00Z"))

A row past the cutoff raises LeakageError:

>>> from mostlyright.core import LeakageError
>>> leaky = pd.DataFrame({
...     "knowledge_time": pd.to_datetime(["2025-01-03T00:00:00Z"], utc=True),
...     "value": [99],
... })
>>> try:
...     assert_no_leakage(leaky, TimePoint("2025-01-02T00:00:00Z"))
... except LeakageError as err:
...     print(err.violating_count)
1

Modules

knowledge_view	KnowledgeView — temporal filtering by knowledge_time.
leakage	LeakageDetector — loud assertion of as-of leakage absence.
timepoint	TimePoint: UTC-aware timestamp wrapper for mostlyright.core.