mostlyright.core.temporal.timepoint

mostlyright.core.temporal.timepoint

TimePoint: UTC-aware timestamp wrapper for mostlyright.core.

Load-bearing for the temporal-safety invariants described in docs/design.md (see “Definitions” — event_time, knowledge_time, retrieved_at semantics).

Every timestamp in mostlyright.core is UTC-aware. TimePoint:

• normalizes any tz-aware input to UTC internally
• rejects naive datetimes loudly (ValueError with “naive” in message)
• rejects date-only ISO strings loudly (ValueError)
• preserves microsecond precision through ISO round-trips
• compares and hashes by UTC value, so two TimePoints constructed from

the same instant via different inputs are equal and have the same hash

Uses stdlib zoneinfo (3.11+) for IANA zone display conversions.

Classes

TimePoint(value)	A UTC-aware timestamp normalized to UTC for storage.

class mostlyright.core.temporal.timepoint.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