app/timeutils.py

"""Display-side time helpers.

Timestamps are STORED in UTC (see models.py / route writes — do not change that).
These helpers exist only to render UTC values in Eastern time (America/New_York,
which automatically handles EST vs EDT) for human-facing output: web UI, PDF, DOCX.
"""
from datetime import datetime, timezone
from zoneinfo import ZoneInfo

EASTERN = ZoneInfo("America/New_York")

# Default display format used across the portal (e.g. "06/25/2026 02:00 PM").
DEFAULT_FMT = "%m/%d/%Y %I:%M %p"


def to_eastern(dt: datetime | None) -> datetime | None:
    """Convert a stored UTC datetime to Eastern. Naive values are assumed UTC."""
    if dt is None:
        return None
    if dt.tzinfo is None:  # legacy naive rows were written as UTC
        dt = dt.replace(tzinfo=timezone.utc)
    return dt.astimezone(EASTERN)


def fmt_eastern(dt: datetime | None, fmt: str = DEFAULT_FMT, default: str = "—") -> str:
    """Format a stored UTC datetime in Eastern time, or return `default` if None."""
    eastern = to_eastern(dt)
    return eastern.strftime(fmt) if eastern else default


def now_eastern() -> datetime:
    """Current time in Eastern (for 'generated on' / 'submitted on' footers)."""
    return datetime.now(EASTERN)