lair.clock.MTN2UTC#

lair.clock.MTN2UTC(x, *, localize=False, driver=None, ambiguous='raise', nonexistent='raise')[source]#

Convert times from Salt Lake City time ('America/Denver') to UTC.

A time without a time zone is taken as Salt Lake City clock time, and a time with one is converted from its own. Daylight saving time repeats one hour in November and skips one in March, so a clock-time file can hold a time that cannot be converted without a choice: ambiguous and nonexistent make it (the clock example shows both).

Parameters:
  • x (dt.datetime | pd.Timestamp | list[dt.datetime] | pd.DataFrame | pd.Series) – The times: a single time, a list of them, or with driver='pandas' the index of a DataFrame or the values of a Series.

  • localize (bool, optional) – If True, drop the time zone from the result and keep the UTC clock time. Default False.

  • driver (None | 'pandas', optional) – 'pandas' for a DataFrame or Series; None for a single time or a list.

  • ambiguous ('raise' | 'NaT' | 'infer' | bool | array of bool, optional) – What to do with a time that happens twice (the clocks go back): True is the first (daylight time), False the second (standard time). The default ‘raise’ raises a ValueError. As in convert_timezones().

  • nonexistent ('raise' | 'NaT' | 'shift_forward' | 'shift_backward' | timedelta, optional) – What to do with a time that never happens (the clocks go forward). The default ‘raise’ raises a ValueError. As in convert_timezones().

Returns:

dt.datetime | pd.Timestamp | list[dt.datetime] | pd.DataFrame | pd.Series – The converted times, in the shape of x: a single time gives a single time, a datetime a datetime and a pd.Timestamp a pd.Timestamp.

Raises:

ValueError – If a time is ambiguous or nonexistent and the option for it is ‘raise’.

See also

MST2UTC

The same from standard time, where nothing is repeated or skipped.

UTC2MTN

The way back, from UTC to Salt Lake City time.

convert_timezones

The general conversion, from any zone to any zone.

Examples

12:00 in Salt Lake City in July is 18:00 UTC:

>>> import datetime as dt
>>> from lair.clock import MTN2UTC
>>> MTN2UTC(dt.datetime(2024, 7, 15, 12))
datetime.datetime(2024, 7, 15, 18, 0, tzinfo=zoneinfo.ZoneInfo(key='UTC'))

The clocks went back on 2024-11-03, so 01:30 happened twice; say which:

>>> MTN2UTC(dt.datetime(2024, 11, 3, 1, 30), ambiguous=True)
datetime.datetime(2024, 11, 3, 7, 30, tzinfo=zoneinfo.ZoneInfo(key='UTC'))
>>> MTN2UTC(dt.datetime(2024, 11, 3, 1, 30), ambiguous=False)
datetime.datetime(2024, 11, 3, 8, 30, tzinfo=zoneinfo.ZoneInfo(key='UTC'))

The index of a DataFrame, kept naive in UTC with localize=True:

>>> import pandas as pd
>>> data = pd.DataFrame(
...     {"ch4": [2000.0]}, index=pd.to_datetime(["2024-07-15 12:00"])
... )
>>> MTN2UTC(data, localize=True, driver="pandas")
                        ch4
2024-07-15 18:00:00  2000.0