daft.functions.to_utc_timestamp#

def to_utc_timestamp(expr: Expression, timezone: str) -> Expression:
    """Interprets a wall-clock timestamp in the given timezone and returns the UTC instant.

    Mirrors Spark's ``to_utc_timestamp``. The input's wall-clock value is treated as
    local time in ``timezone`` and converted to the equivalent UTC instant, returned as
    a tz-naive Timestamp.

    Args:
        expr: A Timestamp expression whose wall-clock is interpreted in ``timezone``.
        timezone: Source timezone name.

    Returns:
        Expression: A tz-naive Timestamp expression representing the UTC instant.

    Note:
        DST transition handling differs from Spark. When the local wall-clock falls
        in a non-existent gap (e.g. the spring-forward hour) or an ambiguous overlap
        (e.g. the fall-back hour), Daft raises a ``ValueError`` rather than silently
        picking a side. Spark instead advances past the gap and resolves ambiguity
        to the pre-transition offset. If you need Spark-compatible behavior, filter
        or pre-shift these inputs before calling.

    Examples:
        >>> import daft
        >>> from datetime import datetime
        >>> from daft.functions import to_utc_timestamp
        >>> df = daft.from_pydict({"ts": [datetime(2017, 7, 14, 3, 40)]})
        >>> df = df.with_column("utc", to_utc_timestamp(df["ts"], "Europe/London"))
        >>> df.to_pydict()["utc"]
        [datetime.datetime(2017, 7, 14, 2, 40)]
    """
    return Expression._call_builtin_scalar_fn("to_utc_timestamp", expr, timezone=timezone)